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.

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

{
  "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

{
  "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.

{
  "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.