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
account_id	uuid	Account this contact belongs to
created_by	uuid	User who created the contact
first_name	string	First name
last_name	string	Last name
email	string	Email address
phone	string	Phone number
company_id	uuid | null	Associated company ID
company_name	string	Company name (read-only, computed)
job_title	string	Job title
address	string	Street address
city	string	City
state	string	State/province
zip_code	string	ZIP/postal code
country	string	Country
notes	string	Free-text notes
tags	string[]	Array of tag strings
source_id	uuid | null	Lead source ID
source_name	string	Source name (read-only, computed)
custom_fields	object	Custom field values keyed by field definition ID
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

List Contacts

Search and filter contacts with cursor-based pagination.

Endpoint: contacts-list

Parameters:

Field	Type	Required	Description
search	string	No	Search across name, email, phone, company name
tags	string[]	No	Filter by tags (contacts must have all specified tags)
company_id	uuid	No	Filter by company
company_ids	uuid[]	No	Filter by multiple companies
source_ids	uuid[]	No	Filter by sources
cursor	string	No	Pagination cursor
limit	integer	No	Results per page (default 25)

Example:

curl -X POST https://api.driftwoodapp.com/api/contacts-list \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "search": "jane",
    "tags": ["vip"],
    "limit": 10
  }'

Response:

{
  "ok": true,
  "result": {
    "items": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "phone": "+1-555-0100",
        "company_id": "660e8400-e29b-41d4-a716-446655440001",
        "company_name": "Acme Corp",
        "job_title": "VP of Engineering",
        "tags": ["vip", "enterprise"],
        "source_name": "Website",
        "custom_fields": {},
        "created_at": "2025-06-01T12:00:00Z",
        "updated_at": "2025-06-01T12:00:00Z"
      }
    ],
    "next_cursor": ""
  }
}

Get Contact

Endpoint: contacts-get

Field	Type	Required	Description
id	uuid	Yes	Contact ID

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

Create Contact

Endpoint: contacts-create

Field	Type	Required	Description
first_name	string	Yes	First name
last_name	string	No	Last name
email	string	No	Email address
phone	string	No	Phone number
company_id	uuid	No	Associate with a company
job_title	string	No	Job title
address	string	No	Street address
city	string	No	City
state	string	No	State/province
zip_code	string	No	ZIP/postal code
country	string	No	Country
notes	string	No	Notes
tags	string[]	No	Tags
source_id	uuid	No	Lead source
custom_fields	object	No	Custom field values

curl -X POST https://api.driftwoodapp.com/api/contacts-create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "company_id": "660e8400-e29b-41d4-a716-446655440001",
    "tags": ["prospect"]
  }'

Update Contact

Partial updates — only include fields you want to change.

Endpoint: contacts-update

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

curl -X POST https://api.driftwoodapp.com/api/contacts-update \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tags": ["vip", "enterprise"],
    "job_title": "CTO"
  }'

Delete Contact

Endpoint: contacts-delete

Field	Type	Required	Description
id	uuid	Yes	Contact ID

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

Response:

{
  "ok": true,
  "result": {
    "deleted": true
  }
}

Error Codes

Code	Description
contacts.invalid_request	Malformed request body
contacts.invalid_id	Invalid UUID format
contacts.not_found	Contact does not exist
contacts.first_name_required	First name is required for creation
contacts.invalid_company_id	Referenced company does not exist
contacts.invalid_source_id	Referenced source does not exist
contacts.invalid_custom_fields	Custom field values don’t match definitions
contacts.internal	Server error