XX (Development)

ct.soa-gw.canadapost.ca

XX (Production)

soa-gw.canadapost.ca

{pin number}

the parcel PIN

{dnc number}

the delivery notice card number

YYYY-MM-DD

the mailing from and to dates

{reference number}

the value you specified in either customer-ref-1 or customer-ref-2 fields when you created the shipment.

{customer number}

your customer number

{destination postal code}

the destination Postal Code of the parcel

Accept

application/vnd.cpc.track-v2+xml (Note: */* in place of the header value will return an error)

Authorization

Basic {Base64 encoding of userid:password}

Accept-language

en-CA or fr-CA

Access by PIN

{pin number}

Directly embedded
in URI

The PIN (Parcel Identification Number) assigned by Canada Post on creation of the shipping label and used for tracking purposes.

(12, 13 or 16 characters)

When executing a request by PIN, this is mandatory and is the only parameter necessary.

The {pin number} is embedded into the URI as follows:

XX/vis/track/pin/{pin number}/summary

Access by DNC Number

{dnc number}

Directly embedded
in URI

The Delivery Notice Card (DNC) number – The number on the card left by delivery personnel when no one is home to receive the delivery.

(15 numeric characters)

When executing a request by DNC number, this is mandatory and is the only parameter necessary.

The {dnc number} is embedded into the URI as follows:

XX/vis/track/dnc/{dnc number}/summary.

Access by Reference Parameters

customerNumber=XXXX

Query
parameter
(Optional)

The customerNumber query parameter value can be either:

• The customer number for the organization initiating the shipment, or
• The customer number of the customer on whose behalf the parcel was mailed.

(10 digit numeric)

This is an optional query parameter. If the customerNumber query parameter is not specified, the customer-number of the user that was used to authenticate this request will be used.

If you ship parcels on behalf of other customers and you specify their customer number in the request, only tracking results of parcels which were mailed "on behalf of" that customer (and that match the other query parameter criteria) are returned. 

If you ship parcels on behalf of other customers and you specify your own customer number, you will receive tracking results for any parcels you shipped for yourself, including all parcels you shipped for any other customers (providing it also matches the other query parameter criteria).

referenceNumber=XXXX

Query parameter
(mandatory)

The value assigned to a parcel by the shipper at the time the shipment was created. This value may have been specified in either "customer-ref1" or "customer-ref2" fields of the submitted parcel.

(up to 35 characters)

When executing a request by reference parameter, the referenceNumber query parameter is mandatory and must be included.

The Get Tracking Summary service only returns tracking results for parcels that match the referenceNumber query parameter value.

destinationPostalCode=XXXX

Query
parameter
(Optional)

The destination Postal Code, zip code or postal identifier for the parcel in its destination country. This is the value that would be supplied in the element "postal-zip-code" in a create shipment request.

Format is any of the following:

• 6-character alphanumeric for Canada
  (A9A9A9)
• 5-digit or 5-4 digit numeric code for U.S.A.
  (99999 or 99999-9999)
• Character String – up to 14 characters (free format) for other countries.

The destinationPostalCode query parameter is optional.

When present, the Get Tracking Summary service only returns tracking results for parcels that match the destinationPostalCode query parameter value.

Note: For zip codes in the form 99999-9999, only the first 5 digits are used in the matching.

mailingDateFrom=
YYYY-MM-DD

Query
parameter
(Mandatory)

The combination of mailingDateFrom and mailingDateTo query parameters defines a range of dates for when the parcel(s) in question were shipped. 

Format is: yyyy-mm-dd

The mailingDateFrom value cannot be earlier than two calendar months from the current date.

When executing a request by reference parameter, both the mailingDateFrom and mailingDateTo query parameters are mandatory and must be included.

The Get Tracking Summary service only returns tracking results for parcels that were shipped within the range of dates specified by the mailingDateFrom and mailingDateTo query parameters.

mailingDateTo=
YYYY-MM-DD

Query
parameter
(Mandatory)

tracking-summary

The top level of the XML structure.

pin-summary

Contains the response for the specified PIN.

Contained within <tracking-summary> element.

pin

(Numeric 15 digits)

The Parcel Identification Number (PIN) that can be used by the client for calling tracking services.

origin-postal-id

The first 3 digits of the origin Postal Code for Canadian destinations.

^[ABCEGHJKLMNPRSTVXY]{1}\d{1}[A-Z]{1}

For an inbound international parcel, this field is blank or contains the postal identifier of the country of origin.

destination-postal-id

The first 3 digits of the destination Postal Code for parcels to be delivered in Canada.

^[ABCEGHJKLMNPRSTVXY]{1}\d{1}[A-Z]{1}

For international parcels this is the postal identifier of the destination country (e.g. ZIP code for parcels with a U.S. destination) or an identifier of the destination country.

destination-province

The 2-digit province code for the destination.

"postal designators" - abbreviations used by Canada Post  ISO 3166-2  for Canadian bound parcels.

Parcels bound for international destinations have the postal identifier of the destination country (e.g. ZIP code for parcels with a U.S. destination).

service-name

Canada Post service name in the language specified. The service-name will default to English if language is not specified.

For inbound international parcels, service name is empty or contains the service name from its shipper of origin if available.

mailed-on-date

yyyy-mm-dd

The date of the first event for the item. If the item has been mailed from an international location this date may be blank.

expected-delivery-date

yyyy-mm-dd

The date the item is expected to reach the destination address for addresses in Canada.

If the item has been mailed from or to an international location this date may be blank.

actual-delivery-date

yyyy-mm-dd

The date the item was delivered.

Blank if not delivered or if delivery information from an international organization for an international shipment has not been provided.

delivery-option-completed-ind

0 – at least one option was not satisfied

1 – all options were satisfied

2 – no options were found

event-date-time

yyyymmdd:hhmmss

The time stamp of the most recent significant event.

event-description

A brief description of the event

attempted-date

yyyy-mm-dd - The date that a delivery was attempted.

For shipments into or within Canada this will indicate that an unsuccessful attempt to deliver the parcel was made on the specified date.

customer-ref-1

(Character string up to 35 characters)

The value supplied by the shipper as customer-ref-1when the shipment was first created with Canada Post. French character set is supported through this interface.

customer-ref-2

(Character string up to 35 characters)

The value supplied by the shipper as customer-ref-2 when the shipment was first created with Canada Post. French character set is supported through this interface.

return-pin

If a return label (PIN) was printed at the same time the shipment was created and the shipment is being returned, the return PIN is displayed.

event-type

The value in this field will indicate what type of event is represented for this item.

event-location

For an event representing a scan or delivery, this value will indicate the location where the event took place.

signatory-name

If the event presented as the last most significant event is a signature, the text of this field contains the signatory name.

Note: For enhanced privacy and security, the signatory name will now always be empty. It may be removed in a future release.

code

 ID associated with the failure of a query.

description

Text message associated with an id.

002

Duplicate Pin

Received on PIN or DNC searches where duplicate PINs have been encountered.

004

No Pin History

No tracking results were found based on the parameters provided. Check your parameters and the order of the from and to dates.

006

Reference number, mailed from date, mailed to date and destination Postal Code are required fields for a reference number search.

Received only on reference number searches.

008

Invalid Date

For summary reference searches, dates greater than 2 months old will result in a return of this error.