Get Contact

Beta

GET

https://api.speechify.ai/v1/contacts/:contact_id

GET

/v1/contacts/:contact_id

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

1 {
2   "id": "contact_01k603xzbcwc8tr7std0hk1dbs",
3   "tenant_id": "ws_01k603xzbcwc8tr7std0hk1dbs",
4   "metadata": {},
5   "identifiers": [
6     {
7       "id": "ident_01k603xzbcwc8tr7std0hk1dbs",
8       "contact_id": "contact_01k603xzbcwc8tr7std0hk1dbs",
9       "kind": "external_id",
10       "value": "+12025550100",
11       "asserted_by": "api",
12       "created_at": "2024-01-15T09:30:00Z",
13       "verified_at": "2024-01-15T09:30:00Z"
14     }
15   ],
16   "first_seen_at": "2024-01-15T09:30:00Z",
17   "last_seen_at": "2024-01-15T09:30:00Z",
18   "created_at": "2024-01-15T09:30:00Z",
19   "updated_at": "2024-01-15T09:30:00Z",
20   "display_name": "string"
21 }

Fetch one contact by id, scoped to the caller’s workspace, with its live identifiers. Returns 404 for missing, merged-away, or foreign-workspace contacts - contact existence is never leaked across workspaces.

Authentication

AuthorizationBearer

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

Path parameters

contact_idstringRequired

Contact id (prefixed external id, contact_...).

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

The contact.

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

Prefixed wire identifier (contact_<26 char Crockford base32>). URL paths accept only this prefixed form; bare UUIDs are rejected with 404.

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

Workspace that owns this contact.

metadatamap from strings to any

Customer-controlled JSON blob.

identifierslist of objects

The contact’s live identifiers. Always present; empty only for a contact whose every link has been detached.

first_seen_atdatetime

Earliest sighting across every channel and agent. A merge widens this to span both records, because the window belongs to the person rather than to whichever record saw them first.

last_seen_atdatetime

created_atdatetime

updated_atdatetime

display_namestringOptional

Operator-editable name. Absent when nobody has named this person and no resolver supplied one.

Errors

401

Unauthorized Error

404

Not Found Error

Authentication

Path parameters

Headers

Response headers

Response

Errors