List Contacts: Paginate and Filter Your Workspace

The List Contacts endpoint returns a paginated array of contact objects from your Workspace. You can narrow results using keyword search, filter by channel type, filter by specific inbox IDs, and control pagination and sort order. Each contact object includes full profile data, tags, custom fields, notes, inbox connections, and the most recent conversation.

GET /api/v1/contacts

Query Parameters

integer

Page number to retrieve. Must be between 1 and 9007199254740991. Defaults to 1.

integer

Number of contacts per page. Must be between 1 and 9007199254740991. Defaults to 20.

array of objects

Array of sort objects. Each object specifies a field and direction to sort by. Example: [{"field": "createdAt", "order": "desc"}].

string

Free-text search string. Matches against contact name, email, and phone number.

object

Advanced filter object for filtering contacts by tag, custom field value, subscription status, and other criteria.

array of strings

Filter contacts by the channels they are active on. Accepted values: omnichannel, webchat, messenger, whatsapp, zalo, smtp, telegram, instagram, tiktok.

array of strings

Filter contacts by specific inbox IDs. Each value must match the pattern \d+.

Code Examples

curl --request GET \
  --url "https://app.chatbotx.io/api/v1/contacts?page=1&perPage=20" \
  --header "Authorization: Bearer YOUR_API_TOKEN"

import requests

url = "https://app.chatbotx.io/api/v1/contacts"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}
params = {"page": 1, "perPage": 20}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const options = {
  method: 'GET',
  headers: { Authorization: 'Bearer YOUR_API_TOKEN' }
};

fetch('https://app.chatbotx.io/api/v1/contacts?page=1&perPage=20', options)
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));

Response Fields

array

required

Array of contact objects.

Show Contact object fields

string

required

Unique contact ID.

string (date-time)

required

Timestamp when the contact was created.

string (date-time)

required

Timestamp of the last update.

string | null

required

URL of the contact’s profile image.

string | null

required

Contact’s phone number.

string | null

required

Contact’s email address.

boolean

required

Whether the email address has been verified.

boolean

required

Whether the contact has opted in to email communications.

string | null

required

Contact’s first name.

string | null

required

Contact’s last name.

string | null

required

Contact’s full name (computed from first + last).

string | null

One of male, female, unknown.

string (date-time) | null

required

When the contact last read a message.

string | null

required

External reference identifier.

string | null

required

Contact’s country.

string | null

required

Contact’s state or region.

string | null

required

Contact’s city.

string | null

required

Contact’s locale string (e.g., en-US).

string | null

required

Contact’s timezone (e.g., America/New_York).

string (date-time) | null

required

When the contact subscribed.

string (date-time) | null

required

When the contact subscribed to broadcasts.

string (date-time) | null

required

When the contact was blocked, or null if not blocked.

string

required

ID of the Workspace this contact belongs to.

array

required

Array of custom field value objects assigned to the contact.

array

required

Array of tag objects applied to the contact.

array

required

Array of note objects attached to the contact.

array

required

Array of inbox connection objects showing which channels the contact is active on.

object | null

required

The most recent conversation object for this contact, or null.

number

required

Total number of pages available based on the current perPage value.

Example Response

{
  "data": [
    {
      "id": "clx1abc123",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "avatar": "https://example.com/avatar.jpg",
      "phoneNumber": "+84708123123",
      "email": "user@example.com",
      "emailVerified": true,
      "emailOptIn": true,
      "firstName": "Jane",
      "lastName": "Doe",
      "fullName": "Jane Doe",
      "lastReadAt": "2023-11-07T05:31:56Z",
      "ref": null,
      "country": "VN",
      "state": null,
      "city": "Ho Chi Minh City",
      "location": null,
      "locale": "vi-VN",
      "timezone": "Asia/Ho_Chi_Minh",
      "subscribedAt": "2023-11-07T05:31:56Z",
      "broadcastSubscribedAt": "2023-11-07T05:31:56Z",
      "blockedAt": null,
      "workspaceId": "ws123",
      "contactCustomFields": [],
      "tags": [
        {
          "id": "tag1",
          "name": "VIP",
          "workspaceId": "ws123",
          "createdAt": "2023-11-07T05:31:56Z",
          "updatedAt": "2023-11-07T05:31:56Z"
        }
      ],
      "contactNotes": [],
      "contactInboxes": [],
      "conversation": null
    }
  ],
  "pageCount": 5
}

Overview

Contacts

Custom Fields

Tags

Flows & Sequences

Broadcasts & Channels

Workspace

AI Agents

List Contacts: Paginate and Filter Your Workspace

Query Parameters

Code Examples

Response Fields

Example Response

​Query Parameters

​Code Examples

​Response Fields

​Example Response

Query Parameters

Code Examples

Response Fields

Example Response