Get company

The request

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

GET /api/v1/companies/{company_id}

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

Name	Kind	Required	Description	Example
`company_id`	id, in the path	Yes	The company id, from List companies or Who am I.	`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 API key company_id (required, id)

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

What comes back

The company: id, name, time_zone, country, service_area and status. A company this credential does not reach answers 404, the same as one that does not exist.

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.
`name`	text	The name, as the app shows it.
`time_zone`	text	The company's time zone name, such as America/Chicago.
`country`	text	The country.
`service_area`	text	The service area.
`status`	text	The job status.

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.
`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.

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.
List companies: The companies this credential reaches, each with its name, time zone, country and service area. The same ids every other call takes as company_id.
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

{
  "id": "cmp_14f5",
  "name": "Sunrise Moving",
  "time_zone": "America/Chicago",
  "country": "US",
  "service_area": "Bloomington and 30 miles around it",
  "status": "active"
}

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

import requests

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

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

Tool: get_company
Arguments: company_id (id, required)
Access: any key
Hints: readOnly=true, destructive=false, idempotent=true, openWorld=false
Try asking: "Using HeadHoncho, get company with company_id cmp_14f5."