Watch method

This API method monitors the delivery status of packages using New Zealand Post’s services.

How the watch method works

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

Parameters for the API request

Required parameters

Parameter	Name	Description	Example
`license_key`	API Key	Your license key for the application.	c4f820f0420a012e a143000c290fbf99
`tracking_code`	Tracking Code	The tracking code of the package that will be watched	XY123456789NZ
`channel`	Channel	Should be one of: email webhook	email
`channel_identifier`	Channel identifier	The email address, internationalised mobile phone number, or webhook URL	[email protected]
`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.	moved

Optional parameters

Parameter	Name	Description	Example
`alias`	Package Alias	User friendly name of the package	Contact Lenses
`template`	Template	You can supplied an alternative template to use for formatting emails and TXT messages
`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.	AUCTION_ID
`variable1_value`	Variable 1 (value)	This is the matching value for variable1_key (above).	123456

API responses

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

`200`	Success - message received
`400`	Bad request - incorrect or missing parameters
`401`	Unauthorised - license key expired or similar
`402`	Premium 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.

WebHook

To use this channel, supply webhookas the channel, 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	http://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.