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": {
"properties": {}
}
}
],
"voice_id": "789e0123-e89b-12d3-a456-426614174000",
"idempotency_key": "call-create-2026-03-04-0001"
}
EOFimport requests
url = "https://api.prod.usesimple.ai/api/v1/calls"
payload = {
"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": { "properties": {} }
}
],
"voice_id": "789e0123-e89b-12d3-a456-426614174000",
"idempotency_key": "call-create-2026-03-04-0001"
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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: {properties: {}}}],
voice_id: '789e0123-e89b-12d3-a456-426614174000',
idempotency_key: 'call-create-2026-03-04-0001'
})
};
fetch('https://api.prod.usesimple.ai/api/v1/calls', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.prod.usesimple.ai/api/v1/calls",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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' => [
'properties' => [
]
]
]
],
'voice_id' => '789e0123-e89b-12d3-a456-426614174000',
'idempotency_key' => 'call-create-2026-03-04-0001'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.prod.usesimple.ai/api/v1/calls"
payload := strings.NewReader("{\n \"to_number\": \"<string>\",\n \"prompt\": \"Hello, I'm calling to confirm your appointment\",\n \"from_number_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"record\": false,\n \"language\": \"en\",\n \"boost_keywords\": [\n \"appointment\",\n \"schedule\",\n \"morning\"\n ],\n \"agent_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"version_id\": \"456e7890-e89b-12d3-a456-426614174000\",\n \"params\": {\n \"appointment_type\": \"morning\",\n \"customer_id\": \"123456\"\n },\n \"external_identifiers\": {\n \"customer_id\": \"CUST-123456\",\n \"order_id\": \"ORD-789012\"\n },\n \"analyzers\": [\n {\n \"title\": \"<string>\",\n \"prompt\": \"<string>\",\n \"output_config\": {\n \"properties\": {}\n }\n }\n ],\n \"voice_id\": \"789e0123-e89b-12d3-a456-426614174000\",\n \"idempotency_key\": \"call-create-2026-03-04-0001\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.prod.usesimple.ai/api/v1/calls")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"to_number\": \"<string>\",\n \"prompt\": \"Hello, I'm calling to confirm your appointment\",\n \"from_number_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"record\": false,\n \"language\": \"en\",\n \"boost_keywords\": [\n \"appointment\",\n \"schedule\",\n \"morning\"\n ],\n \"agent_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"version_id\": \"456e7890-e89b-12d3-a456-426614174000\",\n \"params\": {\n \"appointment_type\": \"morning\",\n \"customer_id\": \"123456\"\n },\n \"external_identifiers\": {\n \"customer_id\": \"CUST-123456\",\n \"order_id\": \"ORD-789012\"\n },\n \"analyzers\": [\n {\n \"title\": \"<string>\",\n \"prompt\": \"<string>\",\n \"output_config\": {\n \"properties\": {}\n }\n }\n ],\n \"voice_id\": \"789e0123-e89b-12d3-a456-426614174000\",\n \"idempotency_key\": \"call-create-2026-03-04-0001\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.prod.usesimple.ai/api/v1/calls")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"to_number\": \"<string>\",\n \"prompt\": \"Hello, I'm calling to confirm your appointment\",\n \"from_number_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"record\": false,\n \"language\": \"en\",\n \"boost_keywords\": [\n \"appointment\",\n \"schedule\",\n \"morning\"\n ],\n \"agent_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"version_id\": \"456e7890-e89b-12d3-a456-426614174000\",\n \"params\": {\n \"appointment_type\": \"morning\",\n \"customer_id\": \"123456\"\n },\n \"external_identifiers\": {\n \"customer_id\": \"CUST-123456\",\n \"order_id\": \"ORD-789012\"\n },\n \"analyzers\": [\n {\n \"title\": \"<string>\",\n \"prompt\": \"<string>\",\n \"output_config\": {\n \"properties\": {}\n }\n }\n ],\n \"voice_id\": \"789e0123-e89b-12d3-a456-426614174000\",\n \"idempotency_key\": \"call-create-2026-03-04-0001\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"status": "<string>",
"uuid": "<string>",
"record": true,
"analyzers": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"prompt": "<string>",
"output_config": {
"properties": {}
}
}
],
"analysis_results": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"analyzer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"prompt": "<string>",
"output_config": {},
"result": {}
}
]
}Calls
Create Call
Create a new AI call
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": {
"properties": {}
}
}
],
"voice_id": "789e0123-e89b-12d3-a456-426614174000",
"idempotency_key": "call-create-2026-03-04-0001"
}
EOFimport requests
url = "https://api.prod.usesimple.ai/api/v1/calls"
payload = {
"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": { "properties": {} }
}
],
"voice_id": "789e0123-e89b-12d3-a456-426614174000",
"idempotency_key": "call-create-2026-03-04-0001"
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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: {properties: {}}}],
voice_id: '789e0123-e89b-12d3-a456-426614174000',
idempotency_key: 'call-create-2026-03-04-0001'
})
};
fetch('https://api.prod.usesimple.ai/api/v1/calls', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.prod.usesimple.ai/api/v1/calls",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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' => [
'properties' => [
]
]
]
],
'voice_id' => '789e0123-e89b-12d3-a456-426614174000',
'idempotency_key' => 'call-create-2026-03-04-0001'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.prod.usesimple.ai/api/v1/calls"
payload := strings.NewReader("{\n \"to_number\": \"<string>\",\n \"prompt\": \"Hello, I'm calling to confirm your appointment\",\n \"from_number_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"record\": false,\n \"language\": \"en\",\n \"boost_keywords\": [\n \"appointment\",\n \"schedule\",\n \"morning\"\n ],\n \"agent_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"version_id\": \"456e7890-e89b-12d3-a456-426614174000\",\n \"params\": {\n \"appointment_type\": \"morning\",\n \"customer_id\": \"123456\"\n },\n \"external_identifiers\": {\n \"customer_id\": \"CUST-123456\",\n \"order_id\": \"ORD-789012\"\n },\n \"analyzers\": [\n {\n \"title\": \"<string>\",\n \"prompt\": \"<string>\",\n \"output_config\": {\n \"properties\": {}\n }\n }\n ],\n \"voice_id\": \"789e0123-e89b-12d3-a456-426614174000\",\n \"idempotency_key\": \"call-create-2026-03-04-0001\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.prod.usesimple.ai/api/v1/calls")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"to_number\": \"<string>\",\n \"prompt\": \"Hello, I'm calling to confirm your appointment\",\n \"from_number_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"record\": false,\n \"language\": \"en\",\n \"boost_keywords\": [\n \"appointment\",\n \"schedule\",\n \"morning\"\n ],\n \"agent_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"version_id\": \"456e7890-e89b-12d3-a456-426614174000\",\n \"params\": {\n \"appointment_type\": \"morning\",\n \"customer_id\": \"123456\"\n },\n \"external_identifiers\": {\n \"customer_id\": \"CUST-123456\",\n \"order_id\": \"ORD-789012\"\n },\n \"analyzers\": [\n {\n \"title\": \"<string>\",\n \"prompt\": \"<string>\",\n \"output_config\": {\n \"properties\": {}\n }\n }\n ],\n \"voice_id\": \"789e0123-e89b-12d3-a456-426614174000\",\n \"idempotency_key\": \"call-create-2026-03-04-0001\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.prod.usesimple.ai/api/v1/calls")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"to_number\": \"<string>\",\n \"prompt\": \"Hello, I'm calling to confirm your appointment\",\n \"from_number_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"record\": false,\n \"language\": \"en\",\n \"boost_keywords\": [\n \"appointment\",\n \"schedule\",\n \"morning\"\n ],\n \"agent_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"version_id\": \"456e7890-e89b-12d3-a456-426614174000\",\n \"params\": {\n \"appointment_type\": \"morning\",\n \"customer_id\": \"123456\"\n },\n \"external_identifiers\": {\n \"customer_id\": \"CUST-123456\",\n \"order_id\": \"ORD-789012\"\n },\n \"analyzers\": [\n {\n \"title\": \"<string>\",\n \"prompt\": \"<string>\",\n \"output_config\": {\n \"properties\": {}\n }\n }\n ],\n \"voice_id\": \"789e0123-e89b-12d3-a456-426614174000\",\n \"idempotency_key\": \"call-create-2026-03-04-0001\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"status": "<string>",
"uuid": "<string>",
"record": true,
"analyzers": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"prompt": "<string>",
"output_config": {
"properties": {}
}
}
],
"analysis_results": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"analyzer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"prompt": "<string>",
"output_config": {},
"result": {}
}
]
}Authorizations
Body
application/json
- Call Request
- Call Request
Request to initiate an AI phone call
The phone number to call in E.164 format
Example:
"+12345678900"
The prompt to use for the AI call. Required if agent_id is not provided
Example:
"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.
Example:
"123e4567-e89b-12d3-a456-426614174000"
Whether to record the call or not
The language to use for the call - English (en) or Spanish (es)
Available options:
en, es, ar Keywords to emphasize during the conversation
Example:
["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.
Example:
"123e4567-e89b-12d3-a456-426614174000"
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"
Additional parameters to pass to the call. These will be subtituted into the prompt for all keys with {{params.key}}
Show child attributes
Show child attributes
Example:
{
"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
Example:
{
"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.
Example:
"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.
Example:
"call-create-2026-03-04-0001"
Response
Successful Response
Available options:
en, es, ar Indicates how the call was answered - by a human, voicemail, or if there was no answer
Available options:
voicemail, human, no_answer, unknown List of analyzers configured for this call
Show child attributes
Show child attributes
Results from analyzers that have completed
Show child attributes
Show child attributes
Was this page helpful?
⌘I