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. {id} accepts either the label UUID or the customerOrderNumber you supplied when creating the label:

curl https://api.flexforwardship.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.flexforwardship.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.flexforwardship.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`, matching the format selected at creation.

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

Time-limited URL — The url is a short-lived download link (currently valid for about one hour, subject to change). Do not persist it. Call GET /labels/{id} again to obtain a fresh URL when you need to download.
Formats — Set label.format to "PDF" or "PNG" when creating a label. Omitting it selects PDF. GET /labels/{id} returns the selected format as lowercase labelFormat: "pdf" or "png"; it does not change the format. The examples on this page retrieve a PDF label.
Re-retrieval — Each call returns a fresh URL for the same document. The document content is stable; the URL string is not.

Batch retrieval

Retrieve multiple label documents in a single request by passing comma-separated identifiers. You can mix label UUIDs and customer order numbers. How the identifier list is processed:

The path parameter is split on commas. Each piece is trimmed, empty pieces are dropped, and duplicates are collapsed, so a,,a, b is treated as a,b.
One remaining identifier returns the single-label response (404 if it does not exist, 422 if the label failed at the courier). Two or more return the labels array shape described below.
Labels that do not exist and labels whose courier submission failed are omitted from labels without an error entry. If none of the identifiers resolve, the request returns 404.
There is no enforced maximum today. Keep batches small (tens, not hundreds); each identifier resolves a document from the courier.

New label requests reject commas in customerOrderNumber; see Customer order numbers for the current restrictions. If a legacy record has a comma in its order number, retrieve it using the label UUID because this endpoint splits identifiers on commas.

curl "https://api.flexforwardship.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.flexforwardship.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.flexforwardship.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; compare the returned `id` / `customerOrderNumber` values against your request to detect them.
`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`, matching that label’s requested format.

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	Account access denied	Your account is not permitted to call the API (for example, a blocked account)
404	Label not found	No label with that UUID or `customerOrderNumber` exists in your account. Labels owned by other accounts are also reported as 404.
422	Label creation failed	A single requested label failed at the courier; create a replacement label after fixing the cause. Failed labels are omitted from batch results.
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