Skip to Content
CallMitraDocs
API referenceCalls

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.

POST
/api/v1/calls/

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.

Authorization

headerX-API-Key<token>

Create in the console: Settings → API & webhooks.

Header Parameters

Idempotency-Key?string

Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice.

Lengthlength <= 255

Request Body

application/json
  1. body

Who to call, with which agent, and what to tell the agent.

agentId*Agentid

Agent 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*To

Number to call in E.164 format, e.g. +919812345678.

Lengthlength <= 32
variables?|

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.

Response Body

OK

application/json
  1. 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?Success

Always true on a 2xx response.

Defaulttrue
[key: string]?any
Example Request
curl -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"  }}'
Example Response
{  "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}