> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.formantai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.formantai.com/_mcp/server.

# Make a Call

> Start one outbound call with a configured FormantAI Voice agent.

Use `POST /v1/call` for transactional calls, test calls, retries, or product workflows where one backend action should trigger one phone call.

```http
POST /v1/call
```

## Required inputs

| Field        | Type    | Description                                                           |
| ------------ | ------- | --------------------------------------------------------------------- |
| `agent_id`   | integer | Agent that should handle the call.                                    |
| `parameters` | array   | Call parameters passed into the agent. Must include `customer_phone`. |

`customer_phone` must be present inside `parameters` because it is the destination phone number.

## Minimal request

```bash
curl -X POST "https://api.voice.formantai.com/v1/call" \
  -H "Authorization: Bearer $FORMANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 123,
    "parameters": [
      { "name": "customer_phone", "value": "+919876543210" },
      { "name": "customer_name", "value": "Rahul" }
    ]
  }'
```

## Response

```json
{
  "data": {
    "agent_id": 123,
    "conversation_id": null,
    "scheduled_for": null,
    "status": "initiated",
    "trace_id": "f9e8d7c6-1234-4d5e-8f90-123456789abc"
  }
}
```

Store `trace_id` for debugging. If you pass `conversation_id`, store it to connect retries or resumed attempts.

## Request body

| Field             | Type              | Required | Description                                                          |
| ----------------- | ----------------- | -------- | -------------------------------------------------------------------- |
| `agent_id`        | integer           | Yes      | Agent ID from the dashboard.                                         |
| `parameters`      | array             | Yes      | Array of `{ name, value }` objects. Must include `customer_phone`.   |
| `conversation_id` | string            | No       | Link this call to an existing conversation chain.                    |
| `idempotency_key` | string            | No       | Prevent duplicate submissions for 24 hours. UUID recommended.        |
| `metadata`        | string            | No       | Opaque metadata passed through for downstream workflows.             |
| `retry_context`   | object            | No       | Resume context from a prior attempt.                                 |
| `scheduled_for`   | ISO 8601 datetime | No       | Schedule the call within the next 30 days. Omit for immediate calls. |

## Scheduled call

```json
{
  "agent_id": 123,
  "scheduled_for": "2026-04-08T14:00:00Z",
  "parameters": [
    { "name": "customer_phone", "value": "+919876543210" }
  ]
}
```

Scheduled calls return `status: "scheduled"`.

## Retry context

Use `retry_context` when a later call should continue with data from a previous attempt.

```json
{
  "retry_context": {
    "collected_data": {
      "customer_name": "Rahul",
      "intent": "payment_follow_up"
    },
    "retry_initial_message": "Hi Rahul, we spoke earlier about your payment.",
    "retry_language": "hi-IN",
    "retry_stage_id": "stage_follow_up"
  }
}
```

## Common failures

| Error                                  | Meaning                                             | Fix                                                      |
| -------------------------------------- | --------------------------------------------------- | -------------------------------------------------------- |
| `agent not found`                      | Agent does not exist or belongs to another tenant.  | Check the `agent_id`.                                    |
| `customer_phone parameter is required` | Destination phone number is missing.                | Add `customer_phone` to `parameters`.                    |
| `agent has no phone number configured` | Agent cannot place outbound calls.                  | Configure a phone number on the agent.                   |
| `idempotency key already used`         | Same idempotency key was used in the last 24 hours. | Reuse response from the first request or send a new key. |
| `rate limit exceeded for this number`  | Same number was called too frequently.              | Retry after the `Retry-After` header.                    |