Contacts and identities

A contact represents a person or system you communicate with. An identity associates that contact with an address on a specific connection. A single contact can have several identities and conversations across channels.

With contacts:write, call POST /api/v2/contacts:

12345{
  "name": "Alex Taylor",
  "external_id": "user-123",
  "metadata": { "source": "application" }
}

The response includes an opaque ctc_ ID. external_id is your application's reference and is unique within that application. It does not authenticate the contact. Metadata belongs to your application; it does not expose another application's attributes.

List contacts with GET /api/v2/contacts and filter by external_id when reconciling your own user records. Use PATCH /api/v2/contacts/{contact_id} to update the name or replace your metadata object.

Call POST /api/v2/contacts/{contact_id}/identities:

12345{
  "connection_id": "conn_your_connection",
  "type": "email",
  "address": "[email protected]"
}

Use phone with an E.164 number for phone messaging or voice connections, email for an email connection, and platform_user for API chat or an existing provider identity. The response includes an idn_ ID and verification state.

Associating an address does not verify ownership. Platform identities on external providers must already have been learned from that connection. An identity attached to another contact cannot be reassigned by this endpoint.

Contact reads require contacts:read and remain limited to your application's contacts and contacts reachable through the key's granted inboxes. Returned identities are filtered to those inboxes.