How to Manifest via the MachShip API

How to Manifest via the MachShip API

The manifesting of a consignment or a series of consignments in MachShip will finalise that consignment in the MachShip system and send through the consignment data to the transport provider. This data transfer will take place via the preferred integration method that the transport provider has requested with MachShip

Manifesting will group together consignments that are from the same location, with the same carrier and (if the carrier requires) the same service.

When looking to create a manifest via the API, there are two available workflows 

Workflow 1:

  • Having Stored a listing of created consignments and their MachShip id within your system, you would pass these through to the endpoint /apiv2/manifests/groupConsignmentsForManifestMachShip will then collect these together into the suitable requests required for Manifesting

Request Parameters for Group Consignments For Manifest

Every consignment generated in MachShip will be given a unique id known as the consignmentid. The groupConsignmentsForManifest endpoint will accept an array of these consignment IDs and group them all together into their respective manifests. These will be split by Carrier, Service, From Location and Despatch Date. 

[
  ...
123456,
569836
  ...
]

Response for Group Consignments For Manifest

If the request to group consignments is successful, MachShip will return an object with an array of grouped manifests. This will contain:

  • ConsignmentId's - This will be an array of consignment id's that all have the same From Location, Despatch Date, Carrier, Service, Company
  • CompanyId -  This will be the Company Id for the grouped consignments
  • PickupDateTime  - This should be passed through as the collection location's local time i.e if you wish for the collection to take place on the 22/2/2022 at 2:22 pm local time. Pass this through as 2022-02-22T14:22:00
  • PalletSpaces  - Will be an estimated count of pallet spaces based on the number of Pallets, Skids, Crates and Packs
  • PickupClosingTime - This should be passed through as the collection location local time i.e if you wish for the collection to take place on the 22/2/2022 at 5:00 pm local time. Pass this through as 2022-02-22T17:00:00
  • PickupSpecialInstructions - Will defaulted to any pre-stored pickup locations 
  • PickupAlreadyBooked - Will default to false - indicating a pickup will need to be Booked
  • CarrierName - Will show the name of the carrier

    Once the consignments have been grouped for manifest then you will be provided with an array of manifests. 
{
  "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" } ] }

 

Workflow 2:

By Posting through a companyId to /apiv2/manifests/groupAllUnmanifestedConsignmentsForManifestMachShip will then collect together ALL unmanifested consignments against that company into the suitable requests required for Manifesting

Request Parameters for Group All Unmanifested Consignments For Manifest

The groupAllUnmanifestedConsignmentsForManifest endpoint requires a user to provide through a companyId and will then group all unmanifested consignments for that company into Manifests. To find the company Id a user would navigate through to the Companies Grid via the below:

Navigate to the Admin tab and under Companies section, select View Companies


                                                                 mceclip0.png

You will then be directed to the View Companies page, use the general Search text box to locate the company you want to edit.

                              mceclip2.png

Once located, click on the cog button in the right corner of the screen and select Edit Company

                                                        mceclip3.png

The URL will then provide you with the unique Id for this company:

mceclip1.png

"123456"

Response for Group all Unmanifested Consignments For Manifest

If the request to group all unmanifested consignments for manifest is successful, MachShip will return an object with an array of grouped manifests. This will contain:

  • ConsignmentId's - This will be an array of consignemnt id's that all have the same From Location, Despatch Date, Carrier, Service, Company
  • CompanyId -  This will be the Company Id for the grouped consignments
  • PickupDateTime  - Will Default at to the current time. This should be passed through as the collection locations local time i.e if you wish for the collection to take place on the 22/2/2022 at 2:22 pm local time. Pass this through as 2022-02-22T14:22:00
  • PalletSpaces  - Will be an estimated count of pallet spaces based on the number of Pallets, Skids, Crates and Packs
  • PickupClosingTime - Will Default at to the current time. This should be passed through as the collection locations local time i.e if you wish for the collection to take place on the 22/2/2022 at 5:00 pm local time. Pass this through as 2022-02-22T17:00:00
  • PickupSpecialInstructions - Will defaulted to any pre-stored pickup locations 
  • PickupAlreadyBooked - Will default to false - indicating a pickup will need to be Booked
  • CarrierName - Will show the name of the carrier

    Once the consignments have been grouped for manifest then you will be provided with an array of manifests. 
{
  "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" } ] }



Once you have navigated with either of the two workflow mentioned above:

  • You may proceed with passing the details/response gathered through to the /apiv2/manifests/manifest. Here you would advise on if a pickup is required and also the collection time, closing time and the number of pallet spaces required. 

Manifest Request Parameters

The request parameters that are required by the endpoint /apiv2/manifests/manifest are provided within the object array from the response to a request to group all unmanifested consignments or to group select consignments together for manifest. 

As described above these will be:

  • ConsignmentId's - This will be an array of consignemnt id's that all have the same From Location, Despatch Date, Carrier, Service, Company
  • CompanyId -  This will be the Company Id for the grouped consignments
  • PickupDateTime  - Will Default at to the current time. This should be passed through as the collection locations local time i.e if you wish for the collection to take place on the 22/2/2022 at 2:22 pm local time. Pass this through as 2022-02-22T14:22:00
  • PalletSpaces  - Will be an estimated count of pallet spaces based on the number of Pallets, Skids, Crates and Packs
  • PickupClosingTime - Will Default at to the current time. This should be passed through as the collection locations local time i.e if you wish for the collection to take place on the 22/2/2022 at 5:00 pm local time. Pass this through as 2022-02-22T17:00:00
  • PickupSpecialInstructions - Will default to any pre-stored pickup locations 
  • PickupAlreadyBooked - Will default to false - indicating a pickup will need to be Booked
  • CarrierName - This will show the name of the carrier
  •  

You will need to confirm and adjust any of the pre-set data that may have changed. The key fields to look at would be:

  • PickupDateTime  - If a Pickup is required please set this to the local date and time that you wish to have the pickup driver arrive. 
  • PalletSpaces  - As discussed MachShip will estimate these based on a simple calculation of Quantity of Item Type Pallet, Skid, Crate and Pack. Please adjust if you have oversized freight or if there is the ability to allow for multiple items per space. 
  • PickupClosingTime - Set this to be the collection location local date and time that your operations would cease for the day
  • PickupSpecialInstructions - Set this to be any sort of special pickup instructions that a pickup driver may need to know
  • PickupAlreadyBooked -Set this to be "true" if a pickup is not required and "false" if a pickup if required.
[
    {
      "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" }
]

Response for a Manifest Request

If the requests to Manifest consignments if successful then MachShip will return an array of successful manifests. This will contain the following

  • ManifestId's - The unique identifier for that manifest in MachShip
  • ConsignmentId's - This will be an array of consignemnt id's that all have the same From Location, Despatch Date, Carrier, Service, Company
  • CompanyId -  This will be the Company Id for the consignments on that manifest
  • PickupDateTime  - Will Default at to the current time
  • CarrierReference- Will show an identifier should the carrier provide back a reference for that Manifest
  • BookingSuccessful- should the manifest be successful this will show as true if the manifest fails it will be set to false
  • ErrorMessage- if the manifest fails then MachShip will advise of the known reason as an error message
{
"object": [
{
"id": 123456789,
"consignmentIds": [
123456,
569836
],
"companyId": 1,
"carrierReference": null,
"bookingSuccessful": true,
"errorMessage": null
}
],
"errors": null
}
    • Related Articles

    • Machship API Integration Workflow Guide

      The objective of this article is to give you a quick-start guide in working with our API that demostrates common integration workflows, and how that affects which API endpoints you wish to use. API Authentication & Documentation Our API accepts and ...
    • A guide to creating Consignments via the API

      Creating consignments is at the core of MachShip's functionality. Consignments describe everything related to a job that needs to travel including the pick-up location, delivery location and the individual items themselves. On top of this, a ...
    • A guide to creating Dangerous Goods Consignments via the API

      Creating consignments is at the core of MachShip's functionality. Consignments describe everything related to a job that needs to travel including the pick-up location, delivery location and the individual items themselves. On top of this, a ...
    • API introduction and authentication

      Our API documentation is designed to be used as a guide for integrating your system directly into MachShip. This documentation describes the technical details of dealing with MachShip’s API layer, the security requirements and provides links to ...
    • How to Edit Consignments Via The API

      The following article will cover how to edit a consignment via the API. The main use cases for an edit workflow include: Adjusting item weights/dimensions Adding new items Removing items Note: This article will not cover the basics of creating ...