The request
Reference for List agency jobs, HeadHoncho API v1. It is a read, sent to the base address https://api.headhoncho.app.
GET /api/v1/agency/jobs
The key needs the Statistics and marketing 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 |
|---|---|---|---|---|
from | date, in the query | No | First day. Default: 45 days ago. | 2026-09-11 |
to | date, in the query | No | Last day, included. Default: today. At most a year from from. | 2026-10-26 |
company_id | id, in the query | No | One company. Default: every company the credential reaches. | cmp_14f5 |
page | number, in the query | No | Default 1. | 1 |
per_page | number, in the query | No | 1 to 500. Default 200. | 200 |
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
from, to, timezone, date_format, columns (the agency's headings), keys, count (rows in all), page, per_page, next (the next page number or null) and rows in the sixteen columns, oldest first. Money is text with two decimals, as the agency's file prints it.
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 |
|---|---|---|
from | date (YYYY-MM-DD) | The first day of the range, inclusive. |
to | date (YYYY-MM-DD) | The last day of the range, inclusive. |
timezone | text | The timezone. |
date_format | text | The date format. |
columns | list of text | The columns. |
keys | list of text | The keys. |
count | whole number | How many match in all, across every page. |
page | whole number | The page number, starting at 1. |
per_page | whole number | The per page. |
next | value or null | The cursor for the next page, or null on the last page. Pass it back as cursor. |
rows | list of objects | The rows. |
rows[].ticket | whole number | The job number the ticket shows. |
rows[].status | text | The job status. |
rows[].customer_phone | text | The customer's phone number. Hidden when the key hides personal details. |
rows[].start_date | date and time (company time zone) | The start date. |
rows[].close_date | date and time (company time zone) | The close date. |
rows[].total | money (decimal as text) | The total, in the company's currency. |
rows[].company_total | money (decimal as text) | The company total. In the company's currency. |
rows[].job_source | text | Where the job came from, such as Google Ads. |
rows[].gclid | text | The Google click id the call or visit carried. |
rows[].callrail_call_id | id (text) | The id of the callrail call. |
rows[].campaign_id | id (text) | The ad platform's id for the campaign. |
rows[].callrail_call_start | date and time (company time zone) | The callrail call start. |
rows[].lead_source | text | How the lead first reached the business. |
rows[].paid_date | date (YYYY-MM-DD) | The paid date. |
rows[].time_zone | text | The company's time zone name, such as America/Chicago. |
rows[].callrail_source_name | text | The callrail source name. |
Same rows, now on a key
This is the feed an agency pulled with its own token, with the same sixteen columns under the same names as the file and the webhook. Only the door changed: a key with access to Statistics and marketing reads it.
Masked until the match is paid
gclid and callrail_call_id print whole once the job's match is paid for: the Google Click IDs report is turned on in Statistics › Reports and the job's one credit is paid (jobs opened before the first Turn on are free). Until then both print masked, their first and last characters around an ellipsis. The webhook and the daily file follow the same rule.
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
- List ad accounts: The ad accounts and call tracking each company has connected, and how each one is doing.
- List campaigns: Spend by campaign for a range, with the calls, leads, lead cost, revenue and profit each one produced, and the revenue that could not be placed.
- Get agency feed: How the workspace sends closed jobs to its agency: the webhook address, the daily file, whether it is on, and the last tries.
- The same records in the app: the Statistics panel.
- How the API fits together: the model, API keys, errors and the MCP server.