The request
Reference for Update job, HeadHoncho API v1. It is a command, sent to the base address https://api.headhoncho.app.
POST /api/v1/commands/update-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 update-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 |
|---|---|---|---|---|
job_id | id, in the JSON body | Yes | The job id, or its number. | job_1203 |
client_name | text, in the JSON body | No | The customer. | None |
client_phone | text, in the JSON body | No | Any format; stored as E.164. | None |
client_secondary_phone | text, in the JSON body | No | A second phone, or empty to clear it. | None |
address | object, in the JSON body | No | All four parts, as for Create a job. | None |
job_type_id | id, in the JSON body | No | From Who am I. | None |
scheduled_start | datetime, in the JSON body | No | ISO 8601. Send null to clear the window. | 2026-10-16T14:00:00-05:00 |
scheduled_end | datetime, in the JSON body | No | The end of the window. | 2026-10-16T17:00:00-05:00 |
quoted_price | money, in the JSON body | No | The new price, a number. | 1600 |
notes | text, in the JSON body | No | Replaces the notes. | None |
What comes back
accepted, job_id, number, position, and changed: the fields that moved.
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. |
| `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
- 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.
- 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.