Skip to content
zonoDocs
On this page

REST API reference

Customers

Admin and owner tokens only, as in the app: other roles get 403. Email addresses and external ids are unique per team. Passwords and tokens are never accepted or returned. Changing an email clears its verification, so the customer must verify the new address before using the portal.

Endpoints

Every request needs a bearer token: an API key or an OAuth access token. See authentication and scopes.

List customers

GET/api/v1/customers

List customers, newest first.

Scope
customers:read
Unscoped key
Read-only or read-write

Query parameters

emailstring
Exact email (case-insensitive).
external_idstring
Your own id for the customer.
marketplace_usernamestring
The customer's username on a connected marketplace, e.g. their Envato buyer username (case-insensitive).
searchstring
Matches name or email.
updated_afterdatetime
ISO-8601 timestamp.
per_pageinteger
1-100, default 25.
cursorstring
meta.next_cursor from the previous page.
Request
curl https://zono.support/api/v1/[email protected] \
  -H "Authorization: Bearer $ZONO_TOKEN" \
  -H "Accept: application/json"
Response200 OK
{
    "data": [
        {
            "object": "customer",
            "id": "01j9x1c2d3e4f5g6h7j8k9m0n1",
            "name": "Ada Lovelace",
            "email": "[email protected]",
            "external_id": "crm-5521",
            "avatar": null,
            "has_deliverable_email": true,
            "created_at": "2026-01-15T09:58:12Z",
            "updated_at": "2026-01-15T09:58:12Z",
            "url": "https://zono.support/customers/01j9x1c2d3e4f5g6h7j8k9m0n1"
        }
    ],
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": "https://zono.support/api/v1/customers?cursor=eyJpZCI6IjAxajl4MnAzcTQiLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
    },
    "meta": {
        "path": "https://zono.support/api/v1/customers",
        "per_page": 25,
        "next_cursor": "eyJpZCI6IjAxajl4MnAzcTQiLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
        "prev_cursor": null
    }
}

Get a customer

GET/api/v1/customers/{customer}

One customer.

Scope
customers:read
Unscoped key
Read-only or read-write

Path parameters

customerstringRequired
Customer id.
Request
curl https://zono.support/api/v1/customers/01j9x1c2d3e4f5g6h7j8k9m0n1 \
  -H "Authorization: Bearer $ZONO_TOKEN" \
  -H "Accept: application/json"
Response200 OK
{
    "object": "customer",
    "id": "01j9x1c2d3e4f5g6h7j8k9m0n1",
    "name": "Ada Lovelace",
    "email": "[email protected]",
    "external_id": "crm-5521",
    "avatar": null,
    "has_deliverable_email": true,
    "created_at": "2026-01-15T09:58:12Z",
    "updated_at": "2026-01-15T09:58:12Z",
    "url": "https://zono.support/customers/01j9x1c2d3e4f5g6h7j8k9m0n1"
}

Create a customer

POST/api/v1/customers

Create a customer. The email is marked verified: your team vouches for it.

Scope
customers:write
Unscoped key
Read-write

Body parameters

emailstringRequired
Unique in the team.
namestring
Defaults to the part of the email before @.
external_idstring
Your own id for the customer; unique in the team.
Request
curl -X POST https://zono.support/api/v1/customers \
  -H "Authorization: Bearer $ZONO_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","name":"Ada Lovelace","external_id":"crm-5521"}'
Response201 Created
{
    "object": "customer",
    "id": "01j9x1c2d3e4f5g6h7j8k9m0n1",
    "name": "Ada Lovelace",
    "email": "[email protected]",
    "external_id": "crm-5521",
    "avatar": null,
    "has_deliverable_email": true,
    "created_at": "2026-01-15T09:58:12Z",
    "updated_at": "2026-01-15T09:58:12Z",
    "url": "https://zono.support/customers/01j9x1c2d3e4f5g6h7j8k9m0n1"
}

Update a customer

PATCH/api/v1/customers/{customer}

Change a customer's name, email or external id.

Scope
customers:write
Unscoped key
Read-write

Path parameters

customerstringRequired
Customer id.

Body parameters

emailstring
Unique in the team.
namestring
Display name.
external_idstring|null
Your own id for the customer.
Request
curl -X PATCH https://zono.support/api/v1/customers/01j9x1c2d3e4f5g6h7j8k9m0n1 \
  -H "Authorization: Bearer $ZONO_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada King"}'
Response200 OK
{
    "object": "customer",
    "id": "01j9x1c2d3e4f5g6h7j8k9m0n1",
    "name": "Ada Lovelace",
    "email": "[email protected]",
    "external_id": "crm-5521",
    "avatar": null,
    "has_deliverable_email": true,
    "created_at": "2026-01-15T09:58:12Z",
    "updated_at": "2026-01-15T09:58:12Z",
    "url": "https://zono.support/customers/01j9x1c2d3e4f5g6h7j8k9m0n1"
}

Set a customer's attributes

PATCH/api/v1/customers/{customer}/attributes

Set details about the customer, shown to your team under Sent by your website. Keys are 1 to 40 lowercase letters, digits and underscores (zono_ is reserved; keys naming passwords, secrets, tokens, cards, CVV, SSN or IBAN are refused). Values are strings of at most 255 characters (ISO dates as strings), numbers or booleans; null deletes the key. At most 30 keys are kept and 4 KB sent per request; the latest write of a key wins. Strings that look like a card number or an IBAN are stored as [removed]. Values written here are marked Signed in the inbox and are never sent to the AI agent.

Scope
customers:write
Unscoped key
Read-write

Path parameters

customerstringRequired
Customer id.

Body parameters

attributesobjectRequired
Keys and values to set; null removes a key.
Request
curl -X PATCH https://zono.support/api/v1/customers/01j9x1c2d3e4f5g6h7j8k9m0n1/attributes \
  -H "Authorization: Bearer $ZONO_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"attributes":{"plan":"pro","seats":12}}'
Response200 OK
{
    "object": "customer",
    "id": "01j9x0a1b2c3d4e5f6g7h8j9k0",
    "attributes": {}
}