Attach Contact Identifier
Assert that a typed identifier denotes this person - the mechanism by
which a phone number becomes linked to the application user it belongs
to, so a call from that number resolves to everything the agent
already knows.
The server stamps `asserted_by: api` and `verified_at` because the
request authenticated: your backend identified the end user before
telling us. Neither can be supplied by the client.
Attaching an identifier another contact already holds is refused with
`409 contact_identifier_conflict` naming the holder - never a silent
re-point, because that would be a merge nobody asked for, and a wrong
merge discloses one person's facts to another. Re-attaching an
identifier this same contact already holds succeeds unchanged.
Authentication
AuthorizationBearer
Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.
Path parameters
contact_id
Contact id (prefixed external id, contact_...).
Headers
Speechify-Version
Request
This endpoint expects an object.
kind
The namespace this value lives in.
value
The handle - an application user id, an E.164 number, an email address.
Response headers
Speechify-Request-Id
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 attached identifier.
id
contact_id
kind
The namespace the value lives in. Values of different kinds never
denote the same person by themselves, whatever they look like.
value
The handle itself - an application user id, an E.164 number, an email address.
asserted_by
Who vouched for this identifier. Server-assigned, never accepted from a client.
api- your authenticated backend, via this endpoint or a server-to-server session. May be linked to an existing contact.telephony- carrier ANI on an inbound call. Trustworthy as a fact about the call and silent about which of your users it is, so it creates a phone-only contact until you say otherwise.unverified- a self-asserted claim from a public or embedded browser session. Nobody stands behind it, so it never joins a verified contact.
created_at
verified_at
When an authenticated party asserted this identifier. Absent
exactly when asserted_by is unverified, which is what lets you
tell a vouched-for handle from a self-claim without re-deriving it
from the value’s shape.
Errors
400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error