How to Manifest via the MachShip API – Machship

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/groupConsignmentsForManifest. MachShip 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/groupAllUnmanifestedConsignmentsForManifest. MachShip 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

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

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

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

"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