Contacts

Contacts are the core records in Driftwood — the people your team interacts with. Contacts can be associated with companies, tagged, and have custom fields.

The Contact Object

Field	Type	Description
id	uuid	Unique identifier of the contact (UUID).
account_id	uuid	ID of the account that owns this contact (UUID).
created_by	uuid	ID of the user who created this contact (UUID).
first_name	string	Contact’s first name.
last_name	string	Contact’s last name.
email	string	Contact’s email address.
phone	string	Contact’s phone number.
company_id	uuid?	ID of the company this contact belongs to (UUID), or null if unassigned.
company_name	string	Name of the associated company, joined from the companies table (read-only).
job_title	string	Contact’s job title.
address	string	Street address.
city	string	City.
state	string	State or province.
zip_code	string	Postal or ZIP code.
country	string	Country.
notes	string	Free-form notes about the contact.
tags	string[]	Tags associated with the contact; normalized to lowercase, trimmed, and deduplicated.
source_id	uuid?	ID of the source this contact came from (UUID), or null if unassigned.
source_name	string	Name of the associated source, joined from the sources table (read-only).
custom_fields	object	Custom field values as a JSON object, validated against the account’s contact custom field definitions.
created_at	datetime	Timestamp when the contact was created (ISO 8601).
updated_at	datetime	Timestamp when the contact was last updated (ISO 8601).

Create a new contact

Endpoint: contacts-create

Field	Type	Required	Description
first_name	string	Yes	Contact’s first name. Required and must be non-empty.
last_name	string	No	Contact’s last name.
email	string	No	Contact’s email address.
phone	string	No	Contact’s phone number.
company_id	string?	No	ID of the company to associate (UUID).
job_title	string	No	Contact’s job title.
address	string	No	Street address.
city	string	No	City.
state	string	No	State or province.
zip_code	string	No	Postal or ZIP code.
country	string	No	Country.
notes	string	No	Free-form notes about the contact.
tags	string[]	No	Tags to assign; normalized to lowercase, trimmed, and deduplicated.
source_id	string?	No	ID of the source to associate (UUID).
custom_fields	object?	No	Custom field values as a JSON object, validated against the account’s contact custom field definitions.

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

Delete a contact

Endpoint: contacts-delete

Field	Type	Required	Description
id	string	Yes	ID of the contact to delete (UUID).

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

Get a contact by ID

Endpoint: contacts-get

Field	Type	Required	Description
id	string	Yes	ID of the contact to retrieve (UUID).

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

List contacts with filtering and pagination

Endpoint: contacts-list

Field	Type	Required	Description
search	string	No	Full-text search query matched against contact fields.
tags	string[]	No	Filter to contacts that have all of these tags; normalized to lowercase, trimmed, and deduplicated.
company_id	string?	No	Filter to contacts belonging to this company (UUID).
company_ids	string[]	No	Filter to contacts belonging to any of these companies (UUIDs).
source_ids	string[]	No	Filter to contacts from any of these sources (UUIDs).
cursor	string	No	Opaque pagination cursor from a previous response’s next_cursor.
limit	int	No	Maximum number of contacts to return per page.

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

Update an existing contact

Endpoint: contacts-update

Field	Type	Required	Description
id	string	Yes	ID of the contact to update (UUID). Required.
first_name	string?	No	New first name. Omit to leave unchanged.
last_name	string?	No	New last name. Omit to leave unchanged.
email	string?	No	New email address. Omit to leave unchanged.
phone	string?	No	New phone number. Omit to leave unchanged.
company_id	string?	No	New associated company ID (UUID). Omit to leave unchanged.
job_title	string?	No	New job title. Omit to leave unchanged.
address	string?	No	New street address. Omit to leave unchanged.
city	string?	No	New city. Omit to leave unchanged.
state	string?	No	New state or province. Omit to leave unchanged.
zip_code	string?	No	New postal or ZIP code. Omit to leave unchanged.
country	string?	No	New country. Omit to leave unchanged.
notes	string?	No	New notes. Omit to leave unchanged.
tags	string[]	No	Replacement set of tags; normalized to lowercase, trimmed, and deduplicated. Omit to leave unchanged.
source_id	string?	No	New associated source ID (UUID); pass an empty string to clear. Omit to leave unchanged.
custom_fields	object?	No	Custom field values to merge onto existing values, validated against the account’s contact custom field definitions. Omit to leave unchanged.

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

Error Codes

Code	Description
contacts.invalid_request	invalid request body
contacts.first_name_required	first name is required
contacts.invalid_company_id	invalid company ID
contacts.invalid_source_id	invalid source ID
contacts.invalid_custom_fields	custom field validation failed
contacts.invalid_id	invalid contact ID
contacts.not_found	contact not found