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

# Placing Outbound Calls

> Initiate calls from Annie to your patients

Annie can place outbound calls on your behalf for appointment reminders, recall campaigns, follow-up calls, and patient outreach.

## How Outbound Calls Work

Annie's outbound calls are driven by the **workflows and training configured on your bot**. For example, you might have a workflow for confirming appointments or a workflow for recall outreach — these define how Annie handles the conversation, what questions to ask, and how to respond.

When initiating a call, you can optionally provide:

* **Patient info** — The patient's name and date of birth so Annie can address them correctly
* **Call context** — Specific details for this individual call (e.g., "Their appointment is Thursday at 2pm")

Think of it this way: your bot's training defines *what* Annie does (confirm an appointment, schedule a recall visit), while patient info and context provide the *specifics* for each call.

<Tip>
  Consider creating separate bots for different outbound campaigns (e.g., one for appointment reminders, another for recall outreach) so each has tailored workflows.
</Tip>

## Making an Outbound Call

To place an outbound call, make a POST request to the calls endpoint:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.helloannie.com/v1/calls \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "fromNumber": "+15551234567",
      "toNumber": "+15559876543",
      "patientInfo": {
        "firstName": "Sarah",
        "lastName": "Johnson",
        "dateOfBirth": "1985-03-22"
      },
      "context": "You are calling Sarah Johnson to remind her about her upcoming cleaning appointment on Friday at 2pm. She prefers to be called by her first name."
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.helloannie.com/v1/calls", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      fromNumber: "+15551234567",
      toNumber: "+15559876543",
      patientInfo: {
        firstName: "Sarah",
        lastName: "Johnson",
        dateOfBirth: "1985-03-22"
      },
      context: "You are calling Sarah Johnson to remind her about her upcoming cleaning appointment on Friday at 2pm. She prefers to be called by her first name."
    })
  })

  const { data } = await response.json()
  // data.conversationId can be used to track the call
  ```

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

  response = requests.post(
      "https://api.helloannie.com/v1/calls",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "fromNumber": "+15551234567",
          "toNumber": "+15559876543",
          "patientInfo": {
              "firstName": "Sarah",
              "lastName": "Johnson",
              "dateOfBirth": "1985-03-22"
          },
          "context": "You are calling Sarah Johnson to remind her about her upcoming cleaning appointment on Friday at 2pm. She prefers to be called by her first name."
      }
  )

  data = response.json()["data"]
  # data["conversationId"] can be used to track the call
  ```
</CodeGroup>

### Request Parameters

| Parameter     | Type   | Required | Description                                                                           |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `fromNumber`  | string | Yes      | The Annie phone number to call from (must be attached to a bot with `outbound: true`) |
| `toNumber`    | string | Yes      | The destination phone number (must be in allowed whitelist for sandbox)               |
| `patientInfo` | object | No       | Patient information for the call (see below)                                          |
| `context`     | string | No       | Custom instructions or context for this specific call (max 500 characters)            |

#### Patient Info Object

| Field         | Type   | Description                                    |
| ------------- | ------ | ---------------------------------------------- |
| `firstName`   | string | Patient's first name (max 100 characters)      |
| `lastName`    | string | Patient's last name (max 100 characters)       |
| `dateOfBirth` | string | Patient's date of birth in `YYYY-MM-DD` format |

<Info>
  The `fromNumber` must be a phone number attached to a bot with `outbound` set to `true`. When creating or updating your bot, set this field to enable outbound calling.
</Info>

## Using Call Context

The `context` field lets you provide call-specific details that supplement your bot's workflows. Your bot's training still drives the conversation and then context just fills in the specifics.

**Example:** If your bot has an appointment confirmation workflow, the context tells Annie *which* appointment to confirm:

```json theme={null}
{
  "context": "Confrim John Deer's cleaning appointment at Thursday, January 30th at 2pm with Dr. Martinez."
}
```

Good uses for context:

* Appointment date, time, and provider details
* Reason for the call (e.g., "6-month recall" or "post-procedure follow-up")
* Patient preferences or notes (e.g., "Prefers morning appointments")

<Tip>
  Combine `patientInfo` with `context` for best results. Patient info helps Annie greet them correctly, while context provides the call-specific details your workflow needs.
</Tip>

## Response

A successful request returns a conversation ID for tracking:

```json theme={null}
{
  "success": true,
  "data": {
    "conversationId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

## Tracking Call Status

Use the conversation ID to check the status and details of the call:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.helloannie.com/v1/conversations/CONVERSATION_ID \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.helloannie.com/v1/conversations/CONVERSATION_ID",
    {
      headers: {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  )

  const { data } = await response.json()
  ```

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

  response = requests.get(
      "https://api.helloannie.com/v1/conversations/CONVERSATION_ID",
      headers={
          "Authorization": "Bearer YOUR_API_KEY"
      }
  )

  data = response.json()["data"]
  ```
</CodeGroup>

## Use Cases

<AccordionGroup>
  <Accordion title="Appointment Reminders">
    Automatically call patients to remind them of upcoming appointments. Configure your bot's workflow to confirm the appointment details during the call.
  </Accordion>

  <Accordion title="Recall Campaigns">
    Reach out to patients who are due for their regular checkups. Annie can check availability and schedule appointments during the call.
  </Accordion>

  <Accordion title="Follow-up Calls">
    Call patients after procedures to check on their recovery and answer any questions they may have.
  </Accordion>
</AccordionGroup>

## Sandbox Limitations

<Warning>
  **Sandbox Environment:** In sandbox mode, you must pre-approve destination phone numbers before Annie can call them. This prevents accidental calls during testing.

  Contact your Annie representative to add numbers to your sandbox allowlist, or email [devs@helloannie.com](mailto:devs@helloannie.com).

  Production endpoints for self-service management of approved numbers are coming soon.
</Warning>

***

<Card title="Calls API Reference" icon="code" href="/api-reference/calls/start-outbound-call">
  See the full API reference for the calls endpoint.
</Card>