> ## 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. # Update agency auto-recharge > Turn your agency wallet's auto-recharge on or off, and choose the plan it buys (the next rate bucket). Switching it on needs a working billing card, added in the dashboard, and permits charges to that card later. `thresholdMinutes` is the balance it buys at. Self-serve agencies recharge at a fixed threshold and cannot set it. A plan that would put rebilled sub-accounts below cost comes back as `marginWarning`; the change is saved either way. Allowed customer roles: `agency_admin`. The agency is the one the credential belongs to. Required API key scope: `billing:write`. ## OpenAPI ````yaml /openapi.yaml put /api/billing/auto-recharge 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/auto-recharge: put: tags: - Billing summary: Update agency auto-recharge description: >- Turn your agency wallet's auto-recharge on or off, and choose the plan it buys (the next rate bucket). Switching it on needs a working billing card, added in the dashboard, and permits charges to that card later. `thresholdMinutes` is the balance it buys at. Self-serve agencies recharge at a fixed threshold and cannot set it. A plan that would put rebilled sub-accounts below cost comes back as `marginWarning`; the change is saved either way. Allowed customer roles: `agency_admin`. The agency is the one the credential belongs to. Required API key scope: `billing:write`. operationId: put-billing-auto-recharge parameters: - name: Idempotency-Key in: header required: false schema: type: string minLength: 8 maxLength: 255 description: >- Optional. A retry with the same key returns the first answer with `idempotentReplay: true`. example: rebill-bright-dental-2026-09-15 requestBody: required: true description: The setting. content: application/json: schema: $ref: '#/components/schemas/BillingAgencyAutoRechargeRequest' examples: 'on': value: enabled: true planCode: GOLD 'off': value: enabled: false responses: '200': description: The auto-recharge setting as it now stands. content: application/json: schema: $ref: '#/components/schemas/BillingAgencyAutoRechargeResponse' examples: default: value: success: true data: autoRecharge: enabled: true status: ENABLED planCode: GOLD thresholdMinutes: 50 blockedReason: null pausedReason: null requiresAction: false recommendedAction: null paymentReviewRequired: false lastSuccessfulRechargeAt: '2026-09-02T08:14:00.000Z' lastFailureAt: null lastFailureCode: null nextRetryAt: null marginWarning: null '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: BadRequest message: 'body: Invalid input: expected boolean, received undefined' '401': description: Missing or invalid authentication. content: application/json: schema: $ref: '#/components/schemas/BillingWriteErrorResponse' examples: default: value: success: false error: Unauthorized '403': description: >- The credential lacks `billing:write` (`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:write '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: USABLE_DEFAULT_PAYMENT_METHOD_REQUIRED message: >- Add or select a working agency billing card before enabling auto-recharge. '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 change that could not be saved. 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 PUT \ --url https://api.teamfollowup.ai/api/billing/auto-recharge \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "enabled": true, "planCode": "GOLD" }' components: schemas: BillingAgencyAutoRechargeRequest: type: object additionalProperties: false required: - enabled properties: enabled: type: boolean description: On or off. planCode: type: string enum: - SILVER - GOLD - DIAMOND description: The plan it buys. Leave out to keep the current one. thresholdMinutes: type: integer minimum: 10 maximum: 200 description: >- Buy when the balance falls to this many minutes. Managed agencies only. BillingAgencyAutoRechargeResponse: 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: - autoRecharge - marginWarning properties: autoRecharge: $ref: '#/components/schemas/BillingAutoRecharge' marginWarning: type: - object - 'null' additionalProperties: {} description: >- Rebilled sub-accounts the new plan would put below cost, or `null`. Advisory: the change was saved. 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. BillingAutoRecharge: type: object additionalProperties: false required: - enabled - status - planCode - thresholdMinutes - blockedReason - pausedReason - requiresAction - recommendedAction - paymentReviewRequired - lastSuccessfulRechargeAt - lastFailureAt - lastFailureCode - nextRetryAt properties: enabled: type: boolean description: >- Whether auto-recharge can fire. `false` while a payment is under review or after a failed charge, whatever the stored setting. status: type: - string - 'null' description: >- Operational status, for example `ENABLED`, `DISABLED` or `SUSPENDED`. planCode: type: - string - 'null' description: The plan it buys. thresholdMinutes: type: - number - 'null' description: It buys when your balance falls to this many minutes. blockedReason: type: - string - 'null' description: Why it cannot charge, when switched on but blocked. pausedReason: type: - string - 'null' description: Why it is paused. requiresAction: type: boolean description: Whether someone has to act before it can charge again. recommendedAction: type: - string - 'null' description: >- What to do, for example `UPDATE_PAYMENT_METHOD` or `CONTACT_SUPPORT`. paymentReviewRequired: type: boolean description: Whether a payment is waiting for our support team. lastSuccessfulRechargeAt: type: - string - 'null' format: date-time description: The last recharge that charged. lastFailureAt: type: - string - 'null' format: date-time description: The last recharge that failed. lastFailureCode: type: - string - 'null' description: Why it failed. nextRetryAt: type: - string - 'null' format: date-time description: When it will try again. securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API key description: 'Send your API key as `Authorization: Bearer YOUR_API_KEY`.' ````