Projects

Projects represent client engagements, internal initiatives, or any body of work. Assign projects to workflows, track value, manage deliverables, and log time.

The Project Object

Field	Type	Description
`id`	uuid	Unique identifier for the project
`account_id`	uuid	ID of the account that owns the project
`created_by`	uuid	ID of the user who created the project
`name`	string	Project name
`description`	string	Free-form project description
`stage_id`	uuid?	ID of the workflow stage the project is currently in
`stage_label`	string	Display label of the current workflow stage (read-only, populated via join)
`stage_color`	string	Color of the current workflow stage (read-only, populated via join)
`company_id`	uuid?	ID of the company (client) associated with the project, if any
`company_name`	string	Name of the associated company (read-only, populated via join)
`assigned_to`	uuid?	ID of the user the project is assigned to, if any
`assigned_name`	string	Name of the assigned user (read-only, populated via join)
`value`	int?	Project value as an integer in the smallest currency unit (cents)
`start_date`	string?	Project start date in ISO 8601 (YYYY-MM-DD) format
`end_date`	string?	Project end date in ISO 8601 (YYYY-MM-DD) format
`is_retainer`	bool	Whether the project is an ongoing retainer engagement rather than a fixed-scope project
`renewal_date`	string?	Renewal date for retainer projects in ISO 8601 (YYYY-MM-DD) format
`currency`	string?	ISO 4217 currency code for the project value (e.g. USD)
`timezone`	string?	IANA timezone name for the project (e.g. America/New_York)
`notes`	string	Free-form notes about the project
`tags`	string[]	List of tags applied to the project
`custom_fields`	object	Account-defined custom field values as a JSON object
`workflow_id`	uuid?	ID of the workflow (pipeline) the project belongs to
`created_at`	datetime	Timestamp the project was created, ISO 8601
`updated_at`	datetime	Timestamp the project was last updated, ISO 8601

Link a contact to a project

Endpoint: projects-contacts-add

Field	Type	Required	Description
`project_id`	string	Yes	ID of the project to link the contact to
`contact_id`	string	Yes	ID of the contact to link
`role`	string	No	Role the contact plays on the project (free-form, e.g. Stakeholder)

curl -X POST https://api.driftwoodapp.com/api/projects-contacts-add \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "...", "contact_id": "..."}'

List contacts linked to a project

Endpoint: projects-contacts-list

Field	Type	Required	Description
`project_id`	string	Yes	ID of the project whose linked contacts to list

curl -X POST https://api.driftwoodapp.com/api/projects-contacts-list \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "..."}'

Remove a contact from a project

Endpoint: projects-contacts-remove

Field	Type	Required	Description
`project_id`	string	Yes	ID of the project to remove the contact from
`contact_id`	string	Yes	ID of the contact to unlink

curl -X POST https://api.driftwoodapp.com/api/projects-contacts-remove \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "...", "contact_id": "..."}'

Create a new project

Endpoint: projects-create

Field	Type	Required	Description
`name`	string	Yes	Project name (required)
`description`	string	No	Free-form project description
`stage_id`	string?	No	ID of the workflow stage to place the project in; defaults to the workflow’s first stage
`workflow_id`	string?	No	ID of the workflow (pipeline) for the project; defaults to the account’s default workflow
`company_id`	string?	No	ID of the company (client) to associate with the project
`assigned_to`	string?	No	ID of the user to assign the project to
`value`	int?	No	Project value as an integer in the smallest currency unit (cents)
`start_date`	string?	No	Project start date in ISO 8601 (YYYY-MM-DD) format
`end_date`	string?	No	Project end date in ISO 8601 (YYYY-MM-DD) format
`is_retainer`	bool	No	Whether the project is an ongoing retainer engagement rather than fixed-scope
`renewal_date`	string?	No	Renewal date for retainer projects in ISO 8601 (YYYY-MM-DD) format
`currency`	string?	No	ISO 4217 currency code for the project value; defaults to the account currency when a value is set
`timezone`	string?	No	IANA timezone name for the project (e.g. America/New_York)
`notes`	string	No	Free-form notes about the project
`tags`	string[]	No	List of tags to apply to the project
`custom_fields`	object?	No	Account-defined custom field values as a JSON object

curl -X POST https://api.driftwoodapp.com/api/projects-create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "..."}'

Delete a project

Endpoint: projects-delete

Field	Type	Required	Description
`id`	string	Yes	ID of the project to delete

curl -X POST https://api.driftwoodapp.com/api/projects-delete \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "..."}'

Get a project by ID

Endpoint: projects-get

Field	Type	Required	Description
`id`	string	Yes	ID of the project to retrieve

curl -X POST https://api.driftwoodapp.com/api/projects-get \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "..."}'

List projects with optional filters

Endpoint: projects-list

Field	Type	Required	Description
`search`	string	No	Full-text search query matched against project fields
`tags`	string[]	No	Filter to projects that have all of these tags
`stage_id`	string?	No	Filter to projects in this workflow stage
`company_id`	string?	No	Filter to projects associated with this company
`assigned_to`	string?	No	Filter to projects assigned to this user
`cursor`	string	No	Opaque pagination cursor from a previous response
`limit`	int	No	Maximum number of projects to return

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

Update an existing project

Endpoint: projects-update

Field	Type	Required	Description
`id`	string	Yes	ID of the project to update
`workflow_id`	string?	No	Move the project to this workflow (pipeline)
`name`	string?	No	Updated project name
`description`	string?	No	Updated project description
`stage_id`	string?	No	Move the project to this workflow stage
`company_id`	string?	No	ID of the company to associate; empty string clears it
`assigned_to`	string?	No	ID of the user to assign; empty string clears the assignment
`value`	int?	No	Project value as an integer in the smallest currency unit (cents)
`start_date`	string?	No	Project start date in ISO 8601 (YYYY-MM-DD) format
`end_date`	string?	No	Project end date in ISO 8601 (YYYY-MM-DD) format
`is_retainer`	bool?	No	Whether the project is an ongoing retainer engagement rather than fixed-scope
`renewal_date`	string?	No	Renewal date for retainer projects in ISO 8601 (YYYY-MM-DD) format
`currency`	string?	No	ISO 4217 currency code for the project value
`timezone`	string?	No	IANA timezone name for the project (e.g. America/New_York)
`notes`	string?	No	Updated free-form notes
`tags`	string[]	No	Replacement list of tags for the project
`custom_fields`	object?	No	Custom field values to merge into the project, as a JSON object

curl -X POST https://api.driftwoodapp.com/api/projects-update \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "..."}'

Error Codes

Code	Description
`projects.invalid_id`	Invalid id
`projects.invalid_contact_id`	Invalid contact id
`projects.not_found`	Not found
`projects.contact_not_found`	Contact not found
`projects.name_required`	Name required
`projects.invalid_workflow_id`	Invalid workflow id
`projects.invalid_stage_id`	Invalid stage id
`projects.invalid_stage`	Invalid stage
`projects.invalid_company_id`	Invalid company id
`projects.invalid_assigned_to`	Invalid assigned to
`projects.invalid_custom_fields`	Invalid custom fields