Place and read calls
Call any number with an agent in one request, then read the call, its transcript, recording and reports.
This guide covers the two halves of the Calls API: placing a single call with POST /api/v1/calls/, and reading calls, transcripts, recordings and reports afterwards.
Pick the right way to call
| You want to | Use |
|---|---|
| Call one number now with an agent, no campaign set up | POST /api/v1/calls/ (this page) |
| Call many leads on a schedule, with a calling window, retries and a daily limit | A campaign (Campaigns) |
| Call a lead that is already on a running campaign, right now | POST /api/v1/instant/call-now with leadId and campaignId |
| Call a lead through the first running campaign it belongs to | POST /api/v1/leads/{lead_id}/call-now |
| Try an agent before going live | POST /api/v1/agents/{agent_id}/test-call |
The two call-now endpoints use the campaign's agent and phone numbers and answer 200 with the same body as POST /calls. They do not accept Idempotency-Key.
Place a call
POST /api/v1/calls/ calls to now with the agent. You need a key with full access that can reach Calls (Authentication).
curl -X POST https://api.callmitra.ai/api/v1/calls/ \
-H "X-API-Key: $CALLMITRA_API_KEY" \
-H "Idempotency-Key: order-A-1042-delivery-call" \
-H "Content-Type: application/json" \
-d '{
"agentId": "4f6d2c1a-9b7e-4c3d-8a21-5e0f7b9c1d23",
"to": "+919812345678",
"name": "Asha Verma",
"variables": { "order_id": "A-1042", "delivery_date": "Friday" },
"metadata": { "crmId": "0065g00000XyZ" }
}'Request body
| Field | Type | Required | Notes |
|---|---|---|---|
agentId | string | yes | Agent that speaks on the call (GET /agents). An archived agent answers 422 agent_state_blocked. |
to | string | yes | Number to call, E.164, up to 32 characters. Spaces, dashes, dots and brackets are removed first; the rest must be + and 7 to 15 digits, not starting with 0. Otherwise 422 invalid_phone_number. |
fromNumberId | string | no | ID of your phone number to call from (GET /phone-numbers). Omitted: a free number from the agent's phone numbers. |
leadId | string | no | Lead this call belongs to. Its phone must match to. |
name | string | no | Name for a new lead, up to 255 characters. Ignored when the lead already exists. |
variables | object | no | Up to 50 values the agent's script can use as {{name}}. Values are strings, numbers or booleans. Keys use letters, digits and underscores, do not start with a digit, and are at most 64 characters. |
metadata | object | no | Your own data, at most 4096 bytes of JSON. Never spoken. Returned unchanged as metadata on the call. |
Any other field is rejected with 422 parameter_invalid. There is no per-call webhook URL: results go to your workspace's webhooks.
Which lead the call belongs to
Every call belongs to a lead, so the call shows up in your reports and lead history:
- With
leadId, that lead is used. A lead from another workspace answers404lead_not_found; a lead whose phone does not matchtoanswers422parameter_invalidwithparam: "leadId". - Without
leadId, CallMitra uses the newest lead in your workspace with exactly this number. - If there is none, it creates a lead with
source: "api", namedname(or the number itself when you send noname).
Caller ID
The call runs on the agent's instant campaign: a campaign CallMitra creates for the agent the first time it is needed, named after the agent with Instant at the end. Its numbers are the agent's numbers.
- Without
fromNumberId, CallMitra picks a free number from that pool. - With
fromNumberId, only that number is used. A number not in your workspace answers404phone_number_not_found. A number that is inactive or has no outbound carrier credentials answers422phone_number_not_dialable.
Response
201 Created means the carrier accepted the dial. It does not mean the call was answered. Follow the call with GET /calls/{call_id} or the call.completed webhook.
{
"success": true,
"call": {
"id": "8c1e5b7a-2d4f-4e9a-b6c3-1f0a9d8e7b65",
"leadId": "b2a7c9d1-6e3f-4a8b-9c0d-1e2f3a4b5c6d",
"leadName": "Asha Verma",
"campaignId": "e3f4a5b6-c7d8-4e9f-a0b1-c2d3e4f5a6b7",
"campaignName": "Delivery desk Instant",
"providerCallId": "CA5f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c",
"status": "queued",
"phoneNumber": "+919812345678",
"phoneNumberId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}
}| Field | Meaning |
|---|---|
call.id | Call ID. Use it with every read endpoint below. |
call.leadId, call.leadName | The lead that was used or created. |
call.campaignId, call.campaignName | The agent's instant campaign. |
call.providerCallId | The carrier's call ID. |
call.status | Carrier status at dial time, usually initiated or queued. |
call.phoneNumber | The number being dialed. |
call.phoneNumberId | Your phone number the call is placed from. |
sipResponse | The carrier's raw answer to the dial request, when present. Fields vary by carrier; do not depend on them. |
One request, one dial
Each POST /calls dials once.
- A call that is not answered, is busy or times out is not redialed.
- A refused dial is not queued to try later. The lead does not stay queued on the agent's instant campaign.
- For a second attempt, place another call. Use a new
Idempotency-Key, or the first result is replayed. - One exception: the callee may ask to be called back, and the agent may book that callback during the call. The booked callback is placed at the agreed time.
Retry safely with Idempotency-Key
A timeout does not tell you whether the call was placed. Send an Idempotency-Key header (1 to 255 characters) and reuse it when you retry the same request. Within 24 hours, the same key with the same body returns the first result with Idempotent-Replayed: true instead of calling again. The full rules are in Idempotency.
Refusals are replayed too
Client errors (4xx) are stored like successes, except 401, 403, 404 and 429. If a call was refused with 409 campaign_call_limit_reached and you retry later with the same key, you get the same 409 back. Once the refusal is resolved, try again with a new key. 5xx, 401, 403, 404 and 429 responses are not stored, so a retry with the same key runs again.
Limits and refusals
These limits apply to every direct call. Each refusal has its own code, and the error body follows the usual error format.
| What | Status and code | What to do |
|---|---|---|
to is outside your workspace's home country. The home country comes from your billing address (India when none is set); support can enable more countries. | 422 destination_not_allowed, param: "to" | The message lists the allowed codes, for example +91. Contact support to call other countries. |
Your workspace placed its daily number of calls through POST /calls. The count runs per UTC day. | 429 daily_call_limit_reached | Wait for Retry-After (seconds until 00:00 UTC). Use a campaign for large volumes, or ask support to raise the limit. |
| The daily call counter is briefly unavailable. Direct calls fail closed. | 503 service_unavailable | Retry shortly. |
| The number is on your do-not-call list. Any lead in your workspace with this number (same number, or same last 10 digits) that opted out blocks the call. | 409 number_on_dnc | Do not call. Remove the number from do-not-call only if the person agreed to be called again. |
| The agent's instant campaign already has a call in progress. By default it runs one call at a time, so one agent places one direct call at a time. | 409 campaign_call_limit_reached | detail.activeCallId is the call in progress. Retry when it ends. |
| Another call for the same agent is being placed at this moment. | 409 campaign_dial_busy | Wait a second and retry. |
| This lead already has a call ringing or connected. | 409 lead_call_in_progress | Retry after it ends. |
| Your plan's limit on simultaneous calls is in use. | 429 concurrent_call_limit_reached | Retry when a call ends. |
| The workspace is out of balance or has no plan that covers calls. | 402 payment_required | Top up or change the plan. |
| The calling number or its carrier account is at its call limit. | 409 carrier_capacity_reached | Retry in a moment. |
| The agent's instant campaign is stopped. | 409 campaign_not_running | Start it with POST /campaigns/{campaign_id}/start. |
| The carrier refused the dial before it rang. | 400 dial_rejected | Read the message. The failed call is recorded; its ID is in detail.call.id. |
| The carrier could not be reached. | 502 dial_failed | Retry. The failed call is recorded in detail.call.id. |
| The agent has no usable phone number, or another request problem. | 400 bad_request | Read the message and fix the setup. |
The API reference lists every code this endpoint can return. Your key's rate limit also applies.
No calling-window check on direct calls
A direct call is placed the moment you ask, at any hour. CallMitra does not check a calling window or time-of-day rules for POST /calls, POST /instant/call-now or POST /leads/{lead_id}/call-now. The do-not-call list is still checked. You are responsible for consent and for calling only at hours the rules allow, including TRAI rules for Indian numbers. See Calling in India.
Read calls
All read endpoints work with a read-only key that can reach Calls.
List calls
GET /api/v1/calls/ returns calls newest first.
| Parameter | Default | Notes |
|---|---|---|
cursor | Send it empty for the first page, then the nextCursor from the previous response. Cursor pages skip the total count and stay fast on long lists. | |
page | 1 | Page number, from 1. Ignored when cursor is sent. |
limit | 25 | Items per page, 1 to 200. |
search | Matches the phone number, customer name or phone, summary, or call name. | |
agentId, leadId, campaignId | Only calls of this agent, lead or campaign. | |
outcome | qualified, interested, callback, not_interested, no_response, no_answer, busy, call_failed or voicemail. | |
sentiment | positive, neutral or negative. | |
channel | inbound, browser (test calls), or instant / bulk (calls by agents in that calling mode). | |
hasRecording | true or false. | |
dateFilter | all | today (since 00:00 UTC), week (last 7 days), month (last 30 days) or all. |
includeTests | true | Set false to leave out test calls. |
There are two ways to page:
- Cursor mode (recommended for syncing): pass
cursor=on the first request. Each response has top-levelnextCursorandhasMore.nextCursorisnullon the last page. Thepaginationobject only hasitemsPerPage,hasNextPageandnextCursor. - Page mode: omit
cursor.paginationhascurrentPage,totalPages,totalItems,itemsPerPage,hasNextPageandhasPreviousPage. Matches are counted up to 10,000; above thattotalCappedistrueandtotalItemsis only a lower bound.
An unreadable cursor answers 422 parameter_invalid. See Pagination.
curl -G https://api.callmitra.ai/api/v1/calls/ \
-H "X-API-Key: $CALLMITRA_API_KEY" \
--data-urlencode "cursor=" \
--data-urlencode "limit=100" \
--data-urlencode "includeTests=false"Get one call
GET /api/v1/calls/{call_id} returns { "success": true, "call": { ... } }. An unknown ID, or a call in another workspace, answers 404 call_not_found. The fields you will use most:
| Field | Meaning |
|---|---|
status | initiated, ringing, answered, completed, no_answer, busy or failed. |
callType | manual for direct and call-now calls; also campaign, inbound or browser. |
startTime, endTime, duration | ISO 8601 times and talk time in seconds. |
outcome, outcomeCategory, merchantOutcome | successful or failed; the detailed disposition; the outcome shown in the console. |
endedReason, failureReason | Why the call ended, and why it failed when it did. |
summary, sentiment, callAnalysis | AI summary, sentiment, and post-call analysis when the agent has it on. |
extractedFields | Details the agent collected, keyed by your capture fields. |
transcript | User: / Assistant: lines. Use the transcript endpoint for parsed turns. |
hasRecording | Whether a recording can be downloaded. |
billableMinutes, billedInr | Minutes charged, and the amount in rupees. |
metadata | The metadata you sent with POST /calls, unchanged. |
fromNumber, phoneNumber, phoneNumberId | Caller ID used, the other party's number, and your number's ID. |
Transcript
GET /api/v1/calls/{call_id}/transcript returns the conversation as text and as ordered turns, plus the tools the agent called. role is user (the other party) or assistant (your agent). The transcript is empty while nothing has been said, and final once the call has ended.
{
"success": true,
"callId": "8c1e5b7a-2d4f-4e9a-b6c3-1f0a9d8e7b65",
"status": "completed",
"transcript": "Assistant: Hi, this is Asha from Acme.\nUser: Hi, yes.",
"turns": [
{ "role": "assistant", "text": "Hi, this is Asha from Acme." },
{ "role": "user", "text": "Hi, yes." }
],
"toolInvocations": []
}Recording
GET /api/v1/calls/{call_id}/recording returns the audio file itself, authenticated with your key like any other request. Check hasRecording on the call first.
- Format: stereo MP3 (
audio/mpeg). An older call that has not been converted yet is served as WAV (audio/wav). Read theContent-Typeheader. 404call_recording_not_found: the call was not answered, recording was off, or the audio is still being saved. Retry a minute after the call ends.410call_recording_deleted: your data retention policy removed the recording. It cannot be restored.
curl https://api.callmitra.ai/api/v1/calls/8c1e5b7a-2d4f-4e9a-b6c3-1f0a9d8e7b65/recording \
-H "X-API-Key: $CALLMITRA_API_KEY" \
-o call.mp3Reports
Both report endpoints use India Standard Time (Asia/Kolkata) to decide where a day or an hour starts.
Calls per day
GET /api/v1/calls/daily-counts takes days (1 to 90, default 30), ending today. Values outside that range are clamped to it. You get one entry per day, oldest first, with zeros for days without calls, plus totals. avgDurationSeconds is the average length of completed calls.
{
"success": true,
"days": 2,
"timezone": "Asia/Kolkata",
"totals": { "total": 12, "completed": 9, "failed": 1, "noAnswer": 2, "avgDurationSeconds": 74.2 },
"daily": [
{ "date": "2026-11-14", "total": 5, "completed": 4, "failed": 0, "noAnswer": 1, "avgDurationSeconds": 80.0 },
{ "date": "2026-11-15", "total": 7, "completed": 5, "failed": 1, "noAnswer": 1, "avgDurationSeconds": 69.6 }
]
}Performance
GET /api/v1/calls/performance returns totals, connect rate, conversion, the outcome and channel split, calls per hour and an agent leaderboard, with the range before it for comparison.
| Parameter | Default | Notes |
|---|---|---|
rangeDays | 30 | 7, 30 or 90, ending today. Any other value means 30. |
agentId | Only calls of this agent. | |
channel | instant, bulk, inbound or browser. | |
includeTests | false | Also count test calls placed from the console. |
Rates (connectRate, conversion, successRate) are between 0 and 1. byHour keys are hours 0 to 23 in IST; empty hours are left out. recent.today counts calls since midnight IST.