Pickup

Get Pickup Request Details – SOAP

Summary

Name: Get Pickup Request Details
Reason to Call: To get all available details for a given pickup request.
Input: Customer number, request-id
Output: Details of pickup request.
Typical Prior Call: Create Pickup Request or Get Pickup Requests
Typical Next Call: N/A
Version history: Release notes
Get Pickup Request Details – Summary of Service

Get Pickup Request Details – Summary of Service

Call Details

WSDL: shipment.wsdl
Endpoint (Development): https://ct.soa-gw.canadapost.ca /enab/soap/pickup
Endpoint (Production): https://soa-gw.canadapost.ca /enab/soap/pickup
Namespace: http://www.canadapost.ca/ws/pickuprequest
Operation: GetPickupRequestDetails

SOAP Body

This section describes the XML input elements to Get Pickup Request Details. For the hierarchical structure, see the XML diagram.

Get Pickup Request Details – Request Elements
Element Name Type Required/Optional Description/Size/Format

get-pickup-request-details-request

Complex

Required

The top level XML element for the request input information.

customer-number

Simple

Required

(1-10 digit numeric)

The 10-digit customer number of the mailed-by customer.

If the number provided has fewer than 10 digits, the system will add leading zeroes.

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.

platform-id

Simple

Optional

Customer number of the platform. For e-commerce platforms only.

request-id

Simple

Required

(35 alphanumeric)

Unique identifier for the request.

Request – XML Diagram

Get Pickup Request Details – Structure of the XML Request

Get Pickup Request Details – Structure of the XML Request

Response Details

Response – Elements

The table below describes the XML fields in the response. For the hierarchy of the response, see the XML diagram.

Get Pickup Request Details – Response Elements
Element Name Type Description

get-pickup-request-details-response

Complex

The top level XML structure that contains the information about the pickup request.

pickup-request-detailed-info

Complex

The XML element that contains the pickup request details.

pickup-request-header

Complex

Basic information about the request.

request-id

Simple

The ID number for the pickup request.

request-status

Simple

Status of the request. Possible values are as follows:

  • New
  • Pending
  • Cancelled
  • Active
  • Missed Pickup

 pickup-type

Simple

The type of pickup you requested: OnDemand.

request-date

Simple

Date the pickup request was created.

next-pickup-date

Simple

Date when the next on-demand pickup was requested for.

pickup-request-details

Complex

Detailed information about the request.

pickup-location

Complex

Structure containing the address where the pickup is to occur.

business-address-flag

Simple

True indicates that the pickup is at your business location. False indicates pickup is at a third-party location.

alternate-address

Complex

Structure containing the address details for pickup at a third-party location.

company

Simple

Company name of the organization requesting the pickup.

address-line-1

Simple

Street address of your pickup location

city

Simple

City of pickup location.

province

Simple

Province of pickup location.

postal-code

Simple

Postal Code of pickup location.

contact-info

Complex

Structure containing the contact for questions or inquiries.

contact-name

Simple

Contact name for the pickup.

email

Simple

Email address to receive status updates regarding your pickup request.

Note: If you have had a long-standing scheduled pickup arrangement in place, this element may have previously been optional. It is now required and you will need to provide it if you update your pickup request.

contact-phone

Simple

Contact phone number for the pickup.

telephone-ext

Simple

Telephone extension.

receive-email-updates-flag

Simple

True indicates that you wish to receive status updates about the request.

location-details

Complex

Structure containing characteristics of the physical location where pickup is to occur.

five-ton-flag

Simple

True identifies that a 5-ton truck is needed.

loading-dock-flag

Simple

True identifies that there is a loading dock at the location.

pickup-instructions

Simple

Instructions for the driver

items-characteristics

Complex

Structure to identify that items for pickup have special processing needs. Only applicable to on-demand pickups.

priority-flag

Simple

Identifies that Priority items could be available for pickup.

returns-flag

Simple

{true, false}
Identifies that returned items could be available for pickup.

heavy-item-flag

Simple

Identifies that some the items to pick up may have a weight greater than 23 kg (50 lbs.)

pickup-volume

Simple

(Character string up to 40 characters)
For on-demand pickup, this is the expected number of items to be picked up.

pickup-times

Complex

Structure containing the date and time range in which the pickup is to be done.

on-demand-pickup-time

Complex

Structure containing the details for an on-demand pickup request.

date

Simple

Date you would like the on-demand pickup.

preferred-time

Simple

The preferred time for the on-demand pickup.

closing-time

Simple

The latest time for the on-demand pickup.

scheduled-pickup-times

Complex

Not used. Request a scheduled pickup using our online tool.

Response – XML Diagram

Get Pickup Request Details - Structure of the XML Response
Get Pickup Request Details - Structure of the XML Response

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.

No errors are expected for this call, but you will receive a 404 error if you invoke Get Pickup Request Details more than 90 days after the pickup request was submitted.

Code Description

11005

Customer number not valid. Please correct or contact Canada Post for details.

11012

Request ID not found. Please verify.

See also Error messages and mitigation strategies.

Examples

Sample SOAP XML Request – Get Pickup Request Details

<get-pickup-request-details-request>
<customer-number>1234567</customer-number>
<locale>EN</locale>
<request-id>0074698052</request-id>
</get-pickup-request-details-request>

Sample SOAP XML Response – Get Pickup Request Details

<get-pickup-request-details-response xmlns="http://www.canadapost.ca/ws/soap/pickuprequest"> 
<pickup-request-detailed-info>
  <pickup-request-header>
    <request-id>0074698052</request-id>
    <request-status>Active</request-status>
    <pickup-type>OnDemand</pickup-type>
    <request-date>2015-01-01</request-date>
  </pickup-request-header>
  <pickup-request-details>
    <pickup-location>
      <business-address-flag>false</business-address-flag>
      <alternate-address>
        <company>Jim Duggan</company>
        <address-line-1>2271 Herring Cove</address-line-1>
        <city>Halifax</city><province>NS</province>
        <postal-code>B3L2C2</postal-code>
      </alternate-address>
    </pickup-location>
    <contact-info>
      <contact-name>John Doe</contact-name>
      <email>john.doe@canadapost.ca</email>
      <contact-phone>800-555-1212</contact-phone>
      <receive-email-updates-flag>true</receive-email-updates-flag>
    </contact-info>
    <location-details>
      <five-ton-flag>false</five-ton-flag>
      <loading-dock-flag>true</loading-dock-flag>
      <pickup-instructions>Door at Back</pickup-instructions>
    </location-details>
    <items-characteristics>
      <pww-flag>true</pww-flag>
      <priority-flag>false</priority-flag>
      <returns-flag>true</returns-flag>
      <heavy-item-flag>true</heavy-item-flag>
    <items-characteristics>
     <pickup-volume>50</pickup-volume>
   <pickup-times>
      <on-demand-pickup-time>
        <date>2015-01-28</date>
        <preferred-time>15:00</preferred-time>
        <closing-time>17:00</closing-time>
      </on-demand-pickup-time>
    </pickup-times>
  </pickup-request-details>
</pickup-request-detailed-info>
</get-pickup-request-details-response>