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

# Setting Up a Phone Number

> A complete guide to provisioning, configuring, and attaching phone numbers to your Annie agent

Phone numbers connect callers to your AI agent. When someone calls the number, Annie answers and handles the conversation based on the attached bot's training. This guide walks through every step of setting up a phone number — from choosing the right area code to attaching it to your bot.

## Prerequisites

Before provisioning a phone number, make sure you have:

* An [organization](/overview/guides/organizations/overview) created with a complete address and timezone
* A [bot](/overview/guides/bots/overview) configured with greetings and training
* An API key with write permissions (see [Authentication](/overview/authentication))

## Step 1: Choose the Right Area Code

When you provision a phone number, Annie purchases a real US phone number for your organization. You can specify a **3-digit US area code** to control where the number appears to be from.

<Tip>
  Choose an area code that matches your organization's location. Patients are more likely to answer calls and trust numbers with a local area code. For example, a dental office in Chicago should use a `312` or `773` area code.
</Tip>

**How area code selection works:**

* If you provide a valid `areaCode`, Annie provisions a number from that area code
* If you omit `areaCode`, a default area code is used — we recommend always specifying one
* The area code must be a valid US area code (3 digits)

To find the right area code, look up the area code for your organization's city or region. If your practice has multiple locations, use a local area code for each.

<Warning>
  In rare cases, a specific area code may not have numbers available. If provisioning fails, try a nearby area code in the same region.
</Warning>

## Step 2: Provision the Phone Number

Create a new phone number by making a POST request to the phone numbers endpoint. You'll need to specify the organization, a friendly name, the language, voice, and area code.

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch("https://api.helloannie.com/v1/phone-numbers", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      orgId: "YOUR_ORG_ID",
      botId: "YOUR_BOT_ID",
      name: "Main Line",
      language: "ENGLISH",
      voiceId: "FRIENDLY_BRIGHT",
      areaCode: "312"
    })
  })

  const { data } = await response.json()
  console.log(data.number) // e.g. "+13125551234"
  console.log(data.id)     // Use this ID for future operations
  ```

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

  response = requests.post(
      "https://api.helloannie.com/v1/phone-numbers",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "orgId": "YOUR_ORG_ID",
          "botId": "YOUR_BOT_ID",
          "name": "Main Line",
          "language": "ENGLISH",
          "voiceId": "FRIENDLY_BRIGHT",
          "areaCode": "312"
      }
  )

  data = response.json()["data"]
  print(data["number"])  # e.g. "+13125551234"
  print(data["id"])      # Use this ID for future operations
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helloannie.com/v1/phone-numbers \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "orgId": "YOUR_ORG_ID",
      "botId": "YOUR_BOT_ID",
      "name": "Main Line",
      "language": "ENGLISH",
      "voiceId": "FRIENDLY_BRIGHT",
      "areaCode": "312"
    }'
  ```
</CodeGroup>

### Required Fields

<ParamField body="orgId" type="string" required>
  The organization ID that will own this phone number. The phone number inherits the organization's context (address, hours, timezone) for handling calls.
</ParamField>

<ParamField body="name" type="string" required>
  A friendly name to identify this phone number. Use descriptive names that reflect the number's purpose.

  **Examples:** `"Main Line"`, `"After Hours"`, `"Spanish Line"`, `"Recall Outreach"`
</ParamField>

<ParamField body="language" type="string" required>
  The language Annie uses when answering calls on this number. This controls both the voice model and the language of the conversation.

  | Value     | Description  |
  | :-------- | :----------- |
  | `ENGLISH` | English (US) |
  | `SPANISH` | Spanish      |
  | `FRENCH`  | French       |

  See [Configuring Language](#configuring-language) for details on setting up language for your phone numbers.
</ParamField>

<ParamField body="voiceId" type="string" required>
  The voice Annie uses when speaking to callers. Each voice has a distinct personality and tone.

  | Voice ID                | Description                             |
  | :---------------------- | :-------------------------------------- |
  | `FRIENDLY_BRIGHT`       | Warm, welcoming, and easy to understand |
  | `CALM_REASSURING`       | Subtle, gentle voice that builds trust  |
  | `POLISHED_PROFESSIONAL` | Crisp, formal, business-ready clarity   |
  | `KIND_CURIOUS`          | Thoughtful and asks with care           |
  | `CONFIDENT_UPBEAT`      | Energetic, decisive, and positive       |
</ParamField>

<Tip>
  `FRIENDLY_BRIGHT` is the most popular choice for dental and healthcare practices.
</Tip>

### Optional Fields

<ParamField body="botId" type="string">
  The bot ID to attach the phone number to immediately. If omitted, the phone number is created in a detached state and must be attached to a bot before it can handle calls. See [Step 3](#step-3-attach-to-a-bot) for details.
</ParamField>

<ParamField body="areaCode" type="string">
  A 3-digit US area code for the phone number (e.g., `"312"` for Chicago, `"212"` for New York). If omitted, a default area code is assigned.

  We strongly recommend providing an area code that matches your organization's location for caller trust and recognition.
</ParamField>

<ParamField body="verifiedCallerId" type="string">
  A verified caller ID for outbound calls, in `+1XXXXXXXXXX` format. Must be pre-registered and verified for the organization. See [Verified Caller IDs](/api-reference/verified-caller-ids/list-verified-caller-ids) for setup.
</ParamField>

<ParamField body="callbackForwardingNumber" type="string">
  If a recipient calls back an outbound number, the call will be forwarded to this phone number. This field only applies to outbound numbers and is ignored for inbound numbers.
</ParamField>

## Step 3: Attach to a Bot

If you provided a `botId` during provisioning, the phone number is already attached and ready to receive calls. If not, attach it now:

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/attach",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        botId: "YOUR_BOT_ID"
      })
    }
  )

  const { data } = await response.json()
  // data.botId now contains the attached bot ID
  ```

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

  response = requests.post(
      "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/attach",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "botId": "YOUR_BOT_ID"
      }
  )

  data = response.json()["data"]
  # data["botId"] now contains the attached bot ID
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/attach \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "botId": "YOUR_BOT_ID"
    }'
  ```
</CodeGroup>

<Info>
  The bot must belong to the same organization as the phone number. You cannot attach a phone number owned by one organization to a bot in a different organization.
</Info>

### Choosing the Right Bot

Which bot you attach determines how Annie handles calls on this number. Consider your use case:

| Use Case                 | Bot Setup                                                                                         |
| :----------------------- | :------------------------------------------------------------------------------------------------ |
| **General receptionist** | A bot trained with comprehensive workflows, FAQs, and scheduling capabilities                     |
| **After-hours line**     | A bot with a `closedPhoneGreeting` and training focused on message-taking and basic scheduling    |
| **Spanish line**         | A bot with Spanish-language training, paired with a phone number set to `language: "SPANISH"`     |
| **Outbound campaigns**   | A bot with `outbound: true` and campaign-specific workflows (e.g., appointment reminders, recall) |
| **Scheduling only**      | A bot trained exclusively on appointment scheduling workflows                                     |

<Tip>
  If you're managing multiple locations, create a separate bot for each location so that each has location-specific training and greetings. Attach each location's phone number to its corresponding bot.
</Tip>

### Detaching a Phone Number

To switch a phone number to a different bot, first detach it:

<CodeGroup>
  ```javascript Node.js theme={null}
  // Detach from current bot
  await fetch(
    "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/detach",
    {
      method: "POST",
      headers: { "Authorization": "Bearer YOUR_API_KEY" }
    }
  )

  // Attach to new bot
  await fetch(
    "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/attach",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ botId: "NEW_BOT_ID" })
    }
  )
  ```

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

  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  # Detach from current bot
  requests.post(
      "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/detach",
      headers=headers
  )

  # Attach to new bot
  requests.post(
      "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/attach",
      headers=headers,
      json={"botId": "NEW_BOT_ID"}
  )
  ```

  ```bash cURL theme={null}
  # Detach from current bot
  curl -X POST https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/detach \
    -H "Authorization: Bearer YOUR_API_KEY"

  # Attach to new bot
  curl -X POST https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/attach \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"botId": "NEW_BOT_ID"}'
  ```
</CodeGroup>

## Step 4: Verify Your Setup

After provisioning and attaching, confirm everything is configured correctly by retrieving your phone number:

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID",
    {
      headers: { "Authorization": "Bearer YOUR_API_KEY" }
    }
  )

  const { data } = await response.json()

  // Verify these fields are set correctly:
  console.log("Number:", data.number)       // The provisioned phone number
  console.log("Bot:", data.botId)           // Should be your bot's ID
  console.log("Org:", data.orgId)           // Should be your org's ID
  console.log("Language:", data.language)   // ENGLISH, SPANISH, or FRENCH
  console.log("Voice:", data.voiceId)       // Your selected voice
  ```

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

  response = requests.get(
      "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )

  data = response.json()["data"]

  # Verify these fields are set correctly:
  print("Number:", data["number"])       # The provisioned phone number
  print("Bot:", data["botId"])           # Should be your bot's ID
  print("Org:", data["orgId"])           # Should be your org's ID
  print("Language:", data["language"])   # ENGLISH, SPANISH, or FRENCH
  print("Voice:", data["voiceId"])       # Your selected voice
  ```

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

**Checklist — make sure:**

* `botId` is not `null` (the number is attached to a bot)
* `language` matches the language your bot is trained in
* `orgId` matches the organization for this location
* `voiceId` is the voice you want callers to hear

## Updating Phone Number Configuration

After provisioning, you can update the language, voice, or caller ID settings:

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID",
    {
      method: "PATCH",
      headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        language: "SPANISH",
        voiceId: "CALM_REASSURING"
      })
    }
  )
  ```

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

  response = requests.patch(
      "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "language": "SPANISH",
          "voiceId": "CALM_REASSURING"
      }
  )
  ```

  ```bash cURL theme={null}
  curl -X PATCH https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "language": "SPANISH",
      "voiceId": "CALM_REASSURING"
    }'
  ```
</CodeGroup>

<Info>
  To change which bot a phone number is attached to, use the [attach](/api-reference/phone-numbers/attach-phone-number-to-bot) and [detach](/api-reference/phone-numbers/detach-phone-number-from-bot) endpoints instead of PATCH. This is a deliberate design decision to prevent accidental changes.
</Info>

## Configuring Language

The `language` field on a phone number controls how Annie listens to and speaks with callers. When you set a language (`ENGLISH`, `SPANISH`, or `FRENCH`), Annie conducts the entire conversation in that language — including speech recognition, responses, and voice output.

### Dedicated Language Lines

For practices that serve specific language communities, dedicate a phone number to each language:

<CodeGroup>
  ```javascript Node.js theme={null}
  // Create a Spanish-language line
  const response = await fetch("https://api.helloannie.com/v1/phone-numbers", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      orgId: "YOUR_ORG_ID",
      botId: "YOUR_SPANISH_BOT_ID",
      name: "Spanish Line",
      language: "SPANISH",
      voiceId: "FRIENDLY_BRIGHT",
      areaCode: "305"
    })
  })
  ```

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

  # Create a Spanish-language line
  response = requests.post(
      "https://api.helloannie.com/v1/phone-numbers",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "orgId": "YOUR_ORG_ID",
          "botId": "YOUR_SPANISH_BOT_ID",
          "name": "Spanish Line",
          "language": "SPANISH",
          "voiceId": "FRIENDLY_BRIGHT",
          "areaCode": "305"
      }
  )
  ```

  ```bash cURL theme={null}
  # Create a Spanish-language line
  curl -X POST https://api.helloannie.com/v1/phone-numbers \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "orgId": "YOUR_ORG_ID",
      "botId": "YOUR_SPANISH_BOT_ID",
      "name": "Spanish Line",
      "language": "SPANISH",
      "voiceId": "FRIENDLY_BRIGHT",
      "areaCode": "305"
    }'
  ```
</CodeGroup>

<Tip>
  Make sure the bot attached to a non-English phone number has training in that language. For example, a Spanish line should be attached to a bot with Spanish-language FAQs, workflows, and greetings.
</Tip>

### Changing a Phone Number's Language

You can update the language of an existing phone number at any time using the PATCH endpoint:

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID",
    {
      method: "PATCH",
      headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        language: "SPANISH"
      })
    }
  )
  ```

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

  response = requests.patch(
      "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "language": "SPANISH"
      }
  )
  ```

  ```bash cURL theme={null}
  curl -X PATCH https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"language": "SPANISH"}'
  ```
</CodeGroup>

## Listing Phone Numbers

Retrieve all phone numbers for your organization:

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch("https://api.helloannie.com/v1/phone-numbers", {
    headers: { "Authorization": "Bearer YOUR_API_KEY" }
  })

  const { data } = await response.json()
  // data.phoneNumbers contains an array of phone numbers
  ```

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

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

  data = response.json()["data"]
  # data["phoneNumbers"] contains an array of phone numbers
  ```

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

You can filter by organization using the `orgId` query parameter:

```bash theme={null}
curl "https://api.helloannie.com/v1/phone-numbers?orgId=YOUR_ORG_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Call Forwarding

You can forward calls from your existing business number to your Annie number. This lets you keep your current phone number while having Annie answer.

Common setups:

* **Forward all calls** — Annie answers everything
* **Forward after hours** — Your staff answers during business hours, Annie handles after-hours
* **Forward on busy/no answer** — Annie picks up overflow calls

Configure forwarding through your phone provider (most VoIP and traditional phone systems support this).

## Multiple Numbers

Each organization can have up to **10 phone numbers**. You can use multiple numbers for different purposes:

* **Main line** → General bot with full training
* **Scheduling line** → Bot focused on appointment scheduling
* **After-hours line** → Bot with after-hours messaging
* **Spanish line** → Bot trained in Spanish, with a number set to `language: "SPANISH"`
* **Outbound line** → Bot configured for outbound campaigns

You can also attach multiple numbers to the same bot — useful for tracking different marketing campaigns or serving the same bot from different area codes.

## Deleting a Phone Number

To delete a phone number, it must first be detached from any bot:

<CodeGroup>
  ```javascript Node.js theme={null}
  // First detach if attached
  await fetch(
    "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/detach",
    {
      method: "POST",
      headers: { "Authorization": "Bearer YOUR_API_KEY" }
    }
  )

  // Then delete
  await fetch(
    "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID",
    {
      method: "DELETE",
      headers: { "Authorization": "Bearer YOUR_API_KEY" }
    }
  )
  ```

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

  headers = {"Authorization": "Bearer YOUR_API_KEY"}

  # First detach if attached
  requests.post(
      "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/detach",
      headers=headers
  )

  # Then delete
  requests.delete(
      "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID",
      headers=headers
  )
  ```

  ```bash cURL theme={null}
  # First detach if attached
  curl -X POST https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/detach \
    -H "Authorization: Bearer YOUR_API_KEY"

  # Then delete
  curl -X DELETE https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

<Warning>
  Deleting a phone number is **irreversible**. The number will be permanently released and cannot be recovered. Make sure you no longer need the number before deleting it.
</Warning>

## Migrating a Phone Number

To move a phone number to a different organization (e.g., when restructuring locations), use the migrate endpoint:

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/migrate",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        targetOrgId: "NEW_ORG_ID"
      })
    }
  )
  ```

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

  response = requests.post(
      "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/migrate",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "targetOrgId": "NEW_ORG_ID"
      }
  )
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/migrate \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "targetOrgId": "NEW_ORG_ID"
    }'
  ```
</CodeGroup>

<Info>
  Migrating a phone number clears its bot attachment, since the bot belongs to the original organization. After migration, attach the number to a bot in the new organization.
</Info>

***

## What's Next

<CardGroup cols={2}>
  <Card title="Inbound Calls" icon="phone-arrow-down-left" href="/overview/guides/deploying/inbound-calls">
    Start receiving calls once your phone number is attached
  </Card>

  <Card title="Outbound Calls" icon="phone-arrow-up-right" href="/overview/guides/deploying/outbound-calls">
    Use your phone number to place outbound calls to patients
  </Card>

  <Card title="Bot Configuration" icon="robot" href="/overview/guides/bots/overview">
    Configure your bot's greetings, industry, and training
  </Card>

  <Card title="Phone Numbers API" icon="code" href="/api-reference/phone-numbers/list-phone-numbers">
    See the full API reference for all phone number endpoints
  </Card>
</CardGroup>