Get calendar

The request

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

GET /api/v1/calendar

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`
`from`	date, in the query	No	The first day, in the company's time zone. Default: the first of this month.	`2026-10-01`
`to`	date, in the query	No	The last day, inclusive. Default: the end of that month. At most 500 days.	`2026-10-31`
`limit`	number, in the query	No	1 to 1000. Default 500.	`500`

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) from (optional, date) to (optional, date) limit (optional, number)

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

What comes back

from and to (the days read), time_zone, items (one job each in the Get a job shape, earliest booked time first), and count, how many jobs are booked in the window in all. The day is read on the clock of the company named, or of the first company when none is named. Trashed jobs are never listed.

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.
`time_zone`	text	The company's time zone name, such as America/Chicago.
`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[].number`	whole number	The number people say out loud, such as the job number.
`items[].company`	object	The company.
`items[].company.id`	id (text)	The id of this record. Ids are opaque text: keep them exactly as given.
`items[].company.name`	text	The name, as the app shows it.
`items[].client`	object	The client.
`items[].client.id`	id (text)	The id of this record. Ids are opaque text: keep them exactly as given.
`items[].client.name`	text	The name, as the app shows it.
`items[].client.phone`	text	A phone number. Hidden when the key hides personal details.
`items[].client.second_phone`	text	A second phone number. Hidden when the key hides personal details.
`items[].address`	object	The address.
`items[].address.line1`	text	The street address. Hidden when the key hides personal details.
`items[].address.line2`	text	The apartment or suite line. Hidden when the key hides personal details.
`items[].address.city`	text	The city.
`items[].address.state`	text	The state or region.
`items[].address.postal_code`	text	The postal code.
`items[].address.one_line`	text	The whole address on one line. Hidden when the key hides personal details.
`items[].job_type`	object	The job type.
`items[].job_type.id`	id (text)	The id of this record. Ids are opaque text: keep them exactly as given.
`items[].job_type.name`	text	The name, as the app shows it.
`items[].status`	object	The job status.
`items[].status.id`	id (text)	The id of this record. Ids are opaque text: keep them exactly as given.
`items[].status.name`	text	The name, as the app shows it.
`items[].status.slug`	text	The same name as a lowercase code word. Match on this, not on the name.
`items[].status.since`	time (ISO 8601, with offset)	From when this has been true. Carries its offset from UTC; `Z` is UTC.
`items[].technicians`	list of objects	The technicians.
`items[].technicians[].id`	id (text)	The id of this record. Ids are opaque text: keep them exactly as given.
`items[].technicians[].name`	text	The name, as the app shows it.
`items[].scheduled_start`	time (ISO 8601, with offset)	When the visit is planned to start. Carries its offset from UTC; `Z` is UTC.
`items[].scheduled_end`	time (ISO 8601, with offset)	When the visit is planned to end. Carries its offset from UTC; `Z` is UTC.
`items[].collected`	money (number)	The money received on the job so far. In the company's currency.
`items[].profit`	money (number)	The job's profit, worked out the way the app works it out. In the company's currency.
`items[].currency`	text	The three-letter currency code (ISO 4217). Every money value in the answer is in it.
`items[].source`	object	The source.
`items[].source.label`	text	The name the app shows for it.
`items[].source.filled_by`	text	How the job source was filled in: `call`, `form` or by hand.
`items[].source.click_id`	id (text)	The Google click id (gclid) the call or visit carried.
`items[].source.call_id`	id (text)	The id of the call.
`items[].source.call_at`	time (ISO 8601, with offset)	When the call happened. Carries its offset from UTC; `Z` is UTC.
`items[].source.campaign`	text	The ad campaign's name.
`items[].is_lead`	true or false	True while the job is still a lead.
`items[].notes`	text	Free-text notes.
`items[].created_at`	time (ISO 8601, with offset)	When it was created. Carries its offset from UTC; `Z` is UTC.
`items[].closed_at`	time or null	When it was closed.
`items[].canceled_at`	time or null	When it was canceled.
`items[].archived_at`	time or null	When it was archived.
`items[].trashed_at`	time or null	When it was trashed.
`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_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 jobs: Jobs and leads in the companies this credential reaches, newest first, with status, technician, schedule, money and the ad click each came from.
Get job: One job or lead: who, where, when, which status, which technicians, the money on it and the ad click it came from.
Get job history: Everything that happened to a job, in order, with who did it: created, moved, assigned, noted, paid. The same log the job page shows.
Get job log: A job's timeline in plain words, one line per thing that happened: notes, moves, texts, money, the rules and the AI, each with who did it.
List situations: The situations the AI dispatcher is working on jobs now: what came up, the plan, and which step it is on.
List job photos: The photos stored on a job, oldest first, each with a link that opens it for one minute.
Get photo: One stored photo and a fresh link to its file. The link works for one minute.
List unscheduled jobs: Open jobs and leads that have no booked time yet, the ones that waited longest first.
Export jobs: Jobs as a CSV file, newest first, up to 10,000 rows: ticket, technicians, status, dates, address, customer and price.
Search jobs: Find jobs by ticket number, customer, address or technician name, and technicians by name.
Get automatic status: Whether a person set this job's status by hand, why its facts do not hold it, and where Back to automatic would put it.
Get job detour: Whether a job is on a detour, such as Waiting on parts, and where Resolve would put it.
List job reassignments: The times this job was handed from one technician to another, oldest first, and how far each one got.
List calendar reassignments: Every reassignment on a job booked in a window: open ones, and ones that closed today.
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

{
  "from": "2026-10-01",
  "to": "2026-10-31",
  "time_zone": "America/Chicago",
  "items": [
    {
      "id": "job_1138",
      "number": 1138,
      "company": {
        "id": "cmp_14f5",
        "name": "Sunrise Moving"
      },
      "client": {
        "id": "cli_77a0",
        "name": "R. Azoulay",
        "phone": "+12175550142",
        "second_phone": ""
      },
      "address": {
        "line1": "2590 Main St",
        "line2": "",
        "city": "Bloomington",
        "state": "IL",
        "postal_code": "61701",
        "one_line": "2590 Main St, Bloomington, IL 61701"
      },
      "job_type": {
        "id": "jt_02",
        "name": "Local move"
      },
      "status": {
        "id": "st_02",
        "name": "Scheduled",
        "slug": "scheduled",
        "since": "2026-10-12T15:04:10Z"
      },
      "technicians": [
        {
          "id": "wrk_3b90",
          "name": "Dana R."
        }
      ],
      "scheduled_start": "2026-10-16T09:00:00-05:00",
      "scheduled_end": "2026-10-16T11:00:00-05:00",
      "collected": 0.0,
      "profit": 0.0,
      "currency": "USD",
      "source": {
        "label": "Google Ads",
        "filled_by": "call",
        "click_id": "Cj0KCQjw...",
        "call_id": "CAL8f2e1",
        "call_at": "2026-10-11T18:22:03Z",
        "campaign": "Moving - Bloomington"
      },
      "is_lead": false,
      "notes": "Two flights of stairs",
      "created_at": "2026-10-11T18:25:40Z",
      "closed_at": null,
      "canceled_at": null,
      "archived_at": null,
      "trashed_at": null
    }
  ],
  "count": 1
}

curl "https://api.headhoncho.app/api/v1/calendar?company_id=cmp_14f5&from=2026-10-01" \
  -H "Authorization: Bearer hh_live_..."

import requests

response = requests.get(
    "https://api.headhoncho.app/api/v1/calendar",
    headers={"Authorization": "Bearer hh_live_..."},
    params={
        "company_id": "cmp_14f5",
        "from": "2026-10-01",
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.headhoncho.app/api/v1/calendar?company_id=cmp_14f5&from=2026-10-01", {
  headers: { Authorization: "Bearer hh_live_..." },
});
const data = await response.json();
console.log(data);

Tool: get_calendar
Arguments: company_id (id, optional), from (date, optional), to (date, optional), limit (number, optional)
Access: read on Jobs
Hints: readOnly=true, destructive=false, idempotent=true, openWorld=false
Try asking: "Using HeadHoncho, get calendar with company_id cmp_14f5."