> ## Documentation Index
> Fetch the complete documentation index at: https://openapidocs.flexforwardship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve Label Documents

> How to retrieve and use printable airway bill documents after label creation

# 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:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.flexforward.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.flexforward.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479',
    { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' } }
  );
  const labelDoc = await response.json();
  console.log(labelDoc.url); // URL to download the document
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.flexforward.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479',
      headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
  )
  label_doc = response.json()
  print(label_doc['url'])  # URL to download the document
  ```
</CodeGroup>

### Response

```json 200 OK theme={null}
{
  "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`:

<CodeGroup>
  ```bash cURL theme={null}
  curl -o label.pdf "https://label-cdn.yunexpress.cn/labels/YT2503010001.pdf"
  ```

  ```javascript Node.js theme={null}
  import { writeFile } from 'fs/promises';

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

  ```python Python theme={null}
  doc_response = requests.get(label_doc['url'])
  with open(f"label.{label_doc['labelFormat']}", 'wb') as f:
      f.write(doc_response.content)
  ```
</CodeGroup>

## 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.flexforward.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479,N2026-05-13-TEST-02" \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.flexforward.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479,N2026-05-13-TEST-02',
    { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' } }
  );
  const result = await response.json();
  result.labels.forEach(label => console.log(label.url));
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.flexforward.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479,N2026-05-13-TEST-02',
      headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
  )
  result = response.json()
  for label in result['labels']:
      print(label['url'])
  ```
</CodeGroup>

### Batch response

```json 200 OK theme={null}
{
  "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`.                                                      |

<Note>
  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.
</Note>

## 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           |

## Next steps

<CardGroup cols={2}>
  <Card title="Track the shipment" icon="location-dot" href="/guides/tracking-updates">
    Monitor shipment progress after printing and attaching the label.
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/error-handling">
    Full reference for all HTTP status codes and error response formats.
  </Card>
</CardGroup>