API REFERENCE

A REST API for voice, messaging & flows.

Create calls, send messages and run flows with simple, predictable REST endpoints. Authenticate with a Bearer key and go.

Base URL & versioning

All endpoints are served over HTTPS from a versioned base URL. Breaking changes ship under a new version; additive changes do not.

https://api.expressivr.com/v1

Authentication

Authenticate every request with your secret key as a Bearer token. Requests without a valid key return 401.

Authorization: Bearer YOUR_API_KEY

Endpoints

POST/v1/calls

Place an outbound call that runs a flow or plays a message.

Parameter	Type	Description
`from`required	string	Caller ID — a number on your account.
`to`required	string	Destination number in E.164 format.
`flow_id`	string	Flow to run when the call connects.
`record`	boolean	Record the call. Defaults to false.

// 201 Created
{
  "id": "cl_8f21a0",
  "status": "queued",
  "from": "+918047182200",
  "to": "+9199XXXXXXXX"
}

POST/v1/messages

Send an SMS, WhatsApp or RCS message.

Parameter	Type	Description
`channel`required	string	One of `sms`, `whatsapp`, `rcs`.
`to`required	string	Recipient number in E.164 format.
`template`required	string	Approved (DLT/WhatsApp) template id.
`variables`	object	Key-value merge fields for the template.

// 201 Created
{
  "id": "msg_4b90c1",
  "channel": "whatsapp",
  "status": "accepted"
}

GET/v1/numbers

List the virtual, toll-free and vanity numbers on your account.

Parameter	Type	Description
`type`	string	Filter by `virtual`, `tollfree` or `vanity`.
`limit`	integer	Page size, 1–100. Defaults to 20.

// 200 OK
{
  "data": [
    { "number": "+918047182200", "type": "virtual" }
  ],
  "has_more": false
}

POST/v1/flows/{id}/run

Trigger a flow run — useful for outbound campaigns and IVR Blast.

Parameter	Type	Description
`audience`required	array	List of recipients, or a saved list id.
`schedule`	string	ISO-8601 time to start. Omit to run now.

// 202 Accepted
{
  "run_id": "run_1c7d55",
  "queued": 10000
}

Errors

Express IVR uses standard HTTP status codes — 2xx success, 4xx for a problem with your request, 5xx for a problem on our side. Error bodies include a machine-readable code and a human message.

Rate limits

Requests are rate-limited per API key. When you exceed the limit you'll receive 429 Too Many Requests with a Retry-After header — back off and retry.