Sortly API

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Pull a Job into Sortly

Rather than creating jobs by hand, listen for job creation in your external system and create the matching job in Sortly in response. Most systems can do this with a webhook or an outbound event; whatever your side emits when a work order is raised, use it to fire the call below. Field techs and warehouse staff then open the job in Sortly and assign items to it while they work.

Try it: POST /api/v1/jobs

external_job_link takes a full URL, not a bare id: give it a properly formed link that opens this job in your own system, such as https://app.servicetitan.com/jobs/10042. Anyone looking at the job in Sortly can then follow it straight back to the source record.

Who the job belongs to. The job is assigned to the owner by default. Job members are not exposed through the API, so you cannot set them on this call. Once the job exists, anyone with an owner or admin role can add members to it through the Sortly app.

Store the mapping. Keep the returned data.id against your system's job id. You need it for every later call, and it saves you searching by name.

Job names are unique within an account, so creating one that already exists fails. Before creating jobs in bulk, list what is already there and skip the names you find:

Try it: GET /api/v1/jobs

The new job comes back in not_started. Keep the id and the version.

Start the Job

When work actually begins in your external system, move the Sortly job to in_progress so anyone looking at it knows the crew is on site and the folder is live.

1. Read the job to get its current version. Status changes are guarded by version, so always read immediately before writing.

Try it: GET /api/v1/jobs/{job_id}

2. Move it to in_progress, passing the version from step 1.

Try it: PUT /api/v1/jobs/{job_id}/status

A 409 means someone changed the job between your read and your write. Re-read it and retry with the new version. Resending a status the job already has is safe, so a retried delivery does no harm. Moving a job backwards is rejected with 400.

Update Job Inventory (External to Sortly)

When usage is recorded in your external system, move what was used off the truck and into the job folder in Sortly, so usage is recorded against the job and replenishment reflects it.

1. Find the job's folder. Read the job back. The response carries folder_id, which is where stock needs to land.

Try it: GET /api/v1/jobs/{job_id}

2. Find the stock on the truck. List the truck folder's contents and match the items your system says were used.

Try it: GET /api/v1/items

3. Move the used quantities onto the job. Both endpoints below perform the same action: they move quantity out of the folder an item currently sits in and onto the job. Neither creates a new item.

Prefer Pull Items into Job. It takes up to 100 items in one request, and those items can sit in different folders, so a whole truck's worth of usage goes over in a single call.

Try it: POST /api/v1/jobs/{job_id}/items

action.reason_id is required here. It is the reason written into each item's history.

• Every Sortly account carries the default move reason Added to Job, e36df891-596f-42a2-a561-3d127d9fa080. Send that unless your account has its own.
• Leave action out and the call is rejected with 400 A reason is required for this action type. That holds even if you send action with only notes in it.
• Returning items needs no reason.

Pass item_version on an entry to have it rejected if the item changed since you read it, rather than applied over the top.

A partial failure still returns 200. Each item is processed on its own, so one bad row does not reject the rest. Check data.errors on every response rather than relying on the status code, and retry only the items listed there.

{ "data": { "added_item_ids": [],
            "errors": [ { "item_id": 14494919, "name": "Copper Pipe",
                          "error": "Invalid quantity for moving item 14494919: 999. Must be between 0 and 4.000000" } ] } }

Note that moving part of a quantity splits the item, so an id in added_item_ids can differ from the one you sent.

The move endpoint reaches the same end state and is available as an alternative, one item per call. Prefer Pull Items into Job either way, including for a single item: it is the call that expresses adding to a job, and it reports per-item failures. Set folder_id to the job's folder_id from step 1.

Try it: POST /api/v1/items/{item_id}/move

On both endpoints quantity is how much to move, not the new total. On the move endpoint, set leave_zero_quantity: true if you want a zero-quantity record left behind rather than the item disappearing from that folder once it hits 0.

Stock lands in the job folder itself, never in a subfolder. Even if the job was created with subfolders, both endpoints drop the items at the top level of the job's folder. If you need them filed into a particular subfolder, do a second move on the item afterwards with folder_id set to that subfolder.

With the truck folder now drawn down, low stock alerts on those items fire as normal and drive replenishment. See Track Stock Levels.