Get Caller | SpeechifyAI API

Fetch a single caller by id. Returns 404 for soft-deleted or foreign-tenant rows — GDPR-purged callers appear as “not found” to the API.

Authentication

AuthorizationBearer

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

Path parameters

caller_idstringRequired

Caller ID.

Response headers

X-Request-IDstring

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an X-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.

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an `X-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.

Response

idstringformat: "^caller_[0-9a-hjkmnp-tv-z]{26}$"

Prefixed wire identifier (caller_<26 char Crockford base32>). URL paths accept only this prefixed form; legacy UUID path parameters are rejected with 404.

tenant_idstringformat: "^ws_[0-9a-hjkmnp-tv-z]{26}$"

Prefixed wire identifier (ws_<26 char Crockford base32>) of the owning workspace.

agent_idstringformat: "^agent_[0-9a-hjkmnp-tv-z]{26}$"

Prefixed wire identifier (agent_<26 char Crockford base32>) of the agent the caller is scoped under.

caller_identitystring

The raw identifier the caller arrived with (E.164 phone for SIP, LiveKit participant id for web). Stable for the life of the caller row.

metadatamap from strings to any

Customer-supplied JSON metadata blob.

first_seen_atdatetime

Timestamp of the earliest observed conversation / memory for this caller.

last_seen_atdatetime

Timestamp of the most recent observation. Drives the default list ordering.

conversation_countinteger

Number of conversation rows currently pointing at this caller.

created_atdatetime

updated_atdatetime

display_namestring or null

Operator-editable display name, nullable.

external_refstring or null

Optional handle into the customer's own CRM, nullable.

Errors

401

Unauthorized Error

404

Not Found Error

1	{
2	"id": "caller_01k603xzbcwc8tr7std0hk1dbs",
3	"tenant_id": "ws_01jqr8x9zg5k2m3n4p5q6r7s8t",
4	"agent_id": "agent_01jqr8x9zg5k2m3n4p5q6r7s8t",
5	"caller_identity": "example",
6	"metadata": {},
7	"first_seen_at": "2026-06-24T18:03:11Z",
8	"last_seen_at": "2026-06-24T18:03:11Z",
9	"conversation_count": 10,
10	"created_at": "2026-06-24T18:03:11Z",
11	"updated_at": "2026-06-24T18:03:11Z",
12	"display_name": "Example name",
13	"external_ref": "example"
14	}

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

Authentication

Path parameters

Headers

Response headers

Response

Errors