Outbound calls

The Outbound Calls endpoints place AI-powered calls to your contacts: a single call or up to ten at once, each with its own prompt values, and let you review how every call went. This page covers the conventions shared by all five endpoints; each endpoint page in this group documents its parameters and responses.

Phone number format

All phone numbers must be in E.164 international format - a + followed by digits only. Send the exact format; numbers are not reformatted for you.

✅  +491761234567
✅  +442071234567
❌  0176 1234567
❌  +49 176 123 4567
❌  491761234567

Identifying your agent

You identify an agent by its phone number (a leading + is optional) - not by an internal database ID.

Personalizing the prompt

Inject dynamic values into your agent’s prompt at call time so each recipient hears a tailored message.

Add placeholders to the agent's prompt

Use {{name}} syntax in the prompt:

Hello {{customer_name}}, I'm calling about your order {{order_id}}.

Provide the values when placing the call

{
  "destination": "+491761234567",
  "agent_number": "+4921186942846",
  "prompt_variables": {
    "customer_name": "Max Mustermann",
    "order_id": "ORD-2026-0042"
  }
}

The prompt is resolved with your values before the call starts.

Rules

Every {{placeholder}} in the prompt must be provided, or the request is rejected with 400.
Extra keys not used by the prompt are accepted and ignored.
Key names should be lower snake_case (letters, digits, underscores), e.g. customer_name. The system__ and secret__ prefixes are reserved.
Values must be strings - send numbers and booleans as strings ("3", "true").
Up to 25 keys; each value up to 500 characters.
In bulk, use either per-destination or a shared top-level prompt_variables, not both.

Correlating calls with your own records

Send your own identifier in metadata.external_call_id and it is echoed back at the top level of the placement response, and carried through to the post-call callback:

{
  "destination": "+491761234567",
  "agent_number": "+4921186942846",
  "metadata": { "external_call_id": "crm-8842" }
}

The response’s call_id is the primary public identifier for a call. It is also available in post-call actions as {{post_call.call_id}}.

Checking results

Every call - single or bulk - belongs to a batch. Use List batches and Get a batch to see whether each call connected. Outcomes also appear in your dashboard, in your outbound call history or in Conversations, together with the full transcript. Filter by the agent you placed the calls with to find them.

Errors

Outbound errors use this shape:

{
  "success": false,
  "error": "Description of the issue"
}

Messages are always in English. Limit-related errors add a machine-readable error_type, and rate limits add a detail pointing you to where you can request more capacity.

Code	Meaning
`400`	Bad request - missing or invalid parameters. No call was placed.
`401`	Unauthorized - missing, invalid, expired or revoked API token
`403`	Forbidden - the token lacks the `outbound` scope, or outbound calling isn’t enabled for your account
`404`	Not found - agent, batch, or call record not found
`422`	Your daily call limit has been reached, or the account is locked
`429`	Too many requests - retry after the `Retry-After` period. See Rate limits.
`503`	Temporarily unavailable - retry shortly

A bulk request returns 201 even when some or all destinations fail. A non-201 means the whole request was rejected and nothing was dialed - check each entry’s success and status in results.

Quickstart

One call:

curl -X POST https://app.miyon.ai/api/v1/outbound/calls \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "+491761234567",
    "agent_number": "+4921186942846"
  }'

Personalized bulk calls:

curl -X POST https://app.miyon.ai/api/v1/outbound/calls/bulk \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_number": "+4921186942846",
    "destinations": [
      { "phone": "+491761111111", "prompt_variables": { "customer_name": "Max Müller" } },
      { "phone": "+491762222222", "prompt_variables": { "customer_name": "Anna Schmidt" } }
    ]
  }'

Removed endpoints

POST /api/v1/outbound/calls/place is no longer available and responds 410 Gone. It existed for the retired SMS-consent flow. Use Place a call or Place calls in bulk instead.

Get started

Voice Agents

Voice Agent Settings

Tools

Conversations

Evals

Outbound calls

Phone number format

Identifying your agent

Personalizing the prompt

Rules

Correlating calls with your own records

Checking results

Errors

Quickstart

Removed endpoints

​Phone number format

​Identifying your agent

​Personalizing the prompt

​Rules

​Correlating calls with your own records

​Checking results

​Errors

​Quickstart

​Removed endpoints

Phone number format

Identifying your agent

Personalizing the prompt

Rules

Correlating calls with your own records

Checking results

Errors

Quickstart

Removed endpoints