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. Fill in our Tracking Notification API form to get your unique key. 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 name@email.com
event Event(s) Which events should send out messages. Accepts one or more or:
  • welcomegreet the user with details of this service
  • unwatchedthe user has cancelled (unwatched) this tracking request
  • movedthe package has been scanned at a new location
  • deliveredthe package was successfully delivered
  • failedwe were unable to deliver the package
  • errora bad tracking code is received
  • untrackedtracking code not yet scanned into our system
  • all_eventAll events

Send repeated eventparams 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.

Related information