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:

Field	Type	Description
`agent_id`	string	The ID of the agent to use
`recipient_phone`	string	E.164 format (e.g., `+919876543210`)
`variables`	object	Key-value pairs injected into the agent prompt
`from_number`	string	Override the caller ID (must be a number you own)
`max_duration`	integer	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:

Parameter	Type	Description
`limit`	integer	Number of results (default: 20, max: 100)
`offset`	integer	Pagination offset
`status`	string	Filter by `completed`, `failed`, `active`
`agent_id`	string	Filter by agent
`from`	timestamp	Start of date range (Unix timestamp)
`to`	timestamp	End 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 Status	Code	Meaning
`400`	`invalid_request`	Missing or malformed request parameters
`401`	`unauthorized`	Invalid or missing API key
`403`	`forbidden`	API key does not have permission for this action
`404`	`not_found`	Resource (agent, call) does not exist
`409`	`conflict`	Duplicate request — call already initiated
`422`	`unprocessable`	Valid JSON but business logic error (e.g., agent not active)
`429`	`rate_limited`	Too many requests — see rate limits below
`500`	`server_error`	Something 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

Plan	Calls per minute	Concurrent calls
Starter	10	1
Growth	60	3
Business	200	10
Enterprise	Custom	Custom

When rate limited, you receive a 429 response with a Retry-After header indicating seconds to wait.

Getting Started

Using Movoice Platform

Pricing

Enterprise

On Premise Deployments

Multilingual Voice Agents

Integrations

Function Calls

Features

Advanced Capabilities

Supported Telephony

Phone Calls using Movoice

Resources

API Reference

API Reference

Base URL

Authentication

Endpoints

Calls

POST /call

GET /calls

GET /calls/

Agents

GET /agents

GET /agents/

PATCH /agents/

Batch Calls

POST /calls/batch

Error Codes

Rate Limits

​API Reference

​Base URL

​Authentication

​Endpoints

​Calls

​POST /call

​GET /calls

​GET /calls/

​Agents

​GET /agents

​GET /agents/

​PATCH /agents/

​Batch Calls

​POST /calls/batch

​Error Codes

​Rate Limits

API Reference

Base URL

Authentication

Endpoints

Calls

POST /call

GET /calls

GET /calls/

Agents

GET /agents

GET /agents/

PATCH /agents/

Batch Calls

POST /calls/batch

Error Codes

Rate Limits