Merge Contacts | SpeechifyAI API

curl -X POST https://api.speechify.ai/v1/contacts/contact_01jqr8x9zg5k2m3n4p5q6r7s8t/merge \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "from_contact_id": "contact_01k603xzbcwc8tr7std0hk1dbs"
}'

{
  "contact": {
    "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"
  },
  "merged": {
    "identifiers": 1,
    "callers": 1,
    "conversations": 1,
    "memories": 1
  }
}

Fold one contact into another: every identifier, caller projection, conversation and memory that pointed at from_contact_id is re-pointed at the contact in the URL, the survivor’s first/last-seen window widens to span both, and the merged-away contact is tombstoned.

This is the deliberate counterpart to the refusal on identifier attach. Merging is destructive and one-way, so it is never inferred - the customer is the only party who knows two records are one person.

All-or-nothing, and safe to retry: a repeat call finds nothing left pointing at the merged-away contact and returns the same survivor with a zeroed tally. Send an Idempotency-Key header to have a retry replay the first response verbatim.

Fold one contact into another: every identifier, caller projection, conversation and memory that pointed at `from_contact_id` is re-pointed at the contact in the URL, the survivor's first/last-seen window widens to span both, and the merged-away contact is tombstoned. This is the deliberate counterpart to the refusal on identifier attach. Merging is destructive and one-way, so it is never inferred - the customer is the only party who knows two records are one person. All-or-nothing, and safe to retry: a repeat call finds nothing left pointing at the merged-away contact and returns the same survivor with a zeroed tally. Send an `Idempotency-Key` header to have a retry replay the first response verbatim.

Authentication

AuthorizationBearer

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

Path parameters

contact_idstringRequired

The SURVIVING contact’s id (prefixed external id, contact_...). Everything from the contact named in the body lands here.

Headers

Idempotency-KeystringOptional<=255 characters

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns 409 idempotency_conflict. A replayed response carries the Idempotent-Replayed: true header.

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns `409 idempotency_conflict`. A replayed response carries the `Idempotent-Replayed: true` header.

Request

This endpoint expects an object.

from_contact_idstringRequired

The contact to fold into the one in the URL. It is tombstoned, and everything pointing at it is re-pointed at the survivor. Must differ from the contact in the URL.

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 surviving contact plus the row counts that moved onto it.

contactobject

A workspace-scoped person. Identity lives in the identifiers set, not in this row: a contact is whoever those handles denote, and each handle records who vouched for it.

mergedobject

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error