ParcelTrack API

(0 reviews)

Track a Parcel

Resource URL

UAT:

https://api.uat.nzpost.co.nz/parceltrack/3.0/parcels/

Production:

https://api.nzpost.co.nz/parceltrack/3.0/parcels/

Resource Description

Query to return tracking information for a specific tracking reference.

Resource Information

AttributeDetail
Response FormatJSON
Requires AuthenticationYes
Rate Limited15 calls per second. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out.

Request Message Fields

FieldDescriptionMandExample
tracking_referenceThe unique parcel identifierYesJP100000271NZ

Sample Request

https://api.nzpost.co.nz/parceltrack/3.0/parcels/JP100000271NZ

Response Parameters

Field NameDescriptionMandExample
successReturns if request is successfulYesTrue
resultsJSON object containing the parcel and event detailNoJSON object

Results Response Elements

Field NameDescriptionMandExample
tracking_referenceTracking Number returnedYesJP100000271NZ
message_idUnique identifier for the messageYes46384aa1-54ae-4097-9f59-b321a80e7c0e
message_datetimeDate and time stamp on the messageYes2015-10-08T12:12:54.0000000Z
serviceDelivery service if knownNoOvernight
carrierCarrier code for the parcelYesCourierPost
tracking_eventsThis may be present when the success flag is true. This may be absent if the parcel has no associated scan events at the time of the request or the success flag is false.NoSee Tracking Events Response Elements

Tracking Events Response Elements

ElementDescriptionMandExample
tracking_referenceTracking Number returnedYes00393311680005810444
event_edifact_codeEDIFACT code for the parcel delivery stepYes13
sourceSource system where event occurred. Valid systems are: CME, Navigator, IPS, ParcelStore, PSGNoCME
seqrefNZ Post internal system reference numberNo2631897613
status_descriptionBrief description the eventString"Out for Delivery"
event_descriptionDetailed description of the eventString"Your item is currently with our courier for delivery."
event_datetimeThis is the time the courier recorded the scan or event. This is the time you should display to your customersDatetime2015-02-04T15:17:03
signed_byIf the item was signature required then the NAME of the signer is shown hereStringSee Signed By Response Elements

Signed By Response Elements

ElementDescriptionValueExample
nameFull name of the person providing the signature.Yes if signature requiredLee Child
signatureString representation of binary data.Noec608f40-2a8b-11e5...

Scan Reason Response Elements

ElementDescriptionValueExample
reason_codeNumber indicating reason for scan typeMand if scan response present2
reason_comment1Description corresponding to reason_codeMand if scan response presentRuralPost

Error Response Elements

Field NameDescriptionMandExample
successReturns if request is successfulYesTrue
errorsError object with error detailsY if success =falseSee Error Object Parameters below
message_idThe unique message identifierYesec608f40-2a8b-11e5-a9c0-025c481d35ef

Error Object Parameters

Field NameDescriptionExample
codeError code where first 3 digits are http status code, last three digits identify error type400002
messageDescription of error codeInvalid Parameter(s)
detailsDescription of specific errorUnauthorised access, please contact administrator

HTTP Status Codes

Note that some error messages are customised for the request, i.e. error code 400 usually will describe what is wrong with the request

CodeMessage
200Success
400Bad request
401Unauthorized
403Forbidden
409Invalid request
500System unavailable

Error Codes

CodeMessage
200001Partial results returned, not all system(s) have responded
200002All sources responded, data may be incomplete
400001Parameter(s) missing
400002Invalid parameter(s)
400003Non mutually exclusive parameters detected
401001Unauthorised access, please contact administrator
500001General Exception
500002System(s) offline

Sample Response

Sample:


{
    "success":true,
    "results":{
        "tracking_reference":"00393311680005810444",
        "message_id":"46384aa1-54ae-4097-9f59-b321a80e7c0e",
        "message_datetime":"2015-10-08T12:12:54.0000000Z",
        "service":"",
        "carrier":"",
        "tracking_events":[
            {
                "tracking_reference":"00393311680005810444",
                "event_edifact_code":"13",
                "source":"CME",
                "seqref":"2631897613",
                "status_description":"Acceptance",
                "event_description":"Your item was picked up by our courier based at Penrose.",
                "event_datetime":"2015-06-24T10:05:13",
                "signed_by":{
                    "name":"",
                    "signature":""
                }
            },
            {
                "tracking_reference":"00393311680005810444",
                "event_edifact_code":"580",
                "source":"CME",
                "seqref":"2632081694",
                "status_description":"Sort To",
                "event_description":"Item has been sorted to a location in the depot",
                "event_datetime":"2015-06-24T11:06:07",
                "signed_by":{
                    "name":"",
                    "signature":""
                }
            },
            {
                "tracking_reference":"00393311680005810444",
                "event_edifact_code":"567",
                "source":"CME",
                "seqref":"2632113942",
                "status_description":"Security",
                "event_description":"Item was identified as high value.",
                "event_datetime":"2015-06-24T11:55:02",
                "signed_by":{
                    "name":"",
                    "signature":""
                }
            },
            {
                "tracking_reference":"00393311680005810444",
                "event_edifact_code":"32",
                "source":"CME",
                "seqref":"2632175995",
                "status_description":"Out for Delivery",
                "event_description":"Your item was processed for delivery.",
                "event_datetime":"2015-06-24T13:25:40",
                "signed_by":{
                    "name":"",
                    "signature":""
                }
            },
            {
                "tracking_reference":"00393311680005810444",
                "event_edifact_code":"22",
                "source":"CME",
                "seqref":"2632230597",
                "status_description":"Delivery",
                "event_description":"Your item was delivered by our courier based at Sunnynook -Auckland. Thank you for using CourierPost",
                "event_datetime":"2015-06-24T14:19:00",
                "signed_by":{
                    "name":"EHMOE TABILI",
                    "signature":"/zwxQS1EK0YpSChMJU4jMUQvRS1IKkonTCROIVAeUxtUGVYWWBNZEFsOWxBZElcVVRdUGlEeTyJNJUspSS1HMUU1RDhDO0E9QEBAQj9DQUFDPkU7RzhJNko3SDpGPEU/Q0JBRUBIPks8TjtSOVQ3VzZZNls1XTVfNV43YDdjNmgzajNsMm8xcTBzMHYveC94MXczdjV5Nns2fTaANoI4hDiGN4g2ijWMNI8zkjKWMJouniyjKqgorSayJLciuyDAH8Qexx3KHcwdyx/IIcUiwCS7JrUoryqoLKAumDCRMok0gTV6N3I3bDhmOGE4XTdZN1c2VTRWMlgyWzFeMWEyZTNpNWw3cDl0PHc+ekF9RH9GgkmDS4ROhVCHUohUiVM="
                }
            }
        ]
    }
}

Reviews