Contacts

Quick Overview

List, view, create, update, delete, and bulk delete contacts through the Public API.

List Contacts

GET /v1/contacts

List all contacts with pagination, search, and filtering.

Query Parameters

Parameter	Type	Default	Description
searchParam	string	-	Search term for name, email, phone, or custom fields.
pageNumber	integer	1	Page number.
pageSize	integer	-	Number of results per page.
sortBy	string	-	Sort order: asc or desc.
labelIds	string or array	-	Filter by label IDs. Can be a single value or comma-separated/list.
channelTypes	string or array	-	Filter by channel types (platform types). Can be comma-separated/list.
filterOperator	string	-	Operator for label/channel filters: AND or OR. Defaults to combined logic as implemented.

Response

{
  "contacts": [
    {
      "id": "contact_abc123",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+1234567890",
      "labels": [],
      "channels": [],
      "customFields": []
    }
  ],
  "count": 1,
  "hasMore": false
}

Get a Contact

GET /v1/contacts/{contactId}

Get details for a single contact.

Path Parameters

Parameter	Type	Required	Description
contactId	string	Yes	Contact ID.

Response

{
  "contact": {
    "id": "contact_abc123",
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+1234567890",
    "labels": [],
    "channels": [],
    "customFields": []
  }
}

Errors

Status	Error Code	Description
404	ERR_CONTACT_NOT_FOUND	Contact not found.

Create a Contact

POST /v1/contacts

Create a new contact.

Request Body

{
  "name": "John Doe",
  "phone": "+1234567890",
  "email": "[email protected]",
  "channels": [
    {
      "platform": "WHATSAPP",
      "identifier": "+1234567890"
    }
  ],
  "customFields": [
    {
      "name": "company",
      "value": "Acme Corp"
    }
  ]
}

Field	Type	Required	Description
name	string	Yes	Contact name (minimum 2 characters).
phone	string	Yes	Phone number.
email	string	No	Email address.
channels	array	No	Channel identifiers to link.
channels[].platform	string	Yes	Platform type.
channels[].identifier	string	Yes	Channel identifier.
customFields	array	No	Custom fields.
customFields[].name	string	Yes	Field name.
customFields[].value	string	Yes	Field value.

Response

{
  "contact": {
    "id": "contact_abc123",
    "name": "John Doe",
    "phone": "+1234567890"
  }
}

Errors

Status	Error Code	Description
400	Validation errors	Invalid input.
409	ERR_CONTACT_ALREADY_EXISTS	Contact already exists.

Update a Contact

PUT /v1/contacts/{contactId}

Update an existing contact.

Path Parameters

Parameter	Type	Required	Description
contactId	string	Yes	Contact ID.

Request Body

{
  "name": "John Smith",
  "email": "[email protected]",
  "channels": [],
  "customFields": [],
  "labels": [
    {
      "labelSlug": "vip"
    }
  ]
}

Field	Type	Required	Description
name	string	No	Contact name (minimum 2 characters).
phone	string	No	Phone number.
email	string	No	Email address.
channels	array	No	Channel identifiers to link.
customFields	array	No	Custom fields.
labels	array	No	Labels to assign by slug.

Response

{
  "contact": {
    "id": "contact_abc123",
    "name": "John Smith"
  }
}

Errors

Status	Error Code	Description
400	Validation errors	Invalid input.
404	ERR_CONTACT_NOT_FOUND	Contact not found.

Delete a Contact

DELETE /v1/contacts/{contactId}

Delete a single contact.

Path Parameters

Parameter	Type	Required	Description
contactId	string	Yes	Contact ID.

Response

{
  "message": "Contact deleted successfully"
}

Errors

Status	Error Code	Description
404	ERR_CONTACT_NOT_FOUND	Contact not found.

Bulk Delete Contacts

DELETE /v1/contacts

Delete multiple contacts at once.

Request Body

{
  "contactIds": ["contact_abc123", "contact_def456"]
}

Field	Type	Required	Description
contactIds	array	Yes	List of contact IDs to delete (minimum 1).

Response

{
  "message": "Contacts deleted successfully"
}

Errors

Status	Error Code	Description
400	Validation errors	contactIds required or empty.
404	ERR_CONTACT_NOT_FOUND	One or more contacts not found.