Import a Task Group

Import a JSON representation of a task group.

Direction WMS → WCS

HTTP Method POST

Path /api/task/pick/import

Request Body

Field notes:

Field Name	Data Type	Description	Notes
externalReference	String	A unique identifier that can be used to link the imported Pick list to the relevant data in the connected WMS, frequently populated with a UUID
taskCategory	String	The identifier for which ‘Queue’ of work this pick list should fall under	3 digits 100-199
expectedCompletionTime	String Date Time	The expected completion time for this pick list, used to aid in determining priority
timeZone	String	The time zone for the expected completion time
externalCustomerOrderId	String	Identifier for the shipment/order this pick list is for, should it be for a single shipment	Can be used in conjunction
externalCustomerBatchId	String	Identifier for the grouping/batch for this pick list, should it be for a collection of shipments/other
shippingBarcode	String	The identifier the operator must scan once the pick list is completed (usually a barcode on a shipment’s label)	Presence results in a print label request being made to the WMS once the pick has been completed. Mutually exclusive with containerRegex
containerRegex	String	A regular expression that defines the format of the container identifiers accepted when performing pick to container	Mutually exclusive with shippingBarcode
shipmentType	String	Identifier for which type of picking this pick list is for	Accepted values: Pick-Pack, Batch-Pick
packagingSuggestion	String	Used to relay relevant packing information to the operative when performing pick, shown in plain text on the operative’s screen
courier	String	Used to relay courier information to the operative when performing pick
prePackMessages	String Array	Used to relay pre-packing instructions to the operative at the port before picking commences
postPackMessages	String Array	Used to relay post packing instructions to the operative once picking has finished
shippingLabelUrl	String
tasks	Object Array	Pick data, this list contains all of the expected products and quantities that are to be retrieved
task.externalReference	String JSON	A JSON string that can be used to link the individual task within this pick list to the relevant data in the connected WMS, for legacy integrations
task.externalReferenceId	String	A unique identifier that can be used to link the individual task within this pick list to the relevant data in the connected WMS, frequently populated with a UUID
task.productId	String	The product ID that is being requested for pick
task.batchId	String	The batch identifier for a specific batch-managed product that is to be picked
task.expiry	String	The expiration identifier for a specific date-managed product that is to be picked
task.stockOwner	String	The stock owner identifier for a specific owner-managed product that is to be picked
task.requestedQuantity	Double	The total amount of units to be picked for this product

** Example Request Body**

{
  "externalReference": "4c859d80-5828-4bf4-b33a-2c6cccd0cfc4",
  "taskCategory": "100",
  "expectedCompletionTime": "2026-01-31 14:30",
  "timeZone": "Europe/London",
  "externalCustomerOrderId": "CUSTOMER12345",
  "externalCustomerBatchId": "CUSTOMERBATCH12345",
  "shippingBarcode": "SHIP123456789",
  "shipmentType": "Pick-Pack",
  "allowShortAllocation": false,
  "containerRegex": "^CONTAINER\\d{10}$",
  "packagingSuggestion": "Medium Box",
  "courier": "Speedy Parcels",
  "shippingLabelUrl": "https://example.com/labels/shipping-label.pdf",
  "prePackMessages": [
    "Fragile items, handle with care",
    "Hazardous items, handle with care"
  ],
  "postPackMessages": [
    "Ensure promotional leaflets are packed",
    "Ensure Hazmat label is applied"
  ],
  "tasks": [
    {
      "externalReference": "{\"ALLOCATION_REFERENCE\":\"REF12345\",\"SKU\":\"SKU12345\"}",
      "externalReferenceId": "a7dd81eb-64b7-42d3-a5cd-09509f0d1c9a",
      "metadata": {"ALLOCATION_REFERENCE": "REF12345", "SKU": "SKU12345"},
      "productId": "PROD12345",
      "batchId": "BATCH12345",
      "expiry": "2027-01-01",
      "stockOwner": "OWNER12345",
      "requestedQuantity": 5.0
    },
    {
      "externalReference": "{\"ALLOCATION_REFERENCE\":\"REF54321\",\"SKU\":\"SKU54321\"}",
      "metadata": {"ALLOCATION_REFERENCE": "REF54321", "SKU": "SKU54321"},
      "productId": "PROD54321",
      "stockOwner": "OWNER12345",
      "requestedQuantity": 10.0
    },
    {
      "externalReference": "{\"ALLOCATION_REFERENCE\":\"REF54321\",\"SKU\":\"SKU54321\"}",
      "externalReferenceId": "484D65C8-1965-4326-8057-5FBE5BC427E1",
      "productId": "PROD1111",
      "stockOwner": "OWNER12345",
      "requestedQuantity": 15.0
    }
  ],
  "allowShortAllocation": false
}

Field notes:

• tasks[].metadata (object, optional): Key-value map of supplementary task data. Not validated as required, so the key can be left out of the request entirely; sending null or an empty object is equivalent.
• allowShortAllocation (boolean, optional): Controls whether the task group may be allocated when there is insufficient stock to fulfil every line. Defaults to false when omitted. When false, the task group is only allocated if every line can be fully allocated; if any line is short, no tasks are created and a short allocation result is returned to the WMS immediately. When true, the task group and its tasks are created for whatever stock can be allocated, and any unfulfilled quantity is recorded as shorted against the affected tasks.

Responses

202: TaskGroup passed validation

{
  "message": "Accepted"
}

400: TaskGroup failed validation

{
  "message": "Bad Request",
  "errors": [
    {
      "message": "Task field externalReference must not be null and contain at least 1 non-whitespace character",
      "path": "externalReference"
    },
    {
      "message": "must match \"\\b\\d{3}\\b\"",
      "path": "taskCategory"
    },
    {
      "message": "Shipment Type field must not be null and contain at least 1 non-whitespace character",
      "path": "shipmentType"
    },
    {
      "message": "Task field tasks must not be empty",
      "path": "tasks"
    },
    {
      "message": "must not be blank",
      "path": "tasks[0].taskId"
    }
  ]
}

401: Access denied, Invalid Authentication

{
  "message": "Unauthorized"
}