Skip to main content

​
API Reference

Movoice AI provides a RESTful API for developers to manage agents, trigger calls, and retrieve analytics programmatically.

​
Base URL

https://api.movoice.ai/v1

​
Authentication

All API requests must include your API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY
Generate an API key in Settings → API Keys in the dashboard.
Never expose your API key in client-side code or public repositories. Rotate keys immediately if compromised.

​
Endpoints

​
Calls

​
POST /call

Trigger an outbound call to a specific number. 
curl -X POST https://api.movoice.ai/v1/call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_12345",
    "recipient_phone": "+919876543210",
    "variables": {
      "name": "Rahul",
      "appointment_time": "Tomorrow at 3 PM"
    }
  }'
Request body:
FieldTypeRequiredDescription
agent_idstring✅The ID of the agent to use
recipient_phonestring✅E.164 format (e.g., +919876543210)
variablesobject❌Key-value pairs injected into the agent prompt
from_numberstring❌Override the caller ID (must be a number you own)
max_durationinteger❌Max call duration in seconds (default: 1800)
Response: 
{
  "call_id": "call_998877",
  "status": "initiated",
  "agent_id": "agent_12345",
  "recipient_phone": "+919876543210",
  "created_at": 1713456000
}

​
GET /calls

List all calls for your account. 
curl https://api.movoice.ai/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY"
Query parameters:
ParameterTypeDescription
limitintegerNumber of results (default: 20, max: 100)
offsetintegerPagination offset
statusstringFilter by completed, failed, active
agent_idstringFilter by agent
fromtimestampStart of date range (Unix timestamp)
totimestampEnd of date range (Unix timestamp)

​
GET /calls/

Retrieve details for a specific call. 
curl https://api.movoice.ai/v1/calls/call_998877 \
  -H "Authorization: Bearer YOUR_API_KEY"
Response includes: duration, transcript, summary, sentiment, outcome, recording URL.

​
Agents

​
GET /agents

List all agents in your account. 
curl https://api.movoice.ai/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY"

​
GET /agents/

Retrieve configuration for a specific agent. 
curl https://api.movoice.ai/v1/agents/agent_12345 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
PATCH /agents/

Update an agent’s configuration. 
curl -X PATCH https://api.movoice.ai/v1/agents/agent_12345 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Updated system prompt...",
    "voice_id": "sarvam_hindi_female_01"
  }'

​
Batch Calls

​
POST /calls/batch

Send calls to multiple recipients at once. See Batch Calls for the full guide. 
curl -X POST https://api.movoice.ai/v1/calls/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_12345",
    "recipients": [
      { "phone": "+919876543210", "variables": { "name": "Rahul" } },
      { "phone": "+919876543211", "variables": { "name": "Priya" } }
    ],
    "schedule_at": 1713456000
  }'

​
Error Codes

HTTP StatusCodeMeaning
400invalid_requestMissing or malformed request parameters
401unauthorizedInvalid or missing API key
403forbiddenAPI key does not have permission for this action
404not_foundResource (agent, call) does not exist
409conflictDuplicate request — call already initiated
422unprocessableValid JSON but business logic error (e.g., agent not active)
429rate_limitedToo many requests — see rate limits below
500server_errorSomething went wrong on our end — contact support
All error responses follow this format: 
{
  "error": {
    "code": "invalid_request",
    "message": "recipient_phone must be in E.164 format",
    "param": "recipient_phone"
  }
}

​
Rate Limits

PlanCalls per minuteConcurrent calls
Starter101
Growth603
Business20010
EnterpriseCustomCustom
When rate limited, you receive a 429 response with a Retry-After header indicating seconds to wait.