Skip to main content
POST
/
calls
Create Call
curl --request POST \
  --url https://api.prod.usesimple.ai/api/v1/calls \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "to_number": "<string>",
  "prompt": "Hello, I'm calling to confirm your appointment",
  "from_number_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "record": false,
  "language": "en",
  "boost_keywords": [
    "appointment",
    "schedule",
    "morning"
  ],
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "version_id": "456e7890-e89b-12d3-a456-426614174000",
  "params": {
    "appointment_type": "morning",
    "customer_id": "123456"
  },
  "external_identifiers": {
    "customer_id": "CUST-123456",
    "order_id": "ORD-789012"
  },
  "analyzers": [
    {
      "title": "<string>",
      "prompt": "<string>",
      "output_config": {
        "type": "string",
        "properties": {}
      }
    }
  ]
}
EOF
{
  "success": true,
  "status": "<string>",
  "uuid": "<string>",
  "language": "en",
  "record": true,
  "answered_by": "voicemail",
  "analyzers": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "prompt": "<string>",
      "output_config": {
        "type": "string",
        "properties": {}
      }
    }
  ],
  "analysis_results": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "analyzer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "prompt": "<string>",
      "output_config": {},
      "result": {}
    }
  ]
}
The simplest way to use Simple AI is to use the create-call endpoint with just a prompt and an array of tools. If you need more control you shoudl use “agents”.

Authorizations

​
Authorization
string
header
required

Body

application/json

Request to initiate an AI phone call

​
to_number
string
required

The phone number to call in E.164 format

​
prompt
string | null
required

The prompt to use for the AI call. Required if agent_id is not provided

Example:

"Hello, I'm calling to confirm your appointment"

​
from_number_id
string<uuid>

The UUID of the phone number to use for the outbound call. If not provided, a phone number will be automatically selected.

​
record
boolean
default:false

Whether to record the call or not

​
language
enum<string>
default:en

The language to use for the call - English (en) or Spanish (es)

Available options:
en,
es,
ar
​
boost_keywords
string[] | null

Keywords to emphasize during the conversation

Example:
["appointment", "schedule", "morning"]
​
agent_id
string<uuid> | null

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.

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
version_id
string<uuid> | null

When using agent_id, specifies which agent version to use. If not provided, uses the most recently updated version.

Example:

"456e7890-e89b-12d3-a456-426614174000"

​
params
Params · object

Additional parameters to pass to the call. These will be subtituted into the prompt for all keys with {{params.key}}

Example:
{
  "appointment_type": "morning",
  "customer_id": "123456"
}
​
external_identifiers
External Identifiers · object

External identifiers to associate with the call. These can be used to find the call later using the find_by_attribute endpoint.

Example:
{
  "customer_id": "CUST-123456",
  "order_id": "ORD-789012"
}
​
analyzers
Analyzers · object[] | null

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.

Response

Successful Response

​
success
boolean
required
​
status
string
required
​
uuid
string
required
​
language
enum<string>
required
Available options:
en,
es,
ar
​
record
boolean
​
answered_by
enum<string>

Indicates how the call was answered - by a human, voicemail, or if there was no answer

Available options:
voicemail,
human,
no_answer,
unknown
​
analyzers
AnalyzerResponse · object[]

List of analyzers configured for this call

​
analysis_results
AnalysisResultResponse · object[]

Results from analyzers that have completed