List contacts
POST /v1/contact/listFor the base URL, request headers and response codes, see the overview.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
PageSize | Integer | No | Items per page. Default 20, maximum 100 |
PageNumber | Integer | No | Page number. Default 1 |
Filter | Array<Object> | No | Filter conditions; see below |
CustomFieldFilter | Array<Object> | No | Filter by custom fields. A contact must match every condition |
Filter item
| Field | Type | Description |
|---|---|---|
FieldName | String | The field to filter on; see the table below |
Values | Array<String> | Filter values |
Supported FieldName values
| FieldName | Values | Example |
|---|---|---|
Tag | Tag names, one or more | ["VIP", "New"] |
List | List names, one or more | ["Newsletter"] |
Channel | Phone numbers of WhatsApp channels, one or more | ["+85298765432"] |
Email | Email addresses, one or more | ["[email protected]"] |
Telephone | Contact phone numbers, one or more | ["+85261234567"] |
UpdateTime | RFC 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
| Field | Type | Description |
|---|---|---|
FieldName | String | Custom field name, exact match |
Value | String | Field 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
| Field | Type | Description |
|---|---|---|
Code | Integer | 200 on success |
Message | String | Status message |
Data.Total | Integer | Total number of matching contacts |
Data.Contacts | Array<Object> | The contacts on this page |
Contacts item
| Field | Type | Description |
|---|---|---|
FirstName | String | First name |
LastName | String | Last name |
Avatar | String | Avatar URL |
Telephone | String | Phone number including country code |
Email | String | Email address |
Tags | Array<String> | Tag names |
Channels | Array<String> | Phone numbers of subscribed channels |
ChannelNames | Array<String> | Names of subscribed channels, in the same order as Channels |
CustomFields | Array<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" }
]
}
]
}
}