# Zahrex API

> Public developer docs for the Zahrex API: send leads and events from your own software, and receive webhooks back.

## Docs
- [Overview](https://developers.zahrex.com/): What the Zahrex API does and where to start.
- [Quickstart](https://developers.zahrex.com/quickstart): Create an app, get a token, send your first lead.
- [Authentication](https://developers.zahrex.com/authentication): Client credentials, API keys and token lifetime.
- [Events](https://developers.zahrex.com/events): Every event you can send, with examples.
- [Webhooks](https://developers.zahrex.com/webhooks): Events Zahrex sends you, signatures and retries.
- [Errors and limits](https://developers.zahrex.com/errors): Error codes, rate limits and idempotency.
- [API reference](https://developers.zahrex.com/api): Every endpoint, its auth and scope.
- [Machine-readable reference](https://developers.zahrex.com/reference.json): same data as https://api.zahrex.com/v1/reference.json

## API (version 2026-11-07)
- Base URL: https://api.zahrex.com/v1
- Token URL: https://api.zahrex.com/v1/oauth/token
- Grant types: client_credentials
- Token lifetime: 3600 seconds
- API key prefixes: zx_live_, zx_test_

## Scopes
- events:write: Send subscription, booking, form and custom events.
- customers:write: Create or update customers.
- leads:write: Create leads.
- orders:write: Send orders and their payments or refunds.
- catalog:read: Read the organization's service and product catalog.
- customers:read: Look up a customer by phone or email.

## Endpoints
- POST /oauth/token: Exchange a client id and secret for a one-hour access token.
- POST /events [scope: depends on event type]: Send one event, or {"events": [...]} as a batch; each event is {id, type, occurred_at?, data} and needs an id or an Idempotency-Key header. Answers per event in results[]: accepted, duplicate, or rejected with an error message. A rejected event does not fail the others.
- GET /catalog/services [scope: catalog:read]: List the organization's active services.
- GET /catalog/products [scope: catalog:read]: List the organization's products.
- GET /customers [scope: customers:read]: Look up a customer by the phone or email query parameter.
- GET /reference.json: This document.

## Events you send
- customer.upserted [scope: customers:write]: Create a customer, or update the one with the same phone or email. required: name, phone or email.
- lead.created [scope: leads:write]: A new prospect who has not bought yet. required: name, phone or email.
- order.created [scope: orders:write]: A new order with its line items. required: external_id, customer.name, items[].name, items[].quantity, items[].unit_price, currency, total.
- payment.succeeded [scope: orders:write]: A payment for an order went through. required: order_external_id, amount, currency.
- payment.refunded [scope: orders:write]: A payment for an order was refunded. required: order_external_id, amount, currency.
- subscription.started [scope: events:write]: A customer started a subscription. required: external_id, customer, plan.
- subscription.renewed [scope: events:write]: A subscription renewed for another period. required: external_id, customer, plan.
- subscription.canceled [scope: events:write]: A customer canceled a subscription. required: external_id, customer, plan.
- booking.created [scope: events:write]: A customer booked a time slot. required: external_id, customer, starts_at.
- booking.updated [scope: events:write]: A booking changed, for example to a new time. required: external_id, customer, starts_at.
- booking.canceled [scope: events:write]: A booking was canceled. required: external_id, customer, starts_at.
- form.submitted [scope: events:write]: A visitor submitted a form on your site. required: form, fields.
- Custom events: type matches custom.<name> [scope: events:write], max 32768 bytes

## Webhook events Zahrex sends
- lead.created: A new lead was created for your project.
- lead.stage_changed: A lead moved to another stage.
- subscription.started: A lead's subscription started.
- subscription.renewed: A lead's subscription renewed.
- subscription.canceled: A lead's subscription was canceled.

## Webhooks
- Signature header: Zahrex-Signature
- Signature format: t=<unix>,v1=<hex>
- Signed payload: <t>.<raw body>
- Algorithm: HMAC-SHA256
- Timeout: 10s
- Retry schedule (seconds): 60, 300, 1800, 7200, 21600, 43200
- Endpoint auto-disabled after 20 consecutive failures
- Max endpoints per app: 5
- Endpoints must use HTTPS

## Limits
- Requests per minute: 60
- Burst: 120
- Max events per batch: 100
- Max body size: 262144 bytes
- Idempotency window: 7 days

## Errors
- 400 invalid_request: The token request body is malformed or grant_type is missing.
- 400 unsupported_grant_type: Only client_credentials is supported.
- 400 invalid_scope: A requested scope is not granted to this app.
- 401 invalid_client: The client id or secret is wrong.
- 401 (message): The API key or access token is missing, invalid, expired or revoked.
- 403 scope_required: The key or token lacks the scope this call needs.
- 403 capability_required: The organization does not have the platform capability.
- 413 payload_too_large: The request body is over the size limit.
- 422 invalid_json: The body is not valid JSON.
- 422 too_many_events: The batch holds more events than the limit.
- 422 idempotency_key_too_long: The Idempotency-Key header is over 128 characters.
- 429 rate_limited: Too many requests; wait for the Retry-After seconds.

## Error shapes
- Token endpoint: {"error":"<code>","error_description":"<message>"}
- Other endpoints: {"detail":"<code or message>"}