Update Contact | SpeechifyAI API

curl -X PATCH https://api.speechify.ai/v1/contacts/contact_01jqr8x9zg5k2m3n4p5q6r7s8t \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "display_name": "Sarah Chen",
  "metadata": {}
}'

{
  "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"
}

Rename a contact or replace its metadata. Omitted fields are unchanged; an empty display_name clears the column; metadata replaces the stored blob in full.

Identifiers are NOT editable here - each one is an assertion of record with its own provenance, so they are attached and detached through their own sub-resource.

Authentication

AuthorizationBearer

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

Path parameters

contact_idstringRequired

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

Request

This endpoint expects an object.

display_namestringOptional

Operator-editable display name. Empty string clears the column; an explicit null is rejected with a 400.

metadatamap from strings to anyOptional

Replacement metadata JSONB. An explicit null is rejected with a 400.

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 updated 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

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error