{"version":"2026-11-07","base_url":"https://api.zahrex.com/v1","auth":{"token_url":"https://api.zahrex.com/v1/oauth/token","token_ttl_seconds":3600,"grant_types":["client_credentials"],"api_key_prefixes":["zx_live_","zx_test_"]},"scopes":[{"id":"events:write","description":"Send subscription, booking, form and custom events."},{"id":"customers:write","description":"Create or update customers."},{"id":"leads:write","description":"Create leads."},{"id":"orders:write","description":"Send orders and their payments or refunds."},{"id":"catalog:read","description":"Read the organization's service and product catalog."},{"id":"customers:read","description":"Look up a customer by phone or email."}],"endpoints":[{"method":"POST","path":"/oauth/token","auth":"client_credentials","scope":null,"description":"Exchange a client id and secret for a one-hour access token."},{"method":"POST","path":"/events","auth":"token_or_key","scope":"depends on event type","description":"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."},{"method":"GET","path":"/catalog/services","auth":"token_or_key","scope":"catalog:read","description":"List the organization's active services."},{"method":"GET","path":"/catalog/products","auth":"token_or_key","scope":"catalog:read","description":"List the organization's products."},{"method":"GET","path":"/customers","auth":"token_or_key","scope":"customers:read","description":"Look up a customer by the phone or email query parameter."},{"method":"GET","path":"/reference.json","auth":"none","scope":null,"description":"This document."}],"events":[{"type":"customer.upserted","scope":"customers:write","description":"Create a customer, or update the one with the same phone or email.","required":["name","phone or email"],"optional":["city","external_id","source","note","tags","stage"],"example":{"name":"Sara Example","phone":"+212600000000","email":"sara@example.com","city":"Casablanca","tags":["vip"]}},{"type":"lead.created","scope":"leads:write","description":"A new prospect who has not bought yet.","required":["name","phone or email"],"optional":["city","external_id","source","note","tags","stage"],"example":{"name":"Sara Example","phone":"+212600000000","email":"sara@example.com","source":"pricing_page","stage":"signed_up"}},{"type":"order.created","scope":"orders:write","description":"A new order with its line items.","required":["external_id","customer.name","items[].name","items[].quantity","items[].unit_price","currency","total"],"optional":["customer.phone","customer.email","customer.city","status","payment_status"],"example":{"external_id":"ord_1001","customer":{"name":"Sara Example","phone":"+212600000000","email":"sara@example.com"},"items":[{"name":"Starter plan","quantity":1,"unit_price":29}],"currency":"USD","total":29,"payment_status":"pending"}},{"type":"payment.succeeded","scope":"orders:write","description":"A payment for an order went through.","required":["order_external_id","amount","currency"],"optional":[],"example":{"order_external_id":"ord_1001","amount":29,"currency":"USD"}},{"type":"payment.refunded","scope":"orders:write","description":"A payment for an order was refunded.","required":["order_external_id","amount","currency"],"optional":[],"example":{"order_external_id":"ord_1001","amount":29,"currency":"USD"}},{"type":"subscription.started","scope":"events:write","description":"A customer started a subscription.","required":["external_id","customer","plan"],"optional":["amount","currency","interval"],"example":{"external_id":"sub_2001","customer":{"name":"Sara Example","phone":"+212600000000","email":"sara@example.com"},"plan":"Pro","amount":29,"currency":"USD","interval":"month"}},{"type":"subscription.renewed","scope":"events:write","description":"A subscription renewed for another period.","required":["external_id","customer","plan"],"optional":["amount","currency","interval"],"example":{"external_id":"sub_2001","customer":{"name":"Sara Example","phone":"+212600000000","email":"sara@example.com"},"plan":"Pro","amount":29,"currency":"USD","interval":"month"}},{"type":"subscription.canceled","scope":"events:write","description":"A customer canceled a subscription.","required":["external_id","customer","plan"],"optional":["amount","currency","interval"],"example":{"external_id":"sub_2001","customer":{"name":"Sara Example","phone":"+212600000000","email":"sara@example.com"},"plan":"Pro"}},{"type":"booking.created","scope":"events:write","description":"A customer booked a time slot.","required":["external_id","customer","starts_at"],"optional":["ends_at","service"],"example":{"external_id":"bk_3001","customer":{"name":"Sara Example","phone":"+212600000000","email":"sara@example.com"},"starts_at":"2026-12-01T10:00:00Z","ends_at":"2026-12-01T10:30:00Z","service":"Consultation"}},{"type":"booking.updated","scope":"events:write","description":"A booking changed, for example to a new time.","required":["external_id","customer","starts_at"],"optional":["ends_at","service"],"example":{"external_id":"bk_3001","customer":{"name":"Sara Example","phone":"+212600000000","email":"sara@example.com"},"starts_at":"2026-12-02T10:00:00Z"}},{"type":"booking.canceled","scope":"events:write","description":"A booking was canceled.","required":["external_id","customer","starts_at"],"optional":["ends_at","service"],"example":{"external_id":"bk_3001","customer":{"name":"Sara Example","phone":"+212600000000","email":"sara@example.com"},"starts_at":"2026-12-01T10:00:00Z"}},{"type":"form.submitted","scope":"events:write","description":"A visitor submitted a form on your site.","required":["form","fields"],"optional":["customer"],"example":{"form":"contact","fields":{"message":"Hello"},"customer":{"name":"Sara Example","phone":"+212600000000","email":"sara@example.com"}}}],"custom_events":{"pattern":"custom.","scope":"events:write","max_bytes":32768},"outbound_events":[{"type":"lead.created","description":"A new lead was created for your project.","example":{"lead_id":"lead_example1","name":"Sara Example","phone":"+212600000000","email":"sara@example.com","stage":"signed_up","subscription":null,"project_id":"prj_example1"}},{"type":"lead.stage_changed","description":"A lead moved to another stage.","example":{"lead_id":"lead_example1","name":"Sara Example","phone":"+212600000000","email":"sara@example.com","stage":"trial","subscription":null,"project_id":"prj_example1","from":"signed_up","to":"trial"}},{"type":"subscription.started","description":"A lead's subscription started.","example":{"lead_id":"lead_example1","name":"Sara Example","phone":"+212600000000","email":"sara@example.com","stage":"paying","subscription":{"external_id":"sub_2001","plan":"Pro","status":"active","amount":29,"currency":"USD","interval":"month","started_at":"2026-11-01T09:00:00+00:00","renewed_at":null,"canceled_at":null},"project_id":"prj_example1"}},{"type":"subscription.renewed","description":"A lead's subscription renewed.","example":{"lead_id":"lead_example1","name":"Sara Example","phone":"+212600000000","email":"sara@example.com","stage":"paying","subscription":{"external_id":"sub_2001","plan":"Pro","status":"active","amount":29,"currency":"USD","interval":"month","started_at":"2026-11-01T09:00:00+00:00","renewed_at":"2026-12-01T09:00:00+00:00","canceled_at":null},"project_id":"prj_example1"}},{"type":"subscription.canceled","description":"A lead's subscription was canceled.","example":{"lead_id":"lead_example1","name":"Sara Example","phone":"+212600000000","email":"sara@example.com","stage":"churned","subscription":{"external_id":"sub_2001","plan":"Pro","status":"canceled","amount":29,"currency":"USD","interval":"month","started_at":"2026-11-01T09:00:00+00:00","renewed_at":null,"canceled_at":"2026-12-15T09:00:00+00:00"},"project_id":"prj_example1"}}],"webhook":{"signature_header":"Zahrex-Signature","signature_format":"t=,v1=","signed_payload":".","algorithm":"HMAC-SHA256","other_headers":["Zahrex-Event-Id","Zahrex-Delivery-Id"],"timeout_seconds":10,"retry_schedule_seconds":[60,300,1800,7200,21600,43200],"max_consecutive_failures":20,"max_endpoints_per_app":5,"https_only":true},"limits":{"requests_per_minute":60,"burst":120,"max_batch_events":100,"max_body_bytes":262144,"idempotency_days":7},"stages":["new","signed_up","trial","paying","churned","lost"],"errors":[{"status":400,"code":"invalid_request","meaning":"The token request body is malformed or grant_type is missing."},{"status":400,"code":"unsupported_grant_type","meaning":"Only client_credentials is supported."},{"status":400,"code":"invalid_scope","meaning":"A requested scope is not granted to this app."},{"status":401,"code":"invalid_client","meaning":"The client id or secret is wrong."},{"status":401,"code":null,"meaning":"The API key or access token is missing, invalid, expired or revoked."},{"status":403,"code":"scope_required","meaning":"The key or token lacks the scope this call needs."},{"status":403,"code":"capability_required","meaning":"The organization does not have the platform capability."},{"status":413,"code":"payload_too_large","meaning":"The request body is over the size limit."},{"status":422,"code":"invalid_json","meaning":"The body is not valid JSON."},{"status":422,"code":"too_many_events","meaning":"The batch holds more events than the limit."},{"status":422,"code":"idempotency_key_too_long","meaning":"The Idempotency-Key header is over 128 characters."},{"status":429,"code":"rate_limited","meaning":"Too many requests; wait for the Retry-After seconds."}],"error_format":{"oauth_token":{"error":"","error_description":""},"other":{"detail":""}}}