Manifesting Consignments via the API

Overview

Manifesting is a crucial step in the shipping process that finalises a consignment in MachShip and transmits the consignment data to the transport provider. This guide explains how to manifest consignments programmatically using the MachShip API.

Understanding the Process

Manifesting Consignments Diagram

Manifesting in MachShip is a two-step process:

  1. Group Consignments: First, you group consignments that share common attributes (carrier, location). This step returns the available options for each group.
  2. Create Manifest: Then, you can manifest each group individually after setting their specific options (pickup times, special instructions, etc.).

This two-step approach allows you to:

  • Group related consignments efficiently
  • Set specific options for each group
  • Handle multiple carriers and locations in a single operation

Step 1: Group Consignments

You have two options for grouping consignments:

Option A: Group Specific Consignments

Use this when you want to manifest specific consignments:

POST /apiv2/manifests/groupConsignmentsForManifest

Request body:

[
  123456,
  569836
]

This endpoint accepts an array of consignment IDs and groups them by:

  • Carrier
  • From Location
  • Despatch Date

Option B: Group All Unmanifested Consignments

Use this when you want to manifest all unmanifested consignments for a specific company:

POST /apiv2/manifests/groupAllUnmanifestedConsignmentsForManifest

Request body:

"123456"  // Company ID

Need help finding your company ID? See our guide on Finding Company IDs.

Response Format

Both grouping endpoints return the same response format:

{
  "object": [
    {
      "consignmentIds": [
        123456,
        569836
      ],
      "companyId": 0,
      "pickupDateTime": "2021-02-05T07:15:19.337",
      "palletSpaces": 0,
      "pickupClosingTime": "2021-02-05T07:15:19.337",
      "pickupSpecialInstructions": "string",
      "pickupAlreadyBooked": true,
      "carrierName": "string"
    }
  ],
  "errors": [
    {
      "validationType": 0,
      "memberNames": [
        "string"
      ],
      "errorMessage": "string"
    }
  ]
}

The response includes:

  • consignmentIds: Array of consignments that share the same attributes
  • companyId: The company ID these consignments belong to
  • pickupDateTime: Default pickup time (local time)
  • palletSpaces: Estimated count based on Pallets, Skids, Crates and Packs
  • pickupClosingTime: Default closing time (local time)
  • pickupSpecialInstructions: Any pre-stored pickup instructions
  • pickupAlreadyBooked: Defaults to false (indicating pickup needs booking)
  • carrierName: The carrier's name

Step 2: Create Manifest

After grouping consignments, you can create manifests using:

POST /apiv2/manifests/manifest

Request Parameters

[
  {
    "consignmentIds": [
      123456,
      569836
    ],
    "companyId": 1,
    "pickupDateTime": "2021-02-09T01:00:00.000Z",
    "palletSpaces": 3,
    "pickupClosingTime": "2021-02-09T04:00:00.000Z",
    "pickupSpecialInstructions": "Driver Must Be Inducted to be on Site",
    "pickupAlreadyBooked": false,
    "carrierName": "string"
  }
]

Key fields to configure:

  • pickupDateTime: When you want the pickup driver to arrive (local time)
  • palletSpaces: Adjust if you have oversized freight or multiple items per space
  • pickupClosingTime: When your operations cease for the day (local time)
  • pickupSpecialInstructions: Any special instructions for the pickup driver
  • pickupAlreadyBooked: Set to true if pickup is not required, false if it is

Response Format

{
  "object": [
    {
      "id": 123456789,
      "consignmentIds": [
        123456,
        569836
      ],
      "companyId": 1,
      "carrierReference": null,
      "bookingSuccessful": true,
      "errorMessage": null
    }
  ],
  "errors": null
}

The response includes:

  • id: Unique identifier for the manifest
  • consignmentIds: Consignments included in this manifest
  • carrierReference: Carrier's reference (if provided)
  • bookingSuccessful: Indicates if manifest was successful
  • errorMessage: Contains error details if manifest failed

Examples

Complete Workflow

  1. Group specific consignments:

    POST /apiv2/manifests/groupConsignmentsForManifest
    [123456, 569836]

  2. Review the grouping response and adjust pickup options as needed

  3. Create manifest with adjusted options:

    POST /apiv2/manifests/manifest
    [
{
"consignmentIds": [123456, 569836],
"companyId": 1,
"pickupDateTime": "2021-02-09T01:00:00.000Z",
"palletSpaces": 3,
"pickupClosingTime": "2021-02-09T04:00:00.000Z",
"pickupSpecialInstructions": "Driver Must Be Inducted to be on Site",
"pickupAlreadyBooked": false,
"carrierName": "string"
}
]

Common Errors

  1. "ConsignmentIds are required": The request is missing consignment IDs
  2. "Invalid Company ID": The specified company ID doesn't exist
  3. "Consignment already manifested": Attempting to manifest a consignment that's already been manifested
  4. "Invalid pickup time": The pickup time is in the past or outside carrier operating hours