> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qall.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Place an outbound call

> Have an assistant ring someone from your own code.

One request dials one person. For a list on a schedule, use a
[campaign](/campaigns) instead — it handles pacing, dialling hours, retries and
voicemail.

## The request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://qall.io/api/telephony/calls/initiate \
    -H "Authorization: Bearer $QALL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to_phone_number": "+4930111111",
      "from_phone_number": "+4930999999",
      "variables": {
        "order_number": "ORD-4417",
        "delivery_date": "14 March"
      }
    }'
  ```

  ```python Python theme={null}
  import os, requests

  result = requests.post(
      "https://qall.io/api/telephony/calls/initiate",
      headers={"Authorization": f"Bearer {os.environ['QALL_API_KEY']}"},
      json={
          "to_phone_number": "+4930111111",
          "from_phone_number": "+4930999999",
          "variables": {"order_number": "ORD-4417", "delivery_date": "14 March"},
      },
      timeout=30,
  ).json()

  print(result["call_sid"])
  ```
</CodeGroup>

| Field | |
| - | - |
| `to_phone_number` | Who to call. Required. |
| `from_phone_number` | Which of your numbers to call from. |
| `welcome_message` | Override the assistant's opening line for this call only. |
| `variables` | Values for this call, readable as `{{var.*}}` in the prompt, the opening line, and any tool. |

## Passing in context

`variables` is what makes an outbound call useful. Whatever you send is available
throughout the call:

```text theme={null}
You are calling {{contact.first_name}} about order {{var.order_number}},
due to arrive on {{var.delivery_date}}.
```

Values you pass in are treated as untrusted and cleaned before use, so a value
from your database can't carry instructions into the prompt. See
[Variables](/variables).

## What comes back

```json theme={null}
{
  "success": true,
  "message": "Call initiated",
  "call_sid": "call_01h...",
  "provider_call_sid": null
}
```

The response returns as soon as the call is queued — **before anyone picks up**.
`provider_call_sid` is empty at this point, because the carrier hasn't been
reached yet.

So don't treat a 200 as "they answered". Wait for
[`call.completed`](/api-reference/webhooks/call-completed), matching on
`call_sid`.

## Knowing how it went

Subscribe to [webhooks](/api-reference/webhooks) rather than polling. You'll get
`call.completed` with the summary, transcript and [outcomes](/outcomes) when the
conversation ends.

To check a single call on demand, `GET /api/calls/{call_sid}`.

## Before it will work

You need a [phone connection](/phone-numbers) with an outbound number, and an
assistant to answer. If `from_phone_number` isn't one of your managed numbers the
request is rejected.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.