Create Outbound Call
curl --request POST \
--url https://allomia.com/api/outbound \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"phoneNumber": "<string>",
"assistantId": "<string>",
"phoneNumberId": "<string>",
"customerName": "<string>",
"dynamicVariables": {},
"callbackUrl": "<string>"
}
'import requests
url = "https://allomia.com/api/outbound"
payload = {
"phoneNumber": "<string>",
"assistantId": "<string>",
"phoneNumberId": "<string>",
"customerName": "<string>",
"dynamicVariables": {},
"callbackUrl": "<string>"
}
headers = {
"Authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
phoneNumber: '<string>',
assistantId: '<string>',
phoneNumberId: '<string>',
customerName: '<string>',
dynamicVariables: {},
callbackUrl: '<string>'
})
};
fetch('https://allomia.com/api/outbound', 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://allomia.com/api/outbound",
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([
'phoneNumber' => '<string>',
'assistantId' => '<string>',
'phoneNumberId' => '<string>',
'customerName' => '<string>',
'dynamicVariables' => [
],
'callbackUrl' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"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://allomia.com/api/outbound"
payload := strings.NewReader("{\n \"phoneNumber\": \"<string>\",\n \"assistantId\": \"<string>\",\n \"phoneNumberId\": \"<string>\",\n \"customerName\": \"<string>\",\n \"dynamicVariables\": {},\n \"callbackUrl\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
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://allomia.com/api/outbound")
.header("Authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"phoneNumber\": \"<string>\",\n \"assistantId\": \"<string>\",\n \"phoneNumberId\": \"<string>\",\n \"customerName\": \"<string>\",\n \"dynamicVariables\": {},\n \"callbackUrl\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://allomia.com/api/outbound")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"phoneNumber\": \"<string>\",\n \"assistantId\": \"<string>\",\n \"phoneNumberId\": \"<string>\",\n \"customerName\": \"<string>\",\n \"dynamicVariables\": {},\n \"callbackUrl\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"outboundCallId": "<string>",
"contactId": "<string>",
"status": "<string>",
"message": "<string>"
}Outbound Calls
Create Outbound Call
Triggers an immediate outbound call to a phone number using the specified AI assistant
POST
/
api
/
outbound
Create Outbound Call
curl --request POST \
--url https://allomia.com/api/outbound \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"phoneNumber": "<string>",
"assistantId": "<string>",
"phoneNumberId": "<string>",
"customerName": "<string>",
"dynamicVariables": {},
"callbackUrl": "<string>"
}
'import requests
url = "https://allomia.com/api/outbound"
payload = {
"phoneNumber": "<string>",
"assistantId": "<string>",
"phoneNumberId": "<string>",
"customerName": "<string>",
"dynamicVariables": {},
"callbackUrl": "<string>"
}
headers = {
"Authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
phoneNumber: '<string>',
assistantId: '<string>',
phoneNumberId: '<string>',
customerName: '<string>',
dynamicVariables: {},
callbackUrl: '<string>'
})
};
fetch('https://allomia.com/api/outbound', 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://allomia.com/api/outbound",
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([
'phoneNumber' => '<string>',
'assistantId' => '<string>',
'phoneNumberId' => '<string>',
'customerName' => '<string>',
'dynamicVariables' => [
],
'callbackUrl' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"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://allomia.com/api/outbound"
payload := strings.NewReader("{\n \"phoneNumber\": \"<string>\",\n \"assistantId\": \"<string>\",\n \"phoneNumberId\": \"<string>\",\n \"customerName\": \"<string>\",\n \"dynamicVariables\": {},\n \"callbackUrl\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
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://allomia.com/api/outbound")
.header("Authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"phoneNumber\": \"<string>\",\n \"assistantId\": \"<string>\",\n \"phoneNumberId\": \"<string>\",\n \"customerName\": \"<string>\",\n \"dynamicVariables\": {},\n \"callbackUrl\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://allomia.com/api/outbound")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"phoneNumber\": \"<string>\",\n \"assistantId\": \"<string>\",\n \"phoneNumberId\": \"<string>\",\n \"customerName\": \"<string>\",\n \"dynamicVariables\": {},\n \"callbackUrl\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"outboundCallId": "<string>",
"contactId": "<string>",
"status": "<string>",
"message": "<string>"
}Create Outbound Call
Triggers a single outbound call to a phone number using the specified AI assistant. The call is dispatched immediately upon receiving the request. Requires a tenant or organization-level API key for authentication.Headers
string
required
API key is required. Enter either your tenant-specific or organization-specific API key in the format
Bearer YOUR-API-KEYBody Parameters
string
required
Phone number to call. E.164 format is recommended (e.g.
+15145551234). Must be between 10 and 20 characters.string
required
UUID of the AI assistant to use for the call. The assistant must belong to the organization associated with the API key.
string
required
UUID of the AlloMia phone number to call from. The phone number must belong to the organization associated with the API key.
string
Name of the person being called. When provided, the AI assistant can use this to personalize the conversation.
object
Key-value pairs passed as dynamic variables to the AI assistant at call time. Values must be strings. These allow the assistant to personalize the conversation based on contextual information (e.g., patient name, appointment slot, practitioner name).
{
"patientId": "12345",
"appointmentSlot": "2026-04-01T10:00:00Z",
"practitioner": "Dr. Smith"
}
string
A URL to receive a
POST webhook request when the call reaches a terminal state (completed, failed, busy, or no-answer). The payload will mirror the Get Outbound Call Status response.Response
string
UUID uniquely identifying this outbound call record. Use this ID to poll Get Outbound Call Status and track the call’s progress.
string
UUID of the contact record created for this outbound call.
string
Initial status of the call. Always
calling on success, indicating the call has been dispatched.string
Human-readable description of the dispatched status (e.g.,
"Outbound call dispatched").Example Request
curl -X POST https://allomia.com/api/outbound \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumber": "+15145551234",
"assistantId": "a1b2c3d4-e5f6-7890-abcd-123456789012",
"phoneNumberId": "b2c3d4e5-f6a7-8901-bcde-234567890123",
"customerName": "John Doe",
"dynamicVariables": {
"patientId": "12345",
"appointmentSlot": "2026-04-01T10:00:00Z",
"practitioner": "Dr. Smith"
},
"callbackUrl": "https://partner.example.com/webhooks/call-status"
}'
Example Response
{
"outboundCallId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"contactId": "d4e5f6a7-b8c9-0123-defa-456789012345",
"status": "calling",
"message": "Outbound call dispatched"
}
Error Responses
400: Invalid request data
400: Invalid request data
Returned when the request body fails validation. The
details array lists each field-level error.{
"error": "Invalid request data",
"details": [
{
"field": "phoneNumber",
"message": "Phone number must be at least 10 digits",
"code": "too_small"
}
]
}
401: Unauthorized
401: Unauthorized
Returned when the API key is missing or invalid.
{
"error": "Invalid or missing API key"
}
403: Forbidden
403: Forbidden
Returned when the API key does not have the required permissions to trigger outbound calls.
{
"error": "Insufficient permissions"
}
404: Resource not found
404: Resource not found
Returned when the specified assistant or phone number does not exist or does not belong to the organization.
{
"error": "Assistant or phone number not found"
}
422: Organization inactive
422: Organization inactive
Returned when the organization associated with the API key is inactive.
{
"error": "Organization is inactive"
}
500: Internal server error
500: Internal server error
{
"error": "Internal server error occurred"
}