Projects

Projects represent work engagements in Driftwood — deals, client projects, partnerships, or any tracked initiative. Projects progress through stages, can be assigned to team members, linked to companies, and have contacts associated with specific roles.

The Project Object

Field	Type	Description
`id`	uuid	Unique identifier
`account_id`	uuid	Account this project belongs to
`created_by`	uuid	User who created the project
`name`	string	Project name
`description`	string	Description
`stage`	string	Current stage: `proposal`, `active`, `review`, `complete`, `archived`
`company_id`	uuid \| null	Associated company ID
`company_name`	string	Company name (read-only, computed)
`assigned_to`	uuid \| null	Assigned user ID
`assigned_name`	string	Assigned user name (read-only, computed)
`value`	integer \| null	Project value in cents
`start_date`	string \| null	Start date (YYYY-MM-DD)
`end_date`	string \| null	End date (YYYY-MM-DD)
`is_retainer`	boolean	Whether this is a recurring retainer
`renewal_date`	string \| null	Next renewal date (YYYY-MM-DD)
`notes`	string	Free-text notes
`tags`	string[]	Array of tag strings
`custom_fields`	object	Custom field values
`created_at`	datetime	Creation timestamp
`updated_at`	datetime	Last update timestamp

Project Stages

Stage	Description
`proposal`	Initial stage — project is being proposed
`active`	Work is in progress
`review`	Under review
`complete`	Work is finished
`archived`	No longer active

List Projects

Endpoint: projects-list

Field	Type	Required	Description
`search`	string	No	Search by name
`tags`	string[]	No	Filter by tags
`stage`	string	No	Filter by stage
`company_id`	uuid	No	Filter by company
`assigned_to`	uuid	No	Filter by assigned user
`cursor`	string	No	Pagination cursor
`limit`	integer	No	Results per page

curl -X POST https://api.driftwoodapp.com/api/projects-list \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"stage": "active", "limit": 10}'

Get Project

Endpoint: projects-get

Field	Type	Required	Description
`id`	uuid	Yes	Project ID

Create Project

Endpoint: projects-create

Field	Type	Required	Description
`name`	string	Yes	Project name
`description`	string	No	Description
`stage`	string	No	Stage (default: `proposal`)
`company_id`	uuid	No	Associated company
`assigned_to`	uuid	No	Assigned user
`value`	integer	No	Value in cents
`start_date`	string	No	Start date (YYYY-MM-DD)
`end_date`	string	No	End date (YYYY-MM-DD)
`is_retainer`	boolean	No	Retainer flag
`renewal_date`	string	No	Renewal date (YYYY-MM-DD)
`notes`	string	No	Notes
`tags`	string[]	No	Tags
`custom_fields`	object	No	Custom field values

curl -X POST https://api.driftwoodapp.com/api/projects-create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website Redesign",
    "company_id": "660e8400-e29b-41d4-a716-446655440001",
    "stage": "proposal",
    "value": 2500000,
    "start_date": "2025-07-01",
    "tags": ["design"]
  }'

Update Project

Endpoint: projects-update — partial updates supported.

Field	Type	Required	Description
`id`	uuid	Yes	Project ID
All other fields from create		No	Fields to update

Delete Project

Endpoint: projects-delete

Field	Type	Required	Description
`id`	uuid	Yes	Project ID

Project Contacts

Associate contacts with projects and assign them roles (e.g., “Stakeholder”, “Decision Maker”).

List Project Contacts

Endpoint: projects-contacts-list

Field	Type	Required	Description
`project_id`	uuid	Yes	Project ID

Response:

{
  "ok": true,
  "result": {
    "contacts": [
      {
        "project_id": "...",
        "contact_id": "...",
        "role": "Decision Maker",
        "contact_name": "Jane Smith",
        "contact_email": "jane@example.com",
        "created_at": "2025-06-01T12:00:00Z"
      }
    ]
  }
}

Add Contact to Project

Endpoint: projects-contacts-add

Field	Type	Required	Description
`project_id`	uuid	Yes	Project ID
`contact_id`	uuid	Yes	Contact ID
`role`	string	No	Role description

Remove Contact from Project

Endpoint: projects-contacts-remove

Field	Type	Required	Description
`project_id`	uuid	Yes	Project ID
`contact_id`	uuid	Yes	Contact ID

Error Codes

Code	Description
`projects.invalid_request`	Malformed request body
`projects.invalid_id`	Invalid UUID format
`projects.not_found`	Project does not exist
`projects.name_required`	Name is required for creation
`projects.invalid_stage`	Stage must be: proposal, active, review, complete, archived
`projects.invalid_company_id`	Referenced company does not exist
`projects.invalid_assigned_to`	Referenced user does not exist
`projects.invalid_custom_fields`	Custom field values don’t match definitions
`projects.internal`	Server error