Skip to main content

Customers & conversations

In the API, a customer is one agent in your account: one chat widget with its own configuration, conversations and billing. Conversation data is reached through its customer, so most paths start with /customers/{id}.

Request examples omit the Authorization: Bearer gtmc_... header for brevity; every request needs it. See authentication.

Customers​

The customer object​

{
"id": 42,
"orgId": "org_2h9x4kQ",
"name": "Acme website",
"widgetKey": "wk_8f3a2c19d7e44b0c9a61f25d3b7e8c04",
"conversionType": "booked_meeting",
"conversionLabel": "Book a demo",
"bookingUrl": "https://acme.com/demo",
"personaPrompt": null,
"allowedScope": null,
"refusalPolicy": null,
"brandColor": "#2563eb",
"escalationThreshold": 0.7,
"motion": "demo_booking",
"vertical": "saas",
"provisioningStatus": "ready",
"active": true,
"createdAt": "2026-09-02T14:00:00.000Z",
"updatedAt": "2026-10-01T10:30:00.000Z",
"delivrPixelId": null,
"leadEmailRecipients": ["sales@acme.com"],
"leadEmailTranscript": true,
"visitorTranscriptEnabled": false,
"serviceEmailRecipients": []
}
FieldTypeNotes
idintegerCustomer id
orgIdstringYour account's organization id
namestring
widgetKeystringPublic key the chat widget uses
conversionTypestringOne of booked_meeting, qualified_lead, sale, resolved_ticket, custom, captured_contact, qualified_meeting
conversionLabelstring or null
bookingUrlstring or nullYour own booking link
personaPromptstring or null
allowedScopestring or null
refusalPolicystring or null
brandColorstringHex colour, #rrggbb
escalationThresholdnumber0 to 1
motionstring or nullOne of demo_booking, quote, self_serve, purchase, qualification, support
verticalstring or null
provisioningStatusstringpending, ready or failed
activebooleanfalse once deleted
createdAt, updatedAtdate-time
delivrPixelIdstring or null
leadEmailRecipientsarray of stringsWho receives lead emails. Read only in the API
leadEmailTranscriptbooleanWhether lead emails include the transcript. Read only in the API
visitorTranscriptEnabledbooleanWhether visitors can request a copy of their chat. Read only in the API
serviceEmailRecipientsarray of stringsRead only in the API

The four read-only fields are set in the dashboard.

List customers​

GET /api/v1/customers?limit=20 HTTP/1.1
Host: app.gtmclarity.ai

Returns active customers, newest first, as { "data": [customer, ...], "has_more": false }. Parameters: limit (1 to 100, default 20), starting_after (a customer id). Needs an agency-scoped key. Responses: 200, 400, 401, 403, 429.

Create a customer​

POST /api/v1/customers HTTP/1.1
Host: app.gtmclarity.ai
Content-Type: application/json
Idempotency-Key: create-acme-website

{
"name": "Acme website",
"conversionType": "booked_meeting",
"conversionLabel": "Book a demo",
"brandColor": "#2563eb",
"motion": "demo_booking",
"vertical": "saas"
}
FieldTypeNotes
namestringRequired, 1 to 200 characters
personaPromptstring
conversionTypestringSee the customer object
conversionLabelstring
allowedScopestring
refusalPolicystring
brandColorstring#rrggbb
motionstringSee the customer object
verticalstringNon-empty

Other fields are rejected. Returns 201 with the customer. Needs a write key with agency scope; Idempotency-Key is optional (see idempotency). A suspended account gets 403 with code account_stopped. Responses: 201, 400, 401, 403, 409, 429.

Retrieve a customer​

GET /api/v1/customers/42 HTTP/1.1
Host: app.gtmclarity.ai

Returns the customer, including a deleted one (active: false). Responses: 200, 401, 403, 404, 429.

Update a customer​

PATCH /api/v1/customers/42 HTTP/1.1
Host: app.gtmclarity.ai
Content-Type: application/json

{
"bookingUrl": "https://acme.com/meet",
"escalationThreshold": 0.6
}

Send at least one of: name, personaPrompt, conversionType, conversionLabel, bookingUrl, allowedScope, refusalPolicy, brandColor, escalationThreshold (0 to 1), motion, vertical. Every field except name, conversionType, brandColor and escalationThreshold also accepts null. Other fields, including the four read-only ones, are rejected. Returns the updated customer. A deleted customer returns 400 with code customer_deactivated. Needs a write key. Responses: 200, 400, 401, 403, 404, 429.

Delete a customer​

DELETE /api/v1/customers/42 HTTP/1.1
Host: app.gtmclarity.ai
{
"deleted": true,
"id": 42
}

Deactivates the customer: it stops appearing in List customers, stays readable by id with active: false, and can no longer be updated. There is no endpoint to reactivate it. A suspended account gets 403 with code account_stopped. Needs an admin key. Responses: 200, 401, 403, 404, 429.

Widget config​

The widget-facing subset of a customer.

GET /api/v1/customers/42/widget-config HTTP/1.1
Host: app.gtmclarity.ai
{
"personaPrompt": null,
"conversionType": "booked_meeting",
"conversionLabel": "Book a demo",
"allowedScope": null,
"refusalPolicy": null,
"brandColor": "#2563eb",
"escalationThreshold": 0.7,
"motion": "demo_booking",
"vertical": "saas",
"widgetKey": "wk_8f3a2c19d7e44b0c9a61f25d3b7e8c04",
"delivrPixelId": null
}

PATCH /api/v1/customers/{id}/widget-config takes the same fields as Update a customer except bookingUrl, and returns the widget config. It needs a write key and rejects a deleted customer with 400 (customer_deactivated).

Responses: GET 200, 401, 403, 404, 429. PATCH 200, 400, 401, 403, 404, 429.

Conversations​

Conversation endpoints return 404 until the customer's provisioningStatus is ready.

The conversation object​

{
"id": 118,
"status": "closed",
"converted": true,
"convertedAt": "2026-10-14T15:20:11.000Z",
"identityResolved": true,
"visitorId": "6f9d2c1e-8a3b-4f70-9c55-2d41e0b7a9c3",
"startedAt": "2026-10-14T15:04:05.000Z",
"endedAt": "2026-10-14T15:31:40.000Z",
"lead": {
"name": "Ada Lovelace",
"firstName": null,
"lastName": null,
"email": "ada@example.com",
"phone": "+61400000000",
"company": null,
"callbackRequested": true,
"preferredContactTime": "after 5pm",
"chatStartedOn": "https://example.com/sell"
}
}
FieldTypeNotes
idintegerConversation id, unique within the customer
statusstringopen, ai_active, human_active, closed or converted
convertedboolean
convertedAtdate-time or null
identityResolvedboolean
visitorIdstring or null
startedAtdate-time
endedAtdate-time or null
leadobject or nullThe contact details captured on the chat: what the visitor typed or an operator entered. null once the chat is erased. Fields as in the captured lead

List conversations​

GET /api/v1/customers/42/conversations?converted=true&started_after=2026-10-01T00:00:00Z HTTP/1.1
Host: app.gtmclarity.ai
ParameterTypeNotes
limitinteger1 to 100, default 20
starting_afterintegerA conversation id
statusstringOne of the status values above
convertedtrue or false
started_afterdate-timeConversations started after this time

Returns { "data": [conversation, ...], "has_more": false }, newest first. Responses: 200, 400, 401, 403, 404, 429.

Retrieve a conversation​

GET /api/v1/customers/42/conversations/118 HTTP/1.1
Host: app.gtmclarity.ai

Returns the conversation object. Responses: 200, 401, 403, 404, 429.

List messages​

GET /api/v1/customers/42/conversations/118/messages?limit=50 HTTP/1.1
Host: app.gtmclarity.ai
{
"data": [
{
"id": 901,
"role": "user",
"content": "Do you integrate with Salesforce?",
"createdAt": "2026-10-14T15:04:05.000Z"
},
{
"id": 902,
"role": "assistant",
"content": "Yes. Leads and transcripts sync to Salesforce.",
"createdAt": "2026-10-14T15:04:07.000Z"
}
],
"has_more": false
}

role is user (the visitor), assistant (the AI), agent (a human operator) or system.

ParameterTypeNotes
limitinteger1 to 100, default 50
starting_afterintegerA message id, default 0
include_systemtrue or falseSystem messages are left out unless true

Messages are returned oldest first. Responses: 200, 400, 401, 403, 404, 429.