---
title: "Moves a job to another status."
method: POST
path: "/api/v1/jobs/{id}/status"
tags: ["Jobs"]
---

# Moves a job to another status.

`POST /api/v1/jobs/{id}/status`

## Request

- Base URL: `https://app.flexonthejob.com`
- URL: `https://app.flexonthejob.com/api/v1/jobs/{id}/status`
- Auth: HTTP bearer

Name the target with `statusId` (one of the organization's status definitions)
or `statusKey` (a status definition name, or a system key such as
`InProgress` / `Completed`), not both. No transition rules are enforced —
any status may follow any other, exactly as in the UI. Requires an
`Idempotency-Key` header.

## Path parameters

- `id` integer, required

## Request body

- SetJobStatusRequest: Body of `POST /api/v1/jobs/{id}/status`. Exactly one of `statusId` / `statusKey` is required.
  - `statusId` integer, nullable: Target status definition id (one of the org's statuses).
  - `statusKey` string, nullable: Target status by name — a status definition name (case-insensitive) or a system status key such as `InProgress`, `Completed`.
  - `note` string, nullable: Optional note appended to the status-change history entry.

## Response `200`

Job id and confirmation message.

- ApiOperationResponse: Body of a successful workflow-style write that has no richer resource to return (assign, start, complete, void…). Id is the affected resource's id; Warning carries a non-fatal note from the service (e.g. an email that could not be sent).
  - `id` integer: Id of the resource the operation acted on (e.g. the job id).
  - `message` string, nullable: Human-readable confirmation from the service (e.g. "Job started."). May be null.
  - `warning` string, nullable: Non-fatal problem encountered while completing the operation (e.g. a notification email that could not be sent). Null when there was none.

## Other responses

- `400`: Neither or both of `statusId` / `statusKey`, or missing `Idempotency-Key`.
- `401`: Unauthorized
- `403`: Forbidden
- `404`: No such job in this organization.
- `409`: The key's creator is unknown on this server, or the service refused the change.
- `422`: Unknown status for this organization.
- `429`: Too Many Requests

---

[API](https://skmtc.dev/flexonthejob/apis/flex-api.md) · [All operations](https://skmtc.dev/flexonthejob/apis/flex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flexonthejob/apis/flex-api/revisions/19c8f4d27acf?raw)