Organization customers
Browse customers across the organization's merchants from the Dashboard.
These endpoints give the organization a consolidated view of customers across all of its merchants: search, list, and open a record for detail.
Customers never cross merchant boundaries — the same person at two merchants is two records — so this view aggregates rather than merges. Use it to answer org-wide questions; manage a customer within its own merchant customers screen.
These endpoints power the Tokeflow Dashboard UI at the organization level. They are session-authenticated (JWT bearer) — the token comes from signing in to the Dashboard, not from an sk_/pk_ API key. Requests also carry the x-organization-id header, and the signed-in user must be a member of that organization.
Endpoints
GET/api/v1/org/customers
Auth: Dashboard session (JWT bearer). Organization membership required.
List customers for organization.
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
page | number | No | Page number (1-indexed). Default 1, min 1. |
limit | number | No | Number of items per page. Default 20, min 1, max 100. |
merchant_id | string | No | Filter by merchant ID |
search | string | No | Search by name, email, or customer ID |
start_date | string | No | Start date (ISO 8601) |
end_date | string | No | End date (ISO 8601) |
Example request
curl -G https://api.tokeflow.com/api/v1/org/customers \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
--data-urlencode "page=1" \
--data-urlencode "limit=20" \
--data-urlencode "merchant_id=mrc_8a3f12d9" \
--data-urlencode "search=string"GET/api/v1/org/customers/:id
Auth: Dashboard session (JWT bearer). Organization membership required.
Get customer by ID.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
Example request
curl https://api.tokeflow.com/api/v1/org/customers/obj_1a2b3c4d \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3"PATCH/api/v1/org/customers/:id
Auth: Dashboard session (JWT bearer). Organization membership required.
Update customer.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
Request fields
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | — |
email | string | No | — |
phone | string | No | — |
document_type | string | No | One of cpf, cnpj, passport, tax_id. |
document_number | string | No | — |
Example request
curl -X PATCH https://api.tokeflow.com/api/v1/org/customers/obj_1a2b3c4d \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Store",
"email": "jane@example.com",
"phone": "+5511987654321",
"document_type": "cpf",
"document_number": "12345678909"
}'Errors
Errors use the standard envelope. The most common cases here:
| HTTP | Meaning |
|---|---|
400 | Invalid parameters or a state that does not allow this operation. |
401 | Missing, expired, or invalid Dashboard session token. |
403 | Authenticated, but the signed-in user lacks access to this entity. |
404 | The record does not exist or is not visible to this entity. |