Tracking

Code Samples for Tracking: Java (.zip) | PHP (.zip) | C# (.zip)

Get Tracking Details – SOAP

Summary

Name: Get Tracking Details
Reason to Call: To get all tracking events for a single parcel
Input: PIN/DNC Number
Output: Basic parcel information, dates, location and status for each event. Summary parcel information.
Error Examples: no PIN History
Possible Prior Calls: Get Tracking Summary
Possible Next Calls: Get Signature Image, Get Delivery Confirmation Certificate
Version history: Release notes

Call Details

WSDL: track.wsdl
Endpoint (Development): https://ct.soa-gw.canadapost.ca/vis/soap/track
Endpoint (Production): https://soa-gw.canadapost.ca/vis/soap/track
Namespace: http://www.canadapost.ca/ws/soap/track
Operation: GetTrackingDetails

SOAP Body

This section describes the XML input elements to this service. For the hierarchical structure, see the XML diagram.

Get Tracking Details – Request Elements
Element Name Type Required / Optional Description

get-tracking-detail-request

complex

required

The top level XML element for the request input information.

locale

simple

optional

Indicates your language preference for receiving error messages.
EN = English
FR = French
If no value is provided, the default language is English.

pin

simple

conditionally required

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.

dnc

simple

conditionally required

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.

Request – XML Diagram

Get Tracking Details – Structure of the XML Request

Get Tracking Details – Structure of the XML Request

Response Details

Response – Elements

The following table describes the XML elements in the response to Get Tracking Details. For the hierarchy of the response, see the
XML diagram.

Get Tracking Details – Response Elements
Element Name Type Description

get-tracking-detail-response

complex

The top level XML element for the response information.
It will either contain the results of a successful completion or the error message structure.

pin-detail

complex

The XML structure containing the results of a successful completion of this service.

pin

simple

The PIN, which can be used for other tracking calls

active-exists

simple

true |false

True indicates that the tracking information is contained in the active data repository.

archive-exists

simple

true |false

True indicates that the tracking information is contained in the archive data repository.

changed-expected-date

simple

yyyy-mm-dd

Indicates a new expected delivery date.

destination-postal-id

simple

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

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

expected-delivery-date

simple

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.

changed-expected-delivery-reason

simple

Text description of reason for change to expected delivery date.

mailed-by-customer-number

simple

Customer number of the mailing customer.

mailed-on-behalf-of-customer-number

simple

Customer number of the mailed-on-behalf-of customer if applicable.

original-pin

simple

In the situation where a parcel is being returned and the original parcel was created with an anticipated return, this field will contain the original PIN when the return PIN is queried.

service-name

simple

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

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

service-name-2

simple

Canada Post service name in the other Canadian official language. For inbound international parcels, service name is empty or contains the service name from its shipper of origin.

customer-ref-1

simple

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

customer-ref-2

simple

The value supplied by the shipper as customer reference 2 when the shipment was first created with Canada Post.

Special characters should be avoided when entering customer reference numbers.

return-pin

simple

In the situation where a parcel is being sent with an anticipated return, this field will contain the return PIN when the original PIN is queried.

signature-image-exists

simple

true | false

True indicates that Get Signature Image will return a signature image. If false, there is no need to call Get Signature Image because it will return “not found”.

suppress-signature

simple

true | false

Indicates whether a signature image collected by Canada Post for domestic parcels has been requested to be suppressed for viewing by the recipient of a parcel.

delivery-options

complex

The set of delivery options requested for this parcel.

delivery-option

simple

The string representing the delivery-option.

delivery-option-description

simple

The description of the delivery option.

cod-remit-info

complex

Information associating a COD parcel with the remittance tracking event or vice versa.

pin

simple

This instance of the PIN specifies the PIN of the COD remittance or the original parcel depending on the value of type.

type

simple

Has the value COD_PIN or REMIT_PIN and indicates what PIN is contained in the PIN value immediately above.

significant-events

complex

The list of events associated with this parcel.

occurrence

complex

The parent element of one set of significant event details.

event-identifier

simple

Event identifier used to identify event types.

event-date

simple

yyyy-mm-dd - Date of a tracking event

event-time

simple

hh:mm:ss - Time of a tracking event

event-time-zone

simple

Time zone associated with an event. May not be populated for international tracking events.

event-description

simple

A brief description of the event.

signatory-name

simple

If the event presented is a signature capture event, the text of this field will represent the name of the signature.

event-site

simple

Site information provided by the parcel handler.

event-province

simple

For domestic events, this contains the province that the event occurred in.

event-retail-location-id

simple

Contains the office-id where a parcel is being/was retained.

event-retail-name

simple

Retail name of the location where a parcel is/was held.

Response – XML Diagram

Response – Possible Error Responses

The response to error conditions for this web service follows the standard SOAP error response approach used for all Canada Post web services. For more information, see SOAP Fundamentals of Canada Post Web Services.

Possible error messages for this service include the following:

Code Description

004

No PIN History

002

Duplicate PIN

Examples

Sample SOAP XML – PIN Detail Request

<get-tracking-detail-request>
<locale>EN</locale>
<pin>1371134583769923</pin>
</get-tracking-detail-request>

Sample SOAP XML – PIN Detail Response

<get-tracking-detail-response>
<tracking-detail>
<pin>1111111583769923</pin>
<active-exists>1</active-exists>
<archive-exists></archive-exists>
<changed-expected-date>2011-02-11</changed-expected-date>
<destination-postal-id>G1K4M7</destination-postal-id>
<expected-delivery-date>2011-02-01</expected-delivery-date>
<changed-expected-delivery-reason>Customer addressing error found; attempting to correct</changed-expected-delivery-reason>
<mailed-by-customer-number>0001111111</mailed-by-customer-number>
<mailed-on-behalf-of-customer-number>0001111111</mailed-on-behalf-of-customer-number>
<original-pin></original-pin>
<service-name>Xpresspost</service-name>
<service-name-2>Xpresspost</service-name-2>
<customer-ref-1>555-5555</customer-ref-1>
<customer-ref-2></customer-ref-2>
<return-pin></return-pin>
<signature-image-exists>true</signature-image-exists>
<suppress-signature>false</suppress-signature>
<delivery-options>
<item>
<delivery-option></delivery-option>
<delivery-option-description></delivery-option-description>
</item>
<item>
<delivery-option>CH_SGN_OPTION</delivery-option>
<delivery-option-description>Signature Required</delivery-option-description>
</item>
</delivery-options>
<significant-events>
<occurrence>
<event-identifier>1496</event-identifier>
<event-date>2011-02-03</event-date>
<event-time>11:59:59</event-time>
<event-time-zone>EST</event-time-zone>
<event-description>Item successfully delivered</event-description>
<signatory-name></signatory-name>
<event-site>SAINTE-FOY</event-site>
<event-province>QC</event-province>
<event-retail-location-id></event-retail-location-id>
<event-retail-name></event-retail-name>
</occurrence>
<occurrence>
<event-identifier>20</event-identifier>
<event-date>2011-02-03</event-date>
<event-time>11:59:59</event-time>
<event-time-zone>EST</event-time-zone>
<event-description>Signature image recorded for Online viewing</event-description>
<signatory-name>HETU</signatory-name>
<event-site>SAINTE-FOY</event-site>
<event-province>QC</event-province>
<event-retail-location-id></event-retail-location-id>
<event-retail-name></event-retail-name>
</occurrence>
<occurrence>
<event-identifier>0174</event-identifier>
<event-date>2011-02-03</event-date>
<event-time>08:27:43</event-time>
<event-time-zone>EST</event-time-zone>
<event-description>Item out for delivery</event-description>
<signatory-name></signatory-name>
<event-site>SAINTE-FOY</event-site>
<event-province>QC</event-province>
<event-retail-location-id></event-retail-location-id>
<event-retail-name></event-retail-name>
</occurrence>
<occurrence>
<event-identifier>0100</event-identifier>
<event-date>2011-02-02</event-date>
<event-time>14:45:48</event-time>
<event-time-zone>EST</event-time-zone>
<event-description>Item processed at postal facility</event-description>
<signatory-name></signatory-name>
<event-site>QUEBEC</event-site>
<event-province>QC</event-province>
<event-retail-location-id></event-retail-location-id>
<event-retail-name></event-retail-name>
</occurrence>
<occurrence>
<event-identifier>0173</event-identifier>
<event-date>2011-02-02</event-date>
<event-time>06:19:57</event-time>
<event-time-zone>EST</event-time-zone>
<event-description>Customer addressing error found; attempting to correct. Possible delay</event-description>
<signatory-name></signatory-name>
<event-site>QUEBEC</event-site>
<event-province>QC</event-province>
<event-retail-location-id></event-retail-location-id>
<event-retail-name></event-retail-name>
</occurrence>
<occurrence>
<event-identifier>1496</event-identifier>
<event-date>2011-02-01</event-date>
<event-time>07:59:52</event-time>
<event-time-zone>EST</event-time-zone>
<event-description>Item successfully delivered</event-description>
<signatory-name></signatory-name>
<event-site>QUEBEC</event-site>
<event-province>QC</event-province>
<event-retail-location-id></event-retail-location-id>
<event-retail-name></event-retail-name>
</occurrence>
<occurrence>
<event-identifier>20</event-identifier>
<event-date>2011-02-01</event-date>
<event-time>07:59:52</event-time>
<event-time-zone>EST</event-time-zone>
<event-description>Signature image recorded for Online viewing</event-description>
<signatory-name>R GREGOIRE</signatory-name>
<event-site>QUEBEC</event-site>
<event-province>QC</event-province>
<event-retail-location-id></event-retail-location-id>
<event-retail-name></event-retail-name>
</occurrence>
<occurrence>
<event-identifier>0500</event-identifier>
<event-date>2011-02-01</event-date>
<event-time>07:51:23</event-time>
<event-time-zone>EST</event-time-zone>
<event-description>Out for delivery</event-description>
<signatory-name></signatory-name>
<event-site>QUEBEC</event-site>
<event-province>QC</event-province>
<event-retail-location-id></event-retail-location-id>
<event-retail-name></event-retail-name>
</occurrence>
<occurrence>
<event-identifier>2300</event-identifier>
<event-date>2011-01-31</event-date>
<event-time>17:06:02</event-time>
<event-time-zone>EST</event-time-zone>
<event-description>Item picked up by Canada Post</event-description>
<signatory-name></signatory-name>
<event-site>MONTREAL</event-site>
<event-province>QC</event-province>
<event-retail-location-id></event-retail-location-id>
<event-retail-name></event-retail-name>
</occurrence>
<occurrence>
<event-identifier>3000</event-identifier>
<event-date>2011-01-31</event-date>
<event-time>14:34:57</event-time>
<event-time-zone>EST</event-time-zone>
<event-description>Order information received by Canada Post</event-description>
<signatory-name></signatory-name>
<event-site>LACHINE</event-site>
<event-province>QC</event-province>
<event-retail-location-id></event-retail-location-id>
<event-retail-name></event-retail-name>
</occurrence>
</significant-events>
</tracking-detail>
</get-tracking-detail-response>