> ## 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. # Place calls in bulk > Place calls to multiple destinations in one request, up to **10 destinations**. **The whole request is validated before any call is placed.** If validation fails - an invalid number, more than 10 destinations, a missing prompt variable - the entire request is rejected with a `400` and **no calls are placed**. **Once validation passes, each destination is dialed independently**, so a bulk can return a mix of successes and failures per destination. It returns `201` even when some - or all - destinations fail: check each entry's `success` and `status` in `results`. Duplicate destinations are de-duplicated; each unique number is called once. Bulk requests do not support `metadata` or `variables`. Use `prompt_variables`, shared or per destination. ## OpenAPI ````yaml /api-reference/openapi.yaml post /api/v1/outbound/calls/bulk openapi: 3.1.0 info: title: Customer API version: 1.0.0-beta description: > **Beta.** This API is in beta. Contracts can still change while we complete it, including breaking changes; we announce changes in the release notes and keep them as rare as we can. Pin your integration to the field names and status codes documented here and treat unknown fields as optional. REST API to create and configure voice agents, add tools, test them with evals, read conversations, and place AI outbound calls. **Authentication.** Voice agents, settings, tools, evals and conversations use an API token created on the **Keys** page of your dashboard. Each operation lists the scope it needs under `x-required-scopes`; `:*` grants every action of a resource. Outbound calls use a separate outbound API token from the **Outbound Calls** page. Send either token as `Authorization: Bearer `. **Responses.** A single resource is returned as a flat JSON object; a collection is wrapped in a plural key (`voice_agents`, `tools`, `evals`, `conversations`) next to its paging fields. Deleting returns `204 No Content`. Everything is addressed by the voice agent's `id`; prompts and numbers are internal. **Errors.** Authentication failures return `{ "error", "message" }`. Request quotas return `429` with a `Retry-After` header and `{ "error", "message", "details" }`, where `error` is a stable machine-readable code. Every API call must finish within 30 seconds; longer requests return `503` with `mf-core:api-request-timeout`. Validation errors list the problems per field; the exact shape is shown on each operation. servers: - url: https://app.miyon.ai security: [] tags: - name: Voice Agents description: >- Create and manage voice agents. Configure them through the voice, prompt and knowledge-base settings endpoints. - name: Voice Agent Settings description: >- Read and change a voice agent's voice, prompt and knowledge-base settings. A voice agent has one prompt (its instructions, greeting and conversation settings). Read the schema of a settings group, then update one `key`/`value` pair per request. - name: Tools description: >- Create, configure, enable and execute agent tools. Tools are enabled per voice agent with `agent_id`. These endpoints accept scoped API tokens only; every error uses the `{ "error", "message", "details" }` envelope with a stable `mf-core:tool-*` code. - name: Outbound Calls description: >- Place AI calls and review their outcome. Authenticate with the outbound API token from the **Outbound Calls** page. - name: Conversations description: >- List and inspect the conversations of your account, including transcripts when your retention settings allow. - name: Evals description: >- Evals are automated test conversations that check how a voice agent responds. A scenario contains cases; each case contains the caller's turns and what the agent must say or do. Run a scenario to get pass/fail results. paths: /api/v1/outbound/calls/bulk: post: tags: - Outbound Calls summary: Place calls in bulk description: > Place calls to multiple destinations in one request, up to **10 destinations**. **The whole request is validated before any call is placed.** If validation fails - an invalid number, more than 10 destinations, a missing prompt variable - the entire request is rejected with a `400` and **no calls are placed**. **Once validation passes, each destination is dialed independently**, so a bulk can return a mix of successes and failures per destination. It returns `201` even when some - or all - destinations fail: check each entry's `success` and `status` in `results`. Duplicate destinations are de-duplicated; each unique number is called once. Bulk requests do not support `metadata` or `variables`. Use `prompt_variables`, shared or per destination. operationId: placeCallsBulk requestBody: required: true content: application/json: schema: type: object required: - destinations - agent_number properties: destinations: description: > Up to 10 destinations, either as objects (with optional per-destination variables) or as plain E.164 strings. The two forms cannot be mixed. oneOf: - type: array title: Objects maxItems: 10 items: type: object required: - phone properties: phone: type: string pattern: ^\+\d+$ examples: - '+491761234567' prompt_variables: $ref: '#/components/schemas/OutboundPromptVariables' - type: array title: Plain numbers maxItems: 10 items: type: string pattern: ^\+\d+$ examples: - - '+491761234567' - '+491769876543' agent_number: type: string description: >- Your agent's phone number, or its SIP ID if your account connects its own SIP trunk (then also set `caller_number`). examples: - '+4921186942846' caller_number: type: string description: >- Caller ID shown to the recipient, in E.164 format. Required when `agent_number` is a SIP ID; ignored otherwise. pattern: ^\+\d+$ prompt_variables: allOf: - $ref: '#/components/schemas/OutboundPromptVariables' description: | Shared variables applied to **every** destination. Cannot be combined with per-destination `prompt_variables` in the same request - use one or the other. examples: shared: summary: Shared variables for every destination value: agent_number: '+4921186942846' destinations: - phone: '+491761234567' - phone: '+491769876543' prompt_variables: campaign: Spring 2026 perDestination: summary: Per-destination variables value: agent_number: '+4921186942846' destinations: - phone: '+491761111111' prompt_variables: customer_name: Max Müller - phone: '+491762222222' prompt_variables: customer_name: Anna Schmidt responses: '201': description: | Request accepted and every destination attempted. Per-destination outcomes are in `results`. content: application/json: schema: type: object properties: success: type: boolean examples: - true description: >- True when the request was processed; check each row's `success` for the outcome per destination. batch_id: type: string format: uuid description: >- Groups these calls together. Use it with [Get a batch](/api-reference/outbound-calls/get-a-batch). total: type: integer examples: - 3 description: Destinations in the request after deduplication. succeeded: type: integer examples: - 2 description: Destinations that were dialed. failed: type: integer examples: - 1 description: Destinations that were not dialed. results: type: array items: $ref: '#/components/schemas/OutboundBulkResult' description: Outcome per destination, in request order. mode: type: string const: direct description: 'Always `direct`: calls are dialed immediately.' examples: partial: summary: Partial failure value: success: true batch_id: 6f1e9c2a-4d3b-4a1f-9c8e-2b7d5a0f3e11 total: 2 succeeded: 1 failed: 1 results: - destination: '+491761234567' success: true consent_id: 48213 call_sid: outb_9f2c1d status: initiated error: null - destination: '+491760000000' success: false consent_id: 48214 call_sid: null status: failed error: >- Something went wrong. Please try again or contact support. '400': $ref: '#/components/responses/OutboundBadRequest' '401': $ref: '#/components/responses/OutboundUnauthorized' '403': $ref: '#/components/responses/OutboundForbidden' '404': $ref: '#/components/responses/OutboundAgentNotFound' '422': $ref: '#/components/responses/OutboundUnprocessableEntity' '429': $ref: '#/components/responses/OutboundRateLimited' '503': $ref: '#/components/responses/OutboundServiceUnavailable' security: - scopedJwt: [] - outboundBearer: [] components: schemas: OutboundPromptVariables: type: object description: > Values injected into the agent's prompt at call time. Every `{{placeholder}}` in the prompt must be supplied, or the request is rejected with 400. Extra keys the prompt does not use are accepted and ignored. Key names should be lower `snake_case`. Values must be strings; send numbers and booleans as strings (`"3"`, `"true"`). Up to 10 keys, each value up to 100 characters. Keys may not start with `system__` or `secret__` and may not reuse a built-in system variable name such as `caller_number` or `called_number`. maxProperties: 10 additionalProperties: type: string maxLength: 100 examples: - customer_name: Max Mustermann order_id: ORD-2026-0042 OutboundBulkResult: type: object required: - destination - success - status properties: destination: type: string examples: - '+491761234567' description: The destination number this row refers to. success: type: boolean description: Whether the call was placed. consent_id: type: integer description: >- ID of the call record. Absent when the destination was blocked by a limit before any record was created. call_sid: type: - string - 'null' description: Telephony call identifier. Absent or null when not dialed. status: type: string description: >- `initiated` on success. On failure, why the destination was not dialed. enum: - initiated - failed - skipped - locked - rate_limited - temporarily_unavailable error: type: - string - 'null' description: English message on `failed`; null otherwise. error_type: type: - string - 'null' description: Classification of a `failed` row; null otherwise. enum: - destination_not_permitted - caller_id_not_allowed - placement_failed - null OutboundError: type: object required: - success - error properties: success: type: boolean const: false description: Always false. error: type: string description: Description of the issue, in English. error_type: type: string description: >- Stable machine-readable cause. Present on limit rejections and on classified placement failures, omitted otherwise. enum: - outbound_burst_limited - outbound_limit_request_exceeded - outbound_temporarily_unavailable - rate_limit - destination_not_permitted - caller_id_not_allowed - placement_failed detail: type: string description: Where to go next. Only present on the `rate_limit` variant of 429. AuthError: type: object description: >- Returned when the API token is missing, invalid, expired or lacks the required scope. properties: error: type: string description: Short error category. examples: - Authentication failed - Forbidden message: type: string description: Human-readable explanation. Absent on some 403 responses. examples: - 'Missing required scope: voice_agents:write' required: - error ApiError: type: object description: >- Error format with a stable machine-readable `error` code, a human-readable `message` and request-specific `details`. properties: error: type: string description: >- Stable machine-readable error code, for example `mf-core:rate-limit-exceeded`. message: type: string description: Human-readable explanation. details: type: object additionalProperties: true description: >- Request-specific data, for example the offending parameter or the quota policy. required: - error - message - details responses: OutboundBadRequest: description: > Missing or invalid parameters; no call was placed. Common causes: a number not in E.164 format, more than 10 bulk destinations, a prompt placeholder with no matching variable, mixing shared and per-destination `prompt_variables`, mixing string and object destinations, a reserved or over-long variable, or sending both `prompt_variables` and `variables`. content: application/json: schema: $ref: '#/components/schemas/OutboundError' examples: format: summary: Invalid number format value: success: false error: >- Invalid destination format. Must be E.164 international format starting with '+', e.g. '+491761234567'. missingVariables: summary: Prompt placeholder not supplied (single call) value: success: false error: 'Missing prompt_variables keys: customer_name, order_id' missingVariablesBulk: summary: Prompt placeholder not supplied (bulk, names the destination) value: success: false error: 'Missing prompt_variables keys for +491761234567: customer_name' tooManyKeys: summary: Variable limits value: success: false error: prompt_variables exceeds maximum of 10 keys reservedKey: summary: Reserved variable key value: success: false error: >- 'variables' key 'system__id' uses a reserved prefix (system__, secret__) sipCallerNumber: summary: SIP agent without caller_number value: success: false error: >- Missing parameter: caller_number. Required when agent_number is a SIP ID. OutboundUnauthorized: description: >- Missing or invalid API token. Outbound-token failures use the `success`/`error` shape; scoped-token failures (expired, revoked, IP not allowed) use the `error`/`message` shape. content: application/json: schema: anyOf: - $ref: '#/components/schemas/OutboundError' - $ref: '#/components/schemas/AuthError' examples: missing: value: success: false error: Missing authorization token invalid: value: success: false error: Invalid authorization token scopedExpired: value: error: Authentication failed message: Token expired OutboundForbidden: description: >- Outbound calling is switched off for your account, or the scoped token lacks the required outbound scope. Contact support for the first case. content: application/json: schema: anyOf: - $ref: '#/components/schemas/OutboundError' - $ref: '#/components/schemas/AuthError' examples: disabled: value: success: false error: Outbound calls are currently disabled missingScope: value: error: Forbidden message: 'Missing required scope: outbound:write' OutboundAgentNotFound: description: No agent matches `agent_number` on your account. content: application/json: schema: $ref: '#/components/schemas/OutboundError' example: success: false error: Agent not found or not accessible OutboundUnprocessableEntity: description: >- The request was valid but the call could not be placed. Calls rejected by a limit or lock are not recorded; a failed carrier attempt is kept and visible in the batch. content: application/json: schema: $ref: '#/components/schemas/OutboundError' examples: dailyLimit: summary: Daily calling allowance exhausted value: success: false error: >- This request exceeds your available outbound calling allowance for today. Request a higher limit to continue. error_type: outbound_limit_request_exceeded locked: summary: Account locked value: success: false error: Tenant is locked destinationNotPermitted: summary: Destination country not enabled value: success: false error: >- Outbound calls to this destination country are not enabled on your account. Please contact support to have the destination enabled. error_type: destination_not_permitted callerIdNotAllowed: summary: Caller ID not registered value: success: false error: >- The sender number you provided is not registered on your account. Please check the caller number and try again. error_type: caller_id_not_allowed placementFailed: summary: Unclassified carrier failure value: success: false error: An error occurred. Please try again or contact support. error_type: placement_failed OutboundRateLimited: description: > Too many requests or calls in a short window. Single-call requests are limited to 20 per 5 minutes and bulk requests to 5 per 10 minutes per account, and at most 20 calls may be started per 5 minutes across API, dashboard and campaign calls. Wait a few minutes and retry. A `Retry-After` header is sent only on the `rate_limit` variant. headers: Retry-After: description: >- Seconds to wait before retrying. Present only on the `rate_limit` variant. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/OutboundError' examples: burst: summary: Request or call burst limit (common) value: success: false error: >- You're placing calls too quickly. Please wait a few minutes and try again. error_type: outbound_burst_limited placement: summary: Limit hit while dialing (rare, carries Retry-After) value: success: false error: Outbound rate limit exceeded. Please retry later. error_type: rate_limit detail: >- You have reached your outbound calling limit. Open the Outbound page in your dashboard to request a higher daily limit. OutboundServiceUnavailable: description: >- Outbound calling is temporarily unavailable, or the request exceeded the 30-second request time limit that applies to every API call. Retry shortly. content: application/json: schema: oneOf: - $ref: '#/components/schemas/OutboundError' title: Outbound unavailable - $ref: '#/components/schemas/ApiError' title: Request timeout examples: limiter: value: success: false error: >- Outbound calling is temporarily unavailable. Please try again in a few minutes. error_type: outbound_temporarily_unavailable timeout: value: error: mf-core:api-request-timeout message: The API request exceeded the 30-second time limit details: {} securitySchemes: scopedJwt: type: http scheme: bearer bearerFormat: JWT description: >- Scoped API token. Required scopes are listed on each operation in x-required-scopes. outboundBearer: type: http scheme: bearer description: > Outbound token from the **Outbound Calls** page. It can no longer be created or rotated; existing tokens keep working with full outbound access. For new integrations, create a scoped API token on the **Keys** page with the Outbound scope (`outbound:read` for read-only, `outbound:*` for full access) and send it as `scopedJwt`. The deprecated `/api/v1/outbound_calls` operations accept only this token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.