• Home
  • Contacts
  • On The Go
  • Track
  • Settings
  • Search

Status API - References/Events

Returns an array of document references with a list of all the events that had happened so far.

In addition to all the details from the References method it also provides events history and the details of who signed for the delivery.

Access

To access to Mainfreight APIs, you have to Register

Resource URI

Make an HTTP GET request to:

https://api.mainfreight.com/Status/1.0/References/Events?serviceType={add service type}&reference={add reference}&referenceType={optional value, relates to service type}

Resource Information

TypeValue
Authentication API Key
Response Formats JSON / XML
HTTP Methods GET
API Version 1.0

HTTP Headers

You must add the following HTTP Headers to your request:

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

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

e.g: Secret wdnOId93-VXZECxvVRPQEJZNxPB5XZ...

RequestedBy string Please provide your application name.

Parameters

You must provide the following parameters:

ParameterTypeDescription
serviceType string

Service type used for the document. Supported values include:

  1. Transport
  2. TransportNZ
  3. TransportAU
  4. TransportUS
  5. TransportEU
  6. Logistics
  7. LogisticsAU
  8. LogisticsNZ
  9. LogisticsUS
  10. LogisticsEU
  11. Containers
  12. ContainersNZ
  13. ContainersAU
  14. AirAndOcean
reference string Document Reference To Search.

Optional Parameters

You may also provide the following parameters:

ParameterTypeDescription
referenceType string

Type of reference supplied in the request. Supported values include:

  1. ConsignmentNumber
  2. HousebillNumber
  3. OutboundReference
  4. InboundReference
  5. ShipmentNumber
  6. Reference
  7. ContainerNumber
  8. CustomerReference

Response Parameters

ParameterTypeDescription
ourReference string System reference for the shipment.
yourReference string Tracking reference for the shipment.
serviceType string Service used for delivery.
trackingURL string URL to track the shipment.
signedBy string Represents the name of the person who has signed the delivery.
relatedItems Array List of items related with the document (PODs, other documents, etc.)
type string Related item type.
value string Related item value.
events Array List of all the statuses the document has been through.
sequence int Order when this event happened
eventDateTime dateTime Date when the event happened.
groupingLevel1Code string A high level term to describe the code (publicly available on the website).
groupingLevel2Code string A more detailed term to describe the code (publicly available on the website).
code string

Event status' system name. This is an immutable value.

A full list of response codes can be found here
displayName string Event status' description
location string Description field containing location or journey of the shipment.
isEstimate bool Represents if the status is an estimated status or real status.

Code samples

JSON Example

To list all available anonymous notifications for a particular document you have to post a json similar to this (notice that no session secret is used):

  • URL
< > grab code
https://api.mainfreight.com/status/1.0/References/Events?servicetype=Transport&reference=ABC300000999

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

  • JSON
< > grab code
[
    {
        "ourReference": "ABC900000999",
        "yourReference": "ABC900000999",
        "serviceType": "Transport",
        "trackingUrl": "https://www.mainfreight.com/track/NZ/ABC900000999",
        "relatedItems": [
			{
			"type": "ProofOfDelivery",
			"value": "http://docs.mainfreight.com/DownloadHandler.ashx?VnohipduDcbWKcxVrWONiZvHnT302oUO2GLn93Zp8GLYFL3u__eAUJtQIGewaOZfvaSKOO0SKOOKf-IcUectXgDj3xMNccwX6JbDcAm9Aptr_unKhRw2" 
			}
		],
        "signedBy": "Jane Doe",
        "events": [
            {
                "sequence": 0,
                "eventDateTime": "2015-12-04T16:15:13",
                "groupLevel1Code": "PickedUp",
"groupLevel2Code": "PickedUp",
"code": "PickUp", "displayName": "Picked Up", "location": "OTAHUHU, AUCKLAND", "isEstimate": false }, { "sequence": 1, "eventDateTime": "2015-12-04T23:28:32.48", "groupLevel1Code": "InTransit",
"groupLevel2Code": "InTransit",
"code": "InTransit", "displayName": "In Transit", "location": "AUCKLAND to NAPIER", "isEstimate": false }, { "sequence": 2, "eventDateTime": "2015-12-07T00:00:00", "groupLevel1Code": "InTransit",
"groupLevel2Code": "OutForDelivery",
"code": "OutForDelivery", "displayName": "On Delivery Vehicle", "location": "NAPIER", "isEstimate": false }, { "sequence": 3, "eventDateTime": "2015-12-07T02:36:44", "groupLevel1Code": "InTransit",
"groupLevel2Code": "AtDeliverySite",
"code": "AtDeliverySite", "displayName": "At Delivery Depot", "location": "NAPIER", "isEstimate": false }, { "sequence": 4, "eventDateTime": "2015-12-07T11:23:13", "groupLevel1Code": "Delivered",
"groupLevel2Code": "Delivered",
"code": "Delivered", "displayName": "Delivered", "location": "WAIPUKURAU", "isEstimate": false } ] } ]
XML Example

To list all available anonymous notifications for a particular document you have to post a XML similar to this (notice that no session secret is used):

  • XML
< > grab code
https://api.mainfreight.com/status/1.0/References/Events?servicetype=Transport&reference=ABC300000999

You are going to get another XML document similar to this:

  • XML
< > grab code
	
<references xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <reference>
        <ourReference>ABC900000999</ourReference>
        <yourReference>ABC900000999</yourReference>
        <serviceType>Transport</serviceType>
        <trackingUrl>https://www.mainfreight.com/track/NZ/ABC900000999</trackingUrl>
        <relatedItems>
            <relatedItem>
                <type>ProofOfDelivery</type>
                <value>http://docs.mainfreight.com/DownloadHandler.ashx?VnohipduDcbWKcxVrWONiZvHnT302oUO2GLn93Zp8GLYFL3u__eAUJtQIGewaOZfvaSKOO0SKOOKf-IcUectXgDj3xMNccwX6JbDcAm9Aptr_unKhRw2</value>
            </relatedItem>
        </relatedItems>
        <signedBy>Jane Doe</signedBy>
        <events>
            <event>
                <sequence>0</sequence>
                <eventDateTime>2015-12-04T16:15:13</eventDateTime>
                <groupLevel1Code>PickedUp</groupLevel1Code>
<groupLevel2Code>PickedUp</groupLevel2Code>
<code>PickUp</code> <displayName>Picked Up</displayName> <location>OTAHUHU, AUCKLAND</location> <isEstimate>false</isEstimate> </event> <event> <sequence>1</sequence> <eventDateTime>2015-12-04T23:28:32.48</eventDateTime> <groupLevel1Code>InTransit</groupLevel1Code>
<groupLevel2Code>InTransit</groupLevel2Code>
<code>InTransit</code> <displayName>In Transit</displayName> <location>AUCKLAND to NAPIER</location> <isEstimate>false</isEstimate> </event> <event> <sequence>2</sequence> <eventDateTime>2015-12-07T00:00:00</eventDateTime> <groupLevel1Code>InTransit</groupLevel1Code>
<groupLevel2Code>OutForDelivery</groupLevel2Code>
<code>OutForDelivery</code> <displayName>On Delivery Vehicle</displayName> <location>NAPIER</location> <isEstimate>false</isEstimate> </event> <event> <sequence>3</sequence> <eventDateTime>2015-12-07T02:36:44</eventDateTime> <groupLevel1Code>InTransit</groupLevel1Code>
<groupLevel2Code>AtDeliverySite</groupLevel2Code>
<code>AtDeliverySite</code> <displayName>At Delivery Depot</displayName> <location>NAPIER</location> <isEstimate>false</isEstimate> </event> <event> <sequence>4</sequence> <eventDateTime>2015-12-07T11:23:13</eventDateTime> <groupLevel1Code>Delivered</groupLevel1Code>
<groupLevel2Code>Delivered</groupLevel2Code>
<code>Delivered</code> <displayName>Delivered</displayName> <location>WAIPUKURAU</location> <isEstimate>false</isEstimate> </event> </events> </reference> </references>

 

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.