Create an outbound call
import { createClient, createResources } from "@morevoice/sdk";
const mv = createResources({ client: createClient({ baseUrl: "https://api.morevoice.ai/v1", auth: process.env.MOREVOICE_API_KEY }),});
const call = await mv.calls.create({ assistant_id: "asst_4Gk2LmN9pQ4rS6tV8wX0yZ", from_number_id: "pn_4Gk2LmN9pQ4rS6tV8wX0yZ", metadata: { crm_contact_id: "0031x00000AbCdE", }, purpose: "service", to: "+972501234567", variables: { customer_name: "Dana", },});console.log(call);import osimport uuid
import requests
response = requests.post( "https://api.morevoice.ai/v1/calls", headers={"Authorization": f"Bearer {os.environ['MOREVOICE_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())}, json={ "assistant_id": "asst_4Gk2LmN9pQ4rS6tV8wX0yZ", "from_number_id": "pn_4Gk2LmN9pQ4rS6tV8wX0yZ", "metadata": { "crm_contact_id": "0031x00000AbCdE", }, "purpose": "service", "to": "+972501234567", "variables": { "customer_name": "Dana", }, },)response.raise_for_status()print(response.json())curl -X POST https://api.morevoice.ai/v1/calls \ -H "Authorization: Bearer $MOREVOICE_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "assistant_id": "asst_4Gk2LmN9pQ4rS6tV8wX0yZ", "from_number_id": "pn_4Gk2LmN9pQ4rS6tV8wX0yZ", "metadata": { "crm_contact_id": "0031x00000AbCdE" }, "purpose": "service", "to": "+972501234567", "variables": { "customer_name": "Dana" }}'Places an outbound call with an assistant, or with a published voice flow and its assistant. purpose is required: it drives the outbound compliance checks (do-not-call list for every call; recorded consent and the national registry for marketing). The Idempotency-Key header is required, so a retried request never calls anyone twice. Test-mode keys place simulated calls that never reach a phone network.
Try it in the API playground with a test-mode key.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”The API version to use for this request. Defaults to the version the API key is pinned to.
Example
2026-11-01Required on this endpoint (400 parameter_missing without it). A unique key (for example a UUID) for this request: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice.
Example
5f0c1e8a-7b2d-4c3e-9f1a-2b6d8e4c0a17Request Bodyrequired
Section titled “Request Bodyrequired”An outbound call to place.
An outbound call to place.
object
Answering-machine detection (default: the assistant’s setting).
object
Detect answering machines.
Spoken after the beep with on_machine=leave_message (default: the assistant’s message).
What to do on a machine (default hangup).
The assistant that handles the call. Pass this or flow_id.
The number to present; it must be allowed on the connection.
The SIP connection to call out on (default: the organisation’s default connection).
A published voice flow; it runs on its linked assistant. Pass this or assistant_id.
The phone number to call from (pn_…, GET /v1/phone_numbers): it sets the connection and the caller ID. Or pass connection_id and caller_id.
End the call after this many seconds (default: the assistant’s limit).
Up to 50 key/value pairs (keys up to 40 characters, values up to 500) you attach to an object. Returned as sent.
object
Service, marketing or survey. Marketing calls need recorded consent and pass the national do-not-call registry (§30A).
The number to call, E.164.
Template variables for the prompt, first message and flow ({{customer_name}}); at most 50.
object
Examples
Call with an assistant
{ "assistant_id": "asst_4Gk2LmN9pQ4rS6tV8wX0yZ", "from_number_id": "pn_4Gk2LmN9pQ4rS6tV8wX0yZ", "metadata": { "crm_contact_id": "0031x00000AbCdE" }, "purpose": "service", "to": "+972501234567", "variables": { "customer_name": "Dana" }}Call with a published voice flow
{ "amd": { "enabled": true, "on_machine": "hangup" }, "flow_id": "flow_4Gk2LmN9pQ4rS6tV8wX0yZ", "purpose": "survey", "to": "+972501234567"}Responses
Section titled “Responses”Created
An inbound, outbound or browser call.
object
The assistant, with expand[]=assistant.
object
A assistant ID (prefix asst_).
What the call cost (an ended call with no recorded provider usage costs 0).
object
The amount in the currency’s minor unit (cents, agorot), rounded.
The exact amount in minor units, as a decimal string (sub-cent precision).
ISO 4217 currency code.
True: an estimate from provider usage, not a billed amount.
The business outcome recorded on the call (set_outcome tool, or the summary).
Why the call ended, e.g. customer-ended-call, assistant-ended-call, customer-busy, customer-did-not-answer.
The calling number (E.164 when it is a phone number) or name.
A call ID (prefix call_).
true in live mode, false in test mode.
Up to 50 key/value pairs (keys up to 40 characters, values up to 500) you attach to an object. Returned as sent.
object
When the call started: dialled out, or rang in.
queued (placed, not ringing yet), ringing, in_progress (answered, or an inbound call being handled) or ended.
The AI summary of a call.
object
Follow-ups for your business; empty when there are none.
A call ID (prefix call_).
What the caller wanted.
How the call ended, or what was agreed.
A two-to-four sentence summary, in the language of the call.
The called number (E.164 when it is a phone number) or destination.
sip for phone calls, webrtc for browser calls and conference rooms.
Who handles the call: an AI assistant, a human agent, an IVR flow, a conference room, or a voicemail box.
The variables the call was created with.
object
Example
{ "agent_id": null, "answered_at": "2026-11-03T09:14:29.410Z", "answered_by": "human", "api_key_id": "key_9i2E2pKO6g3z4nXl57Qb4g", "assistant_id": "asst_4Gk2LmN9pQ4rS6tV8wX0yZ", "campaign_id": null, "connection_id": "conn_2bF8kQ1nR7sT3vW5xY9zA0", "contact_id": null, "cost": { "amount": 4, "amount_decimal": "4.2310", "currency": "USD", "estimate": true }, "direction": "outbound", "disposition": null, "duration_ms": 99710, "end_reason": "customer-ended-call", "ended_at": "2026-11-03T09:16:02.120Z", "flow_id": null, "flow_version": null, "from": "+97237654321", "has_recording": true, "id": "call_8tRPaZp5hLMbrGqdJ9AmNa", "livemode": true, "metadata": { "crm_contact_id": "0031x00000AbCdE" }, "object": "call", "purpose": "service", "queue_id": null, "started_at": "2026-11-03T09:14:22.000Z", "status": "ended", "summary": null, "to": "+972501234567", "transport": "sip", "type": "ai", "variables": { "customer_name": "Dana" }}The request is invalid: a parameter is missing, malformed or unknown, or the version header is unknown.
Every /v1 error.
object
object
A stable, machine-readable code from the error-code catalogue.
Structured context, e.g. required_scope or the compliance verdict.
object
A link to the documentation of this code.
A human-readable explanation. Do not parse it.
The request parameter the error relates to, e.g. to or metadata[order_id].
The X-Request-Id of this request. Quote it when you contact support.
The category of the error.
Example
{ "error": { "code": "parameter_missing", "doc_url": "https://docs.morevoice.ai/api/errors#parameter-missing", "message": "Missing required parameter: to.", "param": "to", "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ", "type": "invalid_request_error" }}Headers
Section titled “Headers”The request’s ID (req_…). Quote it when you contact support.
No valid API key was sent.
Every /v1 error.
object
object
A stable, machine-readable code from the error-code catalogue.
Structured context, e.g. required_scope or the compliance verdict.
object
A link to the documentation of this code.
A human-readable explanation. Do not parse it.
The request parameter the error relates to, e.g. to or metadata[order_id].
The X-Request-Id of this request. Quote it when you contact support.
The category of the error.
Example
{ "error": { "code": "invalid_api_key", "doc_url": "https://docs.morevoice.ai/api/errors#invalid-api-key", "message": "Invalid API key.", "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ", "type": "authentication_error" }}Headers
Section titled “Headers”The request’s ID (req_…). Quote it when you contact support.
The key may not do this (a missing scope, a plan limit, or a compliance block).
Every /v1 error.
object
object
A stable, machine-readable code from the error-code catalogue.
Structured context, e.g. required_scope or the compliance verdict.
object
A link to the documentation of this code.
A human-readable explanation. Do not parse it.
The request parameter the error relates to, e.g. to or metadata[order_id].
The X-Request-Id of this request. Quote it when you contact support.
The category of the error.
Example
{ "error": { "code": "missing_scope", "doc_url": "https://docs.morevoice.ai/api/errors#missing-scope", "message": "This API key lacks the calls:write scope.", "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ", "type": "permission_error" }}Headers
Section titled “Headers”The request’s ID (req_…). Quote it when you contact support.
The request conflicts with the object’s state, or the Idempotency-Key was reused with other parameters.
Every /v1 error.
object
object
A stable, machine-readable code from the error-code catalogue.
Structured context, e.g. required_scope or the compliance verdict.
object
A link to the documentation of this code.
A human-readable explanation. Do not parse it.
The request parameter the error relates to, e.g. to or metadata[order_id].
The X-Request-Id of this request. Quote it when you contact support.
The category of the error.
Example
{ "error": { "code": "idempotency_mismatch", "doc_url": "https://docs.morevoice.ai/api/errors#idempotency-mismatch", "message": "This Idempotency-Key was already used with different parameters.", "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ", "type": "idempotency_error" }}Headers
Section titled “Headers”The request’s ID (req_…). Quote it when you contact support.
Too many requests, or no call capacity right now. Retry after the Retry-After delay.
Every /v1 error.
object
object
A stable, machine-readable code from the error-code catalogue.
Structured context, e.g. required_scope or the compliance verdict.
object
A link to the documentation of this code.
A human-readable explanation. Do not parse it.
The request parameter the error relates to, e.g. to or metadata[order_id].
The X-Request-Id of this request. Quote it when you contact support.
The category of the error.
Example
{ "error": { "code": "rate_limited", "doc_url": "https://docs.morevoice.ai/api/errors#rate-limited", "message": "Too many requests. Retry after 1 second.", "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ", "type": "rate_limit_error" }}Headers
Section titled “Headers”Seconds to wait before retrying.
The request’s ID (req_…). Quote it when you contact support.
Something went wrong on MoreVoice’s side. Retry with the same Idempotency-Key.
Every /v1 error.
object
object
A stable, machine-readable code from the error-code catalogue.
Structured context, e.g. required_scope or the compliance verdict.
object
A link to the documentation of this code.
A human-readable explanation. Do not parse it.
The request parameter the error relates to, e.g. to or metadata[order_id].
The X-Request-Id of this request. Quote it when you contact support.
The category of the error.
Example
{ "error": { "code": "internal_error", "doc_url": "https://docs.morevoice.ai/api/errors#internal-error", "message": "Something went wrong on MoreVoice's side.", "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ", "type": "api_error" }}Headers
Section titled “Headers”The request’s ID (req_…). Quote it when you contact support.