# Place a call (/api-reference/calls/createCall)

## POST /api/v1/calls/

Operation ID: `createCall`
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.

### Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `Idempotency-Key` | header | no | 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. |

### Request body

`application/json` (required)

```json
{
  "additionalProperties": false,
  "description": "Who to call, with which agent, and what to tell the agent.",
  "properties": {
    "agentId": {
      "description": "Agent that speaks on the call. Archived agents cannot call.",
      "title": "Agentid",
      "type": "string"
    },
    "fromNumberId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Your phone number to call from (`GET /phone-numbers`). Omitted: a free number from the agent's phone numbers.",
      "title": "Fromnumberid"
    },
    "leadId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Lead this call belongs to; its phone must match `to`. Omitted: the lead with this number, or a new lead named `name`.",
      "title": "Leadid"
    },
    "metadata": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "description": "Your own data (at most 4096 bytes of JSON). Returned as `metadata` on the call (`GET /calls/{callId}`); never spoken.",
      "title": "Metadata"
    },
    "name": {
      "anyOf": [
        {
          "maxLength": 255,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Name for a new lead. Ignored when the lead exists.",
      "title": "Name"
    },
    "to": {
      "description": "Number to call in E.164 format, e.g. `+919812345678`.",
      "maxLength": 32,
      "title": "To",
      "type": "string"
    },
    "variables": {
      "anyOf": [
        {
          "additionalProperties": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              }
            ]
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "description": "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.",
      "title": "Variables"
    }
  },
  "required": [
    "agentId",
    "to"
  ],
  "title": "CreateCallRequest",
  "type": "object"
}
```

Example:

```json
{
  "agentId": "4f6d2c1a-9b7e-4c3d-8a21-5e0f7b9c1d23",
  "metadata": {
    "crmId": "0065g00000XyZ"
  },
  "name": "Asha Verma",
  "to": "+919812345678",
  "variables": {
    "delivery_date": "Friday",
    "order_id": "A-1042"
  }
}
```

### Responses

#### 201 OK

Example (example):

```json
{
  "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
}
```

#### 400 Bad request: `bad_request`, `campaign_has_no_agent`, `dial_rejected`.

Example (The request could not be processed.):

```json
{
  "detail": "The request could not be processed.",
  "error": {
    "code": "bad_request",
    "docUrl": "https://docs.callmitra.ai/errors/bad_request",
    "message": "The request could not be processed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

Example (Campaign has no agent assigned.):

```json
{
  "detail": "Campaign has no agent assigned.",
  "error": {
    "code": "campaign_has_no_agent",
    "docUrl": "https://docs.callmitra.ai/errors/campaign_has_no_agent",
    "message": "Campaign has no agent assigned.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

Example (The carrier rejected the call.):

```json
{
  "detail": "The carrier rejected the call.",
  "error": {
    "code": "dial_rejected",
    "docUrl": "https://docs.callmitra.ai/errors/dial_rejected",
    "message": "The carrier rejected the call.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`.

Example (The API key has expired.):

```json
{
  "detail": "The API key has expired.",
  "error": {
    "code": "api_key_expired",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_expired",
    "message": "The API key has expired.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (The API key is invalid or has been revoked.):

```json
{
  "detail": "The API key is invalid or has been revoked.",
  "error": {
    "code": "invalid_api_key",
    "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key",
    "message": "The API key is invalid or has been revoked.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (Authentication required.):

```json
{
  "detail": "Authentication required.",
  "error": {
    "code": "unauthenticated",
    "docUrl": "https://docs.callmitra.ai/errors/unauthenticated",
    "message": "Authentication required.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

#### 402 Payment required: `payment_required`.

Example (Your account does not have enough balance or an active plan for this request.):

```json
{
  "detail": "Your account does not have enough balance or an active plan for this request.",
  "error": {
    "code": "payment_required",
    "docUrl": "https://docs.callmitra.ai/errors/payment_required",
    "message": "Your account does not have enough balance or an active plan for this request.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "billing_error"
  }
}
```

#### 403 Forbidden: `api_key_scope_denied`, `permission_denied`.

Example (The API key does not have the scope required for this request.):

```json
{
  "detail": "The API key does not have the scope required for this request.",
  "error": {
    "code": "api_key_scope_denied",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied",
    "message": "The API key does not have the scope required for this request.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

Example (You do not have permission to perform this action.):

```json
{
  "detail": "You do not have permission to perform this action.",
  "error": {
    "code": "permission_denied",
    "docUrl": "https://docs.callmitra.ai/errors/permission_denied",
    "message": "You do not have permission to perform this action.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

#### 404 Not found: `agent_not_found`, `campaign_not_found`, `lead_not_found`, `lead_not_on_campaign`, `phone_number_not_found`.

Example (Agent not found.):

```json
{
  "detail": "Agent not found.",
  "error": {
    "code": "agent_not_found",
    "docUrl": "https://docs.callmitra.ai/errors/agent_not_found",
    "message": "Agent not found.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "not_found_error"
  }
}
```

Example (Campaign not found.):

```json
{
  "detail": "Campaign not found.",
  "error": {
    "code": "campaign_not_found",
    "docUrl": "https://docs.callmitra.ai/errors/campaign_not_found",
    "message": "Campaign not found.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "not_found_error"
  }
}
```

Example (Lead not found.):

```json
{
  "detail": "Lead not found.",
  "error": {
    "code": "lead_not_found",
    "docUrl": "https://docs.callmitra.ai/errors/lead_not_found",
    "message": "Lead not found.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "not_found_error"
  }
}
```

Example (Lead is not on this campaign.):

```json
{
  "detail": "Lead is not on this campaign.",
  "error": {
    "code": "lead_not_on_campaign",
    "docUrl": "https://docs.callmitra.ai/errors/lead_not_on_campaign",
    "message": "Lead is not on this campaign.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "not_found_error"
  }
}
```

Example (Phone number not found.):

```json
{
  "detail": "Phone number not found.",
  "error": {
    "code": "phone_number_not_found",
    "docUrl": "https://docs.callmitra.ai/errors/phone_number_not_found",
    "message": "Phone number not found.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "not_found_error"
  }
}
```

#### 409 Conflict: `campaign_call_limit_reached`, `campaign_dial_busy`, `campaign_no_eligible_leads`, `campaign_not_running`, `carrier_capacity_reached`, `idempotency_key_reused`, `idempotency_request_in_progress`, `lead_call_in_progress`, `number_on_dnc`.

Example (Campaign already has an active call in progress.):

```json
{
  "detail": "Campaign already has an active call in progress.",
  "error": {
    "code": "campaign_call_limit_reached",
    "docUrl": "https://docs.callmitra.ai/errors/campaign_call_limit_reached",
    "message": "Campaign already has an active call in progress.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

Example (Campaign dial in progress.):

```json
{
  "detail": "Campaign dial in progress.",
  "error": {
    "code": "campaign_dial_busy",
    "docUrl": "https://docs.callmitra.ai/errors/campaign_dial_busy",
    "message": "Campaign dial in progress.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

Example (No leads available for calling.):

```json
{
  "detail": "No leads available for calling.",
  "error": {
    "code": "campaign_no_eligible_leads",
    "docUrl": "https://docs.callmitra.ai/errors/campaign_no_eligible_leads",
    "message": "No leads available for calling.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

Example (Campaign is not active.):

```json
{
  "detail": "Campaign is not active.",
  "error": {
    "code": "campaign_not_running",
    "docUrl": "https://docs.callmitra.ai/errors/campaign_not_running",
    "message": "Campaign is not active.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

Example (The phone number or carrier account is at its call limit.):

```json
{
  "detail": "The phone number or carrier account is at its call limit.",
  "error": {
    "code": "carrier_capacity_reached",
    "docUrl": "https://docs.callmitra.ai/errors/carrier_capacity_reached",
    "message": "The phone number or carrier account is at its call limit.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

Example (This Idempotency-Key was already used with a different request body.):

```json
{
  "detail": "This Idempotency-Key was already used with a different request body.",
  "error": {
    "code": "idempotency_key_reused",
    "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request body.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "idempotency_error"
  }
}
```

Example (A request with this Idempotency-Key is still being processed.):

```json
{
  "detail": "A request with this Idempotency-Key is still being processed.",
  "error": {
    "code": "idempotency_request_in_progress",
    "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress",
    "message": "A request with this Idempotency-Key is still being processed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "idempotency_error"
  }
}
```

Example (Lead already has an active call.):

```json
{
  "detail": "Lead already has an active call.",
  "error": {
    "code": "lead_call_in_progress",
    "docUrl": "https://docs.callmitra.ai/errors/lead_call_in_progress",
    "message": "Lead already has an active call.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

Example (This number is on the DNC list and will not be dialed.):

```json
{
  "detail": "This number is on the DNC list and will not be dialed.",
  "error": {
    "code": "number_on_dnc",
    "docUrl": "https://docs.callmitra.ai/errors/number_on_dnc",
    "message": "This number is on the DNC list and will not be dialed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

#### 422 Invalid parameters: `agent_state_blocked`, `destination_not_allowed`, `invalid_phone_number`, `parameter_invalid`, `phone_number_not_dialable`.

Example (The agent cannot make this change yet.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "agent_state_blocked",
    "docUrl": "https://docs.callmitra.ai/errors/agent_state_blocked",
    "message": "The agent cannot make this change yet.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

Example (Calls to this country are not enabled for your workspace.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "destination_not_allowed",
    "docUrl": "https://docs.callmitra.ai/errors/destination_not_allowed",
    "message": "Calls to this country are not enabled for your workspace.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

Example (The phone number is not valid.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "invalid_phone_number",
    "docUrl": "https://docs.callmitra.ai/errors/invalid_phone_number",
    "message": "The phone number is not valid.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

Example (One or more parameters are invalid.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "parameter_invalid",
    "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid",
    "message": "One or more parameters are invalid.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

Example (This phone number cannot place calls.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "phone_number_not_dialable",
    "docUrl": "https://docs.callmitra.ai/errors/phone_number_not_dialable",
    "message": "This phone number cannot place calls.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 429 Too many requests: `campaign_daily_cap_reached`, `concurrent_call_limit_reached`, `daily_call_limit_reached`, `rate_limit_exceeded`.

Example (Daily call limit reached for this campaign.):

```json
{
  "detail": "Daily call limit reached for this campaign.",
  "error": {
    "code": "campaign_daily_cap_reached",
    "docUrl": "https://docs.callmitra.ai/errors/campaign_daily_cap_reached",
    "message": "Daily call limit reached for this campaign.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "rate_limit_error"
  }
}
```

Example (Merchant concurrent call limit reached.):

```json
{
  "detail": "Merchant concurrent call limit reached.",
  "error": {
    "code": "concurrent_call_limit_reached",
    "docUrl": "https://docs.callmitra.ai/errors/concurrent_call_limit_reached",
    "message": "Merchant concurrent call limit reached.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "rate_limit_error"
  }
}
```

Example (Your workspace reached its daily limit for calls placed through the API.):

```json
{
  "detail": "Your workspace reached its daily limit for calls placed through the API.",
  "error": {
    "code": "daily_call_limit_reached",
    "docUrl": "https://docs.callmitra.ai/errors/daily_call_limit_reached",
    "message": "Your workspace reached its daily limit for calls placed through the API.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "rate_limit_error"
  }
}
```

Example (Too many requests. Slow down and retry later.):

```json
{
  "detail": "Too many requests. Slow down and retry later.",
  "error": {
    "code": "rate_limit_exceeded",
    "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded",
    "message": "Too many requests. Slow down and retry later.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "rate_limit_error"
  }
}
```

#### 500 Server error: `internal_error`.

Example (Something went wrong on our side.):

```json
{
  "detail": "Something went wrong on our side.",
  "error": {
    "code": "internal_error",
    "docUrl": "https://docs.callmitra.ai/errors/internal_error",
    "message": "Something went wrong on our side.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "api_error"
  }
}
```

#### 502 Error: `dial_failed`.

Example (Failed to place outbound call.):

```json
{
  "detail": "Failed to place outbound call.",
  "error": {
    "code": "dial_failed",
    "docUrl": "https://docs.callmitra.ai/errors/dial_failed",
    "message": "Failed to place outbound call.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "api_error"
  }
}
```

#### 503 Service unavailable: `service_unavailable`.

Example (The service is temporarily unavailable.):

```json
{
  "detail": "The service is temporarily unavailable.",
  "error": {
    "code": "service_unavailable",
    "docUrl": "https://docs.callmitra.ai/errors/service_unavailable",
    "message": "The service is temporarily unavailable.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "api_error"
  }
}
```

### Error codes

- [`bad_request`](/errors/bad_request)
- [`campaign_has_no_agent`](/errors/campaign_has_no_agent)
- [`dial_rejected`](/errors/dial_rejected)
- [`api_key_expired`](/errors/api_key_expired)
- [`invalid_api_key`](/errors/invalid_api_key)
- [`unauthenticated`](/errors/unauthenticated)
- [`payment_required`](/errors/payment_required)
- [`api_key_scope_denied`](/errors/api_key_scope_denied)
- [`permission_denied`](/errors/permission_denied)
- [`agent_not_found`](/errors/agent_not_found)
- [`campaign_not_found`](/errors/campaign_not_found)
- [`lead_not_found`](/errors/lead_not_found)
- [`lead_not_on_campaign`](/errors/lead_not_on_campaign)
- [`phone_number_not_found`](/errors/phone_number_not_found)
- [`campaign_call_limit_reached`](/errors/campaign_call_limit_reached)
- [`campaign_dial_busy`](/errors/campaign_dial_busy)
- [`campaign_no_eligible_leads`](/errors/campaign_no_eligible_leads)
- [`campaign_not_running`](/errors/campaign_not_running)
- [`carrier_capacity_reached`](/errors/carrier_capacity_reached)
- [`idempotency_key_reused`](/errors/idempotency_key_reused)
- [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress)
- [`lead_call_in_progress`](/errors/lead_call_in_progress)
- [`number_on_dnc`](/errors/number_on_dnc)
- [`agent_state_blocked`](/errors/agent_state_blocked)
- [`destination_not_allowed`](/errors/destination_not_allowed)
- [`invalid_phone_number`](/errors/invalid_phone_number)
- [`parameter_invalid`](/errors/parameter_invalid)
- [`phone_number_not_dialable`](/errors/phone_number_not_dialable)
- [`campaign_daily_cap_reached`](/errors/campaign_daily_cap_reached)
- [`concurrent_call_limit_reached`](/errors/concurrent_call_limit_reached)
- [`daily_call_limit_reached`](/errors/daily_call_limit_reached)
- [`rate_limit_exceeded`](/errors/rate_limit_exceeded)
- [`internal_error`](/errors/internal_error)
- [`dial_failed`](/errors/dial_failed)
- [`service_unavailable`](/errors/service_unavailable)
