Request a demo
LOG IN
Request a demo
LOG IN
  1. Home
  2. Knowledge Base
  3. Integrations and API
  4. How to manage pick lists with the REST API

How to manage pick lists with the REST API

What you’ll learn

The pick list endpoints let an ERP, MES, or tool management system create, read, update, and delete predefined pick lists in CRIBWISE. This article lists all five endpoints, every field in the schema, and how to check whether a queued write actually succeeded.

A pick list names a job, lists the items it needs, and states how many of each to pick. Operators then pick against it on the Shop Floor Interface instead of relying on their own knowledge of the job.

Call flow diagram: the sending ERP system authenticates against the Admin Portal, then calls PickList/Get, PickList/Create, PickList/Update, PickList/Delete, and PickList/GetRequestResult. Get and GetRequestResult return data to the ERP; Create, Update, and Delete send data to the Admin Portal.

The sending system authenticates once, then calls the pick list endpoints. Only Get and GetRequestResult return data.

The pick list endpoints at a glance

Method Endpoint What it does Answers with
GET {url}/ERP/PickList/Get Returns every pick list in the system. The pick lists themselves.
POST {url}/ERP/PickList/Create Creates new pick lists. A request GUID.
POST {url}/ERP/PickList/Update Updates existing pick lists. A request GUID.
POST {url}/ERP/PickList/Delete Deletes existing pick lists. A request GUID.
GET {url}/ERP/PickList/GetRequestResult Reports what happened to a queued create, update, or delete. A request status and a result object.

{url} is the base address of your solution – the host your Admin Portal runs on, without the portal path. If you open the Admin Portal at https://solutionaddress.com/adminportal/yourcompany, then {url} is https://solutionaddress.com.

Before your first call

  • An API key and an access token. Every call carries an Authorization: Bearer header. See How to authenticate with the REST API.
  • Pick lists switched on. Enable Enable predefined pick lists in System settings. Until it is on, pick lists do not appear on the Shop Floor Interface.
  • Item IDs that already exist. Every item on a pick list is referenced by its item ID and is validated against the database. See How to manage items with the REST API.
  • Cost allocation names, if you pre-fill them. Steps are referenced by step name and values by value name, so both must match the current cost allocation set. See How to manage cost allocation with the REST API.

Tip: Call PickList/Get first. It returns the IDs, names, and statuses of the lists that already exist, which is the quickest way to see whether your integration should create a list or update one.

How a call works

Reads and writes behave differently, and the difference decides how your integration has to be built.

  1. Reads answer directly. PickList/Get returns the pick lists in the response body.
  2. Writes are queued. Create, Update, and Delete answer 200 with a request GUID and put the work in a task queue. The response tells you the request was accepted – nothing about whether it worked.
  3. Results are collected separately. Pass the GUID to PickList/GetRequestResult to find out whether the queued work succeeded and which pick lists it touched.

Important: Treat a 200 from Create, Update, or Delete as “queued”, not as “done”. Validation errors are reported in the request result and nowhere else, so an integration that stops at the 200 silently misses every one of them.

Request and object statuses

GetRequestResult reports two things: how far the request itself has got, and what happened to each pick list in it.

Request status What it means
Created The request arrived but is not in the task queue yet.
Ready The request is in the queue, waiting to run.
Running The changes are being applied.
Completed Every change in the request has finished.
Failed The request could not be performed.

The Result object then lists each pick list under the outcome it reached: CreatedPickLists, UpdatedPickLists, DeletedPickLists, or Errors. Validation errors are listed per object and name the parameter that was rejected.

Pick list fields

All three write endpoints reuse the schema that PickList/Get returns. Fields an endpoint does not accept are ignored rather than rejected.

Field Type Required What it does
Id string, 50 Yes The unique ID of the pick list. Together with Name it identifies the list on update and delete.
Name string, 100 Yes The name operators see on the Shop Floor Interface, such as Monday maintenance kit.
CostAllocationSetId string, 50 Only with more than one set Which cost allocation set the pre-filled values belong to. With exactly one set in the system, CRIBWISE selects it for you.
CostAllocations[].StepType string Yes, within the array The name of the cost allocation step. Must match a step in the set.
CostAllocations[].Value string Yes, within the array The name of the value to pre-select for that step. Must exist in that step.
Items[].Id string Yes, within the array The item ID to put on the list. The item must already exist in CRIBWISE.
Items[].QuantityForPick number Yes, within the array How many units of that item to pick. Must be greater than zero.
Users[] array of strings No The logins allowed to see the list. Leave it out and every user sees it.
UserGroups[] array of strings No The user groups allowed to see the list. Leave it out and every group sees it.
AllowChangeQuantity boolean Yes true lets the operator change the quantity while picking. false locks it. Shown as Allow change quantity in the Admin Portal.
FixedQuantities boolean Yes true keeps the list available after everything on it has been picked, so it can be reused. false closes the list once it is fully picked. Shown as Fixed quantity in the Admin Portal.
TargetDate date and time No An informational date shown on the Shop Floor Interface. It does not close the list.
DeviceId string No Restricts the list to one storage device. Leave it out and the list appears on all devices. Part of Availability in the Admin Portal, together with users and groups.
Status string Read only Active, Invalid, or Closed. Returned by Get; ignored on write.

Pick list statuses

Status What it means
Active The list is usable and appears on the Shop Floor Interface for the users, groups, and device it allows.
Invalid A change to the items or to the cost allocation structure has left the list unusable. Get still returns it.
Closed Everything on the list has been picked and FixedQuantities was false, so the list is finished.

Note: FixedQuantities is not about locking quantities. It controls whether the list survives being fully picked. The field that stops an operator changing a quantity is AllowChangeQuantity.

Endpoint reference

PickList/Get

GET {url}/ERP/PickList/Get

Returns every pick list currently in the system, including lists whose status is Invalid or Closed. Use it to reconcile your own job data with what CRIBWISE holds.

Response

[
  {
    "Id": "string",
    "Name": "string",
    "CostAllocationSetId": "string",
    "CostAllocations": [
      { "StepType": "string", "Value": "string" }
    ],
    "Items": [
      { "Id": "string", "QuantityForPick": 0 }
    ],
    "Users": [ "string" ],
    "UserGroups": [ "string" ],
    "AllowChangeQuantity": true,
    "FixedQuantities": true,
    "TargetDate": "2026-09-01T09:58:01.950Z",
    "DeviceId": "string",
    "Status": "Active"
  }
]

PickList/Create

POST {url}/ERP/PickList/Create

Creates one or more pick lists. Send an array, even for a single list. Id and Name must be unique. Every item needs a quantity, and every item ID must already exist in CRIBWISE.

Pre-filled cost allocation is optional. Leave CostAllocations out to let the operator choose on the Shop Floor Interface, or set it to book every pick against the same machine, project, or operation.

Request body

[
  {
    "Id": "PL-1042",
    "Name": "Engine block 123",
    "CostAllocationSetId": "CA-SET-1",
    "CostAllocations": [
      { "StepType": "Machine", "Value": "CNC-04" },
      { "StepType": "Project", "Value": "Engine block 123" }
    ],
    "Items": [
      { "Id": "10001", "QuantityForPick": 4 },
      { "Id": "10002", "QuantityForPick": 2 }
    ],
    "AllowChangeQuantity": true,
    "FixedQuantities": true,
    "TargetDate": "2026-09-01T09:58:01.950Z"
  }
]

The response carries the request GUID. Pass it to PickList/GetRequestResult to confirm the list was created.

PickList/Update

POST {url}/ERP/PickList/Update

Updates existing pick lists. The list is identified by Id and Name, which are the only two fields you must send. Anything you leave out stays as it is, so a partial payload is enough to change one setting.

Arrays are the exception. Items, CostAllocations, Users, and UserGroups are replaced by exactly what you send, not merged into what is there.

Request body – raise one quantity and leave everything else untouched:

[
  {
    "Id": "PL-1042",
    "Name": "Engine block 123",
    "Items": [
      { "Id": "10001", "QuantityForPick": 6 },
      { "Id": "10002", "QuantityForPick": 2 }
    ]
  }
]

Warning: Sending an empty Items array clears every item from the list, and a pick list with no items does not appear on the Shop Floor Interface. Send the full item array whenever you touch it – including the items you are not changing.

PickList/Delete

POST {url}/ERP/PickList/Delete

Deletes existing pick lists. Id and Name are the only fields needed, and anything else you send is ignored.

Request body

[
  {
    "Id": "PL-1042",
    "Name": "Engine block 123"
  }
]

PickList/GetRequestResult

GET {url}/ERP/PickList/GetRequestResult?requestGuid={guid}

Query parameter Value
requestGuid The GUID returned by the Create, Update, or Delete call.

Reports the status of a queued request and lists what it did. Poll it until Status is Completed or Failed. Anything the request rejected appears in Errors, named per object and per parameter.

Response

{
  "Message": "string",
  "Status": "Completed",
  "Result": {
    "Errors": [ "string" ],
    "CreatedPickLists": [ "string" ],
    "UpdatedPickLists": [ "string" ],
    "DeletedPickLists": [ "string" ]
  }
}

Where the results appear

A pick list created through the API is an ordinary pick list. It appears in the Admin Portal under Data management > Pick lists, carrying the ID and name your integration sent and the status CRIBWISE gave it. The Statuses filter above the grid narrows the view to the same three values the Status field returns.

The CRIBWISE Admin Portal pick list overview with red callouts numbered 1 to 4 marking Data management in the left menu, Pick lists below it, the grid row showing pick list ID PL-Id-1 with the name My first Pick List, and the Status column showing Active.

The pick list overview: (1) Data management, (2) Pick lists, (3) the ID and name your payload sent, (4) the value the Status field returns.

Open a list with View detail to see the schema fields as the Admin Portal shows them. It is the quickest way to check that a call landed the way you meant it to, and the Change history tab records every write.

A pick list detail in the CRIBWISE Admin Portal with red callouts numbered 1 to 5 marking the read-only Status field showing Active, the ID field, the Name field, the Target date and Active till date fields, and the Fixed quantity, Allow change quantity and Allow pick more than requested checkboxes.

The same fields from the Admin Portal side: (1) Status, read only, (2) Id, (3) Name, (4) TargetDate – beside Active till date, which the schema does not cover, (5) AllowChangeQuantity and FixedQuantities.

The same screen also creates lists by hand through New pick list, and the export/import function creates them in bulk. Reach for the API when the sending system owns the data and should keep owning it – a nightly ERP run, or an MES that builds one list per work order. Operators then pick against the result on the Shop Floor Interface, as described in How to pick items from a pick list on the Shop Floor Interface.

Common confusion

People often think… But actually…
A 200 from Create means the pick list exists. It means the request was queued. The list exists only once GetRequestResult reports it under CreatedPickLists.
The request GUID goes in the body, or as a path segment. It is a query parameter: GetRequestResult?requestGuid={guid}. Any other spelling answers 404.
FixedQuantities stops the operator changing quantities. It makes the list reusable after it has been fully picked. AllowChangeQuantity is the field that locks quantities.
A partial Update merges the items you send into the list. Arrays are replaced, not merged. Whatever you send in Items becomes the whole list.
The schema covers every pick list field in CRIBWISE. Two fields are missing from it: Allow pick more than requested and Active till date. Both exist on the Admin Portal pick list form and in the export/import template, so set them there if your lists need them.

Take action

Ready to build the integration? Create an API key and exchange it for a token in How to authenticate with the REST API, then call PickList/Get to see what is already in the system before you write anything.

Was this article helpful?

Related Articles

Need Support?

Can't find the answer you're looking for?
Contact Support