The request
Reference for Change job status, HeadHoncho API v1. It is a command, sent to the base address https://api.headhoncho.app.
POST /api/v1/commands/change-job-status
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 change-job-status. 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 |
status | text, in the JSON body | Yes | A status name or slug from Who am I. status_id works too. | Dispatched |
reason | text, in the JSON body | No | Read on a move into Canceled: why. | Customer found another mover |
What comes back
accepted, job_id, number, position, and status: where the job now stands.
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.
- 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.
- 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.