curl --request POST \
--url https://api.usesimple.ai/api/v1/calls \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"to_number": "+15551234567",
"prompt": "You are a friendly assistant calling to confirm an appointment.",
"params": {
"customer_name": "Dana"
},
"idempotency_key": "appointment-1042-reminder"
}
'{
"success": true,
"status": "enqueued",
"uuid": "346fe020-e8c2-4abe-9d40-a4992b016bd6"
}Create an AI Phone Call with the API
Start an outbound AI phone call with a reusable agent or inline prompt, a destination number, and optional call parameters.
curl --request POST \
--url https://api.usesimple.ai/api/v1/calls \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"to_number": "+15551234567",
"prompt": "You are a friendly assistant calling to confirm an appointment.",
"params": {
"customer_name": "Dana"
},
"idempotency_key": "appointment-1042-reminder"
}
'{
"success": true,
"status": "enqueued",
"uuid": "346fe020-e8c2-4abe-9d40-a4992b016bd6"
}Authorizations
Your API key, sent as Authorization: Bearer YOUR_API_KEY
Body
- Call Request
- Call Request
Request to initiate an AI phone call
The phone number to call in E.164 format
"+12345678900"
The prompt to use for the AI call. Required if agent_id is not provided
"Hello, I'm calling to confirm your appointment"
The UUID of the phone number to use for the outbound call. If not provided, a phone number will be automatically selected.
"123e4567-e89b-12d3-a456-426614174000"
Whether to record the call or not
Language code for the call, such as en or es. Defaults to the agent's language when agent_id is provided, otherwise en.
"en"
Keywords to emphasize during the conversation
["appointment", "schedule", "morning"]
ID of the pre-configured agent to handle the call. Required if prompt is not provided. Cannot be used together with prompt or analyzers - use the agent's analyzers instead.
"123e4567-e89b-12d3-a456-426614174000"
When using agent_id, specifies which agent version to use. If not provided, uses the most recently updated version.
"456e7890-e89b-12d3-a456-426614174000"
Additional parameters to pass to the call. These will be substituted into the prompt for all keys with {{params.key}}
{
"appointment_type": "morning",
"customer_id": "123456"
}
External identifiers to associate with the call. These can be used to find the call later using the find_by_attribute endpoint.
Show child attributes
Show child attributes
{
"customer_id": "CUST-123456",
"order_id": "ORD-789012"
}
List of analyzers to run after the call. Can only be provided when agent_id is not provided. If using an agent, use the agent's analyzers instead.
Show child attributes
Show child attributes
The UUID of the voice to use for this call. Overrides the agent's default voice when provided.
"789e0123-e89b-12d3-a456-426614174000"
Optional idempotency key for safe retries. Reusing the same key with the same JSON request body returns the original call response; reusing it with a different body returns 409 conflict.
"call-create-2026-03-04-0001"