API referenceContacts
Create or update a contact by channel identity
PUT
Updates the contact holding {channel}/{externalId}, or creates one with that identity (201). Safe to repeat.
ApiKeyheader
AuthorizationBearer <token>An API key from Developers → API keys: Authorization: Bearer gauge_live_… (or pulse_k_live_…).
channel*stringA channel kind.
externalId*stringThe handle on that channel.
Gauge-Version?stringA dated version. Default 2026-10-21.
application/json- body
displayName?stringLength
1 <= length <= 200title?stringLength
length <= 200companyId?stringFormat
uuidcompanyName?stringLength
1 <= length <= 200customFields?country?stringValue in
"US""CA""GB"The contact (201 when it was created).
application/json- response
id*stringFormat
uuiddisplayName*string|nullemail*string|nullphone*string|nulltitle*string|nullcompanyId*|Format
uuidcompanyName*string|nulllifecycleStage*stringisVip*booleantags*array<string>customFields*identities*array<>createdAt*stringupdatedAt*stringcurl -X PUT 'https://app.gauge.chat/api/v2/contacts/by-identity/string/string' \ -H 'Content-Type: application/json' \ -d '{}'Example Response
{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "displayName": "string", "email": "string", "phone": "string", "title": "string", "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda", "companyName": "string", "lifecycleStage": "string", "isVip": true, "tags": [ "string" ], "customFields": { "property1": null, "property2": null }, "identities": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "channel": "string", "externalId": "string", "connectionId": "84b500d7-71c8-4b1f-adf4-f1eb0000973d" } ], "createdAt": "string", "updatedAt": "string"}