ParcelLabel API

Download
Opens request access modal
(2 reviews)

Get Status of Related Label(s)

Resource URL

UAT:

https://api.uat.nzpost.co.nz/parcellabel/v3/labels/{consignment_id}/related

Production:

https://api.nzpost.co.nz/parcellabel/v3/labels/{consignment_id}/related

Resource Description

Returns the status of all labels within a consignment and the other consignments in the same order.

Note - Order number is put in to the sender_reference_2 field in creating label request. When a consignment id with that order number is queried with the 'related' resource, all consignments with the same order number specified in sender_reference_2 field are returned.

Resource Information

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

Request Parameters

Field NameDescriptionMandExample
consignment_idUnique id of a consignmentYesLLT2BL

Sample Request

https://api.uat.nzpost.co.nz/parcellabel/v3/labels/LLT2BL/related

Response Parameters

The following lists the required fields in the /labels/{consignment_id}/related response message.

Field NameDescriptionMandExample
consignmentsAn array containing all consignments relating to the specific consignment within the same order. See Consignments Object Parameters.YJSON Array
errorsAn array containing error details. See Errors Object Parameters.Y if request is unsuccessfulJSON Array
message_idA unique id for the API callYese50895a0-72aa-11e5-9b3a-02578d875979
successReturns true if request is successful otherwise falseYestrue

Consignments Object Parameters

Field NameDescriptionMandExample
consignment_idUnique identifier for all of the labels in the consignment.YLLT2BL
consignment_statusStatus of the consignment. See Consignment Status Values.YComplete
consignment_urlDownload URL for the consignment, in format PDF.Y if the status of the consignment is Completehttps://api.nzpost.co.nz/parcellabel/v3/labels/LLT2BL?format=PDF
delivery_addressAn object containing the delivery address details of the consignment. See Consignments - Delivery Address Object Parameters.YJSON Object
labelsAn array of the label objects within the consignment. See Consignments - Labels Object Parameters.YJSON Array
page_urlsAn array containing the download URLs for each page in the consignment, in format PNG.Y if the status of the consignment is Completehttps://api.uat.nzpost.co.nz/parcellabel/v3/labels/LLT2BL?format=PNG&page=1

Consignments - Delivery Address Object Parameters

Field NameDescriptionMandExample
building_nameBuilding name of the delivery address.NBeta Company House
company_nameName of company that the parcel is being delivered to.Y if for domestic and is_collection = trueBeta Company
unit_typeUnit type (if applicable) of the delivery address.NSuite
unit_valueUnit value of the delivery address.Y if domestic and unit_type is not blank5
floorFloor of the delivery address.N3
street_numberStreet number of the delivery address.N1600
streetStreet name of the delivery address.Y if address_id, dpid and site_code are blankPennsylvania Avenue
suburbSuburb of the delivery address.Y if address_id, dpid and site_code are blankWashington Central
cityCity of the delivery address.Y if address_id, dpid and site_code are blankWashington
stateRegional, provincial or county name of the delivery address.NDelaware
locality_codeCountry subdivision code identifier that the delivery address belongs to.NDE
country_codeTwo character country code. For domestic labels, this must be set to NZ.YUS
postcodePostal or zip code of the delivery address.Y if address_id, dpid and site_code are blank89102

Consignments - Labels Object Parameters

Field NameDescriptionMandExample
label_idContains the unique label id which can be used to return individual label dataYesLLT2BL-1
tracking_referenceThe tracking reference for the labelYes123456789856AC01

Consignment Status Values

StatusDefinition
AcceptedParcelLabel Request has been received into NZ Post Group systems
ProcessingParcelLabel Request has passed all validation and has been passed to the Label Generator
CompleteLabel Rendering has successfully created an image of all the labels
Complete with warningsAll label images have been generated successfully but the merchant logo was not able to be put into the label image
FailedThe Label Rendering has failed to create an image for at least one label

Errors 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 errorCarrier is a mandatory field

Sample Response

resources/get_status_related_1-8322af29-158c-41b5-81d4-0c3100a05181.PNG

resources/get_status_related_2-442af2a3-1dd2-4929-9a43-72df416a869a.PNG

resources/get_status_related_3-49a228e4-0da2-4164-bc24-fce62b30dff7.PNG


Reviews