> ## Documentation Index > Fetch the complete documentation index at: https://aipro.placetel.de/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 /calls openapi: 3.1.0 info: title: Outbound Calls API version: 1.0.0-beta description: | REST API for placing AI-powered outbound calls to your contacts. Place a single call or a batch, personalize each call's prompt, and review the results. This reference is in **beta**: the endpoints below are live in production, but the reference itself is still being expanded to cover the rest of the platform API. servers: - url: https://aipro.placetel.de/api/v1/outbound security: - bearerAuth: [] tags: - name: Calls description: Place outbound calls. - name: Batches description: Review the outcome of calls you placed. - name: Consents description: Manage individual call records before they are dialed. paths: /calls: post: tags: - 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, the agent's SIP ID works here too - see the Introduction. examples: - '+4921186942846' caller_number: type: string description: | Caller ID shown to the recipient, in E.164 format. Only needed for SIP-trunk agents - see the Introduction. pattern: ^\+\d+$ examples: - '+4921154229976' prompt_variables: $ref: '#/components/schemas/PromptVariables' metadata: $ref: '#/components/schemas/Metadata' 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 call_id: type: string description: > The primary public identifier for this call. Also available in post-call callbacks as `%%call_id%%`. examples: - outb_Ux7yQm2ZK9vLd0Rb1cAeTg consent_id: type: integer description: >- Identifier of the underlying call record. Use it to [cancel](#tag/consents) the call before it is dialed. examples: - 48213 outbound_ref: type: string format: uuid description: Internal reference for this call, stable across retries. 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' agent_number: type: string examples: - '4921186942846' 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/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/AgentNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/ServiceUnavailable' components: schemas: PromptVariables: 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 25 keys, each value up to 500 characters. The `system__` and `secret__` prefixes are reserved. additionalProperties: type: string maxLength: 500 examples: - customer_name: Max Mustermann order_id: ORD-2026-0042 Metadata: type: object description: | Your own values, carried through the call and returned in the post-call callback. `external_call_id` is echoed back at the top level of the placement response so you can correlate it with your own records. properties: external_call_id: type: string description: Your correlation id for this call. additionalProperties: type: string Error: type: object properties: success: type: boolean examples: - false error: type: string description: Description of the issue, in English. error_type: type: string description: Machine-readable error category, present on limit-related errors. detail: type: string description: Where to go next, present on rate-limit errors. responses: BadRequest: 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, or mixing shared and per-destination `prompt_variables`. content: application/json: schema: $ref: '#/components/schemas/Error' 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 value: success: false error: 'Missing prompt_variables keys: customer_name, order_id' Unauthorized: description: Missing or invalid API token. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Outbound calling is not enabled for your account. content: application/json: schema: $ref: '#/components/schemas/Error' AgentNotFound: description: No agent matches `agent_number` on your account. content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false error: Agent not found or not accessible UnprocessableEntity: description: | The request was understood but could not be carried out - most often your daily call limit is reached, or the account is locked. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: > Too many requests, or your outbound calling limit is reached. Retry after the period given in the `Retry-After` header, or request a higher daily limit from the Outbound page in your dashboard. headers: Retry-After: description: >- Seconds to wait before retrying. Present when a retry window is known. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: 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. ServiceUnavailable: description: Outbound calling is temporarily unavailable. Retry shortly. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: | Generate (or rotate) your token on the **Outbound Calls** page in your dashboard. The token is shown once - store it securely; rotating it invalidates the previous token. A token only reaches your own agents and data. ````