Skip to main content

​
Overview

The Samora AI API lets you trigger immediate outbound calls and manage outbound campaigns through the Samora AI system. Use it to start calls with your AI agents, pass per-call context, create campaigns, add recipients, and manage campaign lifecycle from your server.

​
Base URL

All requests go to: 
https://api.samora.ai

​
Authentication

Every request must include your organization API key in the header:
HeaderDescription
X-API-KeyYour unique organization API key
These APIs are intended for server-to-server integrations. Do not expose your organization API key in browser or mobile clients.
Example: 
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"}'

​
Endpoints

​
Calls

MethodPathDescription
POST/v1/call/triggerTrigger an outbound call
GET/v1/call/{call_id}Get details for a specific call

​
Campaigns

MethodPathDescription
POST/v1/external/campaigns/{agent_id}Create a campaign
GET/v1/external/campaigns/{agent_id}List campaigns
GET/v1/external/campaigns/{agent_id}/{campaign_id}Get campaign details
PUT/v1/external/campaigns/{agent_id}/{campaign_id}Update campaign settings
POST/v1/external/campaigns/{agent_id}/{campaign_id}/scheduled-callsAdd campaign recipients
GET/v1/external/campaigns/{agent_id}/{campaign_id}/callsList campaign calls
POST/v1/external/campaigns/{agent_id}/{campaign_id}/startStart a campaign
POST/v1/external/campaigns/{agent_id}/{campaign_id}/stopStop a campaign
POST/v1/external/campaigns/{agent_id}/{campaign_id}/cancelCancel a campaign

​
Webhooks

MethodPathDescription
POST/v2/webhooksCreate a webhook
GET/v2/webhooksList webhooks
GET/v2/webhooks/eventsGet webhook event types
GET/v2/webhooks/{webhook_id}Get webhook details
PUT/v2/webhooks/{webhook_id}Update a webhook
DELETE/v2/webhooks/{webhook_id}Delete a webhook

​
Phone number format

Destination numbers must be in E.164 format (e.g. +919876543210) and include the country code. The pattern is: + followed by 10–15 digits.

​
Call statuses

When you fetch call details, status can be:
  • PENDING — Call request created, not yet initiated
  • TRIGGERED — Call initiated
  • ONGOING — Call in progress
  • CALL_FINISHED — Call completed
  • UNANSWERED — No answer
  • REJECTED — Call rejected

​
Campaign lifecycle

Campaign status can be DRAFT, SCHEDULED, IN_PROGRESS, PAUSED, FINISHED, FAILED, or CANCELLED.
  • Add recipients only when campaign status is DRAFT or PAUSED
  • Start campaigns only from DRAFT or PAUSED
  • Stop campaigns only from IN_PROGRESS
  • Cancel campaigns unless they are already FINISHED, FAILED, or CANCELLED

​
Campaign API limits

  • Request body size: 2 MiB
  • Campaign name: up to 120 characters
  • List campaigns page_size: up to 100
  • Add recipients: up to 5000 phone numbers per request
  • Recipient call_variables: up to 4 KiB per phone number

​
Retry configuration

Campaign create and update endpoints accept an optional retry_config object: 
{
	"max_retries": 2,
	"retry_delay_minutes": 30,
	"retry_on": ["UNANSWERED", "REJECTED", "VOICEMAIL"]
}
Supported retry_on values are UNANSWERED, REJECTED, VOICEMAIL, and FAILED. When retry_config is provided, max_retries must be between 1 and 5, retry_delay_minutes must be between 1 and 1440, and retry_on must include at least one supported status.

​
Transcripts and recordings

For finished calls, the Get call details response can include:
  • transcript_url — Presigned URL for the call transcript (valid 60 minutes)
  • recording_url — Presigned URL for the call recording (valid 60 minutes)

​
Webhooks

Webhooks let you receive real-time notifications when call events occur. You can subscribe to specific event types:
  • CALL_STARTED — Triggered when a call begins
  • CALL_FINISHED — Triggered when a call ends (transcript and recording available)
  • CALL_FAILED — Triggered when a call fails, is rejected, or goes unanswered
Each webhook includes a signing secret (returned only at creation) for verifying payloads. You can optionally include transcript data and recording URLs in the webhook payload via data_options.
Webhook endpoints use the /v2/webhooks base path at https://api.samora.ai.

​
Support

For API support, contact Samora AI Support.