> ## Documentation Index > Fetch the complete documentation index at: https://docs.intentleads.si/llms.txt > Use this file to discover all available pages before exploring further. # Set the automatic top-up > Adds `amount` US dollars ($250 or more) by card **when the available balance drops below `threshold`**, and **on the billing day** once a month. Each automatic top-up has its own invoice. `{"enabled": false}` turns it off. - **No card on file:** `409 card_required` with a `card_setup_url`. Add the card there; the automatic top-up switches on with these settings once it's saved. - **A failed payment** pauses automatic top-ups (`paused: payment_failed`) until a new card is added or the invoice is paid. The low-balance top-up runs at most 5 times a billing month (`paused: monthly_cap`); saving the settings again resumes it. - **An older monthly card payment** ($250, $500, $1,000 or $2,000) is the billing-day part: `amount` must be one of those, and `"low_balance": false` keeps only the monthly payment. **Admin key required.** Standard keys get `403 admin_key_required`. ## OpenAPI ````yaml /api-reference/openapi.json put /api/v1/billing/auto-topup openapi: 3.1.0 info: title: Intent Leads API version: '1.0' description: >- The Intent Leads API finds B2B people actively researching the topics you sell into, and exports them with contact details into your own tools. **Authentication.** Send an API key as a bearer token: `Authorization: Bearer il_live_…`. Standard keys work with everything except billing, team and key management, which need an admin key. **Organizations and workspaces.** An organization holds the balance, invoices and people; lanes, leads, exports, lists, websites and webhooks live in its workspaces. A workspace key works in its workspace. An organization key manages workspaces, billing and people, and works in any of its workspaces with the header `Intent-Leads-Workspace: `. **What costs money.** Only `POST /api/v1/exports` with `"dry_run": false` spends your [balance](/guides/billing) (and website visitors as they're identified). Quotes, counts, checks, estimates, samples and re-downloads are free. **Errors.** Every error is JSON: `{"error": "code", "message": "Plain-English explanation"}`. Codes are stable; messages may change. **Conventions.** JSON by default. Dates are `YYYY-MM-DD` and timestamps ISO 8601, all in UTC. Lane codes (`L1`) are case-insensitive. servers: - url: https://intentleads.si security: - bearerAuth: [] tags: - name: Exports description: Quote (free) and buy new people from your lanes, then download them. - name: Leads description: Pull and re-download the leads you've exported, and list deliveries. - name: Lanes description: >- Create, inspect and tune lanes: keywords plus the companies and roles you want. - name: Topics description: >- Topics we already track: live at once, with history. Use them before adding new keywords. - name: Keywords description: >- Add and remove a lane's keywords: existing topics, or new ones approved as their own topic. - name: Checks description: >- Free lane checks that size every filter step over 14 days, plus quick topic signals. - name: Company list description: >- The target-company list your lanes can narrow to or use instead of industries. - name: Exclusions description: Companies and people left out of every lane, before anything is bought. - name: Suppressions description: >- People you exported who later asked to be removed, by API or pushed to your webhook. - name: Webhooks description: >- Endpoints that receive events as they happen (removals, website visitors), signed, each with its own events, tests and delivery log. - name: Websites description: Identify the people who visit your websites. - name: Billing description: >- Your prepaid balance, prices and cost estimates (any key); top-ups and the monthly top-up (admin keys). - name: Team description: Members and invite links. Admin keys only. - name: Workspaces description: >- One workspace per client, all paid from your balance, with an optional monthly budget each; hand one over to the client. - name: API keys description: Create, rename, rotate and revoke API keys. Admin keys only. - name: Account description: Check which organization a key belongs to, and rename it. - name: Reference description: Valid values for lane filters. - name: Activity description: A feed of changes and events in your organization. paths: /api/v1/billing/auto-topup: put: tags: - Billing summary: Set the automatic top-up description: >- Adds `amount` US dollars ($250 or more) by card **when the available balance drops below `threshold`**, and **on the billing day** once a month. Each automatic top-up has its own invoice. `{"enabled": false}` turns it off. - **No card on file:** `409 card_required` with a `card_setup_url`. Add the card there; the automatic top-up switches on with these settings once it's saved. - **A failed payment** pauses automatic top-ups (`paused: payment_failed`) until a new card is added or the invoice is paid. The low-balance top-up runs at most 5 times a billing month (`paused: monthly_cap`); saving the settings again resumes it. - **An older monthly card payment** ($250, $500, $1,000 or $2,000) is the billing-day part: `amount` must be one of those, and `"low_balance": false` keeps only the monthly payment. **Admin key required.** Standard keys get `403 admin_key_required`. operationId: setAutoTopup requestBody: required: true content: application/json: schema: type: object properties: enabled: type: boolean amount: type: number description: US dollars, $250 or more. threshold: type: number description: US dollars; the low-balance top-up runs below this. low_balance: type: boolean description: >- Only with an older monthly card payment: false keeps just the monthly payment. email: type: string format: email description: Prefills the card page. required: - enabled examples: 'on': summary: Turn on value: enabled: true amount: 500 threshold: 50 'off': summary: Turn off value: enabled: false responses: '200': description: The automatic top-up after the change. content: application/json: schema: type: object properties: enabled: type: boolean description: >- On when anything tops up automatically (the low-balance top-up, the billing-day top-up, or an older monthly card payment). amount_usd: type: - number - 'null' description: Added each time, $250 or more. threshold_usd: type: - number - 'null' description: >- The low-balance top-up runs when the available balance drops below this. Null when that part is off. triggers: type: object properties: low_balance: type: boolean billing_day: type: boolean required: - low_balance - billing_day billing_day_by: type: - string - 'null' enum: - auto - subscription description: >- Who does the billing-day top-up: `auto` (us) or `subscription` (an older monthly card payment). amount_choices_usd: type: - array - 'null' items: type: number description: With a monthly card payment, the amount is one of these. paused: type: - string - 'null' enum: - payment_failed - monthly_cap - no_card description: >- Why automatic top-ups are paused: a failed payment, 5 low-balance top-ups this billing month, or no card. paused_at: type: - string - 'null' format: date-time card: anyOf: - type: object properties: brand: type: string last4: type: string required: - brand - last4 - type: 'null' last: anyOf: - type: object properties: trigger: type: string enum: - low_balance - billing_day amount_usd: type: number status: type: string enum: - pending - paid - failed at: type: string format: date-time paid_at: type: - string - 'null' format: date-time invoice_url: type: - string - 'null' format: uri error: type: - string - 'null' required: - trigger - amount_usd - status - at - paid_at - invoice_url - error - type: 'null' required: - enabled - amount_usd - threshold_usd - triggers - billing_day_by - amount_choices_usd - paused - paused_at - card - last example: enabled: true amount_usd: 500 threshold_usd: 50 triggers: low_balance: true billing_day: true billing_day_by: auto amount_choices_usd: null paused: null paused_at: null card: brand: visa last4: '4242' last: trigger: low_balance amount_usd: 500 status: paid at: '2026-11-20T09:14:02.000Z' paid_at: '2026-11-20T09:14:04.000Z' invoice_url: https://invoice.example.com/i/acct_1/in_1 error: null '400': description: Bad settings. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_body: value: error: invalid_body message: >- Send {"enabled": true, "amount": 500, "threshold": 50} (amount from 250 to 50000 US dollars) or {"enabled": false}. invalid_amount: value: error: invalid_amount message: >- The automatic top-up is from $250 to $50,000, in whole dollars. invalid_threshold: value: error: invalid_threshold message: >- The low-balance amount must be $0 or more, and less than the top-up. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AdminKeyRequired' '409': description: No card yet, or this is a workspace. content: application/json: schema: $ref: '#/components/schemas/Error' examples: card_required: value: error: card_required message: >- Add a card to turn on the automatic top-up. It switches on with these settings once the card is saved: https://checkout.example.com/setup/7f3c2a9e card_setup_url: https://checkout.example.com/setup/7f3c2a9e billed_by_parent: value: error: billed_by_parent message: >- This workspace spends its organization's balance. Top-ups are managed there. '500': $ref: '#/components/responses/InternalError' '502': description: The payment provider refused the request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: billing_failed: value: error: billing_failed message: The payment didn't go through. Try again, or contact us. components: schemas: Error: type: object properties: error: type: string example: lane_not_found description: Stable machine-readable code, e.g. `lane_not_found`. message: type: string example: No lane L9. description: Plain-English explanation you can show to a person. required: - error - message description: Every error has this shape. responses: Unauthorized: description: Missing, malformed, unknown or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' examples: unauthorized: value: error: unauthorized message: 'Send a valid API key as: Authorization: Bearer il_live_…' AdminKeyRequired: description: This endpoint needs an admin key. content: application/json: schema: $ref: '#/components/schemas/Error' examples: admin_key_required: value: error: admin_key_required message: >- This needs an admin API key. Owners create one under Settings → API keys. InternalError: description: >- Unexpected server error. Safe to retry reads; retry an export only with the same `idempotency_key`. content: application/json: schema: $ref: '#/components/schemas/Error' examples: internal_error: value: error: internal_error message: Something went wrong. Try again. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: il_live_… description: >- An Intent Leads API key, e.g. `il_live_` followed by 32 letters and digits. Create one on the API and CLI page of the dashboard. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.