Make a Call | FormantAI | Documentation

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

1 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

$ 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

1 {
2   "data": {
3     "agent_id": 123,
4     "conversation_id": null,
5     "scheduled_for": null,
6     "status": "initiated",
7     "trace_id": "f9e8d7c6-1234-4d5e-8f90-123456789abc"
8   }
9 }

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

1 {
2   "agent_id": 123,
3   "scheduled_for": "2026-04-08T14:00:00Z",
4   "parameters": [
5     { "name": "customer_phone", "value": "+919876543210" }
6   ]
7 }

Scheduled calls return status: "scheduled".

Retry context

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

1 {
2   "retry_context": {
3     "collected_data": {
4       "customer_name": "Rahul",
5       "intent": "payment_follow_up"
6     },
7     "retry_initial_message": "Hi Rahul, we spoke earlier about your payment.",
8     "retry_language": "hi-IN",
9     "retry_stage_id": "stage_follow_up"
10   }
11 }

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.