API Reference

Getting Printable Labels

The label is the piece of paper or sticker that you put on your parcel. It lets the driver know that it's a Sendle parcel and where it should go.

We have two different PDF label options to choose from:

  • A cropped label, that's the perfect size already.
  • A full-sized a4 (Australian) or letter (U.S.) sheet with a label on it.

Our cropped label files have the physical size embedded. But some printing programs don't respect that and try to fill the whole page instead, and the labels end up much bigger than they should be. Using the full sheet makes sure they can be printed at the right size with a home printer.

Generally you should let merchants choose which size to download and use, since which one they prefer will depend on their setup. Make sure that they're also only available when authenticated – the labels contain a lot of personal information!

Label Layouts

Our labels are laid out in specific ways to comply with the requirements of our delivery partners. Because of this, the layout of the labels we supply may change any time.

We recommend supplying the labels as-is for shippers to print and not post-processing them – even rotating the label can degrade the quality of barcodes/text and make it more likely for packages to be lost during their journey. Trying to extract details from the labels or pull barcodes from them is also fragile and may break when we need to update the layout of the label.

QR Code for drop off orders in Australia

Drop off orders originating from Australia, within 25km of an eligible Print In-Store service location will include a QR code version of the label.

The label will available as a png format, as part of the label response.

See more about QR code label in the Changelog and help centre article for Print In-Store service.

Downloading a Label

When creating an order or viewing an order, you'll get an entry that looks like this:

"labels": [
  {
    "format": "pdf",
    "size": "a4",
    "url": "https://api.sendle.com/api/orders/f5233746-71d4-4b05-bf63-56f4abaed5f6/labels/a4.pdf"
  },
  {
    "format": "pdf",
    "size": "cropped",
    "url": "https://api.sendle.com/api/orders/f5233746-71d4-4b05-bf63-56f4abaed5f6/labels/cropped.pdf"
  },
  {
    "format": "png",
    "size": "cropped",
    "url": "https://api.sendle.com/api/orders/f5233746-71d4-4b05-bf63-56f4abaed5f6/labels/cropped.png"
  }
]

Retrieving labels

Those URLs (the 'label URLs') can only be accessed if you also send your API credentials along with the request. When accessing these URLs you should use a HEAD request. The 302 response will contain a JWT-signed URL (the 'download URL') in the Location header, which is valid for 60 seconds and which can be accessed with no authentication required.

Your software doesn't need to download and then forward/store the label file – it can just provide the download URL to the user so their browser or app can access it themselves! Proxying the file can make things feel slow to the user/merchant, so we recommend not doing that. After 60 seconds that URL will expire – and you'll need to go through the above process again to get a new download URL – so make sure that your software doesn't cache or remember the download URL in any way.

If you really do want to download the label file, to attach it to an email for example, you should make sure that only the relevant user can download the file. The label shows personal information like sender/receiver names, addresses, and phone numbers, so keeping it safe is important.

You need to filter on the label format and size when retrieving the label to ensure you get the correct format and size.

Label formats and size

We currently provide printable labels in 2 formats - pdf and png. QR code labels will be represented in png format.

Available sizes for PDF labels will be cropped / a4 / letter, and cropped size for QR code label.

Here's the process your software should follow when a user/merchant clicks a button to see a label:

  1. Your software needs to access the label URL (the one given in the View Order endpoint) with your API credentials attached. You should use HEAD when doing this. That will return a HTTP Redirect (302) with the download URL.
  2. The user's browser or app can access the download URL directly, no API key needed.

And here's a quick diagram that breaks it down:

If your software wants to download the label(s) to attach to an email or similar, you'd do the above but have your software follow the redirect to the download URL and grab the file itself!

Here's a diagram showing off that approach:

Testing with Curl

Curl is a command-line tool for transferring data with URLs. Here's how to download a label file from one of the above URLs:

curl "https://api.sendle.com/api/orders/f5233746-71d4-4b05-bf63-56f4abaed5f6/labels/a4.pdf"
  -u "sendleID:APIKey"
  -o "local_label_filename.pdf"
  -L

The -L flag follows redirects, and the -o flag saves the file with the given filename.

Testing with Postman

Postman lets you test API requests. You can test the Sendle label functionality as you would any other endpoints with this tool.

However, Postman does automatically follow redirects. To disable this, and see the 302 redirect, you must disable this feature in the Postman general or request-specific settings: