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>"
}

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-KEY

Body 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

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

Returned when the API key is missing or invalid.

{
  "error": "Invalid or missing API key"
}

403: Forbidden

Returned when the API key does not have the required permissions to trigger outbound calls.

{
  "error": "Insufficient permissions"
}

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

Returned when the organization associated with the API key is inactive.

{
  "error": "Organization is inactive"
}

500: Internal server error

{
  "error": "Internal server error occurred"
}

Outbound Calls API Get Outbound Call Status

API Documentation

Organizations (Tenant Only)

Calls

Outbound Calls

Create Outbound Call

Create Outbound Call

Headers

Body Parameters

Response

Example Request

Example Response

Error Responses

​Create Outbound Call

​Headers

​Body Parameters

​Response

​Example Request

​Example Response

​Error Responses

Create Outbound Call

Headers

Body Parameters

Response

Example Request

Example Response

Error Responses