Zaapi Open API Platform (1.0.0)

1. Generate an API key

API keys are created and managed by you, inside the Zaapi App. There is no separate application or approval step, and no client secret to exchange.

1. Open the Zaapi App and go to Settings → Developers.
2. Select Add API key.
3. Give the key a name that describes where it will be used, for example Warehouse sync or Reporting dashboard.
4. Tick the scopes the key should have — at least one is required. A key can only call endpoints covered by the scopes you grant it — see Scopes below. Ticking a write scope also grants the matching read scope.
5. Select Create, then copy the key.

The key is shown once, at creation. Store it somewhere safe before closing the dialog — you will not be able to see it again. Keys start with zaapi_. The table on the Developers page only shows a masked value (zaapi_•••••••• plus the last four characters).

If you lose the secret you don't have to start over. Use Rotate key on that row: it issues a new secret, keeps the name and scopes, and restarts the 6-month expiry.

Keys expire 6 months after they are created or last rotated. The expiry date is on the Developers page. An expired key is rejected with 401. Rotate before that date if the integration should keep working.

2. Send the key with every request

Pass the key in the x-api-key header. There is no bearer token, no Authorization header, and no token refresh — the key itself is the credential. A signed request, and the 401 / 403 bodies you get back when the header is missing, unrecognised, or under-scoped, are shown in the samples panel.

Every request is authenticated and scope-checked before it reaches your store's data. A request with no x-api-key header, or an unrecognised, inactive, expired, or deleted key, is rejected with 401. A valid key missing the scope an endpoint requires is rejected with 403. On success the request is scoped to your store, so a caller can only ever see their own data.

3. Keep the key safe

A key carries the scopes you granted it and acts on your store, so treat it like a password.

• Send it only from a server you control. Never embed a key in a mobile app, a browser page, or any client-side code, where it can be read by anyone.
• Use a separate key per integration. If one has to be deleted, the others keep working.
• Grant only the scopes an integration actually needs. A reporting tool that only reads data should not hold write scopes. The form has a Read only shortcut that selects every read scope and none of the write scopes.
• Rotate a key if it may have been exposed, if you lost the secret, or before it expires. Rotating is the usual response to a leaked or lost key, and it restarts the 6-month expiry.
• Delete a key when the integration using it is being retired.

4. Edit, rotate, or delete a key

Each of these lives on the key's ⋮ menu on Settings → Developers.

Editing renames the key or changes its scopes. The secret itself does not change, and nothing is shown again — integrations already using the key keep working. Taking a scope away starts failing those calls with 403 on the next request.

Rotating issues a new secret for the same key and leaves the name and scopes untouched. The new secret is shown once, the same as at creation, and the 6-month expiry restarts today.

The old secret stays valid for two hours. Use that window to deploy the new one. After two hours, anything still sending the old secret fails with 401. If your integration reads the key from a secrets store it can re-read without restarting, update it there and the cutover is immediate.

If two hours is not enough, add a second key with the same scopes, move the integration onto it, confirm it's working, then delete the first.

Rotate when a key has been lost, when it may have been exposed, or before it expires.

Deleting removes a key permanently. It takes effect immediately — the next request using that key fails with 401 — and it cannot be undone. Delete when the integration using a key is being retired for good.

Who can do this. Store owners and admins can add, edit, rotate, and delete API keys. The Developers page is not shown to other roles.

5. Handle the common errors

Failed requests return the same envelope. 401 and 403 from a missing, unrecognised, or under-scoped x-api-key header are shown in the samples panel. Application errors (400, 404, and endpoint-specific failures) look like:

{
  "requestId": "<requestId>",
  "requestReceivedAt": "<timestamp>",
  "storeId": "<id>",
  "error": {
    "message": "Resource not found",
    "statusCode": 404
  }
}

Four failures can happen on any request, so they are described here once rather than repeated on every endpoint below.

400 — the request was malformed or failed validation. Check the request body and query parameters against the endpoint's schema. error.message names the offending field.

401 — the x-api-key header is missing, or the key is not recognised, inactive, expired, or has been deleted. Check that the header is being sent and that the key is correct. If this started more than two hours after a rotation, the old secret is still deployed somewhere. If the key was lost, rotate it. If it expired, rotate it before the next call. If it was deleted, add a new key.

403 — the x-api-key header is valid but was not granted the scope this endpoint requires. Check the scope listed on the endpoint. Edit the key on Settings → Developers to add that scope, or use a different key that already has it.

404 — no such record in your store, or the key cannot reach it. Check the ID. A record belonging to another store returns 404, not 403.

409 — optimistic concurrency conflict. Returned when updating a ticket field whose ticketFieldsUpdatedAt no longer matches, or when creating a contact whose email or phone is already on the store. Re-read the resource and retry, or use a different email or phone.

Treat 401 and 403 as permanent. Retrying with the same key produces the same result, and a retry loop against 401 will simply generate noise. Both need a change to the key itself.

Endpoints that can fail in ways specific to what they do — a conflicting write, for example — document those responses individually.

Scopes decide what a key is allowed to do. You choose them when the key is created, and you can change them later with Edit on that key. Rotating a key preserves its scopes. Granting a write scope also grants the matching read scope; removing a read scope removes the matching write scope.

Each resource has a read and write pair. Write scopes for accounts, users, labels, and teams — and the accounts read scope — are defined so keys issued today do not need reissuing when those routes land.

• tickets:read — read tickets and ticket field definitions
• tickets:write — update ticket fields and close tickets
• conversations:read — read conversations
• conversations:write — mark conversations read and update labels
• contacts:read — read contacts and contact field definitions
• contacts:write — create contacts and update contact fields
• messages:read — read messages and internal comments
• messages:write — send messages and create internal comments
• accounts:read — reserved for future read endpoints
• accounts:write — reserved for future write endpoints
• users:read — read store users
• users:write — reserved for future write endpoints
• labels:read — read labels
• labels:write — reserved for future write endpoints
• teams:read — read teams
• teams:write — reserved for future write endpoints

Each endpoint below states the scope it requires.

URLs. Every path is relative to the versioned base URL, https://openplatform.zaapi.co/v1. Record IDs travel as query parameters on reads and in the request body on writes, rather than as path segments.

Response envelope. Successful responses wrap the result in data:

{
  "requestId": "<requestId>",
  "requestReceivedAt": "<timestamp>",
  "storeId": "<id>",
  "data": { }
}

A single-resource read puts an object in data. A list puts an array in data, including GET /conversations when you look up one conversation by id — that call still returns a one-item array. Failed requests use the same envelope with error instead of data.

Some writes return the updated resource. Others acknowledge the write with { "message": "OK" } inside data and do not echo the resource: marking a conversation read, updating conversation labels, updating a contact field, sending a plain-text message, and adding an internal comment.

Pagination

Collections that can grow without bound are cursor-paginated. Walk them with pageSize and cursor. Do not advance by incrementing page.

Query parameters on paginated endpoints:

• pageSize — items per page. Defaults to 20. Maximum is 50, except GET /messages where the maximum is 15. A value above the endpoint maximum is rejected with 400. On GET /messages you must send pageSize — the default of 20 is above that endpoint's maximum.
• cursor — opaque token from the previous page. Omit it on the first page. Pass the previous x-pagination-next-cursor value back verbatim — do not parse, wrap, or reconstruct it. A malformed cursor is rejected with 400.
• page — optional integer, defaults to 1. Echoed in x-pagination-page. It is not how you walk a collection. Sending page=2 without a cursor does not return the second page.

The response body stays a JSON array inside data. Pagination metadata is returned as headers, not in the body:

• x-pagination-page
• x-pagination-page-size
• x-pagination-total
• x-pagination-next-cursor — present only when this page is full (data.length === pageSize). Omitted on the last page. When it is present, request the next page with the same filters and pageSize, plus cursor set to this value. Stop when the header is missing.

GET /v1/labels?pageSize=20
# read x-pagination-next-cursor, then:
GET /v1/labels?pageSize=20&cursor=<cursor>

Keep pageSize and every filter the same across pages. Changing them mid-walk skips or repeats rows.

These endpoints are cursor-paginated:

• POST /tickets/list — newest message first, max pageSize 50
• GET /conversations — most recent last message first, max pageSize 50
• POST /contacts/list — most recently updated first, max pageSize 50
• GET /messages — newest first, max pageSize 15
• GET /messages/internal-comments — newest first, max pageSize 50
• GET /labels — most recently updated first, max pageSize 50
• GET /teams — max pageSize 50

Small per-store catalogs are returned in full, with no pagination parameters or x-pagination-* headers:

• GET /tickets/fields — all ticket field definitions, display order
• GET /contacts/fields — all contact field definitions, display order
• GET /users — every user on the store

Expanding related records

Pass expand as a query parameter to resolve related ids into small objects. Send a comma-separated list (expand=account,assignee) or repeat the key (expand=account&expand=assignee). Values are exact and case-sensitive. An unknown value is rejected with 400 (Invalid expand value: …).

Each endpoint accepts only the values listed on it. expand=assignee is valid on a ticket and rejected on a conversation — assignee lives on tickets, not conversations.

Two shapes are used:

Replace the id. On tickets and conversations, the id field is omitted and a related object takes its place.

GET /v1/tickets?ticketId=<id>
# { "accountId": "<id>", "assigneeUserId": "<id>" }

GET /v1/tickets?ticketId=<id>&expand=account,assignee
# { "account": { "id": "<id>", "name": "Line Shop", "channel": "line" },
#   "assignee": { "id": "<id>", "name": "Nadia Prasert" } }

Add a sibling, or replace a nested id. On messages, accountId and conversationId stay on the record and account / conversation / sentBy are added beside them. On an internal comment, expand=createdBy replaces noteData.createdBy in place. On a team, expand=users turns each member id into { id, name } when that user exists on the store — otherwise the raw id is left as-is. On a user, expand=role adds role { id, name } and omits roleId.

If a related record cannot be resolved, the expand is skipped for that field and the original id remains.

Allowed expand values:

Related channel objects are { id, name, channel }. Related users are { id, name }, except message sentBy / createdBy, which are { userId, name, roleId }.

Timestamps. Resource timestamps are ISO 8601 in UTC.

Errors. See Handle the common errors above for the shared error shape and the 400, 401, 403, 404, and 409 responses that apply across endpoints.

As well as calling the API, you can have Zaapi notify your systems when something changes in your store. The events we send are:

Messages

• message.received — a message arrives from a contact
• message.sent — a message is sent from Zaapi

Tickets

• ticket.opened — a ticket is opened, including a ticket being reopened
• ticket.closed — a ticket is closed
• ticket.assigned — a ticket is assigned to someone
• ticket.unassigned — a ticket's assignee is removed
• ticket.ticket_field_updated — a ticket field is updated

Conversations

• conversation.label_added — a label is added to a conversation
• conversation.label_removed — a label is removed from a conversation

Contacts

• contact.contact_field_updated — a contact field is updated

AI

• ai.escalated — the AI escalates a chat

Payload schemas, endpoint configuration, and signature verification are documented separately.

Individual pieces of work raised against a conversation — listing, reading, updating fields, and closing.

Channel conversations — finding by conversation or contact, marking read, and applying label changes.

Customer contacts — reading, listing with search, creating, and updating custom fields.

Customer messages and internal comments on a conversation or ticket.