The GET Labels endpoint

The Consignments platform can generate despatch labels for all of it’s carriers, allowing our customers to generate and download labels without having to request them directly from the carrier. This guide explains how to get labels for a specific consignment or an individual package within a consignment.

Getting labels is a key part of all Consignments workflows, as an unlabelled consignment cannot be dispatched. Labels are usually retrieved after a package has been allocated but before it has been manifested.

Get labels for an entire consignment

Consignments offers two endpoints that return labels for all packages in a consignment: Get Labels and Get Labels In Format:

  • Get Labels returns labels for the specified consignment. It has only one parameter: the consignmentReference of the consignment you want to retrieve labels for. To call Get Labels, send a GET request to https://api.electioapp.com/labels/{consignmentReference}.
  • Get Labels in Format is similar to Get Labels, but enables you to specify the file format that you want the labels to be returned in. This must be one of Consignment’s supported consignment label formats: PDF, ZPL or ZPLII. To call Get Labels In Format, send a GET request to https://api.electioapp.com/labels/{consignmentReference}/{labelFormat}.

Get labels for an individual package

The Consignments platform also offers two endpoints that return labels for a specific package in a consignment: Get Package Label and Get Package Label In Format:

  • Get Package Label returns the label for the specified package. It has two required parameters: the packageReference of the relevant package and the consignmentReference of its associated consignment. To call Get Package Label, send a GET request to https://api.electioapp.com/labels/package/{consignmentReference}/{packageReference}.
  • Get Package Label in Format is similar to Get Package Label, but enables you to specify the file format that you want the label to be returned in. This must be one of Consignment’s supported package label formats: PDF, PNG, ZPL or ZPLII. To call Get Package Label In Format, send a GET request to https://api.electioapp.com/labels/package/{consignmentReference}/{packageReference}/{labelFormat}.

The labels response

All Labels API endpoints return labels objects. The labels object has two properties:

  • File - A base64-encoded byte array representing the file content.
  • ContentType - The content type of the file (as specified in the Label Format parameter, where applicable).

Request examples

  • https://api.electioapp.com/labels/EC-000-05D-1ST - a Get Labels request for all package labels associated with consignment EC-000-05D-1ST.
  • https://api.electioapp.com/labels/EC-000-05D-1ST/pdf - a Get Labels In Format request for all package labels associated with consignment EC-000-05D-1ST in PDF format.
  • https://api.electioapp.com/labels/EC-000-05D-1ST/EP-000-05F-1E8 - a Get Package Label request for the label of package EP-000-05F-1E8, which is part of consignment EC-000-05D-1ST.
  • https://api.electioapp.com/labels/EC-000-05D-1ST/EP-000-05F-1E8/pdf - a Get Package Label In Format request for the label of package EP-000-05F-1E8, which is part of consignment EC-000-05D-1ST, in PDF format.

Response example

The below example shows a typical label object.

Label object

  {
  "File": "SlZCRVJpMHhMalFLSmRQcjZl ... VRrNU9ERUtKU1ZGVDBZPQ==",
  "ContentType": "application/pdf"
}

To to use the label data

Once you have downloaded the file data, you will need to decode the file’s Base64 in order to view the label itself. If you are unsure how to do so, see the MDN docs for more information.