Version 1.0

API Reference

REST API for placing and managing click-to-call telephony calls. All requests and responses are JSON over HTTPS. Base URL:

https://api.clouddialer.in

New to the integration? Start with the Integration Guide for the architecture and call flow, then use this reference for endpoint detail.

Authentication

Send your API key (issued during onboarding) as a Bearer token on every request:

Authorization: Bearer <your-api-key>

🔒 Keep this key in your backend only — never in browser-side code. On failure the API returns 401.

Initiate a call

POST/calls

Places a two-leg call: the agent leg rings first, then the customer, bridged together. Identify the agent with either agent_number (a real phone number) or crm_username (your own agent ID → routes to their browser softphone) — not both.

Body

Field	Type	Description
`from_number` required	string	Caller-ID to present, from the numbers assigned to your account.
`to_number` required	string	Customer's number (10-digit or +91).
`uuid` required	string	Your own call ID, echoed back in the result push.
`crm_username`	string	Your agent ID → browser softphone. Mutually exclusive with agent_number.
`agent_number`	string	Agent's real phone number. Mutually exclusive with crm_username.
`recording` optional	boolean	Default `true`.
`max_ring_time` optional	integer	Seconds to ring. Default `30`.

Example request

POST /calls
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "from_number":  "919800000000",
  "to_number":    "9876543210",
  "crm_username": "agent.017",
  "uuid":         "550e8400-e29b-41d4-a716-446655440000"
}

Response

200 OK

{ "status": "success", "call_id": "5deb67aa-…", "message": "Call initiated" }

Status	Meaning
200	Call accepted and queued
400	Validation error, unrecognised caller-ID, or unknown agent
401	Invalid or missing API key
403	Request origin not permitted for this account
502	Telephony platform could not queue the call

Get call status

GET/calls/{call_id}

Poll a call's live status, duration, recording URL, and per-participant detail. Optional — the result push covers the standard flow — but handy for a live status UI or debugging.

Response

200 OK

{
  "status": "success",
  "call_id": "5deb67aa-…",
  "uuid": "your-own-call-id",
  "call_status": "ANSWER",
  "duration": 42,
  "recording_url": "https://api.clouddialer.in/recordings/crm_….wav",
  "start_time": "2026-07-03T10:00:00Z",
  "end_time": null,
  "legs": [
    { "role": "agent",       "number": "agent.017",  "status": "JOINED" },
    { "role": "destination", "number": "9876543210", "status": "JOINED" }
  ]
}

call_status is one of INITIATED, ANSWER, NO_ANSWER, BUSY, FAILED, CANCELED. Each leg's status is DIALING, JOINED, LEFT, or FAILED.

Add a participant (transfer / conference)

POST/calls/{call_id}/add-leg

Dials one more number into an already-active call — a warm transfer or three-way conference. If the added participant doesn't answer, the existing call is unaffected.

Body

Field	Type	Description
`number` required	string	10-digit or +91 number to add.
`max_ring_time` optional	integer	Default `30`.

Response

200 OK

{ "status": "success", "message": "Leg queued", "leg_id": 3 }

Health check

GET/health

Unauthenticated liveness check for your monitoring.

200 OK

{ "status": "success" }

Download a recording

GET/recordings/{filename}

Direct download of a call recording, using the exact URL provided in the result push. The unguessable per-call filename is the access control — treat recording URLs as private. Returns the audio file, or 404 if not found.

Call result push

When a call ends we POST the full result to the callback URL you provide during onboarding — JSON, up to 3 retries, de-duplicate on uuid. Full field list and mechanics are in the Integration Guide.

POST <your callback URL>
Content-Type: application/json

{
  "call_id": "5deb67aa-…", "uuid": "your-own-call-id",
  "status": "ANSWER", "duration": 150,
  "customer_number": "9876543210", "crm_username": "agent.017",
  "call_type": "browser", "disposition": "CRM_CALL",
  "recording_url": "https://api.clouddialer.in/recordings/crm_….wav",
  "start_time": "2026-07-03T10:00:00Z", "end_time": "2026-07-03T10:02:30Z"
}