Wallet — Finn docs

Beta. Every endpoint on this page is live and documented as shipped. Shapes can still change before general availability.

Overview

Each organization has one wallet, held in credits. Calls, phone number rentals and other usage are debited from it. The Wallet API is read-only: you can read the balance and page through the ledger of transactions. Top-ups are made in the dashboard; there is no API to add funds.

Base URL: https://api.hirefinn.ai/api/v1. Auth: Authorization: Bearer finn_live_.... See authentication.

The balance gates other endpoints:

POST /calls returns 402 insufficient_credits when the wallet cannot cover a call. See api-calls.
POST /deployments returns 402 insufficient_credits unless the wallet covers half the audience in one-minute calls. See api-deployments.
POST /phone_numbers debits the rental price and returns 402 insufficient_credits when the balance is too low. See api-phone-numbers.

Endpoints

Method	Path	Rate limit (per API key)
`GET`	`/wallet`	300 per minute, shared with `GET /calls/{call_uuid}`, `GET /finns` and `GET /finns/{finn_id}`
`GET`	`/wallet/transactions`	300 per minute, shared with `GET /deployments` and `GET /deployments/{id}`

Get the balance

GET /wallet

curl https://api.hirefinn.ai/api/v1/wallet \
  -H "Authorization: Bearer $FINN_API_KEY"

{
  "success": true,
  "data": {
    "credits": 4175,
    "currency": "INR",
    "price_per_credit": 7,
    "monetary_value": 29225,
    "low_balance": false
  }
}

Field	Type	Notes
`credits`	number	Current balance in credits. Can be fractional.
`currency`	string or null	Wallet currency.
`price_per_credit`	number or null	Your organization's effective rate per credit, in `currency`.
`monetary_value`	number	`credits × price_per_credit`, rounded to 2 decimals.
`low_balance`	boolean	`true` when the balance is below about 20 calls' worth of credits for your plan.

If your organization has no wallet yet, the response is { "credits": 0, "currency": null, "price_per_credit": null, "monetary_value": 0, "low_balance": true }.

List transactions

GET /wallet/transactions

The ledger, newest first. Every debit and credit to the wallet is one entry.

Query parameter	Type	Default	Notes
`types`	string	none	Comma-separated transaction types to include, for example `debit_call_answered,debit_call_unanswered`. Up to 20 values of lowercase letters and `_`.
`limit`	integer	50	1 to 200. Out-of-range values are clamped.
`offset`	integer	0	Number of entries to skip.

curl "https://api.hirefinn.ai/api/v1/wallet/transactions?types=debit_call_answered,debit_phone_number&limit=2" \
  -H "Authorization: Bearer $FINN_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "48213",
      "type": "debit_call_answered",
      "credits_delta": -2,
      "new_balance": 4175,
      "call_uuid": "b7e3c9a2-4d1f-4e8b-9a6c-2f5d8e1b3c70",
      "created_at": "2026-10-02T10:17:44.000Z"
    },
    {
      "id": "48190",
      "type": "debit_phone_number",
      "credits_delta": -25,
      "new_balance": 4177,
      "call_uuid": "phone:+14155550123",
      "created_at": "2026-10-02T09:58:03.000Z"
    }
  ],
  "limit": 2,
  "offset": 0
}

Field	Type	Notes
`id`	string	Ledger entry ID. Numeric, returned as a string.
`type`	string	What the entry is for. See below.
`credits_delta`	number	Negative for debits, positive for credits.
`new_balance`	number	Balance after this entry.
`call_uuid`	string or null	Reference for the entry. For call charges, the call's UUID, which you can look up with api-calls. For phone number rentals and refunds, `phone:<number>` or `phone:<number>:refund`.
`created_at`	string	ISO 8601.

There is no total count. Page with offset until a page returns fewer than limit items.

Transaction types

Type	Meaning
`debit_call_answered`	Charge for an answered call.
`debit_call_unanswered`	Charge for an unanswered call attempt.
`credit_refund_call_unanswered`	Reverses a `debit_call_unanswered` charge when the call turns out to have been answered, so each call nets one call charge.
`debit_call_recording`	Charge for call recording.
`debit_phone_number`	Phone number rental.
`credit_refund_phone_number`	Refund of a rental whose provisioning failed.
`debit_sms`	SMS charge.
`debit_whatsapp`	WhatsApp charge.
`credit_topup`	Top-up.
`credit_signup_grant`	Credits granted at signup.
`credit_plan_grant`	Credits granted by your plan.
`credit_renewal`	Credits granted on plan renewal.
`credit_adjustment`	Manual adjustment by Finn.
`credit_migration`	Balance carried over during a billing migration.
`currency_realign`	Record of a change to the wallet's currency. `credits_delta` is `0`; the credit balance doesn't change.

New types can be added. Handle unknown values.

The ledger is the record of what was charged. The billing block on a call in api-calls is an estimate and can differ from the ledger entry.

Errors

Status	`error`	Endpoint	When
400	`invalid_request`	`GET /wallet/transactions`	`types` is not a comma-separated list of up to 20 values of `a-z` and `_`.
401	`api_key_required`	both	No `Bearer finn_live_...` key.
401	`invalid_api_key`	both	Key unknown or revoked.
429	`rate_limited`	both	Over the bucket's per-minute limit.
500	`internal_error`	both	Unexpected server error.

Error bodies have the shape { "error": "...", "message": "..." }; internal_error has no message. See api-errors.