Skip to main content

​
Build against contracts that are explicit about ownership.

Callaro API responses follow stable envelope conventions so your integration can process list, detail, and mutation responses consistently. This section combines:
  • generated path contracts from openapi.yaml
  • handwritten workflow guides for implementation patterns and operational handling

​
Standard success envelope

{
  "data": {},
  "message": "Optional human-readable status",
  "meta": {
    "count": 10,
    "page": 1,
    "per_page": 10,
    "pages": 1
  },
  "request_id": "uuid"
}

​
Standard error envelope

{
  "error": "Human-readable error message",
  "error_code": "MACHINE_READABLE_CODE",
  "details": {},
  "errors": {},
  "request_id": "uuid"
}

​
Authentication headers

Authorization: Bearer <jwt>
X-Api-Key: sk_...
X-Partner-Api-Key: pk_...

​
Known contract status

The current docs set intentionally distinguishes source-of-truth boundaries while backend OpenAPI coverage is being expanded.
  • Endpoint operation signatures under generated API reference pages.
  • Response and parameter shape where present in openapi.yaml.
  • Security requirements attached to generated operations.
  • Webhook receiver behavior (retries, idempotency, ordering guidance).
  • Scope planning and role-to-key decision guidance.
  • Cross-endpoint workflows (for example campaign launch to analytics pull).
Some backend route families exist in application routes and permission matrix but are still being fully represented in source openapi.yaml. Those families are documented in handwritten guides with explicit caveats until generated coverage catches up.
Treat generated endpoint schemas as the first source for validation logic. Use handwritten guides for operational strategy, retries, and rollout safety.

​
API shape at a glance

  • Campaign execution is centered around bulk_call_campaigns.
  • Number inventory and provisioning flow through phone_numbers.
  • Contact lifecycle and compliance controls span contacts, segments, imports, exports, and DNC endpoints.
  • Call logs and operational audit data are exposed through voice_sessions, trace endpoints, and export jobs.
  • Partner-specific provisioning and multi-tenant actions live under partner route families.
For production rollout, pair generated schema validation with staged integration tests in sandbox before enabling write scopes in production.