List contacts

GET

/api/v1/contacts

const url = 'https://api.inside.chat/api/v1/contacts?website_id=example&query_field=all&query_match=prefix';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.inside.chat/api/v1/contacts?website_id=example&query_field=all&query_match=prefix' \
  --header 'Authorization: Bearer <token>'

Required scopes: contact_read
Data access: –
MCP tool: contacts_list
Note: query adds contact_read_pii

Page stored contact IDs and blocked state, descending. Personal fields and search need contact_read_pii and PII; query_field selects all/name/email/mobile/phone, query_match prefix/exact. Unrestricted policy required; excludes deleted contacts, custom fields, links and remote CRM.

Authorizations

installation_token
oauth_client_credentials
contact_read

Parameters

Query Parameters

website_id

required

string

/^web_[0-9]{1,20}_[1-9][0-9]{0,18}$/

An explicitly granted website.

query

Requires both contact_read_pii and PII data access. Prefix search over stored native primary name, email, mobile and phone. Wildcards are literal; custom fields and remote CRM data are excluded.

string

>= 1 characters <= 200 characters

query_field

Requires query and current PII access. Exact matching uses native database collation with no address normalization or automatic contact selection.

string

default: all

Allowed values: all name email mobile phone

query_match

Requires query and current PII access. Exact matching uses native database collation with no address normalization or automatic contact selection.

string

default: prefix

Allowed values: prefix exact

limit

integer

>= 1 <= 100

cursor

string

<= 100 characters /^ctc_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$/

Responses

200

Authorized result. Projection depends on current scopes and data policy.

application/json

object

data

required

object

data

required

Array

<= 100 items

One of:

object
object

object

required

string

<= 100 characters /^ctc_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$/

blocked

required

boolean

access

required

object

pii

required

next_cursor

required

Any of:

string
null

string

<= 100 characters /^ctc_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$/

coverage

required

Allowed value: stored_primary_contacts

Example

{
  "data": {
    "data": [
      {
        "access": {
          "pii": false
        }
      }
    ],
    "coverage": "stored_primary_contacts"
  }
}

400

Invalid, duplicate or unsupported request parameters.

401

Missing, expired or revoked installation credential.

404

Resource not found or not permitted by current authority.

422

The requested capability is not available for application installations.

429

Per-app quota exceeded.

Headers

Retry-After

integer

>= 1

503

Enrollment, native service or required authority is unavailable.