The request
Reference for Create job, HeadHoncho API v1. It is a command, sent to the base address https://api.headhoncho.app.
POST /api/v1/commands/create-job
The key or app needs the Jobs area at do. It counts as a write call: 60 a minute for each key or connected app. See rate limits.
It runs the app's own command create-job. Send an Idempotency-Key header with every call: the same key with the same body returns the first answer and runs nothing twice. See the model.
Parameters
| Name | Kind | Required | Description | Example |
|---|---|---|---|---|
company_id | id, in the JSON body | Yes | From Who am I. | cmp_14f5 |
client_name | text, in the JSON body | Yes | The customer, as they gave it. | R. Azoulay |
client_phone | text, in the JSON body | Yes | Any format; stored as E.164. | +12175550142 |
address | object, in the JSON body | Yes | line1, city, state and postal_code. line2 is optional. | {"line1": "2590 Main St", "city": "Bloomington", "state": "IL", "postal_code": "61701"} |
job_type_id | id, in the JSON body | No | From Who am I. | jt_02 |
scheduled_start | datetime, in the JSON body | No | ISO 8601, with scheduled_end. | 2026-10-16T09:00:00-05:00 |
scheduled_end | datetime, in the JSON body | No | ISO 8601. The end of the window. | 2026-10-16T11:00:00-05:00 |
quoted_price | money, in the JSON body | No | The price quoted, a number. | 1450 |
worker_id | id, in the JSON body | No | Assigns the technician now. | wrk_3b90 |
notes | text, in the JSON body | No | Anything the crew should know. | Two flights of stairs |
intent | text, in the JSON body | No | create (default) opens a job; draft opens a lead; dispatch opens it and sends the ticket to the technician. One of create, draft, dispatch. | create |
What comes back
accepted, job_id, number, and position: the event position, usable as after= on the next read so you see your own write. A missing fact the app would hold on Draft is refused here with 422 naming the field.
It never deletes anything. It changes only what the command names, and it writes the change to the job's history with who asked for it.
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. |
| `expired_token` | 401 | That token has expired. Refresh it, or connect the app again. |
| `no_access` | 403 | This credential does not reach that. Ask the person who made it for access. |
| `read_only` | 403 | This credential may read this area but not change it. |
| `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. |
| `missing_idempotency_key` | 400 | Send an Idempotency-Key header on every command. |
| `idempotency_mismatch` | 409 | This Idempotency-Key was used with a different body. |
| `rate_limited` | 429 | Too many calls this minute. Wait and try again. |
Related
- 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: 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: 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: Take a technician or subcontractor off a job. The ticket's cancellation reaches them the way it does from the app.
- Add job note: Add a note to a job. It appends to the job's log and never overwrites.
- The same records in the app: the Jobs panel.
- How the API fits together: the model, API keys, errors and the MCP server.