> ## 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. # Search TFU Live agent numbers > Buying a number for this rep, step 1 of 3: search the numbers it could have, by countryCode, areaCode, place (a town, or a state or province) or tollFree, with the monthly price. Up to ten. With widen=true, a search that finds none where asked widens by itself to the nearest area codes, then the state or province, then the whole country (widened says where they came from). Each number offered can be quoted for five minutes by the same user, for this rep only. Read only: nothing is bought or held. Before buying, check List numbers to connect to a TFU Live agent: a number the agency already has is free. Machine credentials use the returned tfu_live: agent id. Required scope: `agents:read`. Required API key scope: `agents:read`. ## OpenAPI ````yaml /openapi.yaml get /api/tfu-live-agents/{id}/numbers/available openapi: 3.1.0 info: title: TFUAI Server API version: 1.0.0 description: >- API reference for the TFUAI SaaS server. All published endpoints are mounted under `/api`. Responses use a standard envelope: `{ "success": true, ... }` on success and `{ "success": false, "error": "", "message": "..." }` on failure. Branch on the `error` code; `message` is for people and its wording can change. Product API modules are being launched module by module. This spec currently exposes only contracted public modules. Authenticate public API requests with an API key in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. servers: - url: https://api.teamfollowup.ai description: Production API origin. Public API paths are under /api. security: [] tags: - name: Agents description: >- Build the conversation: identity and settings, script, lead context and split testing. - name: Analytics description: >- Understand call volume, pickup, booking and transfer metrics within the selected reporting scope. - name: Billing description: >- Balances, spend, purchases and sub-account rebilling. Reference and guides only; the builder chatbot has no billing playbook. - name: Calls description: >- Review completed calls, recordings, transcripts and campaign run history; distinguish observation from placing a new call. - name: Campaigns description: >- Configure what starts calls, who is eligible, calling windows, caller IDs, activation and the actions that follow each outcome. What runs after a call lands: for each outcome (booked, opted out, asked for a callback…), an ordered chain of actions — tag the contact, move a pipeline stage, send an SMS, book an appointment. Stored as a graph: `nodes` are the actions, `edges` say what follows what, and `dispositionEntries` maps each outcome to the node its chain starts at. **Pick the narrowest endpoint that does the job.** | To | Call | | | --- | --- | --- | | See what fires per outcome | `GET .../workflow?view=summary` | Reads as plain text, no graph walking | | Add steps to an outcome | `POST .../outcomes/{outcome}/nodes` | Server derives node ids, edge ids, handles, layout | | Change a message, tag or setting | `PATCH .../workflow` | Merges; carries no graph, so it cannot damage one | | Remove one step | `DELETE .../nodes/{nodeId}` | Also re-links the chain around it | | Author or replace the whole graph | `PUT .../workflow` | Replaces everything you send | `PUT` is the only one that can re-wire, position nodes, build an `if`, save an unconfigured draft, or copy a whole workflow — and the only one that can overwrite a change someone else made after you read it. Use it when you are genuinely authoring the graph, and send `expectedVersion` when you do. For everything else the narrower endpoints are both easier and safer. - name: Contacts description: >- Find contacts and their calls, manage do-not-call status and identify internal contacts excluded from reporting. - name: In-call Capabilities description: >- Configure actions and instructions the agent uses during a live call: booking, transfers, lookups and custom skills. - name: Master agent description: >- Run a shared agent and campaign across linked projects; manage inheritance, local bindings, synchronization and rollout readiness. - name: Native Calendar description: >- The diary of a sub-account with no CRM: its bookable calendars, the free slots they offer, and the appointments on them. Availability is computed per request against live bookings and is never cached, because a cached slot is one somebody else has already taken. - name: Native Contacts description: >- The people a sub-account with no CRM calls, and the fields it keeps on them. This is the system of record for those contacts: there is nowhere else they exist. A sub-account with a CRM keeps its contacts there and every operation here answers 400 for it. - name: Phone Numbers description: >- Find and manage caller IDs, assign numbers to campaigns and understand connected Twilio numbers. - name: Projects description: >- Understand project ownership, inspect configuration and validate the local resources used by a campaign. - name: TFU Live description: >- Configure instructions, conversation style, workflows, Chat and call handling, then test and go live. - name: Voices description: >- Browse the voice catalogue and select a voice; configure speech and listening behavior in Agents. paths: /api/tfu-live-agents/{id}/numbers/available: get: tags: - TFU Live summary: Search TFU Live agent numbers description: >- Buying a number for this rep, step 1 of 3: search the numbers it could have, by countryCode, areaCode, place (a town, or a state or province) or tollFree, with the monthly price. Up to ten. With widen=true, a search that finds none where asked widens by itself to the nearest area codes, then the state or province, then the whole country (widened says where they came from). Each number offered can be quoted for five minutes by the same user, for this rep only. Read only: nothing is bought or held. Before buying, check List numbers to connect to a TFU Live agent: a number the agency already has is free. Machine credentials use the returned tfu_live: agent id. Required scope: `agents:read`. Required API key scope: `agents:read`. operationId: get-tfu-live-agents-by-id-numbers-available parameters: - name: locationId in: query required: true schema: type: string description: >- Sub-account belonging to the authenticated agency and any narrower credential location binding. - name: id in: path required: true schema: type: string description: TFU Live agent id. Never use an ordinary provider agent id. - name: campaignId in: query schema: type: string pattern: ^[a-zA-Z0-9_-]{1,100}$ description: >- When more than one campaign uses this rep, the one whose calling line to use. - name: countryCode in: query schema: type: string pattern: ^[A-Za-z]{2}$ description: >- Two letters, such as US, CA or GB. Get TFU Live agent numbers lists where numbers are sold. - name: areaCode in: query schema: type: string pattern: ^\d{3}$ - name: place in: query schema: type: string maxLength: 100 description: A town, or a state or province. - name: tollFree in: query schema: type: boolean - name: widen in: query schema: type: boolean description: >- True (or 1): none where asked widens by itself. Omit to search only where asked. responses: '200': description: Successful response. content: application/json: schema: $ref: '#/components/schemas/TfuLiveNumberSearchResponse' example: success: true candidates: - phoneNumber: '+14155550123' locality: San Francisco region: CA price: monthlyUSD: 2 firstMonthUSD: 2 currency: USD search: countryCode: US areaCode: '415' '400': description: >- Refused: { success: false, error, code, message }. Nothing was bought or charged. content: application/json: schema: $ref: '#/components/schemas/TfuLiveNumberError' example: success: false error: invalid_request code: invalid_request message: Please check the details and try again. '401': description: >- Refused: { success: false, error, code, message }. Nothing was bought or charged. content: application/json: schema: $ref: '#/components/schemas/TfuLiveNumberError' example: success: false error: Unauthorized message: Please sign in to continue. '403': description: >- Refused: { success: false, error, code, message }. Nothing was bought or charged. content: application/json: schema: $ref: '#/components/schemas/TfuLiveNumberError' example: success: false error: InsufficientScope message: >- This access key does not allow this action. Please ask your account admin to change its permissions. requiredScope: agents:write '404': description: >- Refused: { success: false, error, code, message }. Nothing was bought or charged. content: application/json: schema: $ref: '#/components/schemas/TfuLiveNumberError' example: success: false error: not_found code: not_found message: We couldn't find that. It may have been moved or deleted. '409': description: >- Refused: { success: false, error, code, message }. Nothing was bought or charged. content: application/json: schema: $ref: '#/components/schemas/TfuLiveNumberError' example: success: false error: quote_expired code: quote_expired message: >- No purchase was made. Please ask for a fresh price before confirming. '422': description: >- Refused: { success: false, error, code, message }. Nothing was bought or charged. content: application/json: schema: $ref: '#/components/schemas/TfuLiveNumberError' example: success: false error: invalid_request code: invalid_request message: Please check the details and try again. '429': description: >- Refused: { success: false, error, code, message }. Nothing was bought or charged. content: application/json: schema: $ref: '#/components/schemas/TfuLiveNumberError' example: success: false error: TooManyRequests message: That's a lot at once. Please wait a moment and try again. '503': description: >- Refused: { success: false, error, code, message }. Nothing was bought or charged. content: application/json: schema: $ref: '#/components/schemas/TfuLiveNumberError' example: success: false error: line_unverified code: line_unverified message: >- We couldn't finish this right now. Please try again in a moment. security: - ApiKeyAuth: [] x-codeSamples: - lang: bash label: cURL source: |- curl --request GET \ --url https://api.teamfollowup.ai/api/tfu-live-agents/{id}/numbers/available \ --header 'Authorization: Bearer YOUR_API_KEY' components: schemas: TfuLiveNumberSearchResponse: type: object required: - success - candidates - price additionalProperties: {} properties: success: const: true candidates: type: array maxItems: 10 items: $ref: '#/components/schemas/PhoneNumbersCandidate' price: type: object required: - monthlyUSD - firstMonthUSD - currency additionalProperties: false properties: monthlyUSD: type: - number - 'null' firstMonthUSD: type: - number - 'null' currency: const: USD search: oneOf: - type: object additionalProperties: false required: - countryCode description: What was finally searched. properties: countryCode: type: - string - 'null' areaCode: type: string place: type: string region: type: string tollFree: type: boolean - type: 'null' widened: type: object additionalProperties: false required: - step - asked - found description: >- Present when none were found where asked and the search widened by itself (widen). properties: step: type: string enum: - nearby - state - country description: >- nearby: the nearest area codes; state: the state or province; country: the whole country. asked: type: object additionalProperties: {} found: type: object additionalProperties: {} TfuLiveNumberError: type: object required: - success - error additionalProperties: {} properties: success: const: false error: type: string description: >- What happened and what to do, in words. Nothing was bought or charged unless it says so. code: type: string description: >- The refusal, kept exactly as the purchase engine named it. Act on it: card_required (add a usable billing card; the quote stays good), search_required (search again, then quote), quote_expired (quote again), number_unavailable (choose another), purchase_in_progress (a number is already being set up for this rep: read Get TFU Live agent numbers), crm_required (connect GoHighLevel first), line_unavailable or number_setup_unavailable (our team must look at the line), line_unverified (retry in a moment), inbound_unconfigured, not_allowed, not_found, invalid_request; for a number the agency already has, also number_not_in_account, number_on_another_trunk and number_in_use. Codes the calling line names start TFU_LIVE_LINE_. message: type: string description: >- The same words as error. A status-wide gate (authentication, scope, rate limit) puts its own name in error and its words here. PhoneNumbersCandidate: type: object additionalProperties: false required: - phoneNumber - locality - region properties: phoneNumber: type: string pattern: ^\+\d{10,15}$ description: Available E.164 phone number. example: '+14155559876' locality: type: - string - 'null' description: City or locality label when available. example: San Francisco region: type: - string - 'null' description: State or province code when available. example: CA smsCapable: type: - boolean - 'null' description: >- Twilio's own flag for whether the number can send texts. `null` when Twilio did not say. Texting from a US local number also needs A2P 10DLC approval, and from a US or Canadian toll-free number, toll-free verification. example: true securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API key description: 'Send your API key as `Authorization: Bearer YOUR_API_KEY`.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.