Search contacts in an organization.

This endpoint supports two pagination methods:

1. Offset-based pagination (default): Use offset and limit request body fields

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

2. Cursor-based pagination: Use cursor and limit request body fields

   • 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 field is provided,
if the offset field is not specified. If both fields 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_data)
    base64_bytes = base64.urlsafe_b64encode(json_string.encode('utf-8'))

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

Invalid or unusable cursors

• A malformed cursor — not valid URL-safe base64, not JSON, or a JSON
  object without exactly the name and id keys — is rejected with a
  422 Unprocessable Entity and {"description": "Invalid cursor format"}.
  The literal strings null and undefined are treated as malformed.
• A well-formed but stale cursor (e.g. the contact it pointed at was
  since deleted or renamed) is still a valid position: the request succeeds
  and returns the contacts after that position. cursor_reset is false.
• A well-formed but unusable cursor (correct keys, but a value that
  can't be a position — e.g. an id that isn't a UUID) does not error.
  The request resets to the first page and the response sets
  cursor_reset to true so you can detect the reset rather than looping.