API referenceContacts
Add an identity
POST
Phones are normalized to E.164 (send country for a national number). A handle another contact holds is a 409.
ApiKeyheader
AuthorizationBearer <token>An API key from Developers → API keys: Authorization: Bearer gauge_live_… (or pulse_k_live_…).
id*stringThe contact id.
Format
uuidGauge-Version?stringA dated version. Default 2026-10-21.
Idempotency-Key*stringRequired on every POST. Retries with the same key replay the first response for 24 h.
Length
1 <= length <= 255application/json- body
channel*stringValue in
"whatsapp_cloud""whatsapp_web""instagram""messenger""email""discord""x""webchat""voice""sms"externalId*stringLength
1 <= length <= 320country?stringValue in
"US""CA""GB"The identity.
application/json- response
id*stringFormat
uuidchannel*stringexternalId*stringconnectionId*|Format
uuidcurl -X POST 'https://app.gauge.chat/backend/v2/contacts/497f6eca-6276-4993-bfeb-53cbbbba6f08/identities' \ -H 'Idempotency-Key: string' \ -H 'Content-Type: application/json' \ -d '{ "channel": "whatsapp_cloud", "externalId": "string"}'Example Response
{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "channel": "string", "externalId": "string", "connectionId": "84b500d7-71c8-4b1f-adf4-f1eb0000973d"}