Retrieve label documents

After creating shipping labels, use GET /labels/{id} to retrieve printable airway bill documents. Pass a single identifier or comma-separated identifiers for batch retrieval. This guide covers the retrieval flow, batch requests, document formats, and practical considerations.

Retrieve the document URL

Use the id from the label creation response:

curl https://api.flexforward.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN"

const response = await fetch(
  'https://api.flexforward.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479',
  { headers: { 'x-rr-apikey': 'YOUR_API_KEY', 'x-rr-apitoken': 'YOUR_API_TOKEN' } }
);
const labelDoc = await response.json();
console.log(labelDoc.url); // URL to download the document

import requests

response = requests.get(
    'https://api.flexforward.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479',
    headers={'x-rr-apikey': 'YOUR_API_KEY', 'x-rr-apitoken': 'YOUR_API_TOKEN'}
)
label_doc = response.json()
print(label_doc['url'])  # URL to download the document

Response

200 OK

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "customerOrderNumber": "N2026-05-13-TEST-01",
  "url": "https://label-cdn.yunexpress.cn/labels/YT2503010001.pdf",
  "labelFormat": "pdf"
}

Field	Description
`id`	The label UUID (same as the request parameter).
`customerOrderNumber`	Customer order number associated with this label.
`url`	Direct download URL for the airway bill document.
`labelFormat`	Document format: `pdf` or `png`.

Download and print

Download the document from the returned url:

curl -o label.pdf "https://label-cdn.yunexpress.cn/labels/YT2503010001.pdf"

import { writeFile } from 'fs/promises';

const docResponse = await fetch(labelDoc.url);
const buffer = Buffer.from(await docResponse.arrayBuffer());
await writeFile(`label.${labelDoc.labelFormat}`, buffer);

doc_response = requests.get(label_doc['url'])
with open(f"label.{label_doc['labelFormat']}", 'wb') as f:
    f.write(doc_response.content)

Document behavior

Permanent URL — The document URL does not expire. You can store it and download the document at any time.
Formats — Documents are available as PDF or PNG, depending on the courier and label configuration.
Re-retrieval — Calling GET /labels/{id} multiple times returns the same URL. The endpoint is naturally idempotent.

Batch retrieval

Retrieve multiple label documents in a single request by passing comma-separated identifiers. You can mix label UUIDs and customer order numbers.

curl "https://api.flexforward.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479,N2026-05-13-TEST-02" \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN"

const response = await fetch(
  'https://api.flexforward.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479,N2026-05-13-TEST-02',
  { headers: { 'x-rr-apikey': 'YOUR_API_KEY', 'x-rr-apitoken': 'YOUR_API_TOKEN' } }
);
const result = await response.json();
result.labels.forEach(label => console.log(label.url));

import requests

response = requests.get(
    'https://api.flexforward.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479,N2026-05-13-TEST-02',
    headers={'x-rr-apikey': 'YOUR_API_KEY', 'x-rr-apitoken': 'YOUR_API_TOKEN'}
)
result = response.json()
for label in result['labels']:
    print(label['url'])

Batch response

200 OK

{
  "labels": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "customerOrderNumber": "N2026-05-13-TEST-01",
      "url": "https://label-cdn.yunexpress.cn/labels/YT2503010001.pdf",
      "labelFormat": "pdf"
    },
    {
      "id": "c8d9e0f1-2345-6789-abcd-ef0123456789",
      "customerOrderNumber": "N2026-05-13-TEST-02",
      "url": "https://label-cdn.yunexpress.cn/labels/YT2503010002.pdf",
      "labelFormat": "pdf"
    }
  ]
}

Field	Description
`labels`	Array of successfully resolved label documents. Missing or failed labels are omitted.
`labels[].id`	Label UUID.
`labels[].customerOrderNumber`	Customer order number associated with this label.
`labels[].url`	Direct download URL for the airway bill document.
`labels[].labelFormat`	Document format: `pdf` or `png`.

Missing or failed labels are silently omitted from the response. Compare the returned labels array against your requested identifiers to detect any that were not resolved.

Error handling

Status	Meaning	Action
200	Document URL retrieved	Download from the `url` field
403	Access denied	The label belongs to a different account
404	Label not found	Verify the label ID is correct
502	Upstream service error	Retry with exponential backoff

Getting Started

Guides

Use-Case Guides

Platform

Retrieve Label Documents

Retrieve label documents

Retrieve the document URL

Response

Download and print

Document behavior

Batch retrieval

Batch response

Error handling

Next steps

Track the shipment

Error Handling

​Retrieve label documents

​Retrieve the document URL

​Response

​Download and print

​Document behavior

​Batch retrieval

​Batch response

​Error handling

​Next steps

Track the shipment

Error Handling

Retrieve label documents

Retrieve the document URL

Response

Download and print

Document behavior

Batch retrieval

Batch response

Error handling

Next steps