Tracking & PODs

Overview

MachShip provides comprehensive tracking capabilities through our RESTful API, allowing you to:

  • Query consignment status and tracking information
  • Generate public tracking page links
  • Retrieve proof of delivery (POD) documents

This guide explains how to effectively use these features in your integration.

Tracking Consignments

Tracking & PODs Diagram

Available Endpoints

MachShip offers several endpoints for retrieving consignment information, each suited for different use cases:

Single Consignment Queries (GET)

  • GET /apiv2/consignments/getConsignment?id=<Integer> - Query by MachShip consignment ID
  • GET /apiv2/consignments/getConsignmentByPendingConsignmentId?id=<Integer> - Query by MachShip pending consignment ID

Multiple Consignment Queries (POST, limit 10 per request)

  • POST /apiv2/consignments/returnConsignments - Query by MachShip consignment IDs
  • POST /apiv2/consignments/returnConsignmentsByCarrierConsignmentId - Query by carrier consignment numbers
  • POST /apiv2/consignments/returnConsignmentsByReference1 - Query by Reference 1 field
  • POST /apiv2/consignments/returnConsignmentsByReference2 - Query by Reference 2 field
  • POST /apiv2/consignments/returnConsignmentsByPendingConsignmentIds - Query consignments by their original pending consignment IDs

Recent Updates Query

  • GET /apiv2/consignments/getRecentlyCreatedOrUpdatedConsignments - Query all consignments with any status change within a time period

The recent updates endpoint accepts these parameters:

  • companyId (Optional) - Filter by company
  • fromDateUtc (Required) - Start of query period
  • toDateUtc (Optional) - End of query period
  • startIndex (Optional) - For pagination, start from this index
  • retrieveSize (Optional) - Number of results (40-200, default 40)
  • carrierId (Optional) - Filter by carrier
  • includeChildCompanies (Optional) - Include child company consignments

Example URL:

GET https://live.machship.com/apiv2/consignments/getRecentlyCreatedOrUpdatedConsignments?companyId=123&fromDateUtc=2023-01-01T00:00:00&toDateUtc=2023-01-02T00:00:00&includeChildCompanies=true

Response Structure

The API response includes a list of consignments and their details:

Status Information

{
.........    
    "carrierConsignmentId": "ABC123456",
    "status": {
      "id": 7,
      "name": "Complete",
      "description": "Complete"
    },
    "manifestId": 12365,
    "bookedDate": "2014-11-13T00:05:00.000",
    "completedDate": "2014-11-18T11:00:00.00",
    "completedDateUtc": "2014-11-18T00:00:00.00",
    "attachmentCount": 1,
    "important": false,
    "carrierName": "VT Freight Express",
    "statusHistory": [
      {
        "consignmentId": 12345,
        "createdByName": "",
        "statusIsPartial": false,
        "consignmentTrackingStatus": {
          "id": 2,
          "name": "Unmanifested",
          "description": "Unmanifested"
        },
        "statusDateLocal": "2014-11-12T17:00:00.000",
        "statusDateUtc": null,
        "carrierStatus": null,
        "carrierStatusDescription": null,
        "createdByUserId": 123398,
        "statusInformation": null
      },
      {
        "consignmentId": 12345,
        "createdByName": "",
        "statusIsPartial": false,
        "consignmentTrackingStatus": {
          "id": 3,
          "name": "Manifested",
          "description": "Manifested"
        },
        "statusDateLocal": "2014-11-13T16:00:00.000",
        "statusDateUtc": null,
        "carrierStatus": null,
        "carrierStatusDescription": null,
        "createdByUserId": 123398,
        "statusInformation": null
      },
      {
        "consignmentId": 12345,
        "createdByName": "",
        "statusIsPartial": false,
        "consignmentTrackingStatus": {
          "id": 5,
          "name": "In Transit",
          "description": "In Transit"
        },
        "statusDateLocal": "2014-11-17T12:00:00.000",
        "statusDateUtc": null,
        "carrierStatus": null,
        "carrierStatusDescription": null,
        "createdByUserId": 123398,
        "statusInformation": null
      },
      {
        "consignmentId": 12345,
        "createdByName": "",
        "statusIsPartial": false,
        "consignmentTrackingStatus": {
          "id": 7,
          "name": "Complete",
          "description": "Complete"
        },
        "statusDateLocal": "2014-11-18T11:00:00.000",
        "statusDateUtc": null,
        "carrierStatus": null,
        "carrierStatusDescription": null,
        "createdByUserId": 123398,
        "statusInformation": null
      }
    ],
.......

Status History

Includes all status events with:

  • Status ID and name
  • Status description
  • Timestamp (local and UTC)
  • Carrier status details
  • User who updated the status (ID 31 indicates carrier system update)

Pricing Information

{
    "consignmentTotal": {
        "sellPricesCleared": false,
        "totalSellPrice": 12.86,
        "totalBaseSellPrice": 10.62,
        "totalTaxSellPrice": 1.17,
        "sellFuelLevyPrice": 1.07,
        "consignmentRouteSellPrice": 10.62,
        "totalSellBeforeTax": 11.68
    }
}

Physical Properties

{
    "totalWeight": 1,
    "totalCubic": 0.75,
    "totalVolume": 0.003,
    "heaviestWeight": 1,
    "totalItemCount": 1
}

Tracking Links

For instructions on how to obtain a tracking link, view our guide here.

Proof of Delivery (PODs)

A POD is a file that is uploaded by a carrier once the goods have been delivered. Some carriers will also upload proof of pick up as well.

These files are file attachments linked to the consignment - and there are two options for retrieval:

  1. Raw POD - the image, PDF or graphic uploaded by the carrier in it's raw form - this can be a variety of formats including jpeg, pdf, tiff and others.
  2. POD PDF - the RAW POD is returned embedded in a PDF template surrounded by details relating to the consignment, including references.

We suggest you try downloading both before deciding which POD format to download and use for your integration.

POD Retrieval

PODs can be retrieved in bulk for multiple consignments, or individually.

Tracking & PODs Diagram

Retrieving PODs individually

The steps for retrieving PODs individually are: 1. Check to see if there is a POD available

Using getConsignment, or another tracking method such as "getRecentlyCreatedOrUpdatedConsignments", confirm the consignment has a status of "COMPLETE" and attachmentCount > 0.

2. List the attachments

POST /apiv2/consignments/getAttachments
BODY
consignmentId = {your consignment id}

This will return a list of attachments on the consignment as follows:

{
  "object": [
    {
      "id": 1212,
      "fileName": "CON1232_POD.jpeg",
      "dateAdded": "2025-01-20T05:48:37.492Z"
    }
  ],
  "errors": [
    {
      "memberNames": [
        "string"
      ],
      "errorMessage": "string",
      "validationType": 0
    }
  ]
}

You can filter these as you see fit, then take the id returned for the next endpoint.

3. Retreive the attachments

You can use either of the following endpoints to return your POD:

  1. Raw POD file - GET /apiv2/attachments/getAttachment?id={attachment id}
  2. POD Embedded PDF - GET /apiv2/attachments/getAttachmentPodReport?id={attachment id}

Retrieving PODs in bulk

Use the following endpoint to retrieve POD documents in their raw format for multiple consignments:

GET https://live.machship.com/apiv2/attachments/getAttachmentsByConsignmentIds?ids=<Integer>

For multiple consignments (recommended limit: 10):

GET https://live.machship.com/apiv2/attachments/getAttachmentsByConsignmentIds?ids=<Integer>&ids=<Integer>

The response will be:

  • Single consignment: Direct image file
  • Multiple images for one consignment: ZIP file containing all images
  • Multiple consignments: ZIP file containing all POD images