Skip to main content

​
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 "Authorization: Bearer YOUR_API_TOKEN"

​
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"
}
FieldDescription
idThe label UUID (same as the request parameter).
customerOrderNumberCustomer order number associated with this label.
urlDirect download URL for the airway bill document.
labelFormatDocument 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"

​
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 "Authorization: Bearer YOUR_API_TOKEN"

​
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"
    }
  ]
}
FieldDescription
labelsArray of successfully resolved label documents. Missing or failed labels are omitted.
labels[].idLabel UUID.
labels[].customerOrderNumberCustomer order number associated with this label.
labels[].urlDirect download URL for the airway bill document.
labels[].labelFormatDocument 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

StatusMeaningAction
200Document URL retrievedDownload from the url field
403Access deniedThe label belongs to a different account
404Label not foundVerify the label ID is correct
502Upstream service errorRetry with exponential backoff

​
Next steps

Track the shipment

Monitor shipment progress after printing and attaching the label.

Error Handling

Full reference for all HTTP status codes and error response formats.