# Jobs

Jobs are work orders. Create a job, assign items to it, move it through
`not_started`, `in_progress` and `completed`, and return items when it's done.


## List Jobs

 - [GET /api/v1/jobs](https://developer.sortly.com/jobs/listjobs.md): Returns the company's jobs, most recently updated first.

## Create a Job

 - [POST /api/v1/jobs](https://developer.sortly.com/jobs/createjob.md): Creates a job and its Job folder. Starts in the not_started status. Name must be unique in the company.

## Fetch a Job

 - [GET /api/v1/jobs/{job_id}](https://developer.sortly.com/jobs/fetchjob.md): Returns a single Job by its ID, including its current status, metadata, assigned item counts, and custom field values.

## Update a Job

 - [PUT /api/v1/jobs/{job_id}](https://developer.sortly.com/jobs/updatejob.md): Updates the job's own details: name, dates, notes, external link and custom field values. It does not touch the job's inventory.
- Any nullable field you omit or send as null is cleared, so fetch the job first and
  send it back with your changes.
- Custom field values are the exception: the ones you send are set, and the rest keep
  their value. A job holds up to 2.
- To add items to the job, use Pull Items into Job. To change status, use the
  status endpoint.

## Delete a Job

 - [DELETE /api/v1/jobs/{job_id}](https://developer.sortly.com/jobs/deletejob.md): Deletes the job and its Job folder, including any items inside. Cannot be undone.

## Change a Job's Status

 - [PUT /api/v1/jobs/{job_id}/status](https://developer.sortly.com/jobs/changejobstatus.md): Moves the job forward to not_started, in_progress or completed. Moving backwards returns 400. Resending the current status is safe to retry. Completing a job locks its folder.

## Pull Items into Job

 - [POST /api/v1/jobs/{job_id}/items](https://developer.sortly.com/jobs/additemstojob.md): Moves an item out of the folder it currently sits in and into the job's folder. It
does not create anything: pass the item_id of any existing item in your account
along with the quantity to move, and that quantity is relocated onto the job.

Up to 100 items per request, and they may sit in different folders, which makes this
the practical way to record a batch of usage in one call.
POST /items/{item_id}/move performs the same action one item at a time.

Items land in the job's folder itself, never in a subfolder. Even when the job
was created with subfolders, everything arrives at the top level of the job folder.
To file an item into a particular subfolder, move it again afterwards with
POST /items/{item_id}/move and folder_id set to that subfolder.

Items are processed independently, so a failure on one does not reject the rest and
a partial failure still returns 200. Always check data.errors rather than relying
on the status code, and retry only the items listed there.

Moving part of a quantity splits the item, so an id in added_item_ids can differ
from the one you sent. Pulling items into a completed job returns 403.

## Return Items from a Job

 - [POST /api/v1/jobs/{job_id}/items/return](https://developer.sortly.com/jobs/returnitemsfromjob.md): Moves each item out of the job folder and into destination_folder_id, up to 100 per request. Items are processed one by one, so check errors in the response.