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

OpenAPI endpoints

Use generated endpoint pages when you need request and response schema details.

Interactive testing

Use the playground guidance page before enabling authenticated interactive requests.

Postman onboarding

Use the Postman collection for fast request discovery and team-shared smoke tests.

​
Best first steps

  1. Review playground-access if you want browser-based testing.
  2. Open ../sdks/postman if you want downloadable request collections and environments.
  3. Move into resource guides or generated endpoints once your auth model is chosen.

​
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.

​
High-value workflow example

curl -X POST "https://api.callaro.ai/api/v1/bulk_call_campaigns" \
  -H "X-Api-Key: $CALLARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Workflow Example Campaign","agent_id":42,"timezone":"Asia/Kolkata","campaign_phone_number_ids":[101]}'

curl -X POST "https://api.callaro.ai/api/v1/contacts/import" \
  -H "X-Api-Key: $CALLARO_API_KEY" \
  -F "file=@contacts.csv" \
  -F 'column_mapping={"Phone":"phone_e164","First Name":"first_name"}'

curl -X POST "https://api.callaro.ai/api/v1/bulk_call_campaigns/123/launch" \
  -H "X-Api-Key: $CALLARO_API_KEY"

const createCampaign = await fetch('https://api.callaro.ai/api/v1/bulk_call_campaigns', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.CALLARO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Workflow Example Campaign',
    agent_id: 42,
    timezone: 'Asia/Kolkata',
    campaign_phone_number_ids: [101]
  })
});
const { data: campaign } = await createCampaign.json();

import requests

campaign = requests.post(
    'https://api.callaro.ai/api/v1/bulk_call_campaigns',
    headers={
        'X-Api-Key': 'YOUR_CALLARO_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'name': 'Workflow Example Campaign',
        'agent_id': 42,
        'timezone': 'Asia/Kolkata',
        'campaign_phone_number_ids': [101],
    },
    timeout=30,
)
print(campaign.json().get('data', {}).get('id'))
For production rollout, pair generated schema validation with staged integration tests in sandbox before enabling write scopes in production.