> ## Documentation Index
> Fetch the complete documentation index at: https://app.miyon.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Outbound calls

> Place AI-powered calls to your contacts, personalize each one, and review the outcome.

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.

**1. Add placeholders to the agent's prompt**

Use `{{name}}` syntax in the prompt:

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

**2. Provide the values when placing the call**

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](https://app.miyon.ai/outbound/history) or in
[Conversations](https://app.miyon.ai/conversations), together with the full
transcript. Filter by the agent you placed the calls with to find them.

## Errors

Outbound errors use this shape:

```json theme={null}
{
  "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](/docs/en/api-reference/rate-limits). |
| `503` | Temporarily unavailable - retry shortly |

> [!TIP]
>
> 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:**

```bash theme={null}
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:**

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.