Start a process run from an outside system

Let your system put work on the floor: your ERP asks for location A-03-2 to be counted, a supplier portal announces a delivery that needs a receiving run, or a planning tool wants a batch picked now. Your system starts a run of a process, and the first operator who claims it on the floor works it.

When to use this

Use this recipe when the work comes from somewhere Picked doesn't plan it. A run you start this way is the same as one a schedule opens: it waits, unassigned, until an operator claims it.

You need a token with the process-runs:write ability (see Authentication).

Find the process

A process is named by its public id, a UUID. In Picked, open Processes, then the process's settings: its API id is there, with a copy button. The process must be published and enabled. A draft that was never published can't be started, and neither can a process that only runs as a step of another one.

The variables a process declares are what a run can start with. If the process marks a variable as required, a run started without it is refused.

Start the run

POST /api/v1/processes/{process}/runs with the warehouse the run is worked in and its starting variables. Only variables the process declares are accepted, each of its declared type: a string, a number, true or false, an object or a list. The others start with their defaults, and null leaves one that isn't required at its default.

Send an Idempotency-Key header, any string unique to this request, such as your own job number. If the call times out and you send it again with the same key, you get the first answer back and no second run opens.

curl -X POST "https://picked.nl/api/v1/processes/0192f5a0-7c1e-7b3a-9d4e-2f6a8b1c3d5e/runs" \
  -H "Authorization: Bearer $PICKED_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-count-48211" \
  -d '{
    "warehouse_id": 12,
    "variables": { "location": "A-03-2", "expected_quantity": 40 }
  }'

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/process-runs/5512

{
  "id": 5512,
  "process": "0192f5a0-7c1e-7b3a-9d4e-2f6a8b1c3d5e",
  "warehouse_id": 12,
  "status": "pending",
  "variables": { "location": "A-03-2", "expected_quantity": 40 },
  "created_at": "2026-10-14T09:12:44.000000Z",
  "started_at": null,
  "completed_at": null,
  "opened": true,
  "_links": {
    "self": { "href": "/api/v1/process-runs/5512" }
  }
}

One run per thing

A retry is one thing; asking twice for the same work is another. If your system may ask to count A-03-2 again while the first count is still open, send dedupe_on with the name of a string variable. When a run of the process is still open with the same value, Picked answers 200 with that run and opened: false, and opens nothing. Once that run has finished, the next request opens a new one.

{
    "warehouse_id": 12,
    "variables": { "location": "A-03-2" },
    "dedupe_on": "location"
}

Read the run back

GET /api/v1/process-runs/{id} answers the run as it is now: pending until an operator claims it, then in_progress, and completed when the work is done. Its variables are the ones the run started with, defaults included.

curl "https://picked.nl/api/v1/process-runs/5512" \
  -H "Authorization: Bearer $PICKED_TOKEN" \
  -H "Accept: application/json"

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 5512,
  "process": "0192f5a0-7c1e-7b3a-9d4e-2f6a8b1c3d5e",
  "warehouse_id": 12,
  "status": "pending",
  "variables": { "location": "A-03-2", "expected_quantity": 40 },
  "created_at": "2026-10-14T09:12:44.000000Z",
  "started_at": null,
  "completed_at": null,
  "_links": {
    "self": { "href": "/api/v1/process-runs/5512" }
  }
}

Errors to handle

Status	What to do
`422` `validation_failed`	A required variable is missing, a variable isn't declared or has the wrong type, the warehouse isn't yours, or the process is disabled or not runnable. Fix the request.
`404` `not_found`	No published process with this id in your workspace, or no run with this id.
`409` `conflict`	The `Idempotency-Key` was already used for a different request. Send a new key.
`400` `bad_request`	The `Idempotency-Key` is empty or longer than 255 characters.
`403` `missing_ability`	The token lacks `process-runs:write`.

Errors lists every code, and Rate limits what to do on a 429.

Testing

Send the call with a Picked-Dry-Run: true header. It is validated against your real processes and warehouses and answers 200 with the run it would open, id null and would: created, and nothing is opened. See Dry runs.