Contact Service

The Contact Service allows you to manage contacts in your workspace. You can create, read, update and delete contacts, and list or search them with filters on any field, including your own custom fields.

Create Contact

Create a new contact in your workspace.

POST /contact

Request Body

Field	Type	Required	Description
first_name	string	No	Contact’s first name
last_name	string	No	Contact’s last name
phone	string	Yes	Contact’s phone number in E.164 format (e.g., +1234567890)
email	string	No	Contact’s email address
additional_notes	string	No	Additional notes about the contact
custom_fields	object	No	Custom field values keyed by the custom field keys defined in your workspace (Portal → Contacts → Custom Fields). Values are validated against each field definition; entries with unknown, archived, or reserved keys — or values failing type validation — are dropped and reported in `custom_field_warnings` (the contact is still created). Stored values can be referenced in agent prompts as `{{custom.<key>}}`.

Example Request

{
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+1234567890",
  "email": "john@example.com",
  "additional_notes": "VIP customer",
  "custom_fields": {
    "account_tier": "gold",
    "renewal_date": "2026-09-01"
  }
}

Response

{
  "status": 201,
  "data": {
    "id": "contact-123",
    "created_at": "2024-03-20T10:00:00Z",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890",
    "email": "john@example.com",
    "additional_notes": "VIP customer",
    "status": "active",
    "updated_at": "2024-03-20T10:00:00Z",
    "workspace_id": "workspace-123",
    "custom_fields": {
      "account_tier": "gold",
      "renewal_date": "2026-09-01"
    }
  }
}

If any custom_fields entries were dropped during validation, the response includes a top-level custom_field_warnings array describing each drop (codes: unknown_key, archived_key, reserved_key, type_mismatch, option_invalid, too_long, empty_value).

Get Contact

Retrieve a specific contact by ID.

GET /contact/{id}

Parameters

Parameter	Type	Required	Description
id	string	Yes	The ID of the contact to retrieve

Response

{
  "id": "contact-123",
  "created_at": "2024-03-20T10:00:00Z",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+1234567890",
  "email": "john@example.com",
  "additional_notes": "VIP customer",
  "status": "active",
  "updated_at": "2024-03-20T10:00:00Z",
  "workspace_id": "workspace-123",
  "custom_fields": {
    "account_tier": "gold",
    "renewal_date": "2026-09-01"
  }
}

List Contacts

Use this to page through your contacts, look someone up by name or phone, or read everyone on one list. For filters on any field, use Search Contacts instead.

GET /contact?q=maria&list_id={listId}&limit=50&offset=0

Query Parameters

Parameter	Type	Required	Description
q	string	No	Matches first and last name and email in any case, and phone digits when it looks like a phone number, so `(415) 555` finds `+14155550101`.
list_id	string	No	Only contacts on this list.
limit	integer	No	Rows per page, 1 to 200. Default 50.
offset	integer	No	Rows to skip. Pass `next_offset` from the previous page. Default 0.

Contacts come newest first. The response has the same shape as Search Contacts below.

Search Contacts

Use this when you need a group of contacts that share something: everyone over 50 with Aetna insurance, everyone opted out, everyone added in the last 30 days who is not on a list yet. This is the same search the contacts page runs when you add filters, so an AI agent or your own code can pull exactly the people a person would see.

POST /contacts/search

Request Body

Field	Type	Required	Description
q	string	No	Free text, matched like `q` above.
list_id	string	No	Only contacts on this list.
filters	array	No	Up to 50 conditions, each `{ "field", "op", "value" }`. A contact must meet all of them.
sort	array	No	Up to 5 `{ "field", "dir" }` entries, `dir` being `asc` (default) or `desc`. Empty values always come last. Default is newest first.
page	object	No	`{ "offset", "limit" }`. `limit` is 1 to 200, default 50.

field is a key from List Contact Fields: one of the core fields name, phone, email, lists, status, created_at and timezone, or the key of one of your custom fields.

Conditions by field type

Field type	Conditions (`op`)	What `value` looks like
Number	`is`, `gt`, `gte`, `lt`, `lte`, `between`, `empty`, `not_empty`	`50`, or `[18, 65]` for `between`
Date, datetime	`is`, `before`, `after`, `between`, `last_days`, `empty`, `not_empty`	`"2026-10-12"`, `["2026-01-01", "2026-03-31"]` for `between`, `30` for `last_days`
Choice (select, and `status`)	`any_of`, `none_of`, `empty`, `not_empty`	`["Aetna", "Cigna"]`
Multiple choice (multi select, and `lists`)	`any_of`, `all_of`, `none_of`, `empty`, `not_empty`	`["recall", "vip"]`; list ids for `lists`
Text, long text, email, URL, phone	`contains`, `is`, `empty`, `not_empty`	`"maria"`
Yes or no	`is`	`true` or `false`

Dates are compared by calendar day in UTC. status is opted_out when the contact’s phone or email is on your do not contact list, and blocked when the contact is blocked. Leave value out for empty and not_empty.

Example Request

Everyone over 50 whose insurance is Aetna, oldest first:

{
  "filters": [
    { "field": "age", "op": "gt", "value": 50 },
    { "field": "insurance", "op": "any_of", "value": ["Aetna"] }
  ],
  "sort": [{ "field": "age", "dir": "desc" }],
  "page": { "offset": 0, "limit": 50 }
}

Response

{
  "status": 200,
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "first_name": "Maria",
      "last_name": "Garcia",
      "phone": "+14155550101",
      "email": "maria@example.com",
      "additional_notes": null,
      "timezone": "America/Los_Angeles",
      "is_blocked": false,
      "opted_out": false,
      "lists": [{ "id": "3f2b8c1e-5d4a-4b6f-9e2a-7c1d0b8a9f33", "name": "Recall due" }],
      "last_call": {
        "id": "8a1c2e4f-6b3d-4f7a-9c0e-1d2b3a4c5e6f",
        "created_at": "2026-10-10T15:04:00.000Z",
        "direction": "outbound",
        "status": "completed"
      },
      "custom_fields": { "age": 54, "insurance": "Aetna" },
      "created_at": "2026-09-01T10:00:00.000Z",
      "updated_at": "2026-10-01T10:00:00.000Z"
    }
  ],
  "total": 1284,
  "next_offset": 50
}

To read every match, keep sending the same request with page.offset set to next_offset until next_offset is null. total is how many contacts match across all pages.

When a request is wrong

A field that does not exist, a condition the field does not allow, or a value of the wrong kind returns 400 with error_code validation_failed and a message that says what to send instead:

{
  "status": 400,
  "error_code": "validation_failed",
  "message": "Filter 1: \"Age\" is a number field, so the condition must be one of: is, gt, gte, lt, lte, between, empty, not_empty.",
  "details": { "field": "age", "op": "has", "allowed": ["is", "gt", "gte", "lt", "lte", "between", "empty", "not_empty"] }
}

List Contact Fields

Use this before building a search: it lists every field a contact has, what type it is, which conditions it accepts, and its choices.

GET /contacts/fields

Response

{
  "status": 200,
  "data": [
    {
      "key": "name",
      "label": "Name",
      "type": "text",
      "source": "core",
      "conditions": ["contains", "is", "empty", "not_empty"],
      "sortable": true,
      "editable": true,
      "description": "First and last name together."
    },
    {
      "key": "insurance",
      "label": "Insurance",
      "type": "select",
      "source": "custom",
      "conditions": ["any_of", "none_of", "empty", "not_empty"],
      "sortable": true,
      "editable": true,
      "options": [
        { "value": "Aetna", "label": "Aetna" },
        { "value": "Cigna", "label": "Cigna" }
      ],
      "filled_by": "person"
    }
  ]
}

Core fields come first, then your custom fields in the order you set. filled_by is agent for fields your agent fills in after calls. To add or change custom fields, see Custom Fields; to manage lists, see Lists.

Update Contact

Update an existing contact.

PUT /contact/{id}

Parameters

Parameter	Type	Required	Description
id	string	Yes	The ID of the contact to update

Request Body

Field	Type	Required	Description
first_name	string	No	Contact’s first name
last_name	string	No	Contact’s last name
phone	string	No	Contact’s phone number in E.164 format
email	string	No	Contact’s email address
additional_notes	string	No	Additional notes about the contact
custom_fields	object	No	Custom field values to merge onto the contact. Merge semantics: keys you send are validated and written, keys you omit are left untouched, and a key set to `null` is removed. Unknown/archived/reserved keys and values failing type validation are dropped and reported in `custom_field_warnings` (the rest of the update still applies).

Example Request

{
  "first_name": "John",
  "last_name": "Smith",
  "phone": "+1987654321",
  "email": "john.smith@example.com",
  "additional_notes": "Updated VIP customer",
  "custom_fields": {
    "account_tier": "platinum",
    "renewal_date": null
  }
}

Response

{
  "status": 200,
  "data": {
    "id": "contact-123",
    "created_at": "2024-03-20T10:00:00Z",
    "first_name": "John",
    "last_name": "Smith",
    "phone": "+1987654321",
    "email": "john.smith@example.com",
    "additional_notes": "Updated VIP customer",
    "status": "active",
    "updated_at": "2024-03-20T11:00:00Z",
    "workspace_id": "workspace-123",
    "custom_fields": {
      "account_tier": "platinum"
    }
  }
}

As with Create, if any custom_fields entries were dropped during validation the response includes a top-level custom_field_warnings array describing each drop.

Delete Contact

Delete a contact from your workspace.

DELETE /contact/{id}

Parameters

Parameter	Type	Required	Description
id	string	Yes	The ID of the contact to delete

Response

{
  "status": 200,
  "message": "Contact deleted successfully"
}

Delete Contacts

Delete up to 500 contacts at once. This can’t be undone. Each contact is deleted the same way as DELETE /contact/{id}: its details and the values in its history are removed, and its history keeps one entry saying who deleted it and when.

POST /contacts/bulk-delete

Request Body

Field	Type	Required	Description
ids	string[]	Yes	The contact ids to delete, 1 to 500. Duplicates are ignored.

Example Request

{
  "ids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "3f2b8c1e-5d4a-4b6f-9e2a-7c1d0b8a9f33"
  ]
}

Response

{
  "status": 200,
  "deleted": 1,
  "deleted_ids": ["123e4567-e89b-12d3-a456-426614174000"],
  "not_found": ["3f2b8c1e-5d4a-4b6f-9e2a-7c1d0b8a9f33"]
}

not_found lists ids with no contact in your workspace (already deleted, or never there), so sending the same request again is safe. To delete everyone matching a search, page through POST /contacts/search and send the ids in batches of up to 500. A wrong request (no ids, an id that isn’t a contact id, or more than 500) returns 400 with error_code: "validation_failed" and a message saying what to fix.

Endpoints

Agents

MCP server

Agent pairing

Webhooks

Contact

Contact Service

Create Contact

Request Body

Example Request

Response

Get Contact

Parameters

Response

List Contacts

Query Parameters

Search Contacts

Request Body

Conditions by field type

Example Request

Response

When a request is wrong

List Contact Fields

Response

Update Contact

Parameters

Request Body

Example Request

Response

Delete Contact

Parameters

Response

Delete Contacts

Request Body

Example Request

Response

​Contact Service

​Create Contact

​Request Body

​Example Request

​Response

​Get Contact

​Parameters

​Response

​List Contacts

​Query Parameters

​Search Contacts

​Request Body

​Conditions by field type

​Example Request

​Response

​When a request is wrong

​List Contact Fields

​Response

​Update Contact

​Parameters

​Request Body

​Example Request

​Response

​Delete Contact

​Parameters

​Response

​Delete Contacts

​Request Body

​Example Request

​Response

Contact Service

Create Contact

Request Body

Example Request

Response

Get Contact

Parameters

Response

List Contacts

Query Parameters

Search Contacts

Request Body

Conditions by field type

Example Request

Response

When a request is wrong

List Contact Fields

Response

Update Contact

Parameters

Request Body

Example Request

Response

Delete Contact

Parameters

Response

Delete Contacts

Request Body

Example Request

Response