API referenceContacts
Create a contact
POST
At least a name, an email or a phone. An email another contact holds is a 409 naming the owner.
ApiKeyheader
AuthorizationBearer <token>An API key from Developers → API keys: Authorization: Bearer gauge_live_… (or pulse_k_live_…).
Gauge-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
displayName?stringLength
1 <= length <= 200email?stringFormat
emailLength
length <= 320phone?stringLength
3 <= length <= 40country?stringValue in
"US""CA""GB"title?stringLength
length <= 200companyId?stringFormat
uuidcompanyName?stringLength
1 <= length <= 200customFields?tags?array<>Items
items <= 50The contact.
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 POST 'https://app.gauge.chat/api/v2/contacts' \ -H 'Idempotency-Key: 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"}