ParcelPickUp API

Download
Opens request access modal
(0 reviews)

Booking

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

AttributeDetail
Response FormatJSON
Requires AuthenticationYes
Rate Limited15 calls per second across all merchants using the API. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out.

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

Request Parameters

Field NameDescriptionMandExample
carrierIndicates company providing the service, Valid values are COURIERPOST or PACEYesCOURIERPOST
callerName of the callerYesJane Jones
nameThe sender contact nameNo but highly recommendedBill Smith
emailCustomer contact email addressNobill@abc.xx.nz
phoneCustomer contact phoneNo but highly recommended+64-27-111-1111
customer_referenceFree text field normally used for return authority or order numberNoOR12354
tracking_referencesThis is relevant for CourierPost only. Contains a JSON array of tracking reference numbers. Note that prepaid ticket numbers can be used.No2289791234567801GDD001AS
service_codePlease do not provide this for CourierPost. This is mandatory for PACE. Please refer to the section Sample Service Codes for PACEYes if Pace3HRA
pickup_addressDetails regarding the Pick up addressYesJSON object. See section Address Object Parameters
delivery_addressDetails regarding the Delivery AddressYes if PACEJSON object. See section Address Object Parameters
is_booking_confirm_requiredIndicates if a confirmation of the pick up booking is requiredNotrue
is_delivery_confirm_requiredIndicates if a confirmation of the delivery is requiredNotrue
confirmation_emailEmail address for confirmationsNotest@example.com
InstructionsA customer noteNoPackage is sitting on the counter at reception
pickup_date_timeIndicates the requested time for pick up in ISO8601 format. Pickup Hours: 0700 - 1800 weekdays; 0800 - 1300 Saturdays. No pickup on Sundays and New Zealand public holidays.Yes2018-03-02T10:00:00
parcel_quantityQuantity of packages to be picked upYes if Pace.3
estimated_weight_kgEstimated total weight of the package in kilogramsNo3
is_label_requiredIndicates whether the sender requires a label to be printed at the depot. Required True for CFF bookings. Defaults to falseNofalse

Address Object Parameters

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

Field NameDescriptionMandExample
nameUsed to identify the name of the contact person at the pick up or delivery locationNoJane Jones
phoneUsed to identify the phone number of the contact person at the pick up or delivery locationNo+64-27-111-1111
emailUsed to identify the email address of the contact person at the pick up or delivery locationNojane@abcd.xx.nz
company_nameUsed to identify the Company Name for the pick up or delivery locationNoAcme Trading
site_codeIndicates the Site Code for the pickup or the delivery addressRefer to Address Rules below79012
unit_typeIndicates the type of unit (if applicable)NoFlat
unit_valueIndicates the value of the unit type (ie the 2 in Flat 2)Yes if Unit Type is not blank2
floorIndicates the floor the address is onNoFloor 5
building_nameName of the buildingNoWesting House
streetIndicates the street addressNo165 White Avenue
suburbIndicates the suburbRefer to Address Rules belowAuckland City
cityIndicates the name of the cityRefer to Address Rules belowAuckland
postcodeIndicates the postcode the address resides inRefer to Address Rules below0600
dpidA numeric place identifier for the pickup address sourced from the ParcelAddress APIRefer to Address Rules below12345
address_idUsed to identify the address ID specifically within the ECL addressing databaseRefer to Address Rules below839750
instructionsUsed to identify any specific pick up or delivery instructionsNoRing Sam on arriving

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

Service CodeProduct Description
3HRA3 HOUR SERVICE AUCKLAND
HDAHOME DELIVERY AUCKLAND
P30APACE 30
P60APACE 60
PBAPACE BULLET
PL1A1 HOUR PALLET SERVICE AUCKLAND
PL2A2 HOUR PALLET SERVICE AUCKLAND
PL3A3 HOUR PALLET SERVICE AUCKLAND

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

Field NameDescriptionMandExample
successConfirms whether the API call is successful or not, Returns true or falseYestrue
message_idSystem generated as submitted in the requestYesded71a90-0e36-11e5-aa3a-02b923c21ef3
resultsRefer to Result Elements section belowYes if success is trueJSON Object
errorsRefer to Error Response Elements section belowYes if success is falseJSON Object

Result Elements

Field NameDescriptionMandExample
response_typeIndicates the response type. A valid response may be given even if no data is returned. Valid Entries are: AP (Acceptance), RE (Rejection)YesAP
job_idECL system reference numberYes5214568
job_numberJob booking number eg PACEnnnnnnnnYes if from Pace100036
customer_referenceCustomer Reference ID as submitted in the requestYesOR12354
reject_codeIndicates the reject reason codeYes, if Resp Type = RE1
tracking_referencesCourierPost tracking reference. JSON ArrayYes for CourierPosttracking_reference:abc_x113

Reject Reasons

Reject CodeError Message
0Success - no message
1Data Source must be INTEGRATED, IVR, ONLINE_PU, ONLINE_FF or ONLINE_SIM
2Invalid Job ID
3Invalid Job category
4No pickup suburb supplied

Error Response Elements

Field NameDescriptionMandExample
successReturns if request is successfulYesTrue
errorsError object with error detailsY if success =falseSee Error Object Parameters below
message_idThe unique message identifierYesec608f40-2a8b-11e5-a9c0-025c481d35ef

Error Object Parameters

Field NameDescriptionExample
codeError code where first 3 digits are http status code, last three digits identify error type400002
messageDescription of error codeInvalid Parameter(s)
detailsDescription of specific errorEmail address must be present for delivery confirmations

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

CodeMessage
200Success
400Bad request
401Unauthorized
403Forbidden
409Invalid request
500System unavailable

Error Codes

CodeMessage
200001Partial results returned, not all system(s) have responded
200002All sources responded, data may be incomplete
400001Parameter(s) missing
400002Invalid parameter(s)
400003Non mutually exclusive parameters detected
401001Unauthorised access, please contact administrator
500001General Exception
500002System(s) offline

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"
   }]
}

Reviews