# The HeadHoncho public API The HeadHoncho public API lets your code, or the AI app you already use, read a client's jobs and raw ad data and change jobs, under the same rules as the app. Page: https://headhoncho.app/docs/api | Part of the HeadHoncho API docs: https://headhoncho.app/docs/api | Machine-readable: https://headhoncho.app/docs/api/openapi.json ## What the API is The HeadHoncho public API is the app, reachable from code. It gives a marketing agency's campaigner, or the developer they hired, the same records the app draws: jobs and leads, the raw rows each ad platform and call tracker reported, and the Google Click ID report. An AI app can use it too, through the [MCP server](https://headhoncho.app/docs/api/mcp). It follows the app's own model. A read is a `GET` over a record the app already shows. A change is a `POST` to `/api/v1/commands/`, where the verb is the app's own command name. Nothing is computed here that the app does not compute. The longer version is on [the model](https://headhoncho.app/docs/api/model). There are 16 endpoints in 5 groups today, all under `https://api.headhoncho.app/api/v1`. It gives you building blocks: records, raw rows and single commands. It never gives you a board, a dashboard or an automation to rebuild the app with. The [roadmap](https://headhoncho.app/docs/api/roadmap) says what is planned and what will never be offered. ## The 5 groups ### Account - [Whoami](https://headhoncho.app/docs/api/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. ### Jobs - [List jobs](https://headhoncho.app/docs/api/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](https://headhoncho.app/docs/api/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](https://headhoncho.app/docs/api/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. ### Job commands - [Create job](https://headhoncho.app/docs/api/create_job): Open a job or a lead in one company: the customer, the address, and optionally the job type, the time window and the technician. - [Update job](https://headhoncho.app/docs/api/update_job): Change a job's facts: the customer, the address, the schedule, the price, the job type or the notes. Only the fields you send change. - [Change job status](https://headhoncho.app/docs/api/change_job_status): Move a job to another status by its name, slug or id. The move lands in the job's history with who asked for it. - [Assign worker](https://headhoncho.app/docs/api/assign_worker): Put a technician or subcontractor on a job. If Job follow-up is on, the automation acts on it at once, as it would from the app. - [Unassign worker](https://headhoncho.app/docs/api/unassign_worker): Take a technician or subcontractor off a job. The ticket's cancellation reaches them the way it does from the app. - [Add job note](https://headhoncho.app/docs/api/add_job_note): Add a note to a job. It appends to the job's log and never overwrites. ### Raw data - [List tables](https://headhoncho.app/docs/api/list_tables): Every raw table, by the provider that produced it, with its columns, its grain and whether this company has it connected. - [Read table](https://headhoncho.app/docs/api/read_table): Rows of one raw table for one company and a date range, exactly as the provider reported them. No joins, no derived figures. - [Export table](https://headhoncho.app/docs/api/export_table): One raw table as a CSV file for a company and a date range, up to 50,000 rows, with its caveat in the last lines. ### Click IDs and conversions - [Get job conversion](https://headhoncho.app/docs/api/get_job_conversion): What this job told the ad platform it was worth: the click it came from, each conversion sent, its value and its basis, and what Google did with it. - [Get click id report](https://headhoncho.app/docs/api/get_click_id_report): The Google Click ID report: one row per job that opened or closed in the range, with its click id, its tracked call, its total and its profit. - [Export click id report](https://headhoncho.app/docs/api/export_click_id_report): The Google Click ID report as a file: the agency's sheet, or the Google Ads offline conversion upload file, ready to upload. ## Get a key Make a key in the app at [Automations, then API keys](https://app.headhoncho.app/automations/api). Choose the companies it reaches, the access it has per area, and whether personal details are hidden. The key is shown once. The full walk-through is on [API keys](https://headhoncho.app/docs/api/keys). Then make your first call. It tells you who the key acts as, which companies it reaches and the statuses, job types and technicians to use in commands: ```bash curl "https://api.headhoncho.app/api/v1/whoami" \ -H "Authorization: Bearer hh_live_..." ``` The answer is shown on [Whoami](https://headhoncho.app/docs/api/whoami). ## Connect an AI app Claude, ChatGPT, Claude Code and Cursor can use the same 16 endpoints as tools, with the same names and arguments. Paste `https://api.headhoncho.app/mcp` into the app's connector settings, or pass a key. Setup for each app is on [the MCP server](https://headhoncho.app/docs/api/mcp). An AI app only ever reaches the companies and areas you approve. ## The same records in the app Everything the API returns is something the app already shows. [The Jobs panel](https://headhoncho.app/docs/jobs) draws the jobs. [The Raw data board](https://headhoncho.app/docs/marketing/raw-data) draws the raw rows. [Offline conversion tracking](https://headhoncho.app/offline-conversion-tracking) explains why the click id matters. [Multiple companies](https://headhoncho.app/docs/companies) explains how one login holds many client businesses, which is what a key's company list is made of. ## What is coming A group of endpoints arrives when the owner approves it, and an endpoint is never built without appearing on [the roadmap](https://headhoncho.app/docs/api/roadmap) first. ## Machine-readable copies - Every page here has a Markdown twin: add `.md` to its address, for example [this page as Markdown](https://headhoncho.app/docs/api.md). - The whole surface as data: [catalog.json](https://headhoncho.app/docs/api/catalog.json). - An OpenAPI 3.1 file for code generators: [openapi.json](https://headhoncho.app/docs/api/openapi.json). - The site-wide guide for agents: [llms.txt](https://headhoncho.app/llms.txt).