Skip to content

List contacts ​

POST /v1/contact/list

For the base URL, request headers and response codes, see the overview.

Request body ​

FieldTypeRequiredDescription
PageSizeIntegerNoItems per page. Default 20, maximum 100
PageNumberIntegerNoPage number. Default 1
FilterArray<Object>NoFilter conditions; see below
CustomFieldFilterArray<Object>NoFilter by custom fields. A contact must match every condition

Filter item

FieldTypeDescription
FieldNameStringThe field to filter on; see the table below
ValuesArray<String>Filter values

Supported FieldName values

FieldNameValuesExample
TagTag names, one or more["VIP", "New"]
ListList names, one or more["Newsletter"]
ChannelPhone numbers of WhatsApp channels, one or more["+85298765432"]
EmailEmail addresses, one or more["[email protected]"]
TelephoneContact phone numbers, one or more["+85261234567"]
UpdateTimeRFC 3339 timestamps. One value means "on or after"; two values mean a range["2026-01-01T00:00:00Z", "2026-12-31T23:59:59Z"]

CustomFieldFilter item

FieldTypeDescription
FieldNameStringCustom field name, exact match
ValueStringField value, exact match

Example request ​

bash
curl -X POST "https://api.chatbooster.ai/v1/contact/list" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "PageSize": 20,
    "PageNumber": 1,
    "Filter": [
      { "FieldName": "Tag", "Values": ["VIP"] },
      { "FieldName": "UpdateTime", "Values": ["2026-01-01T00:00:00Z"] }
    ],
    "CustomFieldFilter": [
      { "FieldName": "Company", "Value": "Example Ltd" }
    ]
  }'

Response ​

FieldTypeDescription
CodeInteger200 on success
MessageStringStatus message
Data.TotalIntegerTotal number of matching contacts
Data.ContactsArray<Object>The contacts on this page

Contacts item

FieldTypeDescription
FirstNameStringFirst name
LastNameStringLast name
AvatarStringAvatar URL
TelephoneStringPhone number including country code
EmailStringEmail address
TagsArray<String>Tag names
ChannelsArray<String>Phone numbers of subscribed channels
ChannelNamesArray<String>Names of subscribed channels, in the same order as Channels
CustomFieldsArray<Object>Custom fields (FieldName, Value). Only fields that have a value are returned
json
{
  "Code": 200,
  "Message": "success",
  "Data": {
    "Total": 1,
    "Contacts": [
      {
        "FirstName": "Peter",
        "LastName": "Chan",
        "Avatar": "",
        "Telephone": "+85261234567",
        "Email": "[email protected]",
        "Tags": ["VIP"],
        "Channels": ["+85298765432"],
        "ChannelNames": ["My WhatsApp Channel"],
        "CustomFields": [
          { "FieldName": "Company", "Value": "Example Ltd" }
        ]
      }
    ]
  }
}