> ## 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 a call > Place a single outbound call. The call is dialed immediately. The whole request is validated before the call is placed - on a `400` no call is made. ## OpenAPI ````yaml /api-reference/openapi.yaml post /api/v1/outbound/calls 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: post: tags: - Outbound Calls summary: Place a call description: | Place a single outbound call. The call is dialed immediately. The whole request is validated before the call is placed - on a `400` no call is made. operationId: placeCall requestBody: required: true content: application/json: schema: type: object required: - destination - agent_number properties: destination: type: string description: >- Number to call, in E.164 format (`+` followed by digits only). pattern: ^\+\d+$ examples: - '+491761234567' agent_number: type: string description: >- Your agent's phone number (a leading `+` is optional). If your account connects its own SIP trunk, pass the agent's SIP ID (a value starting with `t`) instead and 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; the number must be registered on your account. Ignored for agents with a purchased number. pattern: ^\+\d+$ examples: - '+4921154229976' prompt_variables: allOf: - $ref: '#/components/schemas/OutboundPromptVariables' description: >- Deprecated alias of `variables`. Send one of the two, not both. deprecated: true metadata: $ref: '#/components/schemas/OutboundMetadata' variables: allOf: - $ref: '#/components/schemas/OutboundPromptVariables' description: >- Values for the `{{placeholders}}` in the agent's prompt. Send either `variables` or `prompt_variables`, not both. examples: minimal: summary: Minimal request value: destination: '+491761234567' agent_number: '+4921186942846' personalized: summary: Personalized call with correlation id value: destination: '+491761234567' agent_number: '+4921186942846' prompt_variables: customer_name: Max Mustermann order_id: ORD-2026-0042 metadata: external_call_id: crm-8842 responses: '201': description: Call placed. content: application/json: schema: type: object properties: success: type: boolean examples: - true description: Always true. call_id: type: string description: >- The public identifier of this call. Use it to find the conversation in `GET /api/v1/conversations`. examples: - outb_Ux7yQm2ZK9vLd0Rb1cAeTg consent_id: type: integer description: >- Identifier of the underlying call record (the `id` shown in batch detail). The call is already dialed when you receive this response, so it cannot be canceled. examples: - 48213 batch_id: type: string format: uuid description: > Batch this call belongs to (every call gets one, single calls included). Look the call up with `GET /api/v1/outbound/batches/{batch_id}`. outbound_ref: type: string format: uuid description: Reference for this call. Quote it when contacting support. call_sid: type: string description: >- Telephony-level call identifier. Format depends on the carrier behind your agent. status: type: string description: Placement status at the moment of the response. examples: - initiated destination: type: string examples: - '+491761234567' description: The number that was called. agent_number: type: string examples: - '+4921186942846' description: The agent's number in E.164, or its SIP ID. external_call_id: type: string description: | Echoed back unchanged when you send `metadata.external_call_id`. Omitted otherwise. examples: - crm-8842 '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 OutboundMetadata: type: object description: > Your own values, carried through the call and returned with its results. `external_call_id` is echoed back at the top level of the placement response so you can correlate it with your own records. Up to 25 keys; strings, numbers and booleans are accepted (`null` values are dropped), strings up to 500 characters. The same reserved-key rules as `prompt_variables` apply. Not supported on bulk requests. maxProperties: 25 properties: external_call_id: type: string description: Your correlation id for this call. additionalProperties: type: - string - number - boolean 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.