Document Create

Allows customers to create a new Document for Transport movements. Required fields are in bold text.

Access

To get access to this API, please fill in the Developer Registration form

Resource URI

Make an HTTP POST request to:

EnvironmentURL 
LIVE

https://api.mainfreight.com/document/1.1/transportdocument?servicetype={servicetype}&region={region}

UAT

https://apitest.mainfreight.com/document/1.1/transportdocument?servicetype={servicetype}&region={region}

Resource Information

TypeValue 
Authentication API Key  
Response Formats JSON  
HTTP Methods POST  
API Version 1.1  

HTTP Headers

You must add the following HTTP Headers to your request:

HeaderDescriptionTypeRequired
Content-Type Request content type. Supported types are "application/json" or "application/xml" string Yes
Authorization

The word " Secret" followed by a space, then your unique Transport API Key

e.g: Secret wdnOId93-VXZECxvVRPQEJZNxPB5XZ...

string Yes
Accept

Result content type. Supported types are "application/json" or "application/xml"

string No

Parameters

You must provide the parameters marked as required:

 

HTTP Request Parameters

HeaderDescriptionTypeRequired
servicetype

Indicates Service Type. Required type is system.

e.g: https://api.mainfreight.com/document/1.1/transportdocument?servicetype=system&region={region}

string Yes
region

Region code, a list of available regions can be found  here

 

string Yes

Request Body

FieldDescriptionTypeLengthRequired
type Document Type. Currently supported types are NZLabel & AUSLabel string 20 Yes
pageSize Document Size. Currently supported sizes are A4 & STOCK_4X6  string 20 Yes
format Document Format. Currently supported formats are IMG & PDF string 5 Yes
shipment Shipment Details object   Yes
housebillNumber A reference that identifies the shipment string 14 Yes
account Account involved in the shipment object   Yes
code Shorthand code to identify the account string 50 Yes
serviceLevel An entity used to express the duration of transportation (available codes can be found  here ) object   Yes
code Shortland code to identify the service level string 50 Yes
transportMode A term used to distinguish between different ways of transportation of goods (available codes can be found  here ) string 50 Yes
freightTerms An entity used to express how the shipment starts and ends (available codes can be found  here ) string 50 Yes
routingType An entity used to express the optimal carrier and mode to ship a shipment (available codes can be found  here ) string 50 Yes
systemOfMeasurement What measurement type the units are specified on the shipment (available codes can be found  here ) string 50  
origin Defines the specifics of the starting point of the shipment object   Yes
sender The owner of the goods that need to be shipped object   Yes
code Shortland code of the sender string 50  
name Full name of the sender string 200  
address Physical address object   Yes
premises Indicates a named location, usually a building or collection of buildings with a common name string 200  
streetNumber Indicates a street number string 20  
address1 Indicates a street name string 200  Yes
address2 Indicates other address identifiers string 200  
residential Indicates whether a residential address boolean    
suburb Indicates the suburb string 500 Yes
postCode Indicates the postcode string 10 Yes (AU) 
town Indicates the town string 50  
city Indicates the city/place string 50 Yes
stateCode Shorthand code to identify the state string 50 Yes (AU)  
countryCode Shorthand code to identify the country (available codes can be found  here ) string 50  
geometry Contains GPS location information object    
location Contains the geocoded latitude, longitude value object    
latitude Latitude value decimal    
longitude Longitude value decimal    
contact Contact point for sender object    
name Full name of the contact string 200  
phone Phone number of the contact string 150  
phoneExtension Phone number extension of the contact string 20  
emailAddress Email address of the contact string 200  
pickupTime Indicates pickup time information for sender object    
toDateTime

The end date time of the pickup time

Required format: yyyy-MM-ddThh:mm:ss

dateTime    
referenceNumber Indicates reference corresponding to the sender string 50  
instructions Indicates an instruction note corresponding to the sender string 200  
destination Defines the specifics of the ending point of the shipment object   Yes
receiver The party who physically receives the goods object   Yes
name Full name of the receiver string 200  
address Physical address object   Yes
premises Indicates a named location, usually a building or collection of buildings with a common name string 200  
streetNumber Indicates a street number string 20  
address1 Indicates a street name string 200 Yes 
address2 Indicates other address identifiers string 200  
residential Indicates whether a residential address boolean    
suburb Indicates the suburb string 50 Yes
town Indicates the postcode string 10  
postCode Indicates the town string

50

Yes (AU)
city Indicates the city/place string 50 Yes
stateCode Shorthand code to identify the state string 50 Yes (AU) 
countryCode Shorthand code to identify the country (available codes can be found  here ) string 50  
geometry Contains GPS location information object    
location Contains the geocoded latitude, longitude value object    
latitude Latitude value decimal    
longitude Longitude value decimal    
contact Contact point for receiver object    
name Full name of the contact string 200  
phone Phone number of the contact string 150  
phoneExtension Phone number extension of the contact string 20  
emailAddress Email address of the contact string 200  
deliveryTime Indicates delivery time information for receiver object    
toDateTime

The end date time of the delivery time

Required format: yyyy-MM-ddThh:mm:ss

dateTime    
referenceNumber Indicates reference corresponding to the receiver string 50  
instructions Indicates an instruction note corresponding to the receiver string 500  
freightDetails Defines information about types and dimensions of goods shipped on this shipment array of objects   Yes
freightDetail Defines a single goods line of all goods on the shipment object   Yes
ssccNumber Serial Shipping Container Code can be used to identify a logistic unit string 50  
packTypeCode Shorthand code identifying the type of goods on the freight line (available codes can be found  here ) string 50 Yes
description Description of the goods on the freight line string 200  
weight Physical weight of the goods on the freight line integer    
volume Physical volume of the goods on the freight line decimal    
length Length of goods on the freight line decimal    
width Width of goods on the freight line decimal    
height Height of goods on the freight line decimal    
stackable Whether the goods on the freight line can be stacked boolean    
freightClass Freight classification code string 50  
foodGrade Whether the freight line satisfy the classification of highest standard of internal cleanliness boolean    
itemLines Further breakdown of freight line (Said to Contain) array of objects    
itemLine One single Item line object    
units Units integer    
packTypeCode Shorthand code identifying the type of goods on the item line (available codes can be found  here ) string 50  
description Description of the goods on the item line string 500  
dangerousGoodsLines Identification of materials or items with hazardous properties array of objects    
dangerousGoodsLine Identifies one line of dangerous goods (DG) object    
class Classification of DG Class string 50  
unNumber A four-digit code used to identify hazardous materials and articles string 50  
variant Identify variant of DG string 50  
properName Identification of proper name of DG string 255  
technicalName Identification of technical name of DG string 255  
commonName Identification of common name of DG string 50  
subRisk Identification of hazards referred to as Subsidiary Risks string 50  
tertiarySubRisk Another breakdown of sub risk string 50  
hazChem hazardous chemicals string 50  
packingGroup Packing group indicates the degree of danger string 50  
flashPoint In Centigrade string 50  
additionalInfo Additional notes associated with DG string 255  
packageType How DG is contained string 50  
packageInstruction Instructions regarding package string 50  
marinePollutant Whether DG is a Marine Pollutant boolean    
acid Whether DG is acidic boolean 50  
alkali Whether DG is alkali boolean 50  
grossWeight Physical weight of the goods on the DG line integer    
volume Physical volume of the goods on the DG line decimal    
units Units of DG line integer    
description Description of the goods on the DG line string    
hireLines Define information about Hire on the shipment array of objects    
hireLine Identifies one line of hire object    
supplier Supplier of hire (available codes can be found  here ) string 50  
palletType Type of pallet (available codes can be found  here ) string 50  
toAccount To account of hire string 50  
fromAccount From account of hire string 50  
transactionType Transaction type of hire (available codes can be found  here ) string 50  
quantity Quantity of pallets of hire integer    
references Reference types that goes against the shipment array of objects    
reference Single reference type line object    
type Shorthand code of reference type string 50  
value Reference value string 50  
dangerousGoodsSignatory Identifier party responsible for signing for DG object    
name Name of person string 200  
title Title of person string 10  
location Location of person string 50  
signature Name on signature string 200  
emergencyPhone Phone number of person string 150  
cover Identifies Cover related information object    
insuredType Type of Insurance (available codes can be found  here ) string 50  
insuredValue Value of Insurance decimal    
declaredValue The amount stated to be the value of cover decimal    

Response Body

FieldDescriptionTypeLength 
type Document Type. Currently supported types are NZLabel & AUSLabel string  20 Yes 
pageSize Document Size. Currently supported sizes are A4 & STOCK_4X6 string 20 Yes
format Document Format. Currently supported formats are IMG & PDF string 5 Yes 
content Document Content. (PDF format will provide a single Base64 string and IMG format may or may not provide a number of Base64 Strings.) string   Yes

Code samples

JSON Example

To Generate a Shipment in JSON format you will need to POST a JSON object:

  • URL
< > grab code
https://api.mainfreight.com/document/1.1/transportdocument?servicetype=system&region=NZ

You are going to send a JSON object similar to this:

  • REQUEST JSON
< > grab code
[
    {
        "type": "NZLabel",
        "pageSize": "A4",
        "format": "PDF",
        "shipment": {
    "account": {
        "code": "{YOUR_ACCOUNT_CODE}"
    },
    "housebillNumber": "{YOUR_HOUSEBILLNUMBER}",
    "serviceLevel": {
        "code": "LCL"
    },
    "transportMode": "ROAD",
    "freightTerms": "D2D",
    "routingType": "LCL",
    "systemOfMeasurement": "Metric",
    "origin": {
        "sender": {
            "code": null,
            "name": "TEST SENDER"
        },
        "address": {
            "premises": null,
            "streetNumber": "42",
            "address1": "O'Rorke Road",
            "address2": null,
            "residential": false,
            "suburb": "Penrose",
            "postCode": "1061",
            "town": null,
            "city": "Auckland",
            "stateCode": null,
            "countryCode":"NZ",
            "geometry": {
                "location": {
                    "latitude": null,
                    "longitude": null
                }
            }
        },
        "contact": {
            "name": "John Doe",
            "phone": "+64 000 000000",
            "phoneExtension": "856",
            "emailAddress": "example@email.com"
        },
        "pickupTime": {
            "toDateTime": "2023-06-18T09:00:00"
        },
        "referenceNumber": "OriginReferenceNumber",
        "instructions": "Origin Instructions"
    },
    "destination": {
        "receiver": {
            "name": "TEST RECEIVER"
        },
        "address": {
            "premises": null,
            "streetNumber": "21",
            "address1": "Hayton Road",
            "address2": null,
            "residential": false,
            "suburb": "Wigram",
            "postCode": "8042",
            "town": null,
            "city": "Christchurch",
            "stateCode": null,
            "countryCode": "NZ",
            "geometry": {
                "location": {
                    "latitude": -43.542202,
                    "longitude": 172.558036
                }
            }
        },
        "contact": {
            "name": "Jim Doe",
			"phone": "+64 000 000000",
            "phoneExtension": "856",
            "emailAddress": "example@email.com"
        },
        "referenceNumber": "DestinationReferenceNumber",
        "instructions": "Destination Instructions"
    },
    "freightDetails": [{
            "ssccNumber": "123456789012345678",
            "customerItemNumber": "TEST1111",
            "packTypeCode": "Bag",
            "description": "These are the goods",
            "weight": 50,
            "volume": 0.5,
            "length": 0.2,
            "width": 0.25,
            "height": 0.15,
            "stackable": true,
            "freightClass": "100",
            "foodGrade": false,
            "itemLines": [{
                    "units": 100,
                    "packTypeCode": "CTN",
                    "description": "These are the detailed descriptions of the goods",
                    "dangerousGoodsLines": [{
                            "class": "3",
                            "unNumber": "1123",
                            "variant": "1",
                            "properName": "Butyl",
                            "technicalName": "Desmoph",
                            "commonName": "Desmoph",
                            "subRisk": "1",
                            "tertiarySubRisk": "2",
                            "hazChem": "3[Y]",
                            "packingGroup": "III",
                            "flashPoint": "52",
                            "additionalInfo": "Do not store in dir",
                            "packageType": "Metal Drum",
                            "packageInstruction": "DangerousGoodsLine PackageInstruction",
                            "marinePollutant": false,
                            "acid": false,
                            "alkali": false,
                            "grossWeight": 10,
                            "volume": 0.2,
                            "units": 2,
                            "description": "DangerousGoodsLine Description"
                        }
                    ]
                }
            ],
            "hireLines": [{
                    "supplier": "C",
                    "palletType": "B",
                    "toAccount": "0000000000",
                    "fromAccount": "111111111",
                    "transactionType": "T",
                    "quantity": 10
                }
            ]
        }
    ],
    "references": [{
            "type": "ReceiverReference",
            "value": "ReceiverReference"
        }, {
            "type": "SenderReference",
            "value": "SenderReference"
        }
    ],
    "dangerousGoodsSignatory": {
        "name": "Example DG",
        "title": "Dispatch",
        "location": "160 Plank Ave",
        "signature": "Example DG",
        "emergencyPhone": "6400000000"
    },
    "cover": {
        "insuredType": "DV",
        "insuredValue": 1000.00,
        "declaredValue": 1000.00
    },
	"notifications": [{
			"eventTypeCode": "StatusUpdate",
			"transport": {
				"code": "Email",
				"destination": "noemail@mainfreight.com"
			},
			"events": [{
					"code": "StatusUpdateShipmentPODReceived"
				}
			]
		}
	]
}


    }    
]


You are going to get another JSON object similar to this:

  • RESPONSE JSON
< > grab code
[
    {
        "type": "NZLabel",
        "pageSize": "A4",
        "format": "PDF",
        "content": [
                    "{YOUR_BASE64_STRING_RESULT}"
        ]
    }
]

NOTE: Content in the panels below this point are not visible on the site unless used by other features e.g. gadgets, OB&E, etc.