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

# Give a TFU Live rep a phone number

> Buy a number for a TFU Live rep, or connect one the agency already has, for its calls out and in.

A TFU Live rep calls from, and answers, a number on its own calling line. Give it one
the same way the dashboard's Get a number dialog does, with the rep's `tfu_live:` id and
`locationId`. Reading needs `agents:read`; quoting, buying and connecting need `agents:write`.

1. [Get TFU Live agent numbers](/api-reference/tfu-live/get-tfu-live-agent-numbers)
   shows the rep's number now. `line.status` is `ready` or `not_set_up`, and
   `managedBy` says who set the line up (`self` or `staff`). `pending` is a number being set
   up for the rep right now, in state `buying`, `connecting`, `charging` or
   `reconciliation_required` (held for our team), of kind `purchase` or `attach`.
2. A number the agency already has is free. [List numbers to connect to a TFU Live agent](/api-reference/tfu-live/list-numbers-to-connect-to-a-tfu-live-agent),
   then [Connect a number to a TFU Live agent](/api-reference/tfu-live/connect-a-number-to-a-tfu-live-agent).
3. Otherwise buy one in three steps.
   [Search TFU Live agent numbers](/api-reference/tfu-live/search-tfu-live-agent-numbers)
   by area code, place, country or toll free. With `widen=true`, a search that finds none
   widens by itself, and `widened.step` says how far: `nearby`, `state` or `country`.
   [Quote a TFU Live number](/api-reference/tfu-live/quote-a-tfu-live-number) prices one
   and returns its `confirmation`, good for ten minutes. Tell the user the number and what
   it costs now and each month. Only after they agree, send the number and the
   `confirmation` to [Buy a TFU Live number](/api-reference/tfu-live/buy-a-tfu-live-number).
   That call is the payer's yes.

A purchase is paid and needs a usable billing card on file (`card_required` otherwise; the
quote stays good while one is added). The number is bought into the agency's own phone
account on the sub-account's TFU Live calling trunk, then connected for the rep's calls out
and in. The agency wallet is charged once, when it is done. Repeating the purchase with the
same `confirmation` never buys or charges twice. One number is set up for a rep at a time
(`purchase_in_progress`). Refusals keep their `code`, such as `search_required` or
`quote_expired`, so you can act on them.

[Buy phone number](/api-reference/phone-numbers/buy-phone-number) cannot be used for a TFU
Live rep. Use these operations instead.


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