> ## 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. # Buy a plan > Buy a rate bucket for your agency wallet. A self-serve agency is charged now on its default billing card and answers `PAID` (201), or `PROCESSING` (202) while Stripe finishes. A managed agency gets a request our team approves and charges, answered `PENDING_APPROVAL` (202); that needs auto-recharge switched on. A declined card leaves nothing behind. Charges a card now. Needs the `billing:charge` scope, which `billing:write` does not include, and an `Idempotency-Key` header: a retry with the same key returns the first answer instead of charging again. Not available over MCP. Allowed customer roles: `agency_admin`. The agency is the one the credential belongs to. Required API key scope: `billing:charge`. ## OpenAPI ````yaml /openapi.yaml post /api/billing/purchases 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": "..." }` on failure. 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: Manage voice agents, campaigns, workflows, and outcomes. - name: Analytics description: >- Minimal, non-billing performance summary: volume, conversion, and pickup metrics. - name: Billing description: >- Billing for your own agency: balance, spend, transaction history, invoices and sub-account wallets; auto-recharge, rebilling, Credit Guard and Stripe customers; and, with the billing:charge scope, purchases and charges. - name: Calls description: Review calls, test runs, and execution history. - name: Campaign Workflows description: >- 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/digest` | 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: Contact list, filters, contact call history, and do-not-call actions. - name: GHL description: CRM variables and contact helpers used by agent and campaign setup flows. - name: Phone Numbers description: >- Caller ID pool, number search, assignment, movement, and release endpoints. - name: Power Dialer description: >- Power Dialer queue, lead cadence, callback, parked lead, and campaign schedule endpoints. - name: Projects description: >- Project management endpoints: list, update, disconnect, configure project campaigns, and validate setup. - name: Skills and Tools description: Manage reusable agent behaviors and in-call tool descriptions. - name: Split Testing description: >- Split live campaign traffic across agent variants and shift the weights between them. - name: Voices description: Voice catalogue endpoints for choosing the voice used by an agent. paths: /api/billing/purchases: post: tags: - Billing summary: Buy a plan description: >- Buy a rate bucket for your agency wallet. A self-serve agency is charged now on its default billing card and answers `PAID` (201), or `PROCESSING` (202) while Stripe finishes. A managed agency gets a request our team approves and charges, answered `PENDING_APPROVAL` (202); that needs auto-recharge switched on. A declined card leaves nothing behind. Charges a card now. Needs the `billing:charge` scope, which `billing:write` does not include, and an `Idempotency-Key` header: a retry with the same key returns the first answer instead of charging again. Not available over MCP. Allowed customer roles: `agency_admin`. The agency is the one the credential belongs to. Required API key scope: `billing:charge`. operationId: post-billing-purchases parameters: - name: Idempotency-Key in: header required: true schema: type: string minLength: 8 maxLength: 255 description: >- Required. A unique value per purchase, 8 to 255 visible characters. Reuse it only to retry the same request; the retry returns the first answer with `idempotentReplay: true` and charges nothing. A declined card is an answer too: the retry replays the decline, so once the card is fixed, try again with a new key. example: rebill-bright-dental-2026-09-15 requestBody: description: The plan to buy. content: application/json: schema: $ref: '#/components/schemas/BillingPurchaseRequest' type: object additionalProperties: {} examples: gold: value: planCode: GOLD required: true responses: '201': description: 'Paid: the minutes are in your wallet.' content: application/json: schema: $ref: '#/components/schemas/BillingPurchaseResponse' examples: default: value: success: true data: status: PAID requestNumber: REQ-1757937600000-a1b2c3 planCode: GOLD amountUSD: 340 minutes: 1000 '202': description: 'Accepted: waiting for approval, or for Stripe to finish.' content: application/json: schema: $ref: '#/components/schemas/BillingPurchaseResponse' examples: default: value: success: true data: status: PENDING_APPROVAL requestNumber: REQ-1757937600000-d4e5f6 planCode: GOLD amountUSD: 340 minutes: 1000 '400': description: >- The body is malformed (`BadRequest`, whose `message` names the part at fault, for example `body:` or `path:`), the Idempotency-Key is missing or malformed (`IDEMPOTENCY_KEY_REQUIRED`, `IDEMPOTENCY_KEY_INVALID`), or a self-serve agency sent `thresholdMinutes` (`THRESHOLD_FIXED_FOR_SELF_SERVE`). A change the owning service refuses arrives here too: `REBILLING_UPDATE_FAILED`, `AUTO_RECHARGE_CONFIGURATION_INVALID`, `CREDIT_GUARD_UPDATE_FAILED`. content: application/json: schema: $ref: '#/components/schemas/BillingWriteErrorResponse' examples: default: value: success: false error: IDEMPOTENCY_KEY_REQUIRED message: >- This operation can charge a card, so it needs an Idempotency-Key header. Send a unique value per purchase and reuse it only to retry that same purchase. '401': description: Missing or invalid authentication. content: application/json: schema: $ref: '#/components/schemas/BillingWriteErrorResponse' examples: default: value: success: false error: Unauthorized '402': description: >- The card was declined or needs the cardholder, and nothing was kept. The refusal is stored against the Idempotency-Key: retrying with that key replays this same answer, so once the card is fixed, try again with a new key. content: application/json: schema: $ref: '#/components/schemas/BillingWriteErrorResponse' examples: default: value: success: false error: CARD_DECLINED message: Your card was declined. requestNumber: REQ-1757937600000-a1b2c3 '403': description: >- The credential lacks `billing:charge` (`InsufficientScope`), is not an agency admin's (`Forbidden`), or the plan does not include rebilling (`CAPABILITY_NOT_AVAILABLE`). content: application/json: schema: $ref: '#/components/schemas/BillingWriteErrorResponse' examples: default: value: success: false error: InsufficientScope message: This API key does not have the required scope. requiredScope: billing:charge '404': description: A named sub-account, plan or request is not this agency's. content: application/json: schema: $ref: '#/components/schemas/BillingWriteErrorResponse' examples: default: value: success: false error: PLAN_NOT_FOUND message: Plan DIAMOND is not available to this agency. '409': description: >- The change conflicts with the current state, and nothing was changed. `message` says which: `STRIPE_NOT_CONNECTED`, `SUB_ACCOUNT_WALLET_REQUIRED`, `REBILLING_OFF`, `PENDING_CREDITS_EXIST`, `PROJECT_RATE_NEEDS_CONFIRMATION`, `NO_USABLE_CARD`, `PAYMENT_METHOD_SELECTION_REQUIRED`, `USABLE_DEFAULT_PAYMENT_METHOD_REQUIRED`, `AUTO_RECHARGE_NOT_ENABLED`, `AUTO_RECHARGE_CARD_REQUIRED`, `PRIOR_PROJECT_PAYMENT_CONFLICT`, `PROJECT_WALLET_BACKFILL_REQUIRED`, `PAYMENT_METHOD_UNUSABLE`, `STALE_PROJECT_BILLING_CONFIGURATION`, `AUTO_RECHARGE_RECONCILIATION_REQUIRED`, `AUTO_RECHARGE_PAYMENT_IN_PROGRESS`, `IDEMPOTENT_REPLAY` (the funding layer recognised this charge and did not repeat it; read the wallet back), `SUB_ACCOUNT_CHANGED_DURING_WRITE` (someone else changed the sub-account mid-write), or an Idempotency-Key problem: `IDEMPOTENCY_KEY_REUSED`, `IDEMPOTENCY_IN_PROGRESS`, `IDEMPOTENCY_OUTCOME_UNKNOWN` (an earlier attempt on that key may have charged, so use a new one). content: application/json: schema: $ref: '#/components/schemas/BillingWriteErrorResponse' examples: default: value: success: false error: AUTO_RECHARGE_NOT_ENABLED message: >- Turn on auto-recharge before creating an automatic plan request. '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/BillingWriteErrorResponse' examples: default: value: success: false error: TooManyRequests '500': description: >- Unexpected server error (`InternalError`), a rejected change (`REBILLING_UPDATE_FAILED`, `AUTO_RECHARGE_CONFIGURATION_INVALID`, `CREDIT_GUARD_UPDATE_FAILED`), a rollback that could not complete (`LINK_ROLLBACK_INCOMPLETE`, `REBILLING_ROLLBACK_INCOMPLETE`), a bulk change that applied to only some sub-accounts (`CREDIT_GUARD_PARTIALLY_APPLIED`), or a payment that was taken and then refunded (`CREDIT_FAILED_PAYMENT_REFUND_PENDING`, `CREDIT_FAILED_PAYMENT_REFUNDED`). On a charge operation, treat any 500 as an unknown outcome: do not retry on the same Idempotency-Key, read the wallet back first. content: application/json: schema: $ref: '#/components/schemas/BillingWriteErrorResponse' examples: default: value: success: false error: InternalError message: Could not load the rebilling change. '503': description: >- Stripe could not be reached, or could not confirm the card. Nothing was changed; retry with the same Idempotency-Key. content: application/json: schema: $ref: '#/components/schemas/BillingWriteErrorResponse' examples: default: value: success: false error: PAYMENT_METHOD_PROVIDER_UNAVAILABLE message: >- Stripe could not verify your billing card. Nothing was charged; try again. security: - ApiKeyAuth: [] x-codeSamples: - lang: bash label: cURL source: |- curl --request POST \ --url https://api.teamfollowup.ai/api/billing/purchases \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "planCode": "GOLD" }' components: schemas: BillingPurchaseRequest: type: object additionalProperties: false required: - planCode properties: planCode: type: string enum: - SILVER - GOLD - DIAMOND description: The plan to buy. BillingPurchaseResponse: type: object additionalProperties: false required: - success - data properties: success: type: boolean example: true idempotentReplay: type: boolean description: >- Present, and true, when this answer is a replay of an earlier request with the same Idempotency-Key. data: type: object additionalProperties: false required: - status - requestNumber - planCode - amountUSD - minutes properties: status: type: string enum: - PAID - PROCESSING - PENDING_APPROVAL description: >- `PAID`: the minutes are in your wallet. `PROCESSING`: Stripe is finishing the payment. `PENDING_APPROVAL`: our team will approve and charge it. requestNumber: type: string description: The purchase request. planCode: type: string description: The plan. amountUSD: type: number description: Its price. minutes: type: number description: Minutes it adds. BillingWriteErrorResponse: type: object additionalProperties: false required: - success - error properties: success: type: boolean example: false error: type: string description: Machine-readable code. message: type: string description: For a person. Says whether anything was changed. requiredScope: type: string description: On `InsufficientScope`, the scope the credential was missing. idempotentReplay: type: boolean description: >- Present, and true, when this answer is a replay of an earlier request with the same Idempotency-Key. unknownLocationIds: type: array items: type: string description: Named sub-accounts that are not this agency's. withoutWalletLocationIds: type: array items: type: string description: Named sub-accounts with no wallet yet. failedLocationId: type: string description: The sub-account a multi-step change failed on. rollbackFailedLocationIds: type: array items: type: string description: >- Sub-accounts that could not be put back. Review them in the dashboard. cause: type: string description: For a failed rollback, the code of the failure that triggered it. rebillingLeftOn: type: boolean description: The charge's outcome is unknown, so rebilling was left on. requestNumber: type: string description: For a failed purchase, the request it made. requestedCount: type: integer minimum: 0 description: >- On `CREDIT_GUARD_PARTIALLY_APPLIED`, how many sub-accounts were named. appliedCount: type: integer minimum: 0 description: >- On `CREDIT_GUARD_PARTIALLY_APPLIED`, how many the change reached. Read the rest back. projectCardCharged: type: boolean description: >- On a refused charge, present and false when the client's card was never touched. pendingCredits: type: integer minimum: 0 description: Client payments waiting for credit. recommendedAction: type: string description: What to do next, for example `UPDATE_PAYMENT_METHOD`. declineCode: type: string description: The card issuer's reason. failureCategory: type: string description: What kind of failure it was. errorCode: type: string description: The payment provider's code. requiresAction: type: boolean description: Whether someone has to act first. healthStatus: type: string description: Why a card cannot be used. paymentMethods: type: array items: type: object additionalProperties: {} description: >- On `PAYMENT_METHOD_SELECTION_REQUIRED`, the usable cards to choose from in the dashboard. paymentReviewRequired: type: boolean description: A payment is waiting for our support team. reconciliationRequired: type: boolean description: The state needs reconciling before it can change. securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API key description: 'Send your API key as `Authorization: Bearer YOUR_API_KEY`.' ````