Skip to main content
Triggers an immediate outbound call using the specified AI agent. The call is queued and processed asynchronously.
​
X-API-Key
string
required
Your unique organization API key. Required on all requests.

​
Request body

​
agent_id
string
required
The UUID of the AI agent to conduct the call.
​
to_number
string
required
The destination phone number in E.164 format (e.g. +919876543210). Must include country code. Pattern: + followed by 10–15 digits.
​
metadata
object
Optional. Additional metadata to pass context to the agent (e.g. customer information, call objectives). Arbitrary key-value pairs.

​
Response

​
Success (202 Accepted)

Call request accepted and queued.
​
message
string
Human-readable status message.
​
status
string
Status value, e.g. accepted.
​
call_id
string
The unique identifier for the call (UUID). Use this to fetch call details later.

​
Errors

StatusDescription
400Bad request — invalid request body or phone number format
404Agent not found or does not belong to your company
500Internal server error

​
Examples

curl -X POST "https://api.samora.ai/v1/call/trigger" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "123e4567-e89b-12d3-a456-426614174000",
    "to_number": "+919876543210"
  }'

# With metadata
curl -X POST "https://api.samora.ai/v1/call/trigger" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "123e4567-e89b-12d3-a456-426614174000",
    "to_number": "+919876543210",
    "metadata": {
      "name": "John Doe",
      "email": "[email protected]",
      "customer_id": "CUST-001"
    }
  }'

{
  "message": "Call request accepted",
  "status": "accepted",
  "call_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "message": "Invalid phone number format. Please use E.164 format (e.g., +919876543210)"
}

{
  "message": "Agent not found or does not belong to your company"
}