Integration Guide For Carriers
Integration Guide For Carriers

JSON Format

This guide covers the JSON implementation of MachShip’s generic carrier integration format. For detailed field definitions and requirements, see the Generic Data Fields guide.

Overview

The JSON manifest format represents freight consignment data for carrier operations. It contains sender/receiver information, pickup details, and item-level data for shipment processing.

Two Manifest Formats

  • Multi-Consignment Manifest: Multiple consignments in a single JSON file (uses consignments array)
  • Single-Line Manifest: One consignment per JSON file (uses consignment object)

Choose the format that best suits your system’s workflow.

Multi-Consignment Manifest Example

This example shows a complete manifest with three consignments going to different destinations, including various Dangerous Goods scenarios:

{
  "account": "ACMEFRT",
  "payingAccount": "ACMEFRT",
  "despatchDateTime": "2025-11-15",
  "dgsDeclaration": true,
  "pickupRequired": true,
  "pickupAddress": {
    "addressLine1": "142 Manufacturing Drive",
    "addressLine2": "Unit 7",
    "contact": "Sarah Mitchell",
    "email": "dispatch@acmemanufacturing.com.au",
    "name": "ACME Manufacturing Pty Ltd",
    "phone": "03 9876 5432",
    "postcode": "3175",
    "state": "Victoria",
    "stateCode": "VIC",
    "suburb": "DANDENONG SOUTH"
  },
  "pickupDateTime": "2025-11-15T09:30:00",
  "pickupClosingDateTime": "2025-11-15T16:00:00",
  "timeSlot": "9am-12pm",
  "specialInstructions": "Forklift access required. DG consignments present.",
  "consignments": [
    {
      "reference": "ACME0034521",
      "service": "PEXP",
      "extraReferences": {
        "carrierConsignmentReference": "ACME0034521",
        "customerReference": "PO-2025-8847",
        "customerReference2": "INV-98234"
      },
      "toLocation": {
        "addressLine1": "88 Industrial Circuit",
        "contact": "James Wong",
        "email": "receiving@brisbanedistribution.com.au",
        "name": "Brisbane Distribution Centre",
        "phone": "07 3344 7788",
        "postcode": "4178",
        "state": "Queensland",
        "stateCode": "QLD",
        "suburb": "STAPYLTON"
      },
      "items": [
        {
          "height": 120,
          "itemType": "Pallet",
          "length": 120,
          "name": "Industrial Pumps - Model XR500",
          "sku": "PUMP-XR500-A",
          "quantity": 2,
          "weight": 680,
          "width": 100,
          "carrierItemTypeName": "Standard Pallet",
          "carrierItemTypeAbbreviation": "SPAL",
          "Barcode": [
            {"barcodeNumber": "ACME0034521001"},
            {"barcodeNumber": "ACME0034521002"}
          ]
        },
        {
          "consignmentItemDgItems": [
            {
              "unNumber": "1263",
              "packingGroup": "II",
              "containerType": "Drum",
              "aggregateQuantity": 200,
              "isAggregateQuantityWeight": false,
              "numberOfContainers": 4,
              "isMarinePollutant": false,
              "isTemperatureControlled": false,
              "isEmptyDgContainer": false,
              "dgClassType": "3",
              "subDgClassTypes": ["8"],
              "technicalOrChemicalGroupNames": "Epoxy resin mixture",
              "hazchem": "3YE",
              "flashpoint": 23.5,
              "ProperShippingName": "PAINT (including paint, lacquer, enamel, stain, shellac, varnish, polish, liquid filler and liquid lacquer base)"
            }
          ],
          "height": 110,
          "itemType": "Pallet",
          "length": 120,
          "name": "Industrial Paint - Epoxy Coating",
          "sku": "PAINT-EP-200L",
          "quantity": 1,
          "weight": 850,
          "width": 120,
          "Barcode": [{"barcodeNumber": "ACME0034521003"}]
        }
      ],
      "palletTypes": {
        "palletCHEP": 2,
        "palletLOSCAM": 0,
        "palletPLAIN": 0
      },
      "totalWeight": 1530,
      "totalVolume": 3.024,
      "totalCubic": 3.024
    },
    {
      "reference": "ACME0034522",
      "service": "PEXP",
      "extraReferences": {
        "carrierConsignmentReference": "ACME0034522",
        "customerReference": "PO-2025-8849",
        "customerReference2": "INV-98236"
      },
      "toLocation": {
        "addressLine1": "23 Enterprise Way",
        "contact": "Michelle Chen",
        "email": "goods@adelaidehub.com.au",
        "name": "Adelaide Logistics Hub",
        "phone": "08 8123 4567",
        "postcode": "5095",
        "state": "South Australia",
        "stateCode": "SA",
        "suburb": "MAWSON LAKES"
      },
      "specialInstructions": "Deliver to Warehouse B",
      "items": [
        {
          "consignmentItemDgItems": [
            {
              "unNumber": "1950",
              "packingGroup": "N/A",
              "containerType": "Aerosol",
              "aggregateQuantity": 45,
              "isAggregateQuantityWeight": true,
              "numberOfContainers": 120,
              "isMarinePollutant": false,
              "isTemperatureControlled": false,
              "isEmptyDgContainer": false,
              "dgClassType": "2.1",
              "subDgClassTypes": [],
              "hazchem": "2WE",
              "ProperShippingName": "AEROSOLS, flammable"
            }
          ],
          "height": 95,
          "itemType": "Pallet",
          "length": 120,
          "name": "Aerosol Lubricant Spray Cans",
          "sku": "AERO-LUB-500",
          "quantity": 1,
          "weight": 285,
          "width": 100,
          "Barcode": [{"barcodeNumber": "ACME0034522001"}]
        }
      ],
      "totalWeight": 285,
      "totalVolume": 0.84,
      "totalCubic": 0.84
    },
    {
      "reference": "ACME0034523",
      "service": "STD",
      "extraReferences": {
        "carrierConsignmentReference": "ACME0034523",
        "customerReference": "PO-2025-8851"
      },
      "toLocation": {
        "addressLine1": "17 Marriott Road",
        "contact": "Perth Warehouse",
        "name": "Perth Parts Depot",
        "phone": "08 9494 6764",
        "postcode": "6164",
        "state": "Western Australia",
        "stateCode": "WA",
        "suburb": "JANDAKOT"
      },
      "items": [
        {
          "consignmentItemDgItems": [
            {
              "unNumber": "3264",
              "packingGroup": "II",
              "containerType": "IBC",
              "aggregateQuantity": 50,
              "isAggregateQuantityWeight": false,
              "numberOfContainers": 1,
              "isMarinePollutant": true,
              "isTemperatureControlled": false,
              "isEmptyDgContainer": false,
              "dgClassType": "8",
              "subDgClassTypes": ["6.1"],
              "hazchem": "2WE",
              "ProperShippingName": "CORROSIVE LIQUID, ACIDIC, INORGANIC, N.O.S."
            },
            {
              "unNumber": "1005",
              "packingGroup": "N/A",
              "containerType": "Tube",
              "aggregateQuantity": 250,
              "isAggregateQuantityWeight": true,
              "numberOfContainers": 10,
              "isMarinePollutant": false,
              "isTemperatureControlled": false,
              "isEmptyDgContainer": false,
              "dgClassType": "2.3",
              "subDgClassTypes": ["2.1", "8"],
              "hazchem": "2XE",
              "ProperShippingName": "AMMONIA, ANHYDROUS"
            }
          ],
          "height": 140,
          "itemType": "Pallet",
          "length": 120,
          "name": "Chemical Processing Reagents",
          "sku": "CHEM-MIX-A",
          "quantity": 1,
          "weight": 920,
          "width": 100,
          "Barcode": [{"barcodeNumber": "ACME0034523001"}]
        },
        {
          "consignmentItemDgItems": [
            {
              "unNumber": "1325",
              "packingGroup": "III",
              "containerType": "Carton",
              "aggregateQuantity": 80,
              "isAggregateQuantityWeight": true,
              "numberOfContainers": 1,
              "isMarinePollutant": false,
              "isTemperatureControlled": false,
              "isEmptyDgContainer": false,
              "dgClassType": "4.1",
              "subDgClassTypes": [],
              "hazchem": "4W",
              "ProperShippingName": "FLAMMABLE SOLID, ORGANIC, N.O.S."
            }
          ],
          "height": 60,
          "itemType": "Carton",
          "length": 50,
          "name": "Safety Equipment & Materials",
          "sku": "SAFE-KIT-200",
          "quantity": 2,
          "weight": 45,
          "width": 40,
          "Barcode": [
            {"barcodeNumber": "ACME0034523002"},
            {"barcodeNumber": "ACME0034523003"}
          ]
        }
      ],
      "palletTypes": {
        "palletCHEP": 1,
        "palletLOSCAM": 1,
        "palletPLAIN": 0
      },
      "totalWeight": 920,
      "totalVolume": 2.34,
      "totalCubic": 2.34
    }
  ]
}

Multi-Consignment Manifest Structure

This example demonstrates:

  • Manifest Level: Single pickup address (ACME Manufacturing in Dandenong South, VIC), single account (ACMEFRT), single despatch date and pickup window
  • Three Consignments: Different destinations (Brisbane, Adelaide, Perth), different references, different service levels (PEXP, STD)
  • Dangerous Goods Examples:
    • Consignment 1: Class 3 Flammable Liquid with subsidiary Class 8
    • Consignment 2: Class 2.1 Flammable Gas in aerosols with packing group N/A
    • Consignment 3: Multiple DG items on one pallet (Class 8 corrosive + Class 2.3 toxic gas), plus separate cartons with Class 4.1 flammable solid

Single-Line Manifest Example

This format generates individual JSON files for each consignment, useful when consignments need to be managed or tracked separately:

{
  "account": "ACMEFRT",
  "despatchDateTime": "2025-11-15",
  "dgsDeclaration": true,
  "pickupAddress": {
    "addressLine1": "142 Manufacturing Drive",
    "addressLine2": "Unit 7",
    "contact": "Sarah Mitchell",
    "email": "dispatch@acmemanufacturing.com.au",
    "name": "ACME Manufacturing Pty Ltd",
    "phone": "03 9876 5432",
    "postcode": "3175",
    "state": "Victoria",
    "suburb": "DANDENONG SOUTH"
  },
  "pickupClosingDateTime": "2025-11-15T16:00:00",
  "pickupDateTime": "2025-11-15T09:30:00",
  "specialInstructions": "Forklift access required. DG consignment present.",
  "consignment": {
    "reference": "ACME0034521",
    "service": "PEXP",
    "extraReferences": {
      "carrierConsignmentReference": "ACME0034521",
      "customerReference": "PO-2025-8847",
      "customerReference2": "INV-98234"
    },
    "toLocation": {
      "addressLine1": "88 Industrial Circuit",
      "contact": "James Wong",
      "email": "receiving@brisbanedistribution.com.au",
      "name": "Brisbane Distribution Centre",
      "phone": "07 3344 7788",
      "postcode": "4178",
      "state": "Queensland",
      "suburb": "STAPYLTON"
    },
    "specialInstructions": "Handle with care - contains flammable materials",
    "items": [
      {
        "height": 120,
        "itemType": "Pallet",
        "length": 120,
        "name": "Industrial Pumps - Model XR500",
        "sku": "PUMP-XR500-A",
        "quantity": 2,
        "weight": 680,
        "width": 100,
        "Barcode": [
          {"barcodeNumber": "ACME0034521001"},
          {"barcodeNumber": "ACME0034521002"}
        ]
      },
      {
        "consignmentItemDgItems": [
          {
            "unNumber": "1263",
            "packingGroup": "II",
            "containerType": "Drum",
            "aggregateQuantity": 200,
            "isAggregateQuantityWeight": false,
            "numberOfContainers": 4,
            "isMarinePollutant": false,
            "isTemperatureControlled": false,
            "isEmptyDgContainer": false,
            "dgClassType": "3",
            "subDgClassTypes": ["8"],
            "technicalOrChemicalGroupNames": "Epoxy resin mixture",
            "hazchem": "3YE",
            "flashpoint": 23.5,
            "ProperShippingName": "PAINT (including paint, lacquer, enamel, stain, shellac, varnish, polish, liquid filler and liquid lacquer base)"
          }
        ],
        "height": 110,
        "itemType": "Pallet",
        "length": 120,
        "name": "Industrial Paint - Epoxy Coating",
        "sku": "PAINT-EP-200L",
        "quantity": 1,
        "weight": 850,
        "width": 120,
        "Barcode": [{"barcodeNumber": "ACME0034521003"}]
      },
      {
        "consignmentItemDgItems": [
          {
            "unNumber": "1170",
            "packingGroup": "II",
            "containerType": "Bottle",
            "aggregateQuantity": 48,
            "isAggregateQuantityWeight": false,
            "numberOfContainers": 24,
            "isMarinePollutant": false,
            "isTemperatureControlled": false,
            "isEmptyDgContainer": false,
            "dgClassType": "3",
            "subDgClassTypes": [],
            "hazchem": "2YE",
            "flashpoint": 12.0,
            "ProperShippingName": "ETHANOL SOLUTION (Ethyl alcohol solution)"
          }
        ],
        "height": 85,
        "itemType": "Carton",
        "length": 60,
        "name": "Laboratory Grade Ethanol",
        "sku": "ETOH-LAB-2L",
        "quantity": 1,
        "weight": 52,
        "width": 40,
        "Barcode": [{"barcodeNumber": "ACME0034521004"}]
      }
    ],
    "palletTypes": {
      "palletCHEP": 2,
      "palletLOSCAM": 0,
      "palletPLAIN": 0
    },
    "totalWeight": 1582,
    "totalVolume": 3.228,
    "totalCubic": 3.228
  }
}

Key Difference: consignment vs consignments

  • Multi-Consignment: Use "consignments": [...] array
  • Single-Line: Use "consignment": {...} object

JSON Format Notes

Syntax Requirements

  • All property names must be in double quotes
  • String values must use double quotes (not single quotes)
  • Numbers should not be quoted
  • Booleans use lowercase true and false
  • Arrays use square brackets []
  • Objects use curly braces {}
  • No trailing commas allowed

Data Type Examples

  • Strings: "Victoria", "ACME0034521"
  • Numbers: 120, 23.5, 680
  • Integers: 1, 4, 120
  • Booleans: true, false
  • Arrays: ["8"], ["2.1", "8"], []

Common Patterns

Empty Arrays: Use [] for empty arrays (e.g., when no subsidiary hazards exist)

"subDgClassTypes": []

Optional Fields: Omit optional fields entirely or set to null

// Omit optional field
{
  "name": "Test Item",
  "quantity": 1
}

// Or include as null
{
  "name": "Test Item",
  "sku": null,
  "quantity": 1
}

Barcode Quantity Matching: Array length must match quantity value

// Correct: quantity = 2, two barcodes
{
  "quantity": 2,
  "Barcode": [
    {"barcodeNumber": "ABC001"},
    {"barcodeNumber": "ABC002"}
  ]
}

// Incorrect: quantity = 2, one barcode (will be rejected)
{
  "quantity": 2,
  "Barcode": [
    {"barcodeNumber": "ABC001"}
  ]
}

Dangerous Goods Placement Options

JSON format supports dangerous goods data at the item level within the consignmentItemDgItems array. This is the standard and recommended approach, as shown in all examples above.

Item-Level DG (Standard)

Place DG data within each item that contains dangerous goods:

{
  "items": [
    {
      "name": "Paint",
      "quantity": 1,
      "consignmentItemDgItems": [
        {
          "unNumber": "1263",
          "packingGroup": "II",
          "dgClassType": "3",
          ...
        }
      ]
    }
  ]
}

This approach allows:

  • Multiple DG items within a single package
  • Clear association between physical items and their DG properties
  • Item-specific DG declarations
  • Accurate tracking of which items contain dangerous goods

Validation Tips

  • Use a JSON validator to check syntax before sending
  • Verify barcode count matches item quantity
  • Ensure required DG fields are present when consignmentItemDgItems is included
  • Check date/time formats are ISO 8601 compliant
  • Verify all required address fields are present
  • Confirm measurements are in correct units (cm, kg)
  • Include both state (full name) and stateCode (abbreviation) in address objects
  • Set manifest-level dgsDeclaration to true if ANY consignment contains dangerous goods

Related Guides

  • Generic Data Fields: Complete field definitions, requirements, and business rules
  • XML Format: XML implementation of the same data structure
  • CSV Format: CSV implementation of the same data structure
© 2026 MachShip Documentation