> ## 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. # Link a Stripe customer > Link an existing Stripe customer on your connected account to one or more sub-accounts, whose card then pays for them. The customer's default card is used; change the card in the dashboard. Only the sub-accounts you name are linked, all or nothing: if one fails, the ones already linked go back to what they had. The customer must exist, not be deleted, and have a usable card. Other sub-accounts already using the customer are listed in `alsoLinkedTo`. New customers are created in the dashboard, not here. An `Idempotency-Key` is required even though nothing is charged. The sub-accounts are linked one at a time, so a retry without one would start from a half-linked state and put the wrong customer back. Needs a plan that includes rebilling, and Stripe Connect connected for the agency, even when turning something off. Without either the call changes nothing and answers `CAPABILITY_NOT_AVAILABLE` (403) or `STRIPE_NOT_CONNECTED` (409). Allowed customer roles: `agency_admin`. The agency is the one the credential belongs to. Required API key scope: `billing:write`. ## OpenAPI ````yaml /openapi.yaml post /api/billing/customer-links 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/customer-links: post: tags: - Billing summary: Link a Stripe customer description: >- Link an existing Stripe customer on your connected account to one or more sub-accounts, whose card then pays for them. The customer's default card is used; change the card in the dashboard. Only the sub-accounts you name are linked, all or nothing: if one fails, the ones already linked go back to what they had. The customer must exist, not be deleted, and have a usable card. Other sub-accounts already using the customer are listed in `alsoLinkedTo`. New customers are created in the dashboard, not here. An `Idempotency-Key` is required even though nothing is charged. The sub-accounts are linked one at a time, so a retry without one would start from a half-linked state and put the wrong customer back. Needs a plan that includes rebilling, and Stripe Connect connected for the agency, even when turning something off. Without either the call changes nothing and answers `CAPABILITY_NOT_AVAILABLE` (403) or `STRIPE_NOT_CONNECTED` (409). Allowed customer roles: `agency_admin`. The agency is the one the credential belongs to. Required API key scope: `billing:write`. operationId: post-billing-customer-links 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 customer and the sub-accounts. content: application/json: schema: $ref: '#/components/schemas/BillingCustomerLinkRequest' type: object additionalProperties: {} examples: two: value: stripeCustomerId: cus_Qx8LmVt2ZzYQ4p locationIds: - rrHDPw5RIR5ULeUlfSAR - q8LmVt2ZzYQ4pWnKdRb1 required: true responses: '200': description: Every named sub-account is linked. content: application/json: schema: $ref: '#/components/schemas/BillingCustomerLinkResponse' examples: default: value: success: true data: stripeCustomerId: cus_Qx8LmVt2ZzYQ4p subAccounts: - locationId: rrHDPw5RIR5ULeUlfSAR name: Bright Dental isLive: true rebilling: enabled: true clientRatePerMinute: 0.45 wallet: balanceMinutes: 64.5 balanceUSD: 29.03 debtMinutes: 0 status: LOW_BALANCE visibility: ENABLED autoRecharge: enabled: true thresholdUSD: 25 rechargeAmountUSD: 100 blockedReason: null requiresAction: false recommendedAction: null lastSuccessfulRechargeAt: '2026-09-10T09:30:00.000Z' lastFailureAt: null creditGuard: enabled: false pendingCredits: count: 0 minutes: 0 amountUSD: 0 items: [] creditBatches: - id: BKT-51c0 purchasedAt: '2026-09-10T09:30:00.000Z' minutesPurchased: 200 minutesRemaining: 64.5 valueRemainingUSD: 29.03 ratePerMinute: 0.45 isBonus: false expiresAt: null isExpired: false alsoLinkedTo: [] '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: NotFound message: >- Some of these locationIds are not connected sub-accounts of this agency. Nothing was changed. unknownLocationIds: - loc_other '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: PAYMENT_METHOD_SELECTION_REQUIRED message: >- This Stripe customer has multiple usable cards and no default. Select the card to use for this project. No sub-account was changed. failedLocationId: rrHDPw5RIR5ULeUlfSAR '410': description: >- The Stripe customer named has been deleted on your connected account (`CustomerDeleted`). Nothing was changed; link a customer that still exists. content: application/json: schema: $ref: '#/components/schemas/BillingWriteErrorResponse' examples: default: value: success: false error: CustomerDeleted message: >- Customer cus_Qx8LmVt2ZzYQ4p has been deleted in Stripe. No sub-account was changed. '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 POST \ --url https://api.teamfollowup.ai/api/billing/customer-links \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "stripeCustomerId": "cus_Qx8LmVt2ZzYQ4p", "locationIds": [ "rrHDPw5RIR5ULeUlfSAR", "q8LmVt2ZzYQ4pWnKdRb1" ] }' components: schemas: BillingCustomerLinkRequest: type: object additionalProperties: false required: - stripeCustomerId - locationIds properties: stripeCustomerId: type: string pattern: ^cus_[A-Za-z0-9]{6,}$ description: A customer on your connected Stripe account. locationIds: type: array minItems: 1 maxItems: 50 uniqueItems: true items: type: string minLength: 1 description: >- The sub-accounts to link, up to 50, each named once. Nothing else is linked. BillingCustomerLinkResponse: 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: - stripeCustomerId - subAccounts - alsoLinkedTo properties: stripeCustomerId: type: string description: The customer. subAccounts: type: array items: $ref: '#/components/schemas/BillingSubAccountDetail' description: Every named sub-account after the link. alsoLinkedTo: type: array items: $ref: '#/components/schemas/BillingSubAccountRef' description: Other sub-accounts already using this customer. Not changed. 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. BillingSubAccountDetail: type: object additionalProperties: false required: - locationId - name - isLive - rebilling - wallet - autoRecharge - creditGuard - pendingCredits - creditBatches properties: locationId: type: string description: The sub-account's GoHighLevel Location ID. name: type: - string - 'null' description: Display name. A label only; it can change. isLive: type: - boolean - 'null' description: >- `false` when the sub-account is paused. `null` when its status is unknown. rebilling: type: object additionalProperties: false required: - enabled - clientRatePerMinute properties: enabled: type: boolean description: >- Whether this sub-account pays for its own calls from its own wallet. clientRatePerMinute: type: - number - 'null' description: >- What you charge this sub-account per minute. `null` when rebilling is off. wallet: type: object additionalProperties: false required: - balanceMinutes - balanceUSD - debtMinutes - status - visibility properties: balanceMinutes: type: number description: Minutes left, bonus minutes included, expired batches excluded. balanceUSD: type: number description: Value of the paid minutes left. debtMinutes: type: number description: Minutes owed. status: type: string enum: - ACTIVE - LOW_BALANCE - IN_DEBT - DEPLETED description: >- `ACTIVE` above the low mark, `LOW_BALANCE` at or under it, `IN_DEBT` empty and owing, `DEPLETED` empty. visibility: type: string enum: - ENABLED - DISABLED description: Whether the sub-account can see its wallet. autoRecharge: type: object additionalProperties: false required: - enabled - thresholdUSD - rechargeAmountUSD - blockedReason - requiresAction - recommendedAction - lastSuccessfulRechargeAt - lastFailureAt properties: enabled: type: boolean description: Whether the sub-account tops itself up. thresholdUSD: type: - number - 'null' description: >- Top up when the wallet's dollar balance falls below this. `null` when not set. rechargeAmountUSD: type: - number - 'null' description: How much each top-up charges, in dollars. `null` when not set. blockedReason: type: - string - 'null' description: >- Why an enabled auto-recharge cannot charge, for example `NO_CUSTOMER`. 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`. lastSuccessfulRechargeAt: type: - string - 'null' format: date-time description: The last top-up that charged. lastFailureAt: type: - string - 'null' format: date-time description: The last top-up that failed. creditGuard: type: object additionalProperties: false required: - enabled properties: enabled: type: boolean description: >- Whether this sub-account stops its own calls when its wallet is empty. pendingCredits: type: object additionalProperties: false required: - count - minutes - amountUSD - items properties: count: type: integer minimum: 0 description: Payments waiting for credit. minutes: type: number description: Minutes they will add. amountUSD: type: number description: What was paid. items: type: array items: $ref: '#/components/schemas/BillingPendingCreditItem' creditBatches: type: array description: Oldest first, the order minutes are drawn down. items: $ref: '#/components/schemas/BillingCreditBatch' BillingSubAccountRef: type: object additionalProperties: false required: - locationId - name properties: locationId: type: string description: GoHighLevel Location ID. name: type: - string - 'null' description: Display name. BillingPendingCreditItem: type: object additionalProperties: false required: - id - minutes - amountUSD - ratePerMinute - reason - createdAt - expiresAt properties: id: type: - string - 'null' description: Reference. minutes: type: number description: Minutes it will add. amountUSD: type: number description: What was paid. ratePerMinute: type: - number - 'null' description: The rate paid. reason: type: - string - 'null' description: Why it is waiting. createdAt: type: - string - 'null' format: date-time description: When the payment arrived. expiresAt: type: - string - 'null' format: date-time description: When it stops waiting. BillingCreditBatch: type: object additionalProperties: false required: - id - purchasedAt - minutesPurchased - minutesRemaining - valueRemainingUSD - ratePerMinute - isBonus - expiresAt - isExpired properties: id: type: string description: Batch reference. purchasedAt: type: - string - 'null' format: date-time description: When it was bought. minutesPurchased: type: number description: Minutes bought. minutesRemaining: type: number description: Minutes left. `0` once expired. valueRemainingUSD: type: number description: Value of the minutes left. `0` for bonus batches. ratePerMinute: type: - number - 'null' description: The rate it was bought at. isBonus: type: boolean description: Gifted rather than paid for. expiresAt: type: - string - 'null' format: date-time description: When it expires. `null` for never. isExpired: type: boolean description: Whether it has expired. securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API key description: 'Send your API key as `Authorization: Bearer YOUR_API_KEY`.' ````