Upsert a contact identity

PUT 
/v1/contacts/:contact_id/identities

Adds or links a phone/email/external_id identity for the contact. Identities dedup within the account on (type, value), not on contact_id, so three outcomes are possible: 201 when a new row is created and linked to this contact, 200 when the value is already linked to this contact, and 409 when the value already belongs to a DIFFERENT contact in the account (no_auto_merge — the row is not relinked; the caller decides whether to merge contacts or use a different value). Re-adding a previously deleted value revives the same identity row (200), preserving any consent recorded against it.

Permissions - contacts.write. API keys - manage.

Request

Responses

200

The value was already linked to this contact

201

A new identity row was created and linked to this contact

400

BadRequest

Response Headers

X-Request-Id
Unique identifier for the API request, useful for debugging and tracking.
Example: abc123xyz789

401

Unauthorized

Response Headers

X-Request-Id
Unique identifier for the API request, useful for debugging and tracking.
Example: abc123xyz789

404

The specified resource was not found

Response Headers

X-Request-Id
Unique identifier for the API request, useful for debugging and tracking.
Example: abc123xyz789

409

The value already belongs to a different contact in this account. A soft-deleted identity still reserves its (type, value) for the original contact — deleting an identity does not free the value for other contacts.

500

Internal Server Error

Response Headers

X-Request-Id
Unique identifier for the API request, useful for debugging and tracking.
Example: abc123xyz789