Update Caller | SpeechifyAI API

Update the customer-editable fields on a caller. PATCH semantics: omitted fields are unchanged, present fields overwrite. To clear a nullable field (display_name, external_ref) pass an empty string. metadata REPLACES the existing JSONB blob when supplied.

Authentication

AuthorizationBearer

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

Path parameters

caller_idstringRequired

Caller ID.

Request

This endpoint expects an object.

display_namestring or nullOptional

Operator-editable display name. Empty string clears the column.

external_refstring or nullOptional

Optional handle into the customer's own CRM. Empty string clears the column.

metadatamap from strings to anyOptional

Replacement metadata JSONB. Must not be null.

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

The refreshed caller row.

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

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

$	curl -X PATCH https://api.speechify.ai/v1/agents/callers/caller_01jqr8x9zg5k2m3n4p5q6r7s8t \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"display_name": "Example name",
>	"external_ref": "example",
>	"metadata": {}
>	}'

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	}