The request
Reference for List closed balances, HeadHoncho API v1. It is a read, sent to the base address https://api.headhoncho.app.
GET /api/v1/closed-balances
The key needs the Money area at read. An answered call costs 1 credit; a refusal costs nothing. See credits.
Send your key as Authorization: Bearer hh_live_.... See API keys.
Parameters
| Name | Kind | Required | Description | Example |
|---|---|---|---|---|
worker_id | id, in the query | No | Only this technician. | wrk_7a12 |
direction | text, in the query | No | to_worker (the company paid) or from_worker (they paid in). One of to_worker, from_worker. | to_worker |
method | text, in the query | No | ach, cash, check, card or other. | zelle |
voided | text, in the query | No | include (default), hide or only. One of include, hide, only. | hide |
from | date, in the query | No | Paid on or after this day. | 2026-10-01 |
to | date, in the query | No | Paid on or before this day. | 2026-10-31 |
page | number, in the query | No | Default 1, twenty a page. | 1 |
Try it with your key
Paste your key and change the values. The box builds the call as a cURL line and a fetch line, ready to copy. It never sends anything itself.
Your key stays in this page and is never sent anywhere. Copy the line below and run it yourself.
What comes back
closed_balances (id, worker_id, name, paid_on, direction, method, reference, amount, jobs, voided, has_statement), total, page and pages.
It never changes a record. It only reads the companies the key reaches.
Every field in the answer
Types are read from the example answer. Money is a plain number in the company's currency. A time carries its offset from UTC (Z is UTC). Ids are opaque text. A field with no line of its own here has its name spelled out; the common fields mean the same on every page.
| Field | Type | Meaning |
|---|---|---|
closed_balances | list of objects | The closed balances. |
closed_balances[].id | id (text) | The id of this record. Ids are opaque text: keep them exactly as given. |
closed_balances[].worker_id | id (text) | The id of the worker. |
closed_balances[].name | text | The name, as the app shows it. |
closed_balances[].paid_on | date (YYYY-MM-DD) | The date it was paid. |
closed_balances[].direction | text | One of to_worker, from_worker. |
closed_balances[].method | text | How it was paid, such as card or cash. |
closed_balances[].reference | text | The reference the payer or the bank gave. |
closed_balances[].amount | money (number) | The amount. In the company's currency. |
closed_balances[].jobs | whole number | The jobs. |
closed_balances[].voided | true or false | One of include, hide, only. |
closed_balances[].has_statement | true or false | True when there is a statement. |
total | whole number | The total, in the company's currency. |
page | whole number | The page number, starting at 1. |
pages | whole number | How many pages there are. |
The statement file
The statement PDF of a balance close stays in the app, on Finance › History: it is a drawn report, which the API does not hand out.
Errors that apply
| Code | Status | What it means |
|---|---|---|
| `missing_key` | 401 | Send your key as Authorization: Bearer hh_live_... |
| `unknown_key` | 401 | That key is not one we issued, or it was revoked. |
| `no_access` | 403 | This credential does not reach that. Ask the person who made it for access. |
| `not_found` | 404 | No such record in the companies this credential reaches. |
| `invalid` | 422 | Some fields were refused. See fields. |
| `no_credits` | 402 | Out of credits. Top up on Settings › Credits, or turn on auto top-up. |
Related
- List balances: Who owes who, per technician: their cuts and paid-back parts against the cash they hold and what was already paid out.
- Get balance statement: Every line on a technician's balance for a period, with the running balance: cuts, parts, cash held and each payout, voided ones marked.
- The same records in the app: the Finance panel.
- How the API fits together: the model, API keys, errors and the MCP server.