API v2-contacten en -leads
Toon contacten en leads, upsert één contact op basis van extern ID, en importeer contacten in bulk voor een agent.
Contact payloads expose customAttributes; write requests accept customAttributes.plan and other JSON keys such as customAttributes.seats.
Contacten koppelen je eigen stabiele eindgebruikers-ID's aan namen, e-mailadressen en telefoonnummers. Leads zijn alleen-lezen inzendingen die door een agent zijn vastgelegd. Elk endpoint op deze pagina vereist Authorization: Bearer YOUR_API_KEY en toegang tot {agentId}.
Zie Identiteitsverificatie voor ondertekende identiteitsclaims in embedded chat. Zie de foutcatalogus voor gedeelde authenticatie- en validatiefouten.
Contactobject
| Veld | Type | Opmerkingen |
|---|---|---|
id | string | Contact-UUID. |
externalId | string | Je stabiele eindgebruikers-ID. |
name | string of null | Naam van het contact. |
email | string of null | E-mailadres van het contact. |
phone | string of null | Telefoonnummer van het contact. |
createdAt | integer of null | Unix-tijdstempel in seconden. |
updatedAt | integer of null | Unix-tijdstempel in seconden. |
lastSeenAt | integer of null | Unix-tijdstempel in seconden. |
Contacten weergeven
Pad: /api/v2/agents/{agentId}/contacts
GET /api/v2/agents/{agentId}/contacts
Authenticatie: Bearer API-sleutel met toegang tot {agentId}.
| Query | Vereist | Beperkingen |
|---|---|---|
limit | Nee | Geheel getal van 1 tot en met 100; standaard 20. |
cursor | Nee | Ondoorzichtige cursor, teruggegeven door de voorgaande pagina. Geef deze ongewijzigd door. |
search | Nee | Getrimde, hoofdletterongevoelige substring-zoekopdracht (ILIKE) over extern ID, e-mail, naam en telefoon. Procenttekens (%) worden verwijderd, maar het liggende streepje (_) wordt niet ge-escaped en werkt als jokerteken voor één teken — bijvoorbeeld acct_1 komt ook overeen met acctX1. Een leeg resultaat na het trimmen wordt genegeerd. |
curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/contacts?search=alice&limit=20' \ -H 'Authorization: Bearer YOUR_API_KEY'
Succes: 200 OK
{
"data": [
{
"id": "f9878f31-c2b3-469f-a82e-26e996e67721",
"externalId": "customer_123",
"name": "Alice Example",
"email": "[email protected]",
"phone": "+1 555 0100",
"customAttributes": { "plan": "pro", "seats": 4 },
"createdAt": 1784332800,
"updatedAt": 1784332800,
"lastSeenAt": null
}
],
"pagination": {
"cursor": null,
"hasMore": false,
"total": 1
}
}
Ongeldige limieten of cursors geven 400 VALIDATION_INVALID_BODY terug.
Leadobject
| Veld | Type | Opmerkingen |
|---|---|---|
id | string | Lead-UUID. |
name | string of null | Ingediende naam. |
email | string of null | Ingediend e-mailadres. |
phone | string of null | Ingediend telefoonnummer. |
conversationId | string of null | Openbare referentie-ID van het gesprek, wanneer de lead aan een gesprek is gekoppeld. |
createdAt | integer | Unix-tijdstempel in seconden. |
Leads weergeven
Pad: /api/v2/agents/{agentId}/leads
GET /api/v2/agents/{agentId}/leads
Authenticatie: Bearer API-sleutel met toegang tot {agentId}.
| Query | Vereist | Beperkingen |
|---|---|---|
limit | Nee | Geheel getal van 1 tot en met 100; standaard 20. |
cursor | Nee | Ondoorzichtige cursor, teruggegeven door de voorgaande pagina. Geef deze ongewijzigd door. |
createdAfter | Nee | ISO 8601-datumtijd met Z of een UTC-offset. De ondergrens is inclusief. |
createdBefore | Nee | ISO 8601-datumtijd met Z of een UTC-offset. De bovengrens is inclusief. |
Als beide datumfilters aanwezig zijn, moet createdAfter kleiner dan of gelijk zijn aan createdBefore bij vergelijking als tijdstippen. Gelijke grenzen zijn geldig.
curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/leads?createdAfter=2026-07-18T08:00:00Z&limit=20' \ -H 'Authorization: Bearer YOUR_API_KEY'
Succes: 200 OK
{
"data": [
{
"id": "ad47f673-6bfb-43a0-a296-d79c84870a32",
"name": "Alice Example",
"email": "[email protected]",
"phone": "+1 555 0100",
"conversationId": "a1b2c3d4e5f6g7h8",
"createdAt": 1784361600
}
],
"pagination": {
"cursor": null,
"hasMore": false,
"total": 1
}
}
Leads worden gesorteerd op indieningstijd, van nieuw naar oud. Ongeldige limieten, cursors, datumtijden of omgekeerde datumgrenzen geven 400 VALIDATION_INVALID_BODY terug.
Eén contact aanmaken of bijwerken
POST /api/v2/agents/{agentId}/contacts
Authenticatie: Bearer API-sleutel met toegang tot {agentId}.
Dit endpoint doet een upsert op het paar {agentId, externalId}. Als er al een bijpassend contact bestaat, worden alleen de profielvelden bijgewerkt die in de aanvraag aanwezig zijn. Een weggelaten veld behoudt de opgeslagen waarde; een expliciete null of lege string wist deze.
| Bodyveld | Vereist | Type en beperkingen |
|---|---|---|
externalId | Ja | String, getrimd, 1 tot en met 255 tekens. |
name | Nee | String, getrimd tot maximaal 255 tekens, of null. |
email | Nee | Geldig e-mailadres, getrimd tot maximaal 320 tekens, een lege string, of null. |
phone | Nee | String, getrimd tot maximaal 50 tekens, een lege string, of null. |
curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/contacts' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"externalId":"customer_123","name":"Alice Example","email":"[email protected]","customAttributes":{"plan":"pro","seats":4}}'
Succes: 201 Created, zowel bij nieuwe contacten als bij updates door een conflict. Het contactobject wordt zonder envelop geretourneerd.
{
"id": "f9878f31-c2b3-469f-a82e-26e996e67721",
"externalId": "customer_123",
"name": "Alice Example",
"email": "[email protected]",
"phone": null,
"customAttributes": { "plan": "pro", "seats": 4 },
"createdAt": 1784332800,
"updatedAt": 1784332800,
"lastSeenAt": null
}
Ongeldige body's geven 400 VALIDATION_INVALID_BODY terug, met validatiedetails.
Contacten importeren
Pad: /api/v2/agents/{agentId}/contacts/import
POST /api/v2/agents/{agentId}/contacts/import
Authenticatie: Bearer API-sleutel met toegang tot {agentId}.
De aanvraag gebruikt veldnamen in snake_case. rows moet 1 tot en met 1.000 items bevatten.
| Rijveld | Vereist | Type en beperkingen |
|---|---|---|
external_id | Ja | String, getrimd, 1 tot en met 255 tekens. |
name | Nee | String, getrimd tot maximaal 255 tekens, of null. |
email | Nee | Geldig e-mailadres, getrimd tot maximaal 320 tekens, een lege string, of null. |
phone | Nee | String, getrimd tot maximaal 50 tekens, of null; een lege string wordt ook geaccepteerd en opgeslagen als null. |
Rijen worden binnen de aanvraag gededupliceerd op external_id; de laatst voorkomende waarde telt. Anders dan bij de gedeeltelijke upsert van één contact, stelt de import voor elke behouden rij elk profielveld opnieuw samen, dus een weggelaten, null, of lege profielwaarde wordt bij een conflict opgeslagen als null.
curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/contacts/import' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"rows":[{"external_id":"customer_123","name":"Alice Example","email":"[email protected]","phone":"+1 555 0100","customAttributes":{"plan":"pro"}},{"external_id":"customer_456","name":"Bob Example","email":"[email protected]","phone":null}]}'
Succes: 200 OK
{
"processed": 2,
"skipped": 0
}
processed is het aantal unieke externe ID's dat is ge-upsert. skipped is het aantal dubbele rijen dat uit de ingediende batch is verwijderd. Ongeldige body's, waaronder lege batches en batches van meer dan 1.000 rijen, geven 400 VALIDATION_INVALID_BODY terug.