Skip to content
Transdirect Developer Centre

Get a label

Download the shipping label for a booking as a PDF. Print it and attach it to the parcel before the courier arrives.

GET /api/v5/bookings/{id}/label
GET /api/v5/bookings/{id}/a6label

/label returns an A4 page and /a6label returns an A6 label for thermal printers. Both require your API key in the api-key header.

When a label is ready

Section titled “When a label is ready”

A label exists only after the booking is confirmed and paid. Some couriers issue the label straight away; others only once they have accepted the job.

CourierLabel ready when status_code is
Allied, Aramex, Capital Transport, Domestic Freight Express, Followmont, Hunter, TNT, Team Global Express, Xpress, and all international servicesconfirmed
Couriers Pleaseconfirmed. A GET can sometimes return the label at request_sent, but HEAD reports ready only at confirmed.
Northlinepaid, reviewed, confirmed or request_sent
Other couriers, including the demo courierpaid, reviewed, confirmed or demo
Go PeopleNever. There is no Transdirect label for this courier.

Bookings held for review (pending_review, on_hold) have no label until Transdirect releases them.

Check readiness with HEAD

Section titled “Check readiness with HEAD”
HEAD /api/v5/bookings/{id}/label
HEAD /api/v5/bookings/{id}/a6label

A HEAD request returns 200 when the booking’s status says the label should be ready, and 400 when it is not yet. Neither has a body.

Terminal window
curl -I https://api.transdirect.com.au/api/v5/bookings/623630/label \
  -H "api-key: $TD_API_KEY"

HEAD only checks the status. A GET can still return 409 when the label document itself is not available yet, so treat a 409 as “try again shortly”. A sensible loop after confirming:

  1. HEAD the label every 30 to 60 seconds.
  2. When it returns 200, GET the label.
  3. If the GET returns 409, wait a minute and GET again.

Example request

Section titled “Example request”
Terminal window
curl -L https://api.transdirect.com.au/api/v5/bookings/623630/label \
  -H "api-key: $TD_API_KEY" \
  -o label-623630.pdf

Use -L: some labels are served as a short-lived redirect to file storage.

import { writeFile } from 'node:fs/promises';
import { client, getApiV5BookingsByIdLabel, headApiV5BookingsByIdLabel } from '@transdirect/api-sdk';


client.setConfig({ headers: { 'api-key': process.env.TD_API_KEY! } });


const ready = await headApiV5BookingsByIdLabel({ path: { id: '623630' } });
if (ready.response.status === 200) {
  const { data, response } = await getApiV5BookingsByIdLabel({ path: { id: '623630' } });
  if (response.ok && data instanceof Blob) {
    await writeFile('label-623630.pdf', Buffer.from(await data.arrayBuffer()));
  }
}

The SDK returns the PDF as a Blob in data. Use getApiV5BookingsByIdA6Label and headApiV5BookingsByIdA6Label for A6.

Response

Section titled “Response”

200 OK with Content-Type: application/pdf and the label in the body, or a 302 redirect to the PDF.

Errors

Section titled “Errors”
StatusBodyCause
400Empty (HEAD only)The label is not ready for this booking’s status.
401{"error":"missing_api_key"} or {"error":"invalid_api_key"}No key, or a key that is not active.
404{"error":"booking_not_found"}No booking with that id belongs to your account.
409See belowThe label is not available yet.
429{"error":"rate_limited"}More than 600 requests a minute on this key. Wait for the retry-after seconds.
{
  "error": "label_not_ready",
  "message": "The label is not ready through a V5-owned label artifact yet.",
  "booking_id": 623630,
  "status": "paid"
}

status is the booking’s raw status code at the time of the request. A request sent with Accept: text/html (for example, a browser) gets a readable HTML page instead of this JSON.

Try it

Section titled “Try it”

Open the API Explorer, add your key, and find Get a booking label PDF.

Section titled “Related”