List Contacts

Lists contacts in an organization.

This endpoint supports two pagination methods:

1. Offset-based pagination (default): Use offset and limit parameters

   • Default offset is 0 and default limit is 50
   • Maximum limit is 500

2. Cursor-based pagination: Use cursor and limit parameters

   • Default limit is 50
   • Maximum limit is 500
   • Provides more efficient pagination for large datasets
   • Uses the same ordering on contact name (and ID as a tiebreaker)
   • Use the next_cursor from metadata for subsequent requests
   • Filters are not included in the cursor - you still have to include them in subsequent requests or you'll get different data.
   • When next_cursor is null, there are no more results
   • Note: Only forward pagination is supported (no backward navigation for now)

Cursor-based pagination is automatically triggered when a cursor parameter is provided, if the offset parameter is not specified. If both parameters are provided, an error is returned.

Both pagination methods return a metadata object containing a next_cursor field. When there are more results available, next_cursor contains a cursor string that can be used to fetch the next page. When there are no more results, next_cursor is null. This allows you to start with offset-based pagination and switch to cursor-based pagination for subsequent requests if desired.

It is recommended to use cursor-based pagination for large datasets, and offset-based pagination for random access at various parts of the dataset.

The cursor is a base64-encoded string that represents a position in the dataset, based on the default composite ordering by ascending name first, and ID second (as a tiebreaker when there are tied names), used in order to have more deterministic results.

The cursor is built from a JSON object that has a contact ID and the name of the contact that corresponds to the ID. It has a format of {"name": "contact_name", "id": "contact_id"}, encoded as a URL-safe base64 string, with padding removed. If necessary, you can generate the cursor before making an initial request, and start directly at the provided cursor, if it is valid.

For example, this is how you could do that in Python:

import json
import base64

def encode_cursor(name, id):
    cursor_data = {
        "name": name,
        "id": id
    }

    json_string = json.dumps(cursor)
    base64_bytes = base64.urlsafe_b64encode(json_string.encode('utf-8'))

    # remove padding (trailing '=' characters)
    return base64_bytes.decode('utf-8').rstrip('=')