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
| Type | Value |
|---|---|
| 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:
| Header | Type | Description |
|---|---|---|
| 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:
| Parameter | Type | Description |
|---|---|---|
| serviceType | string |
Service type used for the document. Supported values include:
|
| reference | string | Document Reference To Search. |
Optional Parameters
You may also provide the following parameters:
| Parameter | Type | Description |
|---|---|---|
| referenceType | string |
Type of reference supplied in the request. Supported values include:
|
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| 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>