Customers

Operations tagged Customers in the public API.

About Customers

A customer is one person a chatbot can reach back — by email, phone or your own external_id — kept as one profile per chatbot. Profiles come from chat and from you: the lead form of the widget and the hosted agent page (source: widget), the dashboard Test Chat (dashboard), a collect_info Call Action (action), a visitor message that is only contact details (chat_intent), and POST /customers (api).

Identity. A contact is matched within its chatbot on external_id, then email (compared lower-cased), then phone (compared in E.164), so the same person on two chatbots is two customers. A match fills the profile's empty fields and never overwrites one. Nothing is verified: a visitor can type anyone's email. The name and id a host page passes to the widget (visitor) are display data on the conversation — they never match or create a customer, and a customer is never a login.

Personal data. full_name, email, phone and company are personal data, and so are the conversations behind a profile. POST /customers/{id}/anonymize erases them for a data-subject request and keeps the counts; DELETE /customers/{id} removes the profile but keeps its conversations. The CSV export needs customers:write.

Lifecycle. A profile starts at lead_status: new and lifecycle_stage: lead (visitor while it has no contact); moving it along is yours, with PATCH /customers/{id}. Every capture from chat emits lead.captured, plus customer.created or customer.updated; the API's own writes emit customer.created, customer.updated and customer.deleted. Anonymization emits nothing.

IDs you will meet.

id — the customer id, an integer, in every /customers/{id} path and in the bulk operations' ids.
chatbot_id — the chatbot the profile belongs to.
external_id — your own identifier, as you sent it; the strongest match key.
Timeline chat_session_id — the conversation id of the chat the event happened in, for GET /conversations/{id}.

IDs on this page

Chatbot id<CHATBOT_ID>: Integer.
Get it from
GET /v1/chatbots returns it as data[].id
POST /v1/chatbots returns it as id
GET /v1/chatbots/by_handle/{handle} returns it as id
Webhook chatbot.created carries it as data.object.id
In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.
Customer id<CUSTOMER_ID>: Integer.
Get it from
GET /v1/customers returns it as data[].id
POST /v1/customers returns it as id
Webhook customer.created carries it as data.object.id
Webhook lead.captured carries it as data.object.id
lead.captured names the customer the lead was filed under: its data.object is {"object": "lead", "id": <customer id>}. In the dashboard, the id is the number in a customer's address: /dashboard/customers/{id}.
Customer ids<CUSTOMER_IDS>: Array of 1–200 integer customer ids. A repeated id counts once; an id the API key cannot reach is skipped, not an error.
Get it from
GET /v1/customers returns it as data[].id
POST /v1/customers returns it as id
Webhook customer.created carries it as data.object.id
Webhook lead.captured carries it as data.object.id
lead.captured names the customer the lead was filed under: its data.object is {"object": "lead", "id": <customer id>}. In the dashboard, the id is the number in a customer's address: /dashboard/customers/{id}.

/v1/customers

List customers

Returns the profiles of every chatbot the API key reaches, newest first and cursor-paginated. The filters combine: chatbot_id, status (the lead_status), lifecycle_stage, source, utm_source, a search over name, company, email and phone, and two creation-date windows — date_from / date_to (whole UTC days) and the shared created[gte] / created[lte]. sort takes id (the default), created_at or last_seen_at — the last time the person was captured or matched, which the customer object does not return — with a + prefix or order=asc for oldest first.

Required scope: customers:read
Idempotency: Read-only
Rate limits

Before you call

chatbot_id(query)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Query parameters

searchstringnullableOptional
Text the customer's name, company, email or phone contains. At most 255 characters.
Max length: 255
chatbot_idintegernullableOptional
Only this chatbot's customers. A chatbot the API key cannot reach matches nothing: the answer is an empty list, not 404.
statusstringnullableOptional
Only customers with this lead_status.
Possible valuesnewcontactedqualifiedunqualifiedconvertedblockednull
lifecycle_stagestringnullableOptional
Only customers at this lifecycle_stage.
Possible valuesvisitorleadcustomervipnull
sourcestringnullableOptional
Only customers first captured from this source: widget, dashboard, action, chat_intent or api. Exact match.
Max length: 255
utm_sourcestringnullableOptional
Only customers whose captured visit carried this utm_source tag. Exact match; only the widget and hosted agent page lead forms record UTM tags.
Max length: 255
date_fromstringnullableOptional
Earliest creation day, inclusive: Y-m-d or an RFC 3339 date-time (YYYY-MM-DDThh:mm:ss.ffffff). An instant counts as the UTC calendar day it falls on.
Example: "2026-10-01"Format: date-time
date_tostringnullableOptional
Latest creation day, inclusive: Y-m-d or an RFC 3339 date-time (YYYY-MM-DDThh:mm:ss.ffffff). An instant counts as the UTC calendar day it falls on.
Example: "2026-10-31T23:59:59Z"Format: date-time
limitintegerOptional
Page size, clamped to 1–100.
Default: 20Minimum: 1Maximum: 100
starting_afterstringOptional
Cursor from a previous page's next_cursor: returns the page after it. A cursor minted for another list, sort or order is 422 INVALID_CURSOR.
ending_beforestringOptional
Cursor from a previous page's previous_cursor: returns the page before it. Wins when both cursors are sent.
created[gte]stringOptional
Only rows created on or after this instant: YYYY-MM-DD (whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422 INVALID_PARAMETER.
created[lte]stringOptional
Only rows created on or before this instant: YYYY-MM-DD (whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422 INVALID_PARAMETER.

Responses

200
Success.
objectstringRequired
Alwayslist
dataarray of CustomerResourceRequired
has_morebooleanRequired
next_cursorstringnullableRequired
previous_cursorstringnullableRequired
urlstringRequired
Always/v1/customers
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
422
Validation failed. See error.details.
Error codesINVALID_CURSOR INVALID_PARAMETER VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/customers' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "list",
  "data": [
    {
      "object": "customer",
      "id": 1,
      "chatbot_id": 1,
      "external_id": "crm_1042",
      "full_name": "Dana Whitfield",
      "email": "dana.whitfield@example.com",
      "phone": "+442071838750",
      "company": "Northwind Traders",
      "lead_status": "qualified",
      "lifecycle_stage": "lead",
      "source": "widget",
      "created_at": "2026-01-01T00:00:00+00:00",
      "updated_at": "2026-01-01T00:00:00+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "previous_cursor": null,
  "url": "/v1/customers"
}

/v1/customers

Create or match a customer

Files a contact under a chatbot — from your CRM, a form of your own, or a sign-up — with source: api. Send email, phone or both; at least one must be valid. Customers are deduplicated per chatbot on external_id, email and phone, in that order of authority. When the contact matches an existing customer, the submitted fields fill that customer's empty fields (non-empty values are never overwritten) and the call answers 200 with the existing customer and emits customer.updated; a new customer answers 201 and emits customer.created. Neither emits lead.captured, which is for captures from chat.

Required scope: customers:write
Idempotency: Accepts Idempotency-Key
Webhook events: customer.created customer.updated
Rate limits

Before you call

chatbot_id(body)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

chatbot_idintegerRequired
The chatbot the customer belongs to; contacts are matched within this chatbot only. A chatbot of another account is 422 VALIDATION_FAILED.
emailstringnullableOptional
Email address, at most 255 characters. Stored as sent and matched lower-cased. Required without phone.
Format: emailMax length: 255
phonestringnullableOptional
Phone number, at most 32 characters, stored as sent. Send it in E.164 (+14155550123): a number without a country code is read in the platform's default region, and one that cannot be parsed is never matched on. Required without email; with no valid email, an unparseable phone is 422 VALIDATION_FAILED.
Max length: 32
full_namestringnullableOptional
The person's name, at most 255 characters. On a match it only fills an empty name.
Max length: 255
companystringnullableOptional
Company name, at most 255 characters. On a match it only fills an empty company.
Max length: 255
external_idstringnullableOptional
Your own identifier for the person (a CRM id), at most 128 characters. The strongest match key: a known external_id resolves to its customer before email or phone are compared. On a match it is set only when the customer has none.
Max length: 128

Responses

200
CustomerResource
objectstringRequired
Alwayscustomer
idintegerRequired
The customer id.
chatbot_idintegerRequired
The chatbot the profile belongs to. Profiles are per chatbot: the same person on two chatbots is two customers.
external_idstringnullableRequired
Your own identifier for the person, exactly as POST /customers sent it; null when none, or after anonymization. The strongest match key.
full_namestringnullableRequired
Name as captured or set; null when unknown, or after anonymization.
emailstringnullableRequired
Email address as captured or sent (matching compares it lower-cased); null when none, or after anonymization. Not verified.
phonestringnullableRequired
Phone number as captured or sent (matching compares its E.164 form); null when none, or after anonymization. Not verified.
companystringnullableRequired
Company name; null when unknown, or after anonymization.
lead_statusstringRequired
Sales pipeline status: new when captured, then whatever you or the dashboard set (contacted, qualified, unqualified, converted). Anonymization sets blocked.
Possible valuesnewcontactedqualifiedunqualifiedconvertedblocked
lifecycle_stagestringRequired
Relationship stage: visitor (no contact yet), lead (a contact is known — where every new profile with one starts), customer or vip. Only a capture that brings a contact moves visitor to lead; the rest is yours to set.
Possible valuesvisitorleadcustomervip
sourcestringnullableRequired
Where the profile was first captured: widget (the widget or the hosted agent page lead form), dashboard (Test Chat), action (a collect_info Call Action), chat_intent (a visitor message that was only contact details) or api (POST /customers). Never changes after creation.
created_atstringnullableRequired
When the profile was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the profile last changed (ISO 8601, UTC).
201
CustomerResource
objectstringRequired
Alwayscustomer
idintegerRequired
The customer id.
chatbot_idintegerRequired
The chatbot the profile belongs to. Profiles are per chatbot: the same person on two chatbots is two customers.
external_idstringnullableRequired
Your own identifier for the person, exactly as POST /customers sent it; null when none, or after anonymization. The strongest match key.
full_namestringnullableRequired
Name as captured or set; null when unknown, or after anonymization.
emailstringnullableRequired
Email address as captured or sent (matching compares it lower-cased); null when none, or after anonymization. Not verified.
phonestringnullableRequired
Phone number as captured or sent (matching compares its E.164 form); null when none, or after anonymization. Not verified.
companystringnullableRequired
Company name; null when unknown, or after anonymization.
lead_statusstringRequired
Sales pipeline status: new when captured, then whatever you or the dashboard set (contacted, qualified, unqualified, converted). Anonymization sets blocked.
Possible valuesnewcontactedqualifiedunqualifiedconvertedblocked
lifecycle_stagestringRequired
Relationship stage: visitor (no contact yet), lead (a contact is known — where every new profile with one starts), customer or vip. Only a capture that brings a contact moves visitor to lead; the rest is yours to set.
Possible valuesvisitorleadcustomervip
sourcestringnullableRequired
Where the profile was first captured: widget (the widget or the hosted agent page lead form), dashboard (Test Chat), action (a collect_info Call Action), chat_intent (a visitor message that was only contact details) or api (POST /customers). Never changes after creation.
created_atstringnullableRequired
When the profile was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the profile last changed (ISO 8601, UTC).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X POST 'https://api.agentency.com/v1/customers' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "chatbot_id": 1,
  "email": "email",
  "phone": "phone",
  "full_name": "full_name",
  "company": "company",
  "external_id": 1
}'

Response

Example 200 response

json

{
  "object": "customer",
  "id": 0,
  "chatbot_id": 0,
  "external_id": "string",
  "full_name": "string",
  "email": "string",
  "phone": "string",
  "company": "string",
  "lead_status": "new",
  "lifecycle_stage": "visitor",
  "source": "string",
  "created_at": "string",
  "updated_at": "string"
}

Built from the response schema, not recorded from a live call.

/v1/customers/summary

Summarise customers

Returns the customer counts of the dashboard's Customers page: how many profiles there are, how many converted, and how they split by lead_status and lifecycle_stage — all time — plus how many were created in the last 30 days. It covers every chatbot the API key reaches, or one with chatbot_id. The list filters do not apply here.

Required scope: customers:read
Idempotency: Read-only
Rate limits

Before you call

chatbot_id(query)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Query parameters

chatbot_idintegernullableOptional
Summarise one chatbot's customers. Omit for every chatbot the API key reaches. A chatbot the API key cannot reach is 404 NOT_FOUND.
Minimum: 1

Responses

200
Success.
objectstringRequired
Alwayscustomer_summary
idintegerRequired
The account id, the same value as id on GET /me.
totalintegerRequired
Customers in scope, all time.
Minimum: 0
new_in_rangeintegerRequired
Customers created since the start of the day 30 days ago (UTC), today included.
Minimum: 0
convertedintegerRequired
Customers whose lead_status is converted, all time.
Minimum: 0
conversion_ratenumberRequired
converted ÷ total, in percent (0–100, one decimal); 0 when there are no customers.
by_statusobjectRequired
Customers per lead_status, all time. A status no customer has is absent rather than 0.
by_stageobjectRequired
Customers per lifecycle_stage, all time. A stage no customer has is absent rather than 0.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
422
Validation failed. See error.details.
Error codesVALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/customers/summary' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "customer_summary",
  "id": 1,
  "total": 1,
  "new_in_range": 1,
  "converted": 0,
  "conversion_rate": 0,
  "by_status": {
    "qualified": 1
  },
  "by_stage": {
    "lead": 1
  }
}

/v1/customers/{id}

Retrieve a customer

Returns one profile: its contact details, pipeline status and stage, and where it was first captured. What happened to it over time is on GET /customers/{id}/timeline. A deleted customer, or one the API key cannot reach, is 404 NOT_FOUND; an anonymized one is returned with its personal fields null.

Required scope: customers:read
Idempotency: Read-only
Rate limits

Before you call

id(path)Customer id
Integer.
Placeholder in the samples: <CUSTOMER_ID>
Get it from
- GET /v1/customers returns it as data[].id
- POST /v1/customers returns it as id
- Webhook customer.created carries it as data.object.id
- Webhook lead.captured carries it as data.object.id
- lead.captured names the customer the lead was filed under: its data.object is {"object": "lead", "id": <customer id>}. In the dashboard, the id is the number in a customer's address: /dashboard/customers/{id}.

Path parameters

idintegerRequired
The customer id.

Responses

200
CustomerResource
objectstringRequired
Alwayscustomer
idintegerRequired
The customer id.
chatbot_idintegerRequired
The chatbot the profile belongs to. Profiles are per chatbot: the same person on two chatbots is two customers.
external_idstringnullableRequired
Your own identifier for the person, exactly as POST /customers sent it; null when none, or after anonymization. The strongest match key.
full_namestringnullableRequired
Name as captured or set; null when unknown, or after anonymization.
emailstringnullableRequired
Email address as captured or sent (matching compares it lower-cased); null when none, or after anonymization. Not verified.
phonestringnullableRequired
Phone number as captured or sent (matching compares its E.164 form); null when none, or after anonymization. Not verified.
companystringnullableRequired
Company name; null when unknown, or after anonymization.
lead_statusstringRequired
Sales pipeline status: new when captured, then whatever you or the dashboard set (contacted, qualified, unqualified, converted). Anonymization sets blocked.
Possible valuesnewcontactedqualifiedunqualifiedconvertedblocked
lifecycle_stagestringRequired
Relationship stage: visitor (no contact yet), lead (a contact is known — where every new profile with one starts), customer or vip. Only a capture that brings a contact moves visitor to lead; the rest is yours to set.
Possible valuesvisitorleadcustomervip
sourcestringnullableRequired
Where the profile was first captured: widget (the widget or the hosted agent page lead form), dashboard (Test Chat), action (a collect_info Call Action), chat_intent (a visitor message that was only contact details) or api (POST /customers). Never changes after creation.
created_atstringnullableRequired
When the profile was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the profile last changed (ISO 8601, UTC).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/customers/<CUSTOMER_ID>' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "customer",
  "id": 1,
  "chatbot_id": 1,
  "external_id": "crm_1042",
  "full_name": "Dana Whitfield",
  "email": "dana.whitfield@example.com",
  "phone": "+442071838750",
  "company": "Northwind Traders",
  "lead_status": "qualified",
  "lifecycle_stage": "lead",
  "source": "widget",
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00"
}

/v1/customers/{id}

Update a customer

Sets the fields you send and leaves the others alone; contact fields (email, phone, external_id) cannot be changed here. Use it to move a profile along the pipeline (lead_status) or its stage (lifecycle_stage). Every successful call emits customer.updated, even one that changes nothing.

Required scope: customers:write
Idempotency: Accepts Idempotency-Key
Webhook events: customer.updated
Rate limits

Before you call

id(path)Customer id
Integer.
Placeholder in the samples: <CUSTOMER_ID>
Get it from
- GET /v1/customers returns it as data[].id
- POST /v1/customers returns it as id
- Webhook customer.created carries it as data.object.id
- Webhook lead.captured carries it as data.object.id
- lead.captured names the customer the lead was filed under: its data.object is {"object": "lead", "id": <customer id>}. In the dashboard, the id is the number in a customer's address: /dashboard/customers/{id}.

Path parameters

idintegerRequired
The customer id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

full_namestringnullableOptional
The person's name, at most 255 characters; null clears it.
Max length: 255
companystringnullableOptional
Company name, at most 255 characters; null clears it.
Max length: 255
job_titlestringnullableOptional
Job title, at most 255 characters; null clears it. Shown in the dashboard; the /v1 customer object does not return it.
Max length: 255
websitestringnullableOptional
Website, at most 2048 characters, not checked to be a URL; null clears it. Shown in the dashboard; the /v1 customer object does not return it.
Max length: 2048
countrystringnullableOptional
Country, free text up to 100 characters; null clears it. Shown in the dashboard; the /v1 customer object does not return it.
Max length: 100
lead_statusstringOptional
Sales pipeline status. Cannot be null.
Possible valuesnewcontactedqualifiedunqualifiedconvertedblocked
lifecycle_stagestringOptional
Relationship stage. Cannot be null.
Possible valuesvisitorleadcustomervip
extraobjectOptional
Custom key/value data. Replaces what the customer had, so send every key you want to keep. At most 50 top-level keys, 5 levels of nesting and 16 KB as JSON; larger is 422 VALIDATION_FAILED. Shown in the dashboard; the /v1 customer object does not return it.

Responses

200
CustomerResource
objectstringRequired
Alwayscustomer
idintegerRequired
The customer id.
chatbot_idintegerRequired
The chatbot the profile belongs to. Profiles are per chatbot: the same person on two chatbots is two customers.
external_idstringnullableRequired
Your own identifier for the person, exactly as POST /customers sent it; null when none, or after anonymization. The strongest match key.
full_namestringnullableRequired
Name as captured or set; null when unknown, or after anonymization.
emailstringnullableRequired
Email address as captured or sent (matching compares it lower-cased); null when none, or after anonymization. Not verified.
phonestringnullableRequired
Phone number as captured or sent (matching compares its E.164 form); null when none, or after anonymization. Not verified.
companystringnullableRequired
Company name; null when unknown, or after anonymization.
lead_statusstringRequired
Sales pipeline status: new when captured, then whatever you or the dashboard set (contacted, qualified, unqualified, converted). Anonymization sets blocked.
Possible valuesnewcontactedqualifiedunqualifiedconvertedblocked
lifecycle_stagestringRequired
Relationship stage: visitor (no contact yet), lead (a contact is known — where every new profile with one starts), customer or vip. Only a capture that brings a contact moves visitor to lead; the rest is yours to set.
Possible valuesvisitorleadcustomervip
sourcestringnullableRequired
Where the profile was first captured: widget (the widget or the hosted agent page lead form), dashboard (Test Chat), action (a collect_info Call Action), chat_intent (a visitor message that was only contact details) or api (POST /customers). Never changes after creation.
created_atstringnullableRequired
When the profile was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the profile last changed (ISO 8601, UTC).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X PATCH 'https://api.agentency.com/v1/customers/<CUSTOMER_ID>' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "full_name": "full_name",
  "company": "company",
  "job_title": "job_title",
  "website": "website",
  "country": "country",
  "lead_status": "lead_status",
  "lifecycle_stage": "lifecycle_stage",
  "extra": "extra"
}'

Response

Example 200 response

json

{
  "object": "customer",
  "id": 1,
  "chatbot_id": 1,
  "external_id": "crm_2001",
  "full_name": "Sam Rivera",
  "email": "sam.rivera@example.com",
  "phone": "+14155550123",
  "company": "Contoso",
  "lead_status": "contacted",
  "lifecycle_stage": "customer",
  "source": "api",
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00"
}

/v1/customers/{id}

Delete a customer

Removes the profile from /v1 and the dashboard and emits customer.deleted. Its conversations are kept, and the same email or phone captured later becomes a new customer. The profile's contact details are not erased: for a data-subject request use POST /customers/{id}/anonymize instead (or first).

Required scope: customers:write
Idempotency: Accepts Idempotency-Key
Webhook events: customer.deleted
Rate limits

Before you call

id(path)Customer id
Integer.
Placeholder in the samples: <CUSTOMER_ID>
Get it from
- GET /v1/customers returns it as data[].id
- POST /v1/customers returns it as id
- Webhook customer.created carries it as data.object.id
- Webhook lead.captured carries it as data.object.id
- lead.captured names the customer the lead was filed under: its data.object is {"object": "lead", "id": <customer id>}. In the dashboard, the id is the number in a customer's address: /dashboard/customers/{id}.

Path parameters

idintegerRequired
The customer id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Responses

200
Success.
objectstringRequired
Alwayscustomer
idintegerRequired
The deleted customer's id.
deletedbooleanRequired
Always true.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X DELETE 'https://api.agentency.com/v1/customers/<CUSTOMER_ID>' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "customer",
  "id": 1,
  "deleted": true
}

/v1/customers/{id}/timeline

List a customer's timeline

Returns what happened to the profile, newest first and cursor-paginated: lead-form steps, the conversations linked to it, and audit entries such as dashboard views, exports and anonymization. created[gte] / created[lte] filter on occurred_at. Timeline entries are a record, not webhook events: subscribe to customer.* and lead.captured to be told as things happen.

Required scope: customers:read
Idempotency: Read-only
Rate limits

Before you call

id(path)Customer id
Integer.
Placeholder in the samples: <CUSTOMER_ID>
Get it from
- GET /v1/customers returns it as data[].id
- POST /v1/customers returns it as id
- Webhook customer.created carries it as data.object.id
- Webhook lead.captured carries it as data.object.id
- lead.captured names the customer the lead was filed under: its data.object is {"object": "lead", "id": <customer id>}. In the dashboard, the id is the number in a customer's address: /dashboard/customers/{id}.

Path parameters

idintegerRequired
The customer id.

Query parameters

limitintegerOptional
Page size, clamped to 1–100.
Default: 20Minimum: 1Maximum: 100
starting_afterstringOptional
Cursor from a previous page's next_cursor: returns the page after it. A cursor minted for another list, sort or order is 422 INVALID_CURSOR.
ending_beforestringOptional
Cursor from a previous page's previous_cursor: returns the page before it. Wins when both cursors are sent.
created[gte]stringOptional
Only rows created on or after this instant: YYYY-MM-DD (whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422 INVALID_PARAMETER.
created[lte]stringOptional
Only rows created on or before this instant: YYYY-MM-DD (whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422 INVALID_PARAMETER.

Responses

200
Success.
objectstringRequired
Alwayslist
dataarray of CustomerEventResourceRequired
has_morebooleanRequired
next_cursorstringnullableRequired
previous_cursorstringnullableRequired
urlstringRequired
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
422
Validation failed. See error.details.
Error codesINVALID_CURSOR INVALID_PARAMETER
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/customers/<CUSTOMER_ID>/timeline' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "list",
  "data": [
    {
      "object": "customer_event",
      "id": 1,
      "event_type": "lead_form_submitted",
      "properties": {
        "fields": [
          "full_name",
          "email",
          "phone"
        ],
        "source": "widget"
      },
      "chat_session_id": 1,
      "occurred_at": "2026-01-01T00:00:00+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "previous_cursor": null,
  "url": "/v1/customers/1/timeline"
}

/v1/customers/export

Export customers as CSV

Streams the customers GET /customers would list for the same filters as one CSV file, newest first, with no pagination. created[gte] / created[lte] and sort are not read here: bound the dates with date_from / date_to. Bulk personal data: it needs customers:write, and each export is audited (filter names only), with a customer_exported timeline entry when it is scoped to one chatbot. A filtered set over the row cap (50,000) is 422 EXPORT_TOO_LARGE before any row is sent: narrow the filters, or page GET /customers instead.

Required scope: customers:write
Idempotency: Read-only
Rate limits

Before you call

chatbot_id(query)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Query parameters

searchstringnullableOptional
Text the customer's name, company, email or phone contains. At most 255 characters.
Max length: 255
chatbot_idintegernullableOptional
Only this chatbot's customers. A chatbot the API key cannot reach matches nothing: the answer is an empty list, not 404.
statusstringnullableOptional
Only customers with this lead_status.
Possible valuesnewcontactedqualifiedunqualifiedconvertedblockednull
lifecycle_stagestringnullableOptional
Only customers at this lifecycle_stage.
Possible valuesvisitorleadcustomervipnull
sourcestringnullableOptional
Only customers first captured from this source: widget, dashboard, action, chat_intent or api. Exact match.
Max length: 255
utm_sourcestringnullableOptional
Only customers whose captured visit carried this utm_source tag. Exact match; only the widget and hosted agent page lead forms record UTM tags.
Max length: 255
date_fromstringnullableOptional
Earliest creation day, inclusive: Y-m-d or an RFC 3339 date-time (YYYY-MM-DDThh:mm:ss.ffffff). An instant counts as the UTC calendar day it falls on.
Example: "2026-10-01"Format: date-time
date_tostringnullableOptional
Latest creation day, inclusive: Y-m-d or an RFC 3339 date-time (YYYY-MM-DDThh:mm:ss.ffffff). An instant counts as the UTC calendar day it falls on.
Example: "2026-10-31T23:59:59Z"Format: date-time

Responses

200
Success.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
422
Validation failed. See error.details.
Error codesEXPORT_TOO_LARGE VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/customers/export' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 400 response

json

{
  "message": "string",
  "error": {
    "code": "ACCOUNT_SELECTOR_NOT_SUPPORTED",
    "message": "string",
    "details": {
      "header": "X-Account-Id"
    }
  },
  "request_id": "string"
}

Built from the response schema, not recorded from a live call.

/v1/customers/{id}/anonymize

Anonymize a customer

Erases the person for a data-subject request, irreversibly: the profile's name, email, phone, company, external_id and every other personal field become null; its lead_status becomes blocked; the visitor's messages in its conversations read [redacted] and the replies are removed; and the personal data copied onto those conversations and their Call Action runs is cleared. The profile, its conversations, messages and timeline stay, so counts and analytics still add up, and the contact can never be matched again. Returns the anonymized customer. It emits no webhook event; the timeline records customer_anonymized.

Required scope: customers:write
Idempotency: Accepts Idempotency-Key
Webhook events: None
Rate limits

Before you call

id(path)Customer id
Integer.
Placeholder in the samples: <CUSTOMER_ID>
Get it from
- GET /v1/customers returns it as data[].id
- POST /v1/customers returns it as id
- Webhook customer.created carries it as data.object.id
- Webhook lead.captured carries it as data.object.id
- lead.captured names the customer the lead was filed under: its data.object is {"object": "lead", "id": <customer id>}. In the dashboard, the id is the number in a customer's address: /dashboard/customers/{id}.

Path parameters

idintegerRequired
The customer id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Responses

200
CustomerResource
objectstringRequired
Alwayscustomer
idintegerRequired
The customer id.
chatbot_idintegerRequired
The chatbot the profile belongs to. Profiles are per chatbot: the same person on two chatbots is two customers.
external_idstringnullableRequired
Your own identifier for the person, exactly as POST /customers sent it; null when none, or after anonymization. The strongest match key.
full_namestringnullableRequired
Name as captured or set; null when unknown, or after anonymization.
emailstringnullableRequired
Email address as captured or sent (matching compares it lower-cased); null when none, or after anonymization. Not verified.
phonestringnullableRequired
Phone number as captured or sent (matching compares its E.164 form); null when none, or after anonymization. Not verified.
companystringnullableRequired
Company name; null when unknown, or after anonymization.
lead_statusstringRequired
Sales pipeline status: new when captured, then whatever you or the dashboard set (contacted, qualified, unqualified, converted). Anonymization sets blocked.
Possible valuesnewcontactedqualifiedunqualifiedconvertedblocked
lifecycle_stagestringRequired
Relationship stage: visitor (no contact yet), lead (a contact is known — where every new profile with one starts), customer or vip. Only a capture that brings a contact moves visitor to lead; the rest is yours to set.
Possible valuesvisitorleadcustomervip
sourcestringnullableRequired
Where the profile was first captured: widget (the widget or the hosted agent page lead form), dashboard (Test Chat), action (a collect_info Call Action), chat_intent (a visitor message that was only contact details) or api (POST /customers). Never changes after creation.
created_atstringnullableRequired
When the profile was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the profile last changed (ISO 8601, UTC).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X POST 'https://api.agentency.com/v1/customers/<CUSTOMER_ID>/anonymize' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "customer",
  "id": 1,
  "chatbot_id": 1,
  "external_id": null,
  "full_name": null,
  "email": null,
  "phone": null,
  "company": null,
  "lead_status": "blocked",
  "lifecycle_stage": "lead",
  "source": "widget",
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00"
}

/v1/customers/bulk_delete

Delete customers in bulk

DELETE /customers/{id} for up to 200 customers at once, in one transaction: each one deleted emits its own customer.deleted. Ids that do not exist or the API key cannot reach are skipped, so deleted can be lower than the number of ids sent.

Required scope: customers:write
Idempotency: Accepts Idempotency-Key
Webhook events: customer.deleted
Rate limits

Before you call

ids(body)Customer ids
Array of 1–200 integer customer ids. A repeated id counts once; an id the API key cannot reach is skipped, not an error.
Placeholder in the samples: <CUSTOMER_IDS>
Get it from
- GET /v1/customers returns it as data[].id
- POST /v1/customers returns it as id
- Webhook customer.created carries it as data.object.id
- Webhook lead.captured carries it as data.object.id
- lead.captured names the customer the lead was filed under: its data.object is {"object": "lead", "id": <customer id>}. In the dashboard, the id is the number in a customer's address: /dashboard/customers/{id}.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

idsarray of integerRequired
Customer ids, 1–200 of them. An id that does not exist, is deleted, or the API key cannot reach is skipped rather than refused; the response counts only the customers acted on.
Min items: 1Max items: 200

Responses

200
Success.
objectstringRequired
Alwayscustomer_bulk
deletedintegerRequired
How many customers were deleted.
Minimum: 0
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X POST 'https://api.agentency.com/v1/customers/bulk_delete' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "ids": []
}'

Response

Example 200 response

json

{
  "object": "customer_bulk",
  "deleted": 1
}

/v1/customers/bulk_anonymize

Anonymize customers in bulk

POST /customers/{id}/anonymize for up to 200 customers at once. Irreversible, and it emits no webhook event. Ids that do not exist or the API key cannot reach are skipped, so anonymized can be lower than the number of ids sent.

Required scope: customers:write
Idempotency: Accepts Idempotency-Key
Webhook events: None
Rate limits

Before you call

ids(body)Customer ids
Array of 1–200 integer customer ids. A repeated id counts once; an id the API key cannot reach is skipped, not an error.
Placeholder in the samples: <CUSTOMER_IDS>
Get it from
- GET /v1/customers returns it as data[].id
- POST /v1/customers returns it as id
- Webhook customer.created carries it as data.object.id
- Webhook lead.captured carries it as data.object.id
- lead.captured names the customer the lead was filed under: its data.object is {"object": "lead", "id": <customer id>}. In the dashboard, the id is the number in a customer's address: /dashboard/customers/{id}.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

idsarray of integerRequired
Customer ids, 1–200 of them. An id that does not exist, is deleted, or the API key cannot reach is skipped rather than refused; the response counts only the customers acted on.
Min items: 1Max items: 200

Responses

200
Success.
objectstringRequired
Alwayscustomer_bulk
anonymizedintegerRequired
How many customers were anonymized.
Minimum: 0
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X POST 'https://api.agentency.com/v1/customers/bulk_anonymize' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "ids": []
}'

Response

Example 200 response

json

{
  "object": "customer_bulk",
  "anonymized": 1
}

About Customers

IDs on this page

/v1/customers

Query parameters

Responses

See also

Request

Response

/v1/customers

Header parameters

Request body

Responses

See also

Request

Response

/v1/customers/summary

Query parameters

Responses

See also

Request

Response

/v1/customers/{id}

Path parameters

Responses

See also

Request

Response

/v1/customers/{id}

Path parameters

Header parameters

Request body

Responses

See also

Request

Response

/v1/customers/{id}

Path parameters

Header parameters

Responses

See also

Request

Response

/v1/customers/{id}/timeline

Path parameters

Query parameters

Responses

See also

Request

Response

/v1/customers/export

Query parameters

Responses

See also

Request

Response

/v1/customers/{id}/anonymize

Path parameters

Header parameters

Responses

See also

Request

Response

/v1/customers/bulk_delete

Header parameters

Request body

Responses

See also

Request

Response

/v1/customers/bulk_anonymize

Header parameters

Request body

Responses

See also

Request

Response