The request
Reference for List balances, HeadHoncho API v1. It is a read, sent to the base address https://api.headhoncho.app.
GET /api/v1/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
This call takes no parameters.
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
balances, one per technician with any money: worker_id, name, role, payable (cuts, parts and monthly pay owed to them), receivable (cash they collected and hold), paid_out and paid_in (balance closes and payouts each way), net (what the company owes them; below zero, what they owe the company) and says, in words. totals: the same figures for everyone.
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 |
|---|---|---|
balances | list of objects | The balances. |
balances[].worker_id | id (text) | The id of the worker. |
balances[].name | text | The name, as the app shows it. |
balances[].role | text | The role: what this person does on a job. |
balances[].payable | money (number) | What the business owes this person (cuts, parts and pay owed to them). In the company's currency. |
balances[].receivable | money (number) | What this person owes the business (cash they collected and still hold). In the company's currency. |
balances[].paid_out | money (number) | What was paid out by the business. In the company's currency. |
balances[].paid_in | money (number) | What was paid in to the business. In the company's currency. |
balances[].monthly_pay | money (number) | The monthly pay. In the company's currency. |
balances[].cash_held | money (number) | The cash held. In the company's currency. |
balances[].net | money (number) | The net amount, after what is owed either way. In the company's currency. |
balances[].says | text | The text to show a person. |
totals | object | The totals. |
totals.payable | money (number) | What the business owes this person (cuts, parts and pay owed to them). In the company's currency. |
totals.receivable | money (number) | What this person owes the business (cash they collected and still hold). In the company's currency. |
totals.paid_out | money (number) | What was paid out by the business. In the company's currency. |
totals.paid_in | money (number) | What was paid in to the business. In the company's currency. |
totals.net | money (number) | The net amount, after what is owed either way. In the company's currency. |
The same numbers as the app
These are the balances the Team and Finance panels show, from the same function. Trashed jobs count in none of them.
Every company
A balance is a person's, across every company they work for, so a credential must reach every company to read it.
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. |
| `no_credits` | 402 | Out of credits. Top up on Settings › Credits, or turn on auto top-up. |
Related
- 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.
- 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.