Replace job status

The request

Reference for Replace job status, HeadHoncho API v1. It is a command, sent to the base address https://api.headhoncho.app.

POST /api/v1/commands/replace-job-status

The key needs the Company settings area at do. An answered call costs 1 credit; a refusal costs nothing. See credits.

It runs the app's own command replace-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
`status`	text, in the JSON body	Yes	The status: its id, its slug or its name, from Who am I or Company settings.	`waiting`
`into_status`	text, in the JSON body	No	An existing status to take its place: id, slug or name. Leave out when you send new_name.	`scheduled`
`new_name`	text, in the JSON body	No	A new status to create in its place. Leave out when you send into_status.	`On hold`
`new_color`	text, in the JSON body	No	The new status's fill as #rrggbb. Default: the old one's.	None
`new_ink`	text, in the JSON body	No	The new status's text color as #rrggbb. Default: the old one's.	None
`move_jobs`	boolean, in the JSON body	No	true (default) moves every job on the old status to the new one.	`true`
`retire_old`	boolean, in the JSON body	No	true (default) retires the old status so nothing can pick it. Old jobs not moved keep its name.	`true`
`take_place`	boolean, in the JSON body	No	true puts an existing status in the old one's place on the line. A new status always takes it.	`false`

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 status (required, text) into_status (optional, text) new_name (optional, text) new_color (optional, text) new_ink (optional, text) move_jobs (optional, boolean) retire_old (optional, boolean) take_place (optional, boolean)

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

What comes back

accepted, status_id (the old one), into_status_id, into_name, created (whether a new status was made), moved (how many jobs changed status) and retired, and position.

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.

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
`accepted`	true or false	True when the command ran. A command that cannot run is an error instead.
`position`	whole number	Where the change landed in the event log. Pass it as `after` on a read to see your own write.
`status_id`	id (text)	The id of the status.
`into_status_id`	id (text)	The id of the into status.
`into_name`	text	The into name.
`created`	true or false	The created.
`moved`	whole number	The moved.
`retired`	true or false	The retired.

What it does to jobs

With move_jobs true, every job on the old status in every company moves to the new one, and each move lands in that job's history. A job that is closed or canceled travels with the role. With move_jobs false the jobs keep the old name. Sending neither move_jobs nor retire_old as true is refused, because nothing would happen.

Reach

The credential must reach every company, because the jobs of all of them move.

Roles

A status that carries a role (draft, closed, canceled and so on) hands the role to the one taking its place.

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.
`read_only`	403	This credential may read this area but not change it.
`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.
`idempotency_in_progress`	409	A command with this Idempotency-Key is still running. Wait a moment and send it again.
`no_credits`	402	Out of credits. Top up on Settings › Credits, or turn on auto top-up.

Update company: Change one company's own facts: name, service area, time zone, country, color, week, opening hours or service places. Only what you send changes.
Create company: Add another company to the workspace. It starts with the first company's time zone and country unless you send your own.
Update organization: Rename the workspace. A company still carrying the old workspace name is renamed with it.
Add job type: Add a kind of work the business does, such as Local move or Roof repair. A name already in use is refused.
Update job type: Rename a job type, move it in the list, or retire it so new jobs cannot pick it. Old jobs keep it.
Update job status: Rename a status, change its look, move it in the list, or retire it. A rename shows on every job at once. Its slug and band stay.
Set status band: Put a status on the line (a step every job passes) or off it as a detour (a place a job gets stuck). The line closes up behind it.
Add job status: Add a status to the workspace's list, on the line or as a detour. It carries no role: it is a name and a color.
Reorder line: Set the order of the statuses on the line, the order every picker offers. Send every status on the line, once each.
Update agency feed: Change how closed jobs reach the agency: the webhook address, the daily file address and hour, or switch the feed on or off. Secrets are not touched.
Sync callrail: Pull the company's new CallRail calls and forms now, match them to jobs, and say how many landed. The hourly sync does this on its own.
Update callrail tracking: Set the tracking phone numbers on a company's CallRail connection. They replace the list whole. The webhook signing key is set in the app.
Refresh sources: Clear the Call center source stamped on a company's jobs, pull all its CallRail history again and re-read every call, so each job's source is worked out afresh.
Sync ad platform: Pull a company's latest campaigns and spend from one ad platform now. The hourly sync does this on its own.
The same records in the app: Settings.
How the API fits together: the model, API keys, errors and the MCP server.

Answer cURL Python JavaScript Your AI

{
  "accepted": true,
  "position": 88611,
  "status_id": "st_09",
  "into_status_id": "st_12",
  "into_name": "On hold",
  "created": true,
  "moved": 4,
  "retired": true
}

curl -X POST "https://api.headhoncho.app/api/v1/commands/replace-job-status" \
  -H "Authorization: Bearer hh_live_..." \
  -H "Idempotency-Key: 6f1d2c9e-1b7a-4c1e-9a52-0d3f8e4b7a10" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "waiting",
  "into_status": "scheduled",
  "new_name": "On hold",
  "move_jobs": true,
  "retire_old": true,
  "take_place": false
}'

import requests
import uuid

response = requests.post(
    "https://api.headhoncho.app/api/v1/commands/replace-job-status",
    headers={
        "Authorization": "Bearer hh_live_...",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "status": "waiting",
        "into_status": "scheduled",
        "new_name": "On hold",
        "move_jobs": True,
        "retire_old": True,
        "take_place": False,
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.headhoncho.app/api/v1/commands/replace-job-status", {
  method: "POST",
  headers: {
    Authorization: "Bearer hh_live_...",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "status": "waiting",
    "into_status": "scheduled",
    "new_name": "On hold",
    "move_jobs": true,
    "retire_old": true,
    "take_place": false
  }),
});
const data = await response.json();
console.log(data);

Tool: replace_job_status
Arguments: status (text, required), into_status (text, optional), new_name (text, optional), new_color (text, optional), new_ink (text, optional), move_jobs (boolean, optional), retire_old (boolean, optional), take_place (boolean, optional)
Access: do on Company settings
Hints: readOnly=false, destructive=true, idempotent=false, openWorld=false
Try asking: "Using HeadHoncho, replace job status with status waiting and into_status scheduled."