Create Outbound Call
curl --request POST \
--url https://api.cartesia.ai/agents/calls \
--header 'Authorization: Bearer <token>' \
--header 'Cartesia-Version: <cartesia-version>' \
--header 'Content-Type: application/json' \
--data '
{
"from_number_id": "<string>",
"agent_id": "<string>",
"outbound_calls": [
{
"to_number": "<string>",
"metadata": {}
}
],
"ringing_timeout_seconds": 42,
"max_call_duration_minutes": 123
}
'import requests
url = "https://api.cartesia.ai/agents/calls"
payload = {
"from_number_id": "<string>",
"agent_id": "<string>",
"outbound_calls": [
{
"to_number": "<string>",
"metadata": {}
}
],
"ringing_timeout_seconds": 42,
"max_call_duration_minutes": 123
}
headers = {
"Cartesia-Version": "<cartesia-version>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Cartesia-Version': '<cartesia-version>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
from_number_id: '<string>',
agent_id: '<string>',
outbound_calls: [{to_number: '<string>', metadata: {}}],
ringing_timeout_seconds: 42,
max_call_duration_minutes: 123
})
};
fetch('https://api.cartesia.ai/agents/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.cartesia.ai/agents/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([
'from_number_id' => '<string>',
'agent_id' => '<string>',
'outbound_calls' => [
[
'to_number' => '<string>',
'metadata' => [
]
]
],
'ringing_timeout_seconds' => 42,
'max_call_duration_minutes' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Cartesia-Version: <cartesia-version>",
"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.cartesia.ai/agents/calls"
payload := strings.NewReader("{\n \"from_number_id\": \"<string>\",\n \"agent_id\": \"<string>\",\n \"outbound_calls\": [\n {\n \"to_number\": \"<string>\",\n \"metadata\": {}\n }\n ],\n \"ringing_timeout_seconds\": 42,\n \"max_call_duration_minutes\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Cartesia-Version", "<cartesia-version>")
req.Header.Add("Authorization", "Bearer <token>")
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.cartesia.ai/agents/calls")
.header("Cartesia-Version", "<cartesia-version>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"from_number_id\": \"<string>\",\n \"agent_id\": \"<string>\",\n \"outbound_calls\": [\n {\n \"to_number\": \"<string>\",\n \"metadata\": {}\n }\n ],\n \"ringing_timeout_seconds\": 42,\n \"max_call_duration_minutes\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cartesia.ai/agents/calls")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Cartesia-Version"] = '<cartesia-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"from_number_id\": \"<string>\",\n \"agent_id\": \"<string>\",\n \"outbound_calls\": [\n {\n \"to_number\": \"<string>\",\n \"metadata\": {}\n }\n ],\n \"ringing_timeout_seconds\": 42,\n \"max_call_duration_minutes\": 123\n}"
response = http.request(request)
puts response.read_body{
"calls": [
{
"number": "<string>",
"agent_call_id": "<string>",
"error": {}
}
]
}Calls
Create Outbound Call
POST
/
agents
/
calls
Create Outbound Call
curl --request POST \
--url https://api.cartesia.ai/agents/calls \
--header 'Authorization: Bearer <token>' \
--header 'Cartesia-Version: <cartesia-version>' \
--header 'Content-Type: application/json' \
--data '
{
"from_number_id": "<string>",
"agent_id": "<string>",
"outbound_calls": [
{
"to_number": "<string>",
"metadata": {}
}
],
"ringing_timeout_seconds": 42,
"max_call_duration_minutes": 123
}
'import requests
url = "https://api.cartesia.ai/agents/calls"
payload = {
"from_number_id": "<string>",
"agent_id": "<string>",
"outbound_calls": [
{
"to_number": "<string>",
"metadata": {}
}
],
"ringing_timeout_seconds": 42,
"max_call_duration_minutes": 123
}
headers = {
"Cartesia-Version": "<cartesia-version>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Cartesia-Version': '<cartesia-version>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
from_number_id: '<string>',
agent_id: '<string>',
outbound_calls: [{to_number: '<string>', metadata: {}}],
ringing_timeout_seconds: 42,
max_call_duration_minutes: 123
})
};
fetch('https://api.cartesia.ai/agents/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.cartesia.ai/agents/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([
'from_number_id' => '<string>',
'agent_id' => '<string>',
'outbound_calls' => [
[
'to_number' => '<string>',
'metadata' => [
]
]
],
'ringing_timeout_seconds' => 42,
'max_call_duration_minutes' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Cartesia-Version: <cartesia-version>",
"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.cartesia.ai/agents/calls"
payload := strings.NewReader("{\n \"from_number_id\": \"<string>\",\n \"agent_id\": \"<string>\",\n \"outbound_calls\": [\n {\n \"to_number\": \"<string>\",\n \"metadata\": {}\n }\n ],\n \"ringing_timeout_seconds\": 42,\n \"max_call_duration_minutes\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Cartesia-Version", "<cartesia-version>")
req.Header.Add("Authorization", "Bearer <token>")
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.cartesia.ai/agents/calls")
.header("Cartesia-Version", "<cartesia-version>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"from_number_id\": \"<string>\",\n \"agent_id\": \"<string>\",\n \"outbound_calls\": [\n {\n \"to_number\": \"<string>\",\n \"metadata\": {}\n }\n ],\n \"ringing_timeout_seconds\": 42,\n \"max_call_duration_minutes\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cartesia.ai/agents/calls")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Cartesia-Version"] = '<cartesia-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"from_number_id\": \"<string>\",\n \"agent_id\": \"<string>\",\n \"outbound_calls\": [\n {\n \"to_number\": \"<string>\",\n \"metadata\": {}\n }\n ],\n \"ringing_timeout_seconds\": 42,\n \"max_call_duration_minutes\": 123\n}"
response = http.request(request)
puts response.read_body{
"calls": [
{
"number": "<string>",
"agent_call_id": "<string>",
"error": {}
}
]
}Authorizations
Cartesia API key (sk_car_...). Get one at play.cartesia.ai/keys.
Headers
API version header.
Available options:
2026-03-01 Example:
"2026-03-01"
Body
application/json
Request body for starting outbound calls from an agent phone number.
Phone number ID to place calls from. The attached provider handles outbound calling for this number.
Agent that handles the outbound calls.
Per-call destination and metadata configuration.
Minimum array length:
1Show child attributes
Show child attributes
Seconds to wait for the callee to answer before giving up. Omit to use the default (60 seconds).
Required range:
5 <= x <= 80Optional maximum call duration in minutes.
Response
Outbound call requests accepted.
Show child attributes
Show child attributes
Was this page helpful?
⌘I