Place a call
Calls `to` now with the agent, outside any campaign schedule. The number is saved as a lead (or matched to an existing one) and dialed through the agent's instant campaign, one call at a time per agent. Numbers on your do-not-call list are never dialed. The response means the carrier accepted the dial; follow the call with `GET /calls/{callId}` or call webhooks. Send an `Idempotency-Key` header so a retried request does not call twice. Each request dials once. A call that is not answered, is busy or times out is not redialed, and a refused dial is not queued for later: place another call if you want a second attempt. The one exception is a callback the callee asks for and the agent books during the call; that scheduled callback is placed at the agreed time. Toll-fraud limits: `to` must be in your workspace's home country (from your billing address; India when none is set) unless support enabled more countries, and each workspace may place a fixed number of calls per UTC day through this endpoint (`daily_call_limit_reached` with `Retry-After` until 00:00 UTC). Calling hours (TRAI / local quiet hours) are not enforced on direct calls: checking the time of day at the callee is your responsibility. Campaigns apply their own calling windows.
Calls to now with the agent, outside any campaign schedule. The number is saved as a lead (or matched to an existing one) and dialed through the agent's instant campaign, one call at a time per agent. Numbers on your do-not-call list are never dialed. The response means the carrier accepted the dial; follow the call with GET /calls/{callId} or call webhooks. Send an Idempotency-Key header so a retried request does not call twice.
Each request dials once. A call that is not answered, is busy or times out is not redialed, and a refused dial is not queued for later: place another call if you want a second attempt. The one exception is a callback the callee asks for and the agent books during the call; that scheduled callback is placed at the agreed time.
Toll-fraud limits: to must be in your workspace's home country (from your billing address; India when none is set) unless support enabled more countries, and each workspace may place a fixed number of calls per UTC day through this endpoint (daily_call_limit_reached with Retry-After until 00:00 UTC). Calling hours (TRAI / local quiet hours) are not enforced on direct calls: checking the time of day at the callee is your responsibility. Campaigns apply their own calling windows.
X-API-Key<token>Create in the console: Settings → API & webhooks.
Idempotency-Key?stringAny unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice.
length <= 255application/json- body
Who to call, with which agent, and what to tell the agent.
agentId*AgentidAgent that speaks on the call. Archived agents cannot call.
fromNumberId?|Your phone number to call from (GET /phone-numbers). Omitted: a free number from the agent's phone numbers.
leadId?|Lead this call belongs to; its phone must match to. Omitted: the lead with this number, or a new lead named name.
metadata?|Your own data (at most 4096 bytes of JSON). Returned as metadata on the call (GET /calls/{callId}); never spoken.
name?|Name for a new lead. Ignored when the lead exists.
to*ToNumber to call in E.164 format, e.g. +919812345678.
length <= 32variables?|Up to 50 values the agent's script can use as {{name}}. Keys are letters, digits and underscores and must not start with a digit.
OK
application/json- response
A call was handed to the carrier. Progress arrives on GET /calls/{callId} and webhooks.
call*The call that was placed.
sipResponse?|The carrier's answer to the dial request; fields vary by carrier.
success?SuccessAlways true on a 2xx response.
true[key: string]?anycurl -X POST 'https://api.callmitra.ai/api/v1/calls/' \ -H 'Content-Type: application/json' \ -d '{ "agentId": "4f6d2c1a-9b7e-4c3d-8a21-5e0f7b9c1d23", "metadata": { "crmId": "0065g00000XyZ" }, "name": "Asha Verma", "to": "+919812345678", "variables": { "delivery_date": "Friday", "order_id": "A-1042" }}'{ "call": { "campaignId": "e3f4a5b6-c7d8-4e9f-a0b1-c2d3e4f5a6b7", "campaignName": "Delivery desk Instant", "id": "8c1e5b7a-2d4f-4e9a-b6c3-1f0a9d8e7b65", "leadId": "b2a7c9d1-6e3f-4a8b-9c0d-1e2f3a4b5c6d", "leadName": "Asha Verma", "phoneNumber": "+919812345678", "phoneNumberId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "providerCallId": "CA5f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c", "status": "queued" }, "success": true}Call a lead in a campaign now POST
Places the call immediately, outside the dial schedule, with the campaign's agent and numbers. Numbers on do-not-call are never dialed. To call any number without a campaign, use `POST /calls`.
Get a call GET
Status, transcript, summary, outcome, cost and the details the agent collected.