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

> ## Agent Instructions
> Use the public API base URL: https://api.teamfollowup.ai/api.
> Authenticate public API requests with Authorization: Bearer YOUR_API_KEY.
> Use product-owned terms: agents, campaigns, projects (GoHighLevel sub-accounts), contacts, calls, outcomes, skills, cadences, phone numbers.
> Scope requests by locationId rather than projectName.
> Read the guide linked from each API reference group before recommending an endpoint.

# Phone numbers and caller ID

> Every campaign dials from numbers you own. Buy them, bring your own, assign them to campaigns, and release the ones you no longer pay for.

A campaign shows the lead a phone number when it calls. That number is the
caller ID, and it is yours: bought through the platform or brought from your
own Twilio account. Local numbers get picked up more than unfamiliar ones, so
which number a campaign dials from is a real decision, not plumbing.

## The pool and the campaign

Your agency has a **pool**: every number it owns, across every project. A
campaign carries `fromNumbers`, the subset of the pool it dials from. One
number can serve several campaigns.

Each number in the pool reads as:

| Field                      | Meaning                                                                                                                |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `phoneNumber` and `pretty` | The number in E.164, and formatted for display.                                                                        |
| `source`                   | Where it came from. `customer-twilio` and `custom` are numbers you own. Anything else was bought through the platform. |
| `monthlyChargeUSD`         | What the platform bills for it each month. `0` for numbers you own.                                                    |
| `campaigns[]`              | The campaigns currently dialling from it.                                                                              |

## Getting a number

Two paths, same result.

* **Buy one.** Search the inventory, then buy. Search takes `place` (a city or
  state), `areaCode`, `countryCode` (`US` or `CA`), `contains` for a digit
  pattern, and `tollFree`. When nothing matches, the response says why:
  `unknown_place`, `no_inventory` or `out_of_coverage`, with the coverage list
  and suggested alternatives. Buying is a paid action and the number lands in
  the pool.
* **Bring your own.** Connect your Twilio account and attach the numbers you
  already own. They are never billed by the platform. See
  [Connect your Twilio](/campaigns/connect-your-twilio).

Agent-scoped endpoints under the agent do the same search, buy and attach,
and assign the result to that agent's campaign in one move. Use them when you
are setting up one agent. Use the pool endpoints when you manage numbers
across the agency.

## Moving numbers around

* **Assign** adds a number to a campaign's `fromNumbers`. It does not remove it
  from any other campaign.
* **Unassign** takes a number off one campaign. The number stays in the pool.
* **Move** takes a number off one campaign and puts it on another in one step,
  so there is no moment where neither campaign has it.
* **Release** hands a platform-bought number back to the carrier and stops the
  monthly charge. For a number you own, the same call removes it from the pool
  and leaves your Twilio account untouched.

<Warning>
  Release is irreversible. The number goes back to general inventory and you
  cannot get it back. It needs the separate `phone_numbers:release` scope, and
  the response says `released` or `releaseFailed` per number. A campaign whose
  last number is released cannot dial.
</Warning>

## Boundaries

* A live campaign needs at least one number in `fromNumbers`.
* Numbers travel in E.164 with a leading `+`. In a URL path the `+` must be
  encoded as `%2B`, so `+14155550100` becomes `%2B14155550100`.
* Inbound campaigns answer on their numbers. Outbound campaigns dial from
  them. The number does not know the difference; the campaign does.
* Buying spends money. Releasing cannot be undone. Both are deliberate acts
  and neither is safe to retry without reading the pool first.

## In the API

Pool, across the agency:

* [List phone numbers](/api-reference/phone-numbers/list-phone-numbers),
  [Search phone numbers](/api-reference/phone-numbers/search-phone-numbers) and
  [Buy phone number](/api-reference/phone-numbers/buy-phone-number)
* [Assign phone number](/api-reference/phone-numbers/assign-phone-number),
  [Unassign phone number](/api-reference/phone-numbers/unassign-phone-number) and
  [Move phone number](/api-reference/phone-numbers/move-phone-number)
* [Release phone number](/api-reference/phone-numbers/release-phone-number)

Scoped to one agent:

* [List agent phone numbers](/api-reference/phone-numbers/list-agent-phone-numbers),
  [Search agent phone numbers](/api-reference/phone-numbers/search-agent-phone-numbers),
  [Buy agent phone number](/api-reference/phone-numbers/buy-agent-phone-number) and
  [Attach agent phone number](/api-reference/phone-numbers/attach-agent-phone-number)
* Every field above is defined in the [Glossary](/glossary#phone-numbers)

## Related

* [Phone numbers on a campaign](/campaigns/phone-numbers) covers the
  dashboard side and local presence.
* [Go live](/campaigns/going-live) lists a number as one of the three things
  a campaign needs.