Pickup

Get Pickup Requests – REST

Summary

Name: Get Pickup Requests
Reason to Call: To retrieve links to existing open pickup requests
Input: No XML input data required
Output: A list of links to individual pickup requests resources
Version history: Release notes
Get Pickup Requests – Summary of Service

Get Pickup Requests – Summary of Service

Request Details

Request – Structure for Get Pickup Requests

Endpoint

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

Authorization

Basic {Base64 encoding of userid:password}

Accept-language

en-CA or fr-CA

Body

None

Request – Elements

The Get Pickup Requests service does not require any input XML data.

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 Requests – Response Elements
Element Name Type Description

pickup-requests

Complex

This is the top level XML element of the response structure.

pickup-request

Complex

The top level structure for each pickup request. All open/active requests plus recent history (up to 20 pickups) will be returned.

pickup-request-header

Complex

Structure containing basic information about the pickup request.

request-id

Simple

The ID number for the pickup request.

request-status

Simple

Status of the request; possible values are:

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

links

Complex

Structure containing links to information related to the pickup request.

link

Complex

Use these links to invoke additional functions on the pickup request. Each link represents a link to one of the web services.
May occur 1 .. N times
The following links may be returned and each will have a unique rel type:

  1. rel="self"

This link represents the pickup request itself. The href attribute can be used as an endpoint to the Update Pickup Request service.

  1. rel = "details"

This link represents additional details about the Pickup Request that are not returned in the Get Pickup Requests response. The href attribute is an endpoint to the Get Pickup Request Details service.

  1. rel = "hold"

For future use

  1. rel = "resume"

For future use

  1. rel = "cancel"

This link is used to cancel/delete a pickup request. The href attribute is an endpoint to the Cancel Pickup Request service.
In all of the above cases, the value of the media-type attribute indicates the version of the XML that will be returned and should be included as an HTTP Accept header in any of the calls to other services pointed to by the href.

Response – XML Diagram

Get Pickup Requests - Structure of the XML Response
Get Pickup Requests - Structure of the XML Response

Response – Possible Error Responses

An HTTP return code of 404 (Not found) is returned if no pickup request is found.

Code Description

11005

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

See also HTTP status codes and Error messages and mitigation strategies.

Examples

Sample REST XML Request – Get Pickup Requests

GET https://ENV/enab/1234567/pickuprequest
Accept  application/vnd.cpc.pickuprequest+xml
Authorization:Basic s7HD7gwsennesc==

Sample REST XML Response – Get Pickup Requests

<pickup-requests>
  <pickup-request>
    <pickup-request-header>
      <request-id>0074698052</request-id>
      <request-status>Pending</request-status>
      <pickup-type>OnDemand</pickup-type>
      <request-date>2014-09-09</request-date>
    </pickup-request-header>
    <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>
</pickup-requests>

Development (Sandbox) Environment XML Response – Get Pickup Requests

The response is stubbed (static) in the development environment, so you will always receive the response below, regardless of the data in your request.

<pickup-requests>
  <pickup-request>
    <pickup-request-header>
      <request-id>0074698052</request-id>
      <request-status>Active</request-status>
      <request-date>2015-01-01</request-date>
    </pickup-request-header>
    <links>
      <link rel="self" href="https://ct.soa-gw.canadapost.ca/enab/ your customer number /pickuprequest/0074698052" media-type="application/vnd.cpc.pickuprequest+xml"></link>
      <link rel="details" href="https://ct.soa-gw.canadapost.ca/enab/ your customer number /pickuprequest/0074698052/details" media-type="application/vnd.cpc.pickuprequest+xml"></link>
    </links>
  </pickup-request>
  <pickup-request>
    <pickup-request-header>
      <request-id>00110215</request-id>
      <request-status>Active</request-status>
      <request-date>2015-01-01</request-date>
      <next-pickup-date>2015-06-01</next-pickup-date>
    </pickup-request-header>
    <links>
      <link rel="self" href="https://ct.soa-gw.canadapost.ca/enab/ your customer number /pickuprequest/0074698052" media-type="application/vnd.cpc.pickuprequest+xml"></link>
      <link rel="details" href="https://ct.soa-gw.canadapost.ca/enab/ your customer number /pickuprequest/0074698052/details" media-type="application/vnd.cpc.pickuprequest+xml"></link>
      <link rel="hold" href="https://ct.soa-gw.canadapost.ca/enab/ your customer number /pickuprequest/0074698052/hold" media-type="application/vnd.cpc.pickuprequest+xml"></link>
    </links>
  </pickup-request>
</pickup-requests>