The request
Reference for Get balance statement, HeadHoncho API v1. It is a read, sent to the base address https://api.headhoncho.app.
GET /api/v1/balances/{worker_id}/statement
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 path | Yes | The technician, from Who am I's technicians. | wrk_7a12 |
from | date, in the query | No | First day. Default: the first of this month. | 2026-10-01 |
to | date, in the query | No | Last day, included. Default: today. | 2026-10-31 |
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
worker_id, name, from, to, opening_balance (everything before the period), lines (id, kind: ledger or payout, label, job_id, job_number, amount, delta, running_balance, on, memo, voided, void_reason) and closing_balance, which is the balance on the last day.
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 |
|---|---|---|
worker_id | id (text) | The id of the worker. |
name | text | The name, as the app shows it. |
from | date (YYYY-MM-DD) | The first day of the range, inclusive. |
to | date (YYYY-MM-DD) | The last day of the range, inclusive. |
opening_balance | money (number) | The balance at the start of the range. In the company's currency. |
lines | list of objects | The lines, oldest first. |
lines[].id | id (text) | The id of this record. Ids are opaque text: keep them exactly as given. |
lines[].kind | text | What sort of thing this is. |
lines[].label | text | The name the app shows for it. |
lines[].job_id | id (text) | The id of the job. |
lines[].job_number | whole number | The job number people say out loud. |
lines[].amount | money (number) | The amount. In the company's currency. |
lines[].delta | money (number) | How much this line moved the balance. In the company's currency. |
lines[].running_balance | money (number) | The balance after this line. In the company's currency. |
lines[].on | date (YYYY-MM-DD) | The date it happened, as a date in the company's time zone. |
lines[].memo | text | A free-text note on the line. Empty when there is none. |
lines[].voided | true or false | True when the line was voided. A voided line counts in no figure. |
lines[].void_reason | text | Why it was voided. Empty when it was not. |
closing_balance | money (number) | The balance at the end of the range. In the company's currency. |
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.
- List closed balances: Every balance close and payout, newest first, voided ones included, with the jobs each one covered.
- The same records in the app: the Finance panel.
- How the API fits together: the model, API keys, errors and the MCP server.