> ## 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. # Outbound Calls API > REST API for placing AI-powered outbound calls to your contacts. REST API for placing AI-powered outbound calls to your contacts. Place a single call or a batch, personalize each call's prompt, and check the results. **Base URL:** `https://aipro.placetel.de/api/v1/outbound` ## Authentication Every request must send a Bearer token in the `Authorization` header: ``` Authorization: Bearer ``` Generate (or rotate) your token on the **Outbound Calls** page in your dashboard ("Generate API Token"). The token is shown once — store it securely; rotating it invalidates the previous token. Each token only reaches your own agents and data. ## 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 ``` ## Endpoints ### Place a Call ``` POST /api/v1/outbound/calls ``` Place a single outbound call. The call is dialed immediately. #### Request Body (JSON) | Parameter | Type | Required | Description | | ------------------ | ------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `destination` | string | Yes | Number to call (E.164) | | `agent_number` | string | Yes | Your agent's phone number (a leading `+` is optional), or its SIP ID (a value starting with `t`) | | `prompt_variables` | object | No | Values injected into the agent's prompt. See [Personalizing the Prompt](#personalizing-the-prompt). | | `caller_number` | string | SIP agents only | Caller ID shown to the recipient (E.164). Required when `agent_number` is a SIP ID, and must be a number registered on your Placetel account. | #### Response ```json theme={null} HTTP 201 Created { "success": true, "call_id": "outb_...", "status": "dialing", "destination": "+491761234567" } ``` Use `call_id` to reference the call. The call's outcome and transcript appear in your dashboard — see [Checking Results](#checking-results). ### Place Calls in Bulk ``` POST /api/v1/outbound/calls/bulk ``` Place calls to multiple destinations in one request. Up to **10 destinations**. #### Request Body (JSON) | Parameter | Type | Required | Description | | ------------------ | ------ | --------------- | ------------------------------------------------------------------------------- | | `destinations` | array | Yes | Up to 10 destinations. See formats below. | | `agent_number` | string | Yes | Your agent's phone number or SIP ID | | `prompt_variables` | object | No | Shared variables applied to every destination (see the mixing rule below) | | `caller_number` | string | SIP agents only | Caller ID for SIP agents; must be a number registered on your Placetel account. | #### Destinations format Each destination is an object with a `phone` field and optional per-destination `prompt_variables`: ```json theme={null} "destinations": [ { "phone": "+491761234567", "prompt_variables": { "customer_name": "Max" } }, { "phone": "+491769876543", "prompt_variables": { "customer_name": "Anna" } } ] ``` If you don't need per-destination values, omit `prompt_variables`: ```json theme={null} "destinations": [ { "phone": "+491761234567" }, { "phone": "+491769876543" } ] ``` To apply the **same** values to every destination, send a single top-level `prompt_variables` instead: ```json theme={null} { "agent_number": "+4921186942846", "destinations": [ { "phone": "+491761234567" }, { "phone": "+491769876543" } ], "prompt_variables": { "campaign": "Spring 2026" } } ``` Top-level and per-destination `prompt_variables` **cannot be combined** in the same request — use one or the other. **The whole request is validated before any call is placed.** If it fails validation — for example an invalid number format, more than 10 destinations, or a missing or invalid prompt variable — the entire request is rejected with a `400` and **no calls are placed**. **Once validation passes, each destination is dialed independently.** If the call fails at the telephony level for one number, the others still go through — so a bulk can return a mix of successes and failures per destination (see the response below). Duplicate destinations (identical numbers) are de-duplicated — each unique number is called once. #### Response ```json theme={null} HTTP 201 Created { "success": true, "total": 3, "succeeded": 2, "failed": 1, "results": [ { "destination": "+491761234567", "success": true, "status": "dialing", "error": null }, { "destination": "+491760000000", "success": false, "status": "failed", "error": "Something went wrong. Please try again or contact support." } ] } ``` A bulk returns `201` even when some — or all — calls fail: check each entry's `success` and `status` in `results[]`, and the top-level `succeeded` / `failed` counts summarize the batch. A non-`201` status means the whole request was rejected (see [Errors](#errors)). Call outcomes also appear in your dashboard — see [Checking Results](#checking-results). ### Checking Results Call outcomes appear in your dashboard — in your [outbound call history](https://aipro.placetel.de/outbound/history) or in [Conversations](https://aipro.placetel.de/conversations): whether each call connected, plus the full conversation and transcript. Filter by the agent you placed the calls with to find them. ## 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 using `{{name}}` syntax: ``` Hello {{customer_name}}, I'm calling about your order {{order_id}}. ``` **2. Provide the values** in `prompt_variables` 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`. * Values must be strings (send numbers and booleans as strings, e.g. `"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. ## Errors All errors share this shape: ```json theme={null} { "success": false, "error": "Description of the issue" } ``` #### HTTP Status Codes | Code | Meaning | | ----- | --------------------------------------------------------------- | | `201` | Success — call(s) placed | | `400` | Bad request — missing or invalid parameters | | `401` | Unauthorized — missing or invalid API token | | `403` | Forbidden — outbound calling isn't enabled for your account | | `404` | Not found — agent not found | | `422` | Your daily call limit has been reached — contact us to raise it | #### Common Validation Errors (400) | Error message | Cause | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | `Missing parameter: destination` | `destination` not provided | | `Missing parameter: agent_number` | `agent_number` not provided | | `Invalid destination format. Must be E.164 international format starting with '+', e.g. '+491761234567'.` | Number not in E.164 | | `Agent not found or not accessible` | Agent doesn't exist | | `Maximum 10 destinations allowed per request` | Bulk request over the limit | | `Missing prompt_variables keys: customer_name, order_id` | Prompt has placeholders not covered by the supplied variables | | `prompt_variables values must be strings` | A prompt-variable value is not a string | | `Cannot combine top-level prompt_variables with per-destination prompt_variables` | Mixed variable modes in a bulk request | ## Quickstart **One call:** ```bash theme={null} curl -X POST https://aipro.placetel.de/api/v1/outbound/calls \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "destination": "+491761234567", "agent_number": "+4921186942846" }' ``` **Personalized bulk calls:** ```bash theme={null} curl -X POST https://aipro.placetel.de/api/v1/outbound/calls/bulk \ -H "Authorization: Bearer " \ -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" } } ] }' ``` **Check results** — call outcomes and transcripts appear in your dashboard; see [Checking Results](#checking-results).