API Reference

Contacts

Manage contacts scoped to your company. Every contact record belongs to a user in your company; the API exposes a company-wide view automatically.

GET /contacts

List all contacts for your company, ordered by last contact date.

Requires contacts:read

Query parameters

Name	Type	Required	Description
`limit`	integer	optional	Max results to return (default 20, max 100)
`startKey`	string	optional	Pagination cursor from a previous response

Response

{
  "operation": "listContacts",
  "filterType": "COMPANY",
  "contacts": [
    {
      "contactId": "dc9e8a9f-2222-4537-a4bf-abb047049359",
      "name": "Sarah Chen",
      "email": "sarah.chen@lumiere-boutique.com",
      "phone": "+14155550192",
      "source": "manual",
      "createdAt": "2026-05-10T09:12:00Z",
      "updatedAt": "2026-06-20T14:30:00Z",
      "lastContactDate": "2026-06-20T14:30:00Z",
      "metadata": {
        "notes": "West Coast boutique owner.",
        "tags": [],
        "customFields": {}
      }
    }
  ],
  "nextKey": "eyJQSyI6...",
  "count": 20
}

POST /contacts

Create a new contact. A contact must have at least a name.

Requires contacts:write

Request body

{
  "name": "Sarah Chen",
  "email": "sarah.chen@lumiere-boutique.com",
  "phone": "+1 415 555 0192",
  "metadata": {
    "notes": "Met at Paris showroom"
  }
}

Response

{
  "operation": "createContact",
  "contact": {
    "contactId": "dc9e8a9f-2222-4537-a4bf-abb047049359",
    "name": "Sarah Chen",
    "email": "sarah.chen@lumiere-boutique.com",
    "phone": "+14155550192",
    "createdAt": "2026-06-25T10:00:00Z"
  }
}

GET /contacts/{contactId}

Fetch a single contact by ID. Includes linked email thread IDs.

Requires contacts:read

Response

{
  "operation": "getContact",
  "contact": {
    "contactId": "dc9e8a9f-2222-4537-a4bf-abb047049359",
    "name": "Sarah Chen",
    "email": "sarah.chen@lumiere-boutique.com",
    "phone": "+14155550192",
    "emailThreads": [
      "55274d36-7b41-486c-ab88-4b55f25f7fe1"
    ],
    "scheduledAppointments": [],
    "metadata": { "notes": "", "tags": [], "customFields": {} }
  }
}

PUT /contacts/{contactId}

Update a contact's fields. Only the fields you send are changed.

Requires contacts:write

Request body

{
  "name": "Sarah Chen-Walters",
  "metadata": {
    "notes": "Attended AW26 showroom in London"
  }
}

Response

{
  "operation": "updateContact",
  "contact": { "contactId": "dc9e8a9f-...", "name": "Sarah Chen-Walters", "..." }
}

GET /contacts/search/email

Find a contact by email address.

Requires contacts:read

Query parameters

Name	Type	Required	Description
`email`	string	required	Email address to look up

Response

{
  "operation": "findContactByEmail",
  "contact": { "contactId": "...", "name": "Sarah Chen", "email": "sarah.chen@lumiere-boutique.com" }
}

GET /contacts/search/phone

Find a contact by phone number. The number is normalised before lookup.

Requires contacts:read

Query parameters

Name	Type	Required	Description
`phone`	string	required	Phone number (any format, e.g. +1 415 555 0192)

Response

{
  "operation": "findContactByPhone",
  "contact": { "contactId": "...", "name": "Sarah Chen", "phone": "+14155550192" }
}