List needs you

The request

Reference for List needs you, HeadHoncho API v1. It is a read, sent to the base address https://api.headhoncho.app.

GET /api/v1/needs-you

The key needs the Jobs 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
`company_id`	id, in the query	No	One company. Default: every company the credential reaches.	`cmp_14f5`
`limit`	number, in the query	No	1 to 200. Default 50.	`50`
`page`	number, in the query	No	Page number, from 1.	`1`

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 API key company_id (optional, id) limit (optional, number) page (optional, number)

Your key stays in this page and is never sent anywhere. Copy the line below and run it yourself.

What comes back

items, most urgent first: job (in the Get a job shape), band (now, today or later), due_at (when the harm lands) and reasons. Each reason has slug, label, severity (danger or warn), verb (the one thing that clears it), band and due_at. count is how many jobs wait in all. Jobs in Trash or Archive never appear.

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
`items`	list of objects	The rows on this page.
`items[].job`	object	The job.
`items[].job.id`	id (text)	The id of this record. Ids are opaque text: keep them exactly as given.
`items[].job.number`	whole number	The number people say out loud, such as the job number.
`items[].job.status`	object	The job status.
`items[].job.status.id`	id (text)	The id of this record. Ids are opaque text: keep them exactly as given.
`items[].job.status.name`	text	The name, as the app shows it.
`items[].job.status.slug`	text	The same name as a lowercase code word. Match on this, not on the name.
`items[].job.technicians`	list	The technicians.
`items[].band`	text	The band.
`items[].due_at`	time (ISO 8601, with offset)	When the due happened. Carries its offset from UTC; `Z` is UTC.
`items[].reasons`	list of objects	The reasons.
`items[].reasons[].slug`	text	The same name as a lowercase code word. Match on this, not on the name.
`items[].reasons[].label`	text	The name the app shows for it.
`items[].reasons[].severity`	text	The severity.
`items[].reasons[].verb`	text	The verb.
`items[].reasons[].band`	text	The band.
`items[].reasons[].due_at`	time (ISO 8601, with offset)	When the due happened. Carries its offset from UTC; `Z` is UTC.
`count`	whole number	How many match in all, across every page.

Same reasons as the app

The reasons are the app's own catalogue, read with the same rules the Needs you list uses. Reasons a workspace has not switched on are left out, as they are in the app.

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.

List leads: Leads in the companies this credential reaches, newest first, with stage, service, estimate and where each came from.
Get lead: One lead: who, what and when they asked for, the estimate, its stage and what happened to it so far.
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 Jobs panel.
How the API fits together: the model, API keys, errors and the MCP server.

Answer cURL Python JavaScript Your AI

{
  "items": [
    {
      "job": {
        "id": "job_1138",
        "number": 1138,
        "status": {
          "id": "st_02",
          "name": "Scheduled",
          "slug": "scheduled"
        },
        "technicians": []
      },
      "band": "now",
      "due_at": "2026-10-26T09:00:00Z",
      "reasons": [
        {
          "slug": "no_tech",
          "label": "No tech",
          "severity": "danger",
          "verb": "Assign a tech",
          "band": "now",
          "due_at": "2026-10-26T09:00:00Z"
        }
      ]
    }
  ],
  "count": 1
}

curl "https://api.headhoncho.app/api/v1/needs-you?company_id=cmp_14f5&limit=50" \
  -H "Authorization: Bearer hh_live_..."

import requests

response = requests.get(
    "https://api.headhoncho.app/api/v1/needs-you",
    headers={"Authorization": "Bearer hh_live_..."},
    params={
        "company_id": "cmp_14f5",
        "limit": "50",
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.headhoncho.app/api/v1/needs-you?company_id=cmp_14f5&limit=50", {
  headers: { Authorization: "Bearer hh_live_..." },
});
const data = await response.json();
console.log(data);

Tool: list_needs_you
Arguments: company_id (id, optional), limit (number, optional), page (number, optional)
Access: read on Jobs
Hints: readOnly=true, destructive=false, idempotent=true, openWorld=false
Try asking: "Using HeadHoncho, list needs you with company_id cmp_14f5."