The request
Reference for List field reports, HeadHoncho API v1. It is a read, sent to the base address https://api.headhoncho.app.
GET /api/v1/field-reports
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 |
|---|---|---|---|---|
job_id | id, in the query | No | Only this job, by id or number. | job_1138 |
company_id | id, in the query | No | Only this company. Default: every company in reach. | cmp_14f5 |
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
field_reports: id, job (id, number, status), worker_id, worker_name, collected, method, parts, total and reported_at. Booked and set-aside ones are not listed.
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 |
|---|---|---|
field_reports | list of objects | The field reports. |
field_reports[].id | id (text) | The id of this record. Ids are opaque text: keep them exactly as given. |
field_reports[].job | object | The job. |
field_reports[].job.id | id (text) | The id of this record. Ids are opaque text: keep them exactly as given. |
field_reports[].job.number | whole number | The number people say out loud, such as the job number. |
field_reports[].job.status | text | The job status. |
field_reports[].worker_id | id (text) | The id of the worker. |
field_reports[].worker_name | text | The worker name. |
field_reports[].collected | money (number) | The money received on the job so far. In the company's currency. |
field_reports[].method | text | How it was paid, such as card or cash. |
field_reports[].parts | money (number) | The parts. In the company's currency. |
field_reports[].total | money (number) | The total, in the company's currency. |
field_reports[].reported_at | time (ISO 8601, with offset) | When it was reported. Carries its offset from UTC; Z is UTC. |
Where they come from
A technician texts the numbers when the job is done. The app reads them into a field report; Book it or Not this decides it, here or on Finance.
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. |
| `out_of_scope` | 404 | No such company 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
- Get job money: What a job made and where the money went: money in, parts and fees, the profit, each person's share, and every payment and expense line.
- The same records in the app: the Finance panel.
- How the API fits together: the model, API keys, errors and the MCP server.