Retrieves a paginated list of your contacts (both users and leads). This endpoint supports
filtering, searching, and sorting to help you find the contacts you need.

What is a Contact?

A contact can be either:

• User: A registered user who has authenticated in your app
• Lead: A potential customer who hasn't registered yet (e.g., from a chat conversation)

Pagination

This endpoint uses offset-based pagination for efficient browsing:

1. First request: GET /contacts?per_page=20
2. Response includes a cursor value in the response body (e.g. 20)
3. Next page: GET /contacts?per_page=20&cursor=20
4. Continue until cursor is null (no more contacts)

The cursor is the offset of the next page, not a contact ID. Keep the other query parameters
identical across pages, otherwise the offset points at a different result set.

Filtering Options

You can combine multiple filters to narrow down results:

Search by keyword:

• Searches across name, email, and WhatsApp number
• Minimum 3 characters required
• Example: ?keyword=john finds "John Doe", "[email protected]", etc.

Filter by role:

• user: Only registered users
• lead: Only leads (not yet registered)
• Omit to get both users and leads
• Example: ?role=user

Filter by segment:

• Get contacts belonging to a specific segment
• Use the segment ID from your Customerly dashboard
• Example: ?contact_segment_id=42

Sorting

Sort results by any of these fields:

• name: Alphabetically by contact name
• email: Alphabetically by email address
• If not specified, contacts are sorted by internal ID (creation order)

Direction:

• ascending: A to Z, oldest to newest
• descending: Z to A, newest to oldest (default)

Example: ?sort_by=name&order=ascending

Response Data

The response includes:

• Array of contacts: Each contact includes basic information (ID, name, email, role, etc.),
  all custom attributes, and all tags
• Cursor: For pagination - use this value in the next request to get the next page.
  When cursor is null, you've reached the last page

Example Requests

# Get first 50 users, sorted by name
GET /contacts?role=user&per_page=50&sort_by=name&order=ascending

# Search for contacts named "Sarah" in segment 10
GET /contacts?keyword=sarah&contact_segment_id=10

# Get second page of leads
GET /contacts?role=lead&per_page=20&cursor=20