Outbound Calls API

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 <your-api-token>

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.
`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

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.

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:

"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:

"destinations": [
  { "phone": "+491761234567" },
  { "phone": "+491769876543" }
]

To apply the same values to every destination, send a single top-level prompt_variables instead:

{
  "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

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). Call outcomes also appear in your dashboard — see Checking Results.

Checking Results

Call outcomes appear in your dashboard — in your outbound call history or in 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:

{
  "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:

{
  "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:

curl -X POST https://aipro.placetel.de/api/v1/outbound/calls \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "+491761234567",
    "agent_number": "+4921186942846"
  }'

Personalized bulk calls:

curl -X POST https://aipro.placetel.de/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" } }
    ]
  }'

Check results — call outcomes and transcripts appear in your dashboard; see Checking Results.

Getting Started

AI Assistants

AI Content & Context

Advanced Features

Chat Channels

Tickets

Team

Agent Templates

Authentication

Phone Number Format

Endpoints

Place a Call

Request Body (JSON)

Response

Place Calls in Bulk

Request Body (JSON)

Destinations format

Response

Checking Results

Personalizing the Prompt

Rules

Errors

HTTP Status Codes

Common Validation Errors (400)

Quickstart

​Authentication

​Phone Number Format

​Endpoints

​Place a Call

​Request Body (JSON)

​Response

​Place Calls in Bulk

​Request Body (JSON)

​Destinations format

​Response

​Checking Results

​Personalizing the Prompt

​Rules

​Errors

​HTTP Status Codes

​Common Validation Errors (400)

​Quickstart

Authentication

Phone Number Format

Endpoints

Place a Call

Request Body (JSON)

Response

Place Calls in Bulk

Request Body (JSON)

Destinations format

Response

Checking Results

Personalizing the Prompt

Rules

Errors

HTTP Status Codes

Common Validation Errors (400)

Quickstart