List companies

The request

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

GET /api/v1/companies

Any key can call it. 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 API key

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

What comes back

items, one company each: id, name, time_zone, country, service_area and status (active or archived); count, how many in all. Only companies this credential reaches are listed. Who am I carries the same ids with the lookups a command needs.

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[].id`	id (text)	The id of this record. Ids are opaque text: keep them exactly as given.
`items[].name`	text	The name, as the app shows it.
`items[].time_zone`	text	The company's time zone name, such as America/Chicago.
`items[].country`	text	The country.
`items[].service_area`	text	The service area.
`items[].status`	text	The job status.
`count`	whole number	How many match in all, across every page.

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_credits`	402	Out of credits. Top up on Settings › Credits, or turn on auto top-up.

Whoami: Who this key or app acts as, which companies it reaches, what it may do, and the words to use in commands: statuses, job types and technicians.
Get company: One company this credential reaches: its name, time zone, country and service area.
Get usage: What the plan has used, what API calls cost and what this credential called, by day or by endpoint, with the credits left.
Get credits: This month's credits: the plan's grant, what rolled over, what was bought, what was used and what is left.
List plans: The plans on offer, with price and what each includes, and which one this workspace is on.
The same records in the app: Multiple companies.
How the API fits together: the model, API keys, errors and the MCP server.

Answer cURL Python JavaScript Your AI

{
  "items": [
    {
      "id": "cmp_14f5",
      "name": "Sunrise Moving",
      "time_zone": "America/Chicago",
      "country": "US",
      "service_area": "Bloomington and 30 miles around it",
      "status": "active"
    },
    {
      "id": "cmp_8a21",
      "name": "Capital Roofing",
      "time_zone": "America/New_York",
      "country": "US",
      "service_area": "",
      "status": "active"
    }
  ],
  "count": 2
}

curl "https://api.headhoncho.app/api/v1/companies" \
  -H "Authorization: Bearer hh_live_..."

import requests

response = requests.get(
    "https://api.headhoncho.app/api/v1/companies",
    headers={"Authorization": "Bearer hh_live_..."},
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.headhoncho.app/api/v1/companies", {
  headers: { Authorization: "Bearer hh_live_..." },
});
const data = await response.json();
console.log(data);

Tool: list_companies
Arguments: none
Access: any key
Hints: readOnly=true, destructive=false, idempotent=true, openWorld=false
Try asking: "Using HeadHoncho, list companies."