Skip to main content

Contacts API

Beta

The Contacts API is currently in beta. If you would like to join the beta, please contact us.

The Contacts API allows you to manage contacts in your workspace, including their custom field values, contact list membership, notes, and bulk import operations.

See the authentication page for how to obtain a bearer token. All endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <token>

JSON Field Casing

All response bodies use snake_case field names. Request bodies and query parameters also use snake_case, with request bodies additionally accepting camelCase for backward compatibility.

Error Responses

All endpoints return errors in a consistent format:

{
"error": {
"message": "401 UNAUTHORIZED",
"details": "Unauthorized access."
}
}

Validation errors (422) include a structured errors array inside details:

{
"error": {
"message": "422 UNPROCESSABLE ENTITY",
"details": {
"errors": [
{
"type": "missing",
"in": "body",
"field": "name",
"msg": "Field required"
}
]
}
}
}

Common error status codes:

StatusMeaning
400Bad request -- invalid or missing data
401Unauthorized -- invalid or missing token
404Not found -- resource does not exist
422Unprocessable entity -- validation error
500Internal server error

Pagination

Endpoints that return lists accept limit and offset query parameters and include a pagination object in the response:

ParameterTypeDefaultMinMax
limitinteger501100
offsetinteger00--
{
"pagination": {
"limit": 50,
"offset": 0,
"total": 142
}
}

Contacts

List Contacts

Retrieve a paginated list of contacts in the workspace.

GET https://api.cuedesk.com/v1/contacts
Authorization: Bearer <token>

Query Parameters

NameTypeDefaultDescription
limitint50Page size (1-100)
offsetint0Number of items to skip
order_fieldstringcreated_atSort field: created_at, first_name, last_name, updated_at, external_contact_id
orderstringdescSort direction: asc or desc
contact_list_uuidUUID--Filter to contacts in a specific contact list

Response 200 OK

{
"contacts": [
{
"uuid": "ff0556cf-fbad-4d55-94cd-119bac9df2da",
"workspace_uuid": "ff027904-fdbc-4c30-a533-105d1c96e1cb",
"first_name": "Bruce",
"last_name": "Wayne",
"external_contact_id": "batman",
"email": "batman@example.com",
"phone_number": "1234567890",
"whatsapp_id": "1234567890",
"fb_messenger_id": "fb_12345",
"archived": false,
"created_at": "2025-12-10T10:31:34.353Z",
"updated_at": "2025-12-10T10:31:34.353Z",
"last_engaged_at": "2025-12-09T14:57:36Z",
"custom_fields": {
"date_of_birth": "1985-02-19",
"subscription": "Enterprise",
"is_verified": true,
"num_seats": 450
}
}
],
"pagination": {
"limit": 50,
"offset": 0,
"total": 1
}
}

Search Contacts

Advanced contact search with filtering, sorting, and pagination. Supports free-text search, field-level filters (including custom fields), and custom sort orders.

All request body fields are optional. An empty body {} returns all contacts (equivalent to List Contacts without filters).

POST https://api.cuedesk.com/v1/contacts/search
Authorization: Bearer <token>
Content-Type: application/json

Query Parameters

NameTypeDefaultDescription
limitint10Page size (1-100)
offsetint0Number of items to skip

Request Body

FieldTypeRequiredDescription
search_termstringNoFree-text search across default contact fields
advanced_searcharrayNoArray of filter objects (see below)
sort_byobjectNoSort configuration (see below)

Filter Object (advanced_search items)

FieldTypeRequiredDefaultDescription
fieldstringYes--Field name to filter on (predefined or custom field key)
operatorstringYes--Search operator (see table below)
valuestring or arrayNo--Value(s) to match. For range, provide [min, max]. Not needed for exists/not_exists
data_typestringNotextData type hint for custom fields: text, long, double, date, boolean

Search Operators

OperatorDescription
equalsExact match
not_equalsDoes not match
containsContains substring
not_containsDoes not contain substring
starts_withStarts with value
ends_withEnds with value
rangeWithin range (provide [min, max] as value)
gtGreater than
ltLess than
gteGreater than or equal to
lteLess than or equal to
existsField has a value (no value needed)
not_existsField has no value (no value needed)

Sort Object (sort_by)

FieldTypeRequiredDefaultDescription
fieldstringYes--Field name to sort by (predefined or custom field key)
sort_orderstringNoascSort direction: asc or desc
data_typestringNotextData type hint for custom fields: text, long, double, date, boolean

Predefined Fields

The following fields are predefined contact fields. Any field name not in this list is treated as a custom field key:

first_name, last_name, email, phone_number, whatsapp_id, fb_messenger_id, external_contact_id, client_reference, archived, created_at, updated_at, last_engaged_at

info

When filtering or sorting on custom fields, set data_type to match the custom field's type for correct results. For predefined fields, data_type is ignored.

Request Examples

{
"search_term": "john"
}

Response 200 OK

{
"contacts": [
{
"uuid": "ff0556cf-fbad-4d55-94cd-119bac9df2da",
"workspace_uuid": "ff027904-fdbc-4c30-a533-105d1c96e1cb",
"first_name": "Bruce",
"last_name": "Wayne",
"external_contact_id": "batman",
"email": "batman@example.com",
"phone_number": "1234567890",
"whatsapp_id": "1234567890",
"fb_messenger_id": "fb_12345",
"archived": false,
"created_at": "2025-12-10T10:31:34.353Z",
"updated_at": "2025-12-10T10:31:34.353Z",
"last_engaged_at": "2025-12-09T14:57:36Z",
"custom_fields": {
"date_of_birth": "1985-02-19",
"subscription": "Enterprise",
"is_verified": true,
"num_seats": 450
}
}
],
"pagination": {
"limit": 10,
"offset": 0,
"total": 1
}
}

Create a Contact

Create a new contact in the workspace.

info

At least one identifier field (external_contact_id, email, phone_number, whatsapp_id, or fb_messenger_id) is required.

POST https://api.cuedesk.com/v1/contacts
Authorization: Bearer <token>
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
first_namestringNoFirst name
last_namestringNoLast name
external_contact_idstringNo*External system identifier
emailstringNo*Email address
phone_numberstringNo*Phone number
whatsapp_idstringNo*WhatsApp identifier
fb_messenger_idstringNo*Facebook Messenger identifier
custom_fieldsobjectNoObject mapping custom field keys to values

Example

{
"first_name": "Bruce",
"last_name": "Wayne",
"email": "batman@example.com",
"phone_number": "1234567890",
"custom_fields": {
"date_of_birth": "1985-02-19"
}
}

Response 201 Created

Returns the created Contact object (same shape as in List Contacts).


Get a Contact

Retrieve a single contact by UUID.

GET https://api.cuedesk.com/v1/contacts/{contact_uuid}
Authorization: Bearer <token>

Response 200 OK

Returns a single Contact object.


Update a Contact

Partially update a contact. Only include the fields you want to change.

PATCH https://api.cuedesk.com/v1/contacts/{contact_uuid}
Authorization: Bearer <token>
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
first_namestringNoFirst name
last_namestringNoLast name
external_contact_idstringNoExternal system identifier
emailstringNoEmail address
phone_numberstringNoPhone number
whatsapp_idstringNoWhatsApp identifier
fb_messenger_idstringNoFacebook Messenger identifier
custom_fieldsobjectNoObject mapping custom field keys to values

Example

{
"first_name": "Bruce",
"last_name": "Wayne-Kent",
"custom_fields": {
"date_of_birth": "1985-02-19"
}
}

Response 200 OK

Returns the updated Contact object.


Bulk Create Contacts

Create up to 1,000 contacts in a single request. This operation is asynchronous -- contacts are imported via a background pipeline. The response contains a contact_import_uuid that can be used to track progress.

POST https://api.cuedesk.com/v1/contacts/bulk
Authorization: Bearer <token>
Content-Type: application/json

Request Body

FieldTypeRequiredDefaultDescription
contactsarrayYes--Array of contact objects (1-1000 items)
contact_list_uuidUUIDNo--Add all contacts to this contact list
match_on_fieldstringNo--Field to match existing contacts: email, phone_number, or external_contact_id
merge_typestringNocreate_or_updateMerge strategy (see below)

Contact Object

Each item in the contacts array accepts the same fields as Create a Contact. No identifier validation is enforced at the gateway level -- the upstream import pipeline handles per-contact validation.

Merge Strategies

ValueBehaviour
create_or_updateCreate new contacts or update existing ones matched by match_on_field
createOnly create new contacts; skip existing matches
updateOnly update existing contacts matched by match_on_field; skip new ones

Example

{
"contact_list_uuid": "ff234212-c92e-4f33-9350-297887ca11de",
"contacts": [
{
"first_name": "Bruce",
"last_name": "Wayne",
"email": "batman@example.com",
"phone_number": "1234567890",
"custom_fields": {
"date_of_birth": "1985-02-19"
}
},
{
"first_name": "Clark",
"last_name": "Kent",
"email": "clark.kent@dailyplanet.com",
"phone_number": "9876543210"
}
],
"match_on_field": "email",
"merge_type": "create_or_update"
}

Response 202 Accepted

{
"contact_import_uuid": "ff28a1b2-c3d4-5e6f-7a8b-9c0d1e2f3a4b"
}

Get Contact Import Status

Check the status and progress of a bulk contact import.

GET https://api.cuedesk.com/v1/contacts/bulk/{contact_import_uuid}
Authorization: Bearer <token>

Response 200 OK

{
"contact_import_uuid": "ff28a1b2-c3d4-5e6f-7a8b-9c0d1e2f3a4b",
"status": "completed",
"summary": {
"total": 2,
"created": 1,
"failed": 1
}
}

Status Values

ValueDescription
pendingImport has been queued but not yet started
processingImport is currently being processed
completedImport has finished (may include partial failures)
failedImport failed entirely

Summary Fields

FieldTypeDescription
totalintTotal number of rows in the import
createdintNumber of contacts successfully created or updated
failedintNumber of contacts that failed to import

Contact Custom Fields

Manage custom field values on individual contacts.

List Contact Custom Fields

Get all custom field values for a contact.

GET https://api.cuedesk.com/v1/contacts/{contact_uuid}/custom-fields
Authorization: Bearer <token>

Response 200 OK

{
"custom_fields": {
"date_of_birth": "1985-02-19",
"subscription": "Enterprise",
"is_verified": true,
"num_seats": 450
}
}

Values can be strings, numbers, booleans, arrays, or objects depending on the custom field type.


Add a Custom Field to a Contact

Set a single custom field value on a contact.

POST https://api.cuedesk.com/v1/contacts/{contact_uuid}/custom-fields
Authorization: Bearer <token>
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
custom_field_uuidUUIDYesThe custom field definition UUID
valueanyYesThe value to set (can be null to clear)

Example

{
"custom_field_uuid": "ff24cdaf-f0a1-4db9-ba47-109f6d663544",
"value": "1985-02-19"
}

Response 201 Created

Returns the full custom_fields object for the contact (same shape as List Contact Custom Fields).


Update Contact Custom Fields

Update multiple custom field values on a contact at once.

PATCH https://api.cuedesk.com/v1/contacts/{contact_uuid}/custom-fields
Authorization: Bearer <token>
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
custom_fieldsobjectYesObject mapping custom field keys to their new values

Example

{
"custom_fields": {
"date_of_birth": "1990-01-15",
"subscription": "Startup"
}
}

Response 200 OK

Returns the full custom_fields object for the contact.


Delete a Custom Field from a Contact

Remove a custom field value from a contact.

DELETE https://api.cuedesk.com/v1/contacts/{contact_uuid}/custom-fields/{custom_field_uuid}
Authorization: Bearer <token>

Response 204 No Content

No response body.


Contact Lists

List Contact Lists

Retrieve a paginated list of contact lists in the workspace.

GET https://api.cuedesk.com/v1/contact-lists
Authorization: Bearer <token>

Query Parameters

NameTypeDefaultDescription
limitint50Page size (1-100)
offsetint0Number of items to skip
statusstringactiveFilter by status: active or archived
sort_orderstringascSort direction: asc or desc
sort_fieldstringnameSort field: name or created_at
searchstring--Search contact lists by name

Response 200 OK

{
"contact_lists": [
{
"uuid": "ff234212-c92e-4f33-9350-297887ca11de",
"name": "VIP Customers",
"status": "active",
"emoji": "\u2b50",
"workspace_uuid": "ff027904-fdbc-4c30-a533-105d1c96e1cb",
"count": 42,
"created_by": "ff027904-fdbc-4c30-a533-105d1c96e1cb",
"updated_by": "ff027904-fdbc-4c30-a533-105d1c96e1cb",
"created_at": "2025-12-10T11:08:38.055790Z",
"updated_at": "2025-12-10T11:08:47.852679Z"
}
],
"pagination": {
"limit": 50,
"offset": 0,
"total": 1
}
}

Create a Contact List

Create a new contact list in the workspace.

POST https://api.cuedesk.com/v1/contact-lists
Authorization: Bearer <token>
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
namestringYesContact list name
emojistringNoUnicode emoji

Example

{
"name": "VIP Customers",
"emoji": "\u2b50"
}

Response 201 Created

Returns the created ContactList object (same shape as in List Contact Lists).


Get a Contact List

Retrieve a single contact list by UUID.

GET https://api.cuedesk.com/v1/contact-lists/{contact_list_uuid}
Authorization: Bearer <token>

Response 200 OK

Returns a single ContactList object.


Update a Contact List

Partially update a contact list. Only include the fields you want to change.

PATCH https://api.cuedesk.com/v1/contact-lists/{contact_list_uuid}
Authorization: Bearer <token>
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
namestringNoContact list name
emojistringNoUnicode emoji

Example

{
"name": "Premium VIP Customers",
"emoji": "\ud83d\udc8e"
}

Response 200 OK

Returns the updated ContactList object.


Delete a Contact List

Delete a contact list.

DELETE https://api.cuedesk.com/v1/contact-lists/{contact_list_uuid}
Authorization: Bearer <token>

Response 204 No Content

No response body.


Contact List Membership

Manage which contacts belong to which contact lists.

List Contacts in a Contact List

Retrieve a paginated list of contacts that belong to a contact list.

GET https://api.cuedesk.com/v1/contact-lists/{contact_list_uuid}/contacts
Authorization: Bearer <token>

Query Parameters

NameTypeDefaultDescription
limitint50Page size (1-100)
offsetint0Number of items to skip
include_archivedbooleanfalseInclude archived contacts

Response 200 OK

Returns a contacts array and pagination object (same shape as List Contacts).


Add Contacts to a Contact List

Add one or more contacts to a contact list.

POST https://api.cuedesk.com/v1/contact-lists/{contact_list_uuid}/contacts
Authorization: Bearer <token>
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
contact_uuidsarray[UUID]YesUUIDs of contacts to add (1-100 items)

Example

{
"contact_uuids": [
"ff0556cf-fbad-4d55-94cd-119bac9df2da",
"ff1667df-acde-4e66-a5de-220cbe916e2b"
]
}

Response 201 Created

{
"message": "Contacts successfully added to contact list.",
"added": [
"ff0556cf-fbad-4d55-94cd-119bac9df2da",
"ff1667df-acde-4e66-a5de-220cbe916e2b"
],
"warnings": []
}
FieldTypeDescription
messagestringSuccess message
addedarray[UUID]UUIDs of contacts that were successfully added
warningsarrayList of warning objects with uuid and message for contacts that could not be added

Remove Contacts from a Contact List

Remove one or more contacts from a contact list.

DELETE https://api.cuedesk.com/v1/contact-lists/{contact_list_uuid}/contacts
Authorization: Bearer <token>

Request Body

FieldTypeRequiredDescription
contact_uuidsarray[UUID]YesUUIDs of contacts to remove (1-100 items)

Example

{
"contact_uuids": [
"ff0556cf-fbad-4d55-94cd-119bac9df2da"
]
}

Response 204 No Content

No response body.


Get Contact Lists for a Contact

List all contact lists that contain a specific contact.

GET https://api.cuedesk.com/v1/contacts/{contact_uuid}/contact-lists
Authorization: Bearer <token>

Query Parameters

NameTypeDefaultDescription
limitint50Page size (1-100)
offsetint0Number of items to skip
statusstring--Filter by status: active or archived

Response 200 OK

Returns a contact_lists array and pagination object (same shape as List Contact Lists).


Custom Fields

Manage workspace-level custom field definitions. These define the schema for custom fields that can be assigned to contacts (see Contact Custom Fields for managing values on individual contacts).

Field Types

Custom fields support the following types:

TypeDescription
textSingle-line text
number:integerWhole number
number:decimalDecimal number
number:percentagePercentage value
checkboxBoolean checkbox
dateDate only
date:date_timeDate and time
date:timeTime only
date:relativeRelative date
selectSingle-select dropdown
multiselectMulti-select dropdown
userUser reference
info

For select and multiselect types, select_options must be provided with at least one option.


List Custom Fields

Retrieve a paginated list of custom field definitions in the workspace.

GET https://api.cuedesk.com/v1/custom-fields
Authorization: Bearer <token>

Query Parameters

NameTypeDefaultDescription
limitint50Page size (1-100)
offsetint0Number of items to skip

Response 200 OK

{
"custom_fields": [
{
"uuid": "ff24cdaf-f0a1-4db9-ba47-109f6d663544",
"workspace_uuid": "ff027904-fdbc-4c30-a533-105d1c96e1cb",
"name": "Revenue",
"icon": null,
"field_type": "number:integer",
"field_key": "revenue",
"status": "active",
"created_at": "2025-12-10T10:31:34.353Z",
"updated_at": "2025-12-10T10:31:34.353Z",
"archived_at": null,
"editable": true,
"sensitive": false
},
{
"uuid": "ff35debc-a1b2-4c3d-be58-210e7d774655",
"workspace_uuid": "ff027904-fdbc-4c30-a533-105d1c96e1cb",
"name": "Priority",
"icon": "star",
"field_type": "select",
"field_key": "priority",
"status": "active",
"created_at": "2025-12-11T08:15:00.000Z",
"updated_at": "2025-12-11T08:15:00.000Z",
"archived_at": null,
"editable": true,
"sensitive": false,
"select_options": [
{ "uuid": "opt-uuid-1", "display_label": "Low", "field_key": "low", "archived": false },
{ "uuid": "opt-uuid-2", "display_label": "Medium", "field_key": "medium", "archived": false },
{ "uuid": "opt-uuid-3", "display_label": "High", "field_key": "high", "archived": false }
]
}
],
"pagination": {
"limit": 50,
"offset": 0,
"total": 2
}
}
info

The select_options field is only present on custom fields with field_type of select or multiselect. It is omitted entirely for all other field types.


Create a Custom Field

Create a new custom field definition in the workspace.

POST https://api.cuedesk.com/v1/custom-fields
Authorization: Bearer <token>
Content-Type: application/json

Request Body

FieldTypeRequiredDefaultDescription
namestringYes--Field name (3-250 characters)
field_typestringYes--One of the field types listed above
field_keystringNonullUnique key identifier for the custom field
editablebooleanNotrueWhether the field value can be edited on contacts
sensitivebooleanNofalseWhether the field contains sensitive data
iconstringNonullIcon identifier
select_optionsarray[string]NonullList of option labels
danger

If field_key is omitted, a value will be generated from name. The field_key cannot be changed after creation.

info

select_options is required and must be non-empty when field_type is select or multiselect.

Example

{
"name": "Priority",
"field_type": "select",
"field_key": "priority",
"editable": true,
"icon": "star",
"select_options": ["Low", "Medium", "High"]
}

Response 201 Created

Returns the created CustomField object (same shape as in List Custom Fields).


Get a Custom Field

Retrieve a single custom field definition by UUID.

GET https://api.cuedesk.com/v1/custom-fields/{custom_field_uuid}
Authorization: Bearer <token>

Response 200 OK

Returns a single CustomField object.


Update a Custom Field

Update a custom field definition. All fields in the request body are required -- this endpoint expects the full object, not a partial update.

PATCH https://api.cuedesk.com/v1/custom-fields/{custom_field_uuid}
Authorization: Bearer <token>
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
namestringYesField name (3-250 characters)
field_typestringYesOne of the field types listed above
editablebooleanYesWhether the field value can be edited on contacts
sensitivebooleanYesWhether the field contains sensitive data
iconstringYesIcon identifier (use null to clear)
select_optionsarray[string]NoList of option labels
info

select_options is required and must be non-empty when field_type is select or multiselect.

Example

{
"name": "Updated Priority",
"field_type": "select",
"editable": true,
"sensitive": false,
"icon": "star",
"select_options": ["Low", "Medium", "High", "Critical"]
}

Response 200 OK

Returns the updated CustomField object.


Delete a Custom Field

Delete a custom field definition.

DELETE https://api.cuedesk.com/v1/custom-fields/{custom_field_uuid}
Authorization: Bearer <token>

Response 204 No Content

No response body.


Contact Notes

Manage notes attached to individual contacts.

List Contact Notes

Retrieve a paginated list of notes for a contact.

GET https://api.cuedesk.com/v1/contacts/{contact_uuid}/notes
Authorization: Bearer <token>

Query Parameters

NameTypeDefaultDescription
limitint50Page size (1-100)
offsetint0Number of items to skip

Response 200 OK

{
"notes": [
{
"uuid": "ff46efcd-b2c3-4d4e-cf69-321f8e885766",
"title": "Meeting Notes",
"content": {
"text": "Discussed project timeline and deliverables."
},
"created_at": "2025-12-10T09:00:00.000Z",
"updated_at": "2025-12-10T09:30:00.000Z",
"archived_at": null,
"status": "active"
}
],
"pagination": {
"limit": 50,
"offset": 0,
"total": 1
}
}

Create a Contact Note

Create a new note on a contact.

POST https://api.cuedesk.com/v1/contacts/{contact_uuid}/notes
Authorization: Bearer <token>
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
titlestringNoNote title
contentobjectYesNote content object
content.textstringYesText body of the note

Example

{
"title": "Meeting Notes",
"content": {
"text": "Discussed project timeline and deliverables."
}
}

Response 201 Created

Returns the created Note object (same shape as in List Contact Notes).


Get a Contact Note

Retrieve a single note by UUID.

GET https://api.cuedesk.com/v1/contacts/{contact_uuid}/notes/{note_uuid}
Authorization: Bearer <token>

Response 200 OK

Returns a single Note object.


Update a Contact Note

Replace a note entirely. This is a full replacement -- all fields in the request body are required.

PUT https://api.cuedesk.com/v1/contacts/{contact_uuid}/notes/{note_uuid}
Authorization: Bearer <token>
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
titlestringYesNote title
contentobjectYesNote content object
content.textstringYesText body of the note

Example

{
"title": "Updated Meeting Notes",
"content": {
"text": "Revised action items from the meeting."
}
}

Response 200 OK

Returns the updated Note object.


Delete a Contact Note

Delete a note from a contact.

DELETE https://api.cuedesk.com/v1/contacts/{contact_uuid}/notes/{note_uuid}
Authorization: Bearer <token>

Response 204 No Content

No response body.