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

# Purchase and assign phone numbers

> Search available numbers by country and area code, purchase one in seconds, and assign it to any AI assistant in your Talkturo workspace.

Adding a phone number to Talkturo takes less than a minute. You search for an available number using country and area code filters, click **Buy**, and the number appears in your account ready to assign to an assistant. This page walks you through the full process, including how to unassign a number when you want to re-route it.

<Steps>
  <Step title="Open Phone Numbers">
    In the left sidebar, navigate to **Phone Numbers**. You'll see a table of all numbers already in your account. If this is your first number, the table will be empty.
  </Step>

  <Step title="Open the purchase dialog">
    Click the **Buy Number** button in the top-right corner of the card. The **Get Phone Number** dialog opens.
  </Step>

  <Step title="Choose a provider">
    Select **TalkTuro** as your provider. This is the recommended option and the only one currently available. Other providers (Twilio, Telnyx, Plivo, Wavix) are coming soon.
  </Step>

  <Step title="Set your search filters">
    Use the search form to narrow down available numbers:

    * **Number type** — Choose **Local Number (Geographic)** for a standard local number, or **Toll-Free** (800, 888, 877, etc.) for a number your callers can dial at no charge to them.
    * **Country** — Select the country where you need the number.
    * **Area code** *(local numbers only)* — Enter a 3-digit area code to find numbers in a specific region, for example `415` for San Francisco.
    * **State / City** *(local numbers only)* — Optionally narrow the search further by state abbreviation or city name.
    * **Prefix** *(toll-free only)* — Pick a specific toll-free prefix such as `800` or `888`.

    <Tip>
      Leave the area code blank to see any available number in the selected country. You can always run a second search with a more specific area code if you want a local feel.
    </Tip>
  </Step>

  <Step title="Search for available numbers">
    Click **Search Numbers**. Talkturo queries the carrier network and displays up to 20 available numbers. Each result shows the phone number, its city and state, and the monthly cost.
  </Step>

  <Step title="Purchase a number">
    Find the number you want and click **Buy** next to it. The button shows a spinner while the order processes. On success, a green confirmation banner appears and the number is removed from the results list — it now belongs to your account.

    <Note>
      Free plan accounts receive one **trial number** at no charge. Trial numbers expire after **5 days** and are then released back to the carrier pool. Upgrade to a paid plan to keep numbers indefinitely.
    </Note>
  </Step>

  <Step title="Assign the number to an assistant">
    After purchasing, go to **Assistants** and open the assistant you want to connect. Navigate to the **Telephony** section of the assistant settings. Select your new number from the **Phone Numbers** dropdown and save.

    The assistant is now live — inbound calls to that number will be answered by the assistant, and outbound campaigns can use it as the caller ID.
  </Step>
</Steps>

## Unassign a number from an assistant

To disconnect a number from its current assistant without deleting the number:

1. Open the assistant in **Assistants**.
2. Go to the **Telephony** section.
3. Remove the number from the assigned list and save.

The number returns to an unassigned state in your **Phone Numbers** list and can be assigned to a different assistant at any time.

## API reference

You can also manage phone numbers programmatically using the Talkturo REST API.

**Search available numbers**

```http theme={null}
POST /api/phone-numbers/search
Authorization: Bearer <token>
Content-Type: application/json

{
  "filters": {
    "countryCode": "US",
    "areaCode": "415",
    "numberType": "local",
    "limit": 20
  }
}
```

**Purchase a number**

```http theme={null}
POST /api/phone-numbers/purchase
Authorization: Bearer <token>
Content-Type: application/json

{
  "phoneNumber": "+14155550100",
  "teamId": "your-team-id"
}
```

**List your numbers**

```http theme={null}
GET /api/phone-numbers/purchase?teamId=your-team-id
Authorization: Bearer <token>
```

**Assign a number to an assistant**

```http theme={null}
PATCH /api/assistants/{assistantId}/telephony/phone-numbers
Authorization: Bearer <token>
Content-Type: application/json

{
  "accountSlug": "your-account-slug",
  "phoneNumberIds": ["phone-number-uuid"]
}
```

To unassign all numbers from an assistant, send an empty array for `phoneNumberIds`.

<Warning>
  Reassigning a number to a new assistant takes effect immediately. Any active inbound call on that number at the moment of reassignment will complete on the original assistant, but all subsequent calls will route to the newly assigned one.
</Warning>

## Troubleshooting

<Accordion title="The number is stuck in 'purchasing' status">
  Refresh the page after 60 seconds. If the status has not changed to `active`, the carrier provisioning may have encountered an issue. Try purchasing a different number. If the problem persists, contact [support@talkturo.com](mailto:support@talkturo.com).
</Accordion>

<Accordion title="I get a 403 error when trying to purchase">
  Your current plan has reached its number limit. Upgrade your plan to purchase additional numbers, or unassign and delete an existing number first.
</Accordion>

<Accordion title="No numbers appear in search results">
  Try broadening your filters — remove the area code restriction or change the number type. Some geographic areas have limited availability, especially for toll-free numbers.
</Accordion>