The request
Reference for Get lead, HeadHoncho API v1. It is a read, sent to the base address https://api.headhoncho.app.
GET /api/v1/leads/{lead_id}
The key needs the Leads 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 |
|---|---|---|---|---|
lead_id | id, in the path | Yes | The lead id, or its number. | lead_5d21 |
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
The lead. stage is new, taken, quoted, won, lost or passed. missing names the facts still needed before a job can be booked. job is set once the lead is booked. history lists what happened, oldest first: at, line and by.
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 |
|---|---|---|
id | id (text) | The id of this record. Ids are opaque text: keep them exactly as given. |
number | whole number | The number people say out loud, such as the job number. |
ticket | text | The job number the ticket shows. |
company | object | The company. |
company.id | id (text) | The id of this record. Ids are opaque text: keep them exactly as given. |
company.name | text | The name, as the app shows it. |
stage | text | How far along it is, as a code. |
stage_since | time (ISO 8601, with offset) | The moment: stage since. Carries its offset from UTC; Z is UTC. |
client_name | text | The customer's name. Hidden when the key hides personal details. |
client_phone | text | The customer's phone number. Hidden when the key hides personal details. |
address | object | The address. |
address.line1 | text | The street address. Hidden when the key hides personal details. |
address.city | text | The city. |
address.state | text | The state or region. |
service | object | The service. |
service.id | id (text) | The id of this record. Ids are opaque text: keep them exactly as given. |
service.name | text | The name, as the app shows it. |
wanted_start | time (ISO 8601, with offset) | The moment: wanted start. Carries its offset from UTC; Z is UTC. |
wanted_end | time (ISO 8601, with offset) | The moment: wanted end. Carries its offset from UTC; Z is UTC. |
urgent | true or false | The urgent. |
notes | text | Free-text notes. |
estimate | object | The estimate. |
estimate.amount | money (number) | The amount. In the company's currency. |
estimate.source | text | The source. |
quoted | value or null | The price quoted for the job. |
lost_reason | text | The lost reason. |
pass_reason | text | The pass reason. |
job | value or null | The job. |
assigned_to | value or null | The assigned to. |
source | object | The source. |
source.kind | text | What sort of thing this is. |
source.label | text | The name the app shows for it. |
source.channel | value or null | The channel. |
arrivals | whole number | The arrivals. |
arrived_at | time (ISO 8601, with offset) | When it was arrived. Carries its offset from UTC; Z is UTC. |
missing | list of text | The missing. |
ready | true or false | The ready. |
archived_at | time or null | When it was archived. |
created_at | time (ISO 8601, with offset) | When it was created. Carries its offset from UTC; Z is UTC. |
history | list of objects | The history. |
history[].at | time (ISO 8601, with offset) | The moment it happened. Carries its offset from UTC; Z is UTC. |
history[].line | text | The line. |
history[].by | value or null | Who did it. A key shows as its name, then "for" and the member it acts as. |
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 leads: Leads in the companies this credential reaches, newest first, with stage, service, estimate and where each came from.
- List needs you: Jobs that wait on a person, most urgent first, each with the reasons: no technician, unpaid cut, no answer and more.
- List conversion reviews: Ad clicks the matcher would not guess at. Each waits for you to pick the job it produced, or to reject it.
- The same records in the app: the Leads panel.
- How the API fits together: the model, API keys, errors and the MCP server.