Tracking Notification API

This API introduces a push capability for monitoring the delivery status of packages using New Zealand Post’s services. This push capability enables messages to be sent to different channel types such as email, webhooks and sms. The system has been designed to allow additional channels to be easily added in the future.

Request

Send an HTTP POST to https://api.nzpost.co.nz/tracking-notification/api/watch with the form parameters listed below. An HTML form is available for easy testing of requests.

Parameter Name Description Required Example
license_key API Key Your license key for the application. Please contact developer@nzpost.co.nz for a license key Yes c4f820f0420a012ea143000c290fbf99
tracking_code Tracking Code The tracking code of the package that will be watched Yes XY123456789NZ
alias Package Alias User friendly name of the package No Contact Lenses
channel Channel Should be one of:
  • email
  • sms
  • webhook
 Yes email
channel_identifier Channel identifier The email address, internationalised mobile phone number, or webhook URL Yes +6421444827
event Event(s) Which events should send out messages. Accepts one or more or:
  • welcome - greet the user with details of this service
  • unwatched - the user has cancelled (unwatched) this tracking request
  • moved - the package has been scanned at a new location
  • delivered - the package was successfully delivered
  • failed - we were unable to deliver the package
  • error - a bad tracking code is received
  • untracked - tracking code not yet scanned into our system
  • all_event - All events
Send repeated event params for multiples. 		Yes moved
template Template You can supplied an alternative template to use for formatting emails and TXT messages No
variable1_key Variable 1 (key) You can supply variables that can be used in the email and txt templates. This is the key.

Any number of variables can be supplied, and should be named as variableX_key and variableX_value. 		No AUCTION_ID
variable1_value Variable 1 (value) This is the matching value for variable1_key (above). No 123456

Responses

The API calls will respond with one of the following HTTP response codes:

200Success - message received
400Bad request - incorrect or missing parameters
401Unauthorised - license key expired or similar
402Premium channel (SMS) was requested, but is not available for license key

If the API returns a 200 code, then the response will also contain a JSON hash populated with additional information. At a minimum, it will contain the tracking_identifier created for this request.

{"tracking_identifier":"0WuD56wGyTeNekdxtUT3"}

In the case of a 40x error, the response will again contain a JSON hash with a “message” value, and optionally further details in a “errors” value. For example, an invalid mobile phone number will give this response:

{"errors":[{"channel_identifier":"should use international phone number format, ie: +6421100100"}], "message":"Validation errors"}

Channels

The following channels are supported:

Email

To use this channel, supply “email” as the channel, and the user’s email address as the channel_identifier. The email body may contain a link to the Cancel Notification path, should the user wish to stop receiving messages.

Text Message

To use this channel, supply “sms” as the channel, and the user’s mobile phone number as the channel_identifier. This channel is considered a premium service, so the owner of the license key needs to be granted access.

Mobile phone numbers are validated. The expected format is the international mobile number format (eg: +64210000000)

An invalid number would result in a 400 (bad request) response code.

WebHook

To use this channel, supply webhook as the channel (learn more), and a URL as the channel_identifier. Messages sent to this channel will result in the following HTTP POST being made (when events occur):

Parameter Name Description Example
tracking_code Tracking code The tracking code of the package XY123456789NZ
cancel_url Cancel URL The URL to call which will cancel monitoring of this package https://api.nzpost.co.nz/tracking-notification/api/cancel?tracking_identifier=123456
tracking_identifier Tracking Identifier The unique identifier for the package in question 0WuD56wGyTeNekdxtUT3
event Event The event that occurred moved
datetime DateTime The ISO formatted timestamp of this event 2011-12-24 23:59
message Event Message Human readable message describing the event Your parcel XY123456789NZ has not been scanned into our system. We will let you know as soon as this happens.
package_alias Package Alias The supplied user friendly name of the package Contact Lenses

The supplied URL may be validated. An invalid URL would result in a 400 (bad request) response code.

Additional behaviour

Resubmissions

If a watch message is resubmitted, then the record in the system will be updated with the supplied values. For example, a second request might supply a new alias, or different events.

When a resubmission occurs, an additional welcome message will not be sent.