Developer Program

Ready to join the Developer Program? Join NOW FREE

Resources

Pickup

Create Pickup Request – REST

Summary

Name:	Create Pickup Request
Reason to Call:	To create a request for a one-time on-demand pickup.
Input:	Pickup details
Output:	Pickup request ID and links
Typical Prior Call:	Get Pickup Availability
Typical Next Call:	Get Pickup Request Details
Version history:	Release notes

Create Pickup Request – Summary of Service

Request Details

Request – Structure for Create Pickup Request

Endpoint

POST https://XX/enab/{customer}/pickuprequest
Replace...	With...
XX (Development)	ct.soa-gw.canadapost.ca
XX (Production)	soa-gw.canadapost.ca
{customer}	your customer number

HTTP Headers

HTTP Header Variable	Value
Accept	application/vnd.cpc.pickuprequest+xml (Note: / in place of the header value will return an error)
Content-Type	application/vnd.cpc.pickuprequest+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

Body

<?xml version="1.0" encoding="utf-8"?>
<pickup-request-details xmlns="http://www.canadapost.ca/ws/pickuprequest”>
xxx
</pickup-request-details>

Request – Elements

The table below describes the XML input elements for Create Pickup Request. For the hierarchical structure of the inputs, see the XML diagram.

Create Pickup Request – Request Elements
Element Name	Type	Required/Optional	Description/Size/Format
pickup-request-details	Complex	Required	The top level XML element for the request input information.
pickup-type	Simple	Required	Type of pickup requested: Ondemand – for an on-demand (one-time) pickup
pickup-location	Complex	Required	Structure containing the address where the pickup is to occur.
business-address-flag	Simple	Required	{true}, {false} True indicates that the pickup (or pickups) is at the business address specified in your Canada Post profile. (You can sign in to your profile to check the address we have on file for you.) False indicates that the pickup is at an alternate address. You must specify the alternate address. Please note the following: On-demand pickups at an alternate address can only be paid for by credit card.
alternate-address	Complex	Conditionally required	Address for third-party pickup. Required for third-party pickups (business-address-flag=false). Must not be supplied if business-address-flag = true.
company	Simple	Required	(Character string up to 35 characters) Company name of the organization requesting the pickup. Required for third-party pickups (business-address-flag=false). Must not be supplied if business-address-flag = true.
address-line-1	Simple	Required	(Character string up to 35 characters) Street address of your pickup location Required for third-party pickups (business-address-flag=false). Must not be supplied if business-address-flag = true.
city	Simple	Required	(Character string up to 35 characters) City of pickup location. Required for third-party pickups (business-address-flag=false). Must not be supplied if business-address-flag = true.
province	Simple	Required	(2 characters) Province of pickup location. Use standard 2-character Canadian province codes. Required for third-party pickups (business-address-flag=false). Must not be supplied if business-address-flag = true.
postal-code	Simple	Required	(6-character alphanumeric) Postal Code of pickup location in format A9A9A9 Required for third-party pickups (business-address-flag=false). Must not be supplied if business-address-flag = true.
contact-info	Complex	Required	Structure containing the contact for questions or inquiries.
contact-name	Simple	Required	(Character string up to 45 characters) Contact name for the pickup.
email	Simple	Required	(Character string up to 60 characters) Must be a valid email address. Pattern is (['_A-Za-z0-9\-\+]+)(\.['_A-Za-z0-9\-\+]+)@([A-Za-z0-9\-]+)(\.[A-Za-z0-9\-]+)(\.[A-Za-z]{2,5}) Email address to receive status updates regarding your pickup request.
contact-phone	Simple	Required	(Character string up to 16 numeric characters) Contact phone number for the pickup. Format 999-999-9999
telephone-ext	Simple	Optional	(up to 6 numeric digits) Telephone extension.
receive-email-updates-flag	Simple	Optional	{true, false} True indicates that you wish to receive status updates about the request. Defaults to False
location-details	Complex	Required	Structure containing characteristics of the physical location where pickup is to occur.
five-ton-flag	Simple	Optional	{true, false} True identifies that a 5-ton truck is needed. Only applicable to an on-demand pickup request. Defaults to False
loading-dock-flag	Simple	Optional	{true, false} True identifies that there is a loading dock at the location. Defaults to False
pickup-instructions	Simple	Required	(Character string up to 132 characters, but truncates to 40) Instructions for the driver (e.g., use back door, use side entrance, bring a dolly)
items-characteristics	Complex	Optional	Structure to identify that items for pickup have special processing needs. Only applicable to on-demand pickups.
priority-flag	Simple	Optional	{true, false} Identifies that Priority items could be available for pickup. Defaults to False
returns-flag	Simple	Optional	{true, false} Identifies that returned items could be available for pickup. Defaults to False
heavy-item-flag	Simple	Optional	{true, false} Identifies that some the items to pick up may have a weight greater than 23 kg (50 lbs.) Defaults to False
pickup-volume	Simple	Required	(Character string up to 40 characters) The expected number of items to be picked up. You can also include additional details, such as “50 parcels and 10 packets”.
pickup-times	Complex	Required	Structure containing the date and time range in which the pickup is to be done.
on-demand-pickup-time	Complex	Conditionally required	Structure containing the details for an on-demand pickup request. Mandatory for an on-demand pickup request; must not be provided otherwise.
date	Simple	Required	(YYYY-MM-DD format) Date you would like the on-demand pickup. The date cannot be more than 5 days in the future, unless you have a parcels agreement, in which case it can be up to 30 days.
preferred-time	Simple	Required	(hh:mm format) The preferred time for the on-demand pickup. Must be between noon (12:00) and 4 p.m. (16:00), in 15-minute intervals (i.e. minutes must be 00, 15, 30 or 45).
closing-time	Simple	Required	(hh:mm format) The latest time for the on-demand pickup. Must be a minimum of one hour after preferred-time, in 15-minute intervals (i.e. minutes must be 00, 15, 30 or 45).
scheduled-pickup-times			Not used. Request a scheduled pickup using our online tool.
payment-info	Complex	Optional	Structure containing details on payment.
contract-id	Simple	Optional	(Up to 10 numeric digits) Your parcels agreement number, if applicable.
method-of-payment	Simple	Optional	For future use only. In the initial release, the system will determine the method of payment: If you do not have a parcels agreement, fees will be charged to the default credit card in your online profile (or the request rejected if you do not have a default credit card on file). If you have a parcels agreement and request a pickup at your main address (on demand), it will be billed to your account (unless your account is blocked, in which case the default credit card in your online profile would be used, or the request rejected if you do not have a default credit card on file). If you have, or have authority to use, a parcels agreement with third-party pickup activated and request a pickup at an alternate address, it will be billed to your account (unless your account is blocked, in which case the default credit card in your online profile would be used, or the request rejected if you do not have a default credit card on file).

Request – XML Diagram

Create Pickup Request – Structure of the XML Request

View full-size image

Response Details

Response – Elements

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

Create Pickup Request – Response Elements
Element Name	Type	Description
pickup-request-info	Complex	The top level XML element for the response that contains the information about the pickup request.
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. Active will always be the status of a successful Create Pickup Request. See the response of Get Pickup Request Details for other possible statuses after creation.
pickup-type	Simple	The type of pickup you requested: OnDemand.
request-date	Simple	Date the pickup request was created.
pickup-request-price	Complex	Only provided for on-demand pickup requests.
pre-tax-amount	Simple	Base charges for the pickup.
gst-amount	Simple	Goods and services tax amount.
pst-amount	Simple	Provincial sales tax amount.
hst-amount	Simple	Harmonized sales tax amount.
due-amount	Simple	Total charges.
cc-receipt-details	Complex	This structure contains details for a credit card receipt. These details are provided only for on-demand pickup requests paid by credit card.
merchant-name	Simple	Will have the value: "Canada Post"
merchant-url	Simple	Will have the value: "www.canadapost.ca"
name-on-card	Simple	The name on the default credit card stored by Canada Post, if supplied.
auth-code	Simple	The authorization code received from the credit card issuer.
auth-timestamp	Simple	The date and time that the credit card company authorized the transaction.
card-type	Simple	The type of credit card used for the purchase.
charge-amount	Simple	The amount authorized by the credit card issuer.
currency	Simple	The currency of the transaction: CAD.
transaction-type	Simple	Will have the value: "Sale".
links	Complex	Structure containing links to information related to the pickup request.
link	Complex	Use these links to retrieve different results of the Create Pickup Request service, and/or invoke different additional functions on the pickup request. Each link represents a link to one of the web services. May occur 1 .. N times (Note: The link element is "complex" because it contains a number of attributes. It does not contain any sub-elements). The following links will be returned and each will have a unique rel type: rel="self" This link represents the pickup request just created. The href attribute can be used as an endpoint to the Update Pickup Request service. rel = "details" This link provides additional details about the pickup request that are not returned in the Create Pickup Request response. The href attribute is an endpoint to the Get Pickup Request Details service to retrieve that additional information.

Response – XML Diagram

Create Pickup Request - Structure of the XML Response

View full-size image

Response – Possible Error Responses

Code	Description
11000	Address is incomplete (missing unit number for example).
11001	The contract number is not found or invalid. Note that you must use a parcels agreement.
11002	There is already a pickup request within one hour of this one.
11003	Pickup cannot be done on the date requested (may be in the past, invalid or not a business day).
11005	Customer number not valid. Please correct or contact Canada Post for details.
11009	Pickup is not available for the postal code you provided.
11010	You must have a credit card on file when paying by this method of payment.
11015	Missing preferred time. Please correct your request.
11016	Your closing time cannot be before your preferred pickup time.
11018	Payment approval failed. Please try later or contact the Credit Management Group at 1-800-267-7651.
11020	The transaction could not be authorized. Please verify your credit card.
11021	Pickup cannot be done at the time requested as it is outside pickup hours of {0} to {1}.
11022	It is too late to request a pickup today; the cut-off time was {0}.
11111	System error. Please try later or contact the Canada Post helpdesk.

Examples

Sample REST XML Request – Create Pickup Request


  <pickup-request-details>

   <pickup-type>OnDemand</pickup-type>

   <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>

     <opt-out-email-updates-flag>true</opt-out-email-updates-flag>

    <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>

Sample REST XML Response – Create Pickup Request


  <pickup-request-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-price>

     <pre-tax-amount>3.50</pre-tax-amount>

     <hst-amount>0.46</hst-amount>

     <due-amount>3.96</due-amount>

  </pickup-request-price>

   <links>

    <link  rel="self" href="https://ct.soa-gw.canadapost.ca/enab/1234567/pickuprequest/0074698052" media-type="application/vnd.cpc.pickuprequest+xml"></link>

    <link  rel="details" href="https://ct.soa-gw.canadapost.ca/enab/1234567/pickuprequest/0074698052/details" media-type="application/vnd.cpc.pickuprequest+xml"></link>

  </links>

</pickup-request-info>

Development (Sandbox) Environment XML Response – Create Pickup Request

The response is stubbed (static) in the development environment, so you will always receive the same response regardless of the data in your request. Please note, however, that the request-ids in the development environment are as follows:

On-demand pickups: 0074698052

To test a backend error (i.e. schema validations are all done in the development environment), in the pickup-location structure set the postal-code element to A9A9A9; error 11000 will be returned. No other error message will be returned in the development environment; for example, your contract number will not be verified for existence or validity.

Sign in