Contact Service

The Contact Service allows you to manage contacts in your workspace. You can create, read, update, and delete contacts.

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"
  }
}

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"
}

​Contact Service

​Create Contact

​Request Body

​Example Request

​Response

​Get Contact

​Parameters

​Response

​Update Contact

​Parameters

​Request Body

​Example Request

​Response

​Delete Contact

​Parameters

​Response

Contact Service

Create Contact

Request Body

Example Request

Response

Get Contact

Parameters

Response

Update Contact

Parameters

Request Body

Example Request

Response

Delete Contact

Parameters

Response