ParcelPickUp API

Resource URL

UAT:

https://api.uat.nzpost.co.nz/parcelpickup/v3/bookings

Production:

https://api.nzpost.co.nz/parcelpickup/v3/bookings

Resource Description

Creates pick up event for requested Pace or CourierPost service.

Resource Information

Please note that all request parameters should be in lower case.

Request Parameters

Address Object Parameters

The following lists the information that may be provided in pickup and delivery address for the ParcelPickUp request:

Address Rules
One and only one of the following is required for a delivery address:
1. DPID or
2. Address_id or
3. Site_code or
4. Suburb and city and postcode

Please note that if more than one of the above options is provided, the request will be rejected.

Sample Service Codes for Pace

Note: The above is not a comprehensive list of products and their service codes available for PACE. This is a sample only. Please talk to your NZ Post account manager to get a full list of PACE products and their service codes

Sample Requests

Please try these samples against UAT link only. Please contact your NZ Post account manager to get an account number (TPID) and a site code to test this. If this is tried in production there is a risk that this may trigger billing.

Sample Request - Pace Booking

  {
     "carrier": "PACE",
     "caller": "Jane Jones",
     "service_code": "3HRA",
     "pickup_date_time": "2018-06-23T10:00:00",
     "parcel_quantity": 2,
     "pickup_address": {
        "phone": "021 123 456",
        "site_code": "28979",
        "instructions": "Please dial 159 on the intercom when you arrive."
     },
     "delivery_address": {
        "name": "Jane Jones",
        "phone": "021 456 789",
        "email": "janejones@example.com",
        "company_name": "Cupcake company inc",
        "unit_type": "Suite",
        "unit_value": "4",
        "floor": "G",
        "building_name": "Test Delivery Building Name",
        "street": "42C Tawa Drive",
        "suburb": "Albany",
        "city": "Auckland",
        "postcode": "0632",
        "instructions": "Entrance can be found down the side of the building to the door at the back"
     }
  }

Sample Request - CourierPost Booking

  {
      "carrier": "COURIERPOST",
      "caller":"Jane Jones",
      "pickup_date_time":"2018-06-23T10:00:00",
      "parcel_quantity":2,
      "pickup_address": {
          "name": "John Smith",
          "phone": "6490000000",
          "email": "johnsmith@example.com",
          "company_name": "John's mobile store",
          "unit_type": "Unit",
          "unit_value": "2",
          "floor": "5",
          "building_name": "Victoria Street Plaza",
          "street": "151 Victoria Street West",
          "suburb": "Auckland Central",
          "city": "Auckland",
          "postcode": "1010",
          "instructions": "Please dial 159 on the intercom when you arrive."
      }
  }

Note:Tracking references can be empty

Response Message Fields

Result Elements

Reject Reasons

Error Response Elements

Error Object Parameters

HTTP Status Codes

Note that some error messages are customised for the request, i.e. error code 400 usually will describe what is wrong with the request

Error Codes

Sample Response

{
   "success": true,
   "results":    {
      "response_type": "AP",
      "message_id": "0c4a650c-9f4d-4628-98f1-db9bb3e33d03",
      "job_id": "20155401",
      "job_number": "100036",
      "customer_reference": "TEST JOB DO NOT DESPATCH",
      "reject_code": "0",
      "tracking_references":       [
         {"tracking_reference": "8441112178053201AKL020AS"},
         {"tracking_reference": "8441112178053202AKL020AS"}
      ]
   }
}

Sample Error Response

{
   "success": false,
   "message_id": "ded71a90-0e36-11e5-aa3a-02b923c21ef3",
   "errors": [   {
      "code": "400002",
      "message": "Invalid parameter(s)",
      "details": "Email address must be present for delivery confirmations"
   }]
}