List Contacts | SpeechifyAI API

{
  "next_cursor": "string",
  "has_more": true,
  "contacts": [
    {
      "id": "contact_01k603xzbcwc8tr7std0hk1dbs",
      "tenant_id": "ws_01k603xzbcwc8tr7std0hk1dbs",
      "metadata": {},
      "identifiers": [
        {
          "id": "ident_01k603xzbcwc8tr7std0hk1dbs",
          "contact_id": "contact_01k603xzbcwc8tr7std0hk1dbs",
          "kind": "external_id",
          "value": "+12025550100",
          "asserted_by": "api",
          "created_at": "2024-01-15T09:30:00Z",
          "verified_at": "2024-01-15T09:30:00Z"
        }
      ],
      "first_seen_at": "2024-01-15T09:30:00Z",
      "last_seen_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "display_name": "string"
    }
  ]
}

List the workspace’s contacts, most-recently-seen first, each with its live identifier set. Cursor-paginated: omit cursor for the first page; walk pages while has_more is true (default page size 50, max 200).

Contacts are workspace-level, not per-agent: the same person reached on two agents and on two channels is one row here, while /v1/agents/callers stays the per-agent observation of them.

List the workspace's contacts, most-recently-seen first, each with its live identifier set. Cursor-paginated: omit `cursor` for the first page; walk pages while `has_more` is true (default page size 50, max 200). Contacts are workspace-level, not per-agent: the same person reached on two agents and on two channels is one row here, while `/v1/agents/callers` stays the per-agent observation of them.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Query parameters

qstringOptional

Prefix search across the display name AND the identifier values, so the same box finds “Sarah” and “+1202555”. %/_ in the input are escaped as literals.

cursorstringOptional

Opaque pagination cursor from a previous response.

limitintegerOptional1-200Defaults to 50

Max items per page (default 50, max 200).

Response headers

Speechify-Request-IdstringOptional

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a Speechify-Request-Id request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests

it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

The legacy alias X-Request-ID carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a `Speechify-Request-Id` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope. The legacy alias `X-Request-ID` carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Response

One page of the workspace's contacts.

next_cursorstring or null

Opaque keyset cursor for the next page. Pass back as the cursor request parameter. null when the caller has reached the end of the list (has_more is also false in that case).

has_moreboolean

True when more rows exist beyond this page.

contactslist of objects

Errors

400

Bad Request Error

401

Unauthorized Error

$	curl https://api.speechify.ai/v1/contacts \
>	-H "Authorization: Bearer <token>"

Authentication

Headers

Query parameters

Response headers

Response

Errors