# Get a waybill

`GET /v2/shipments/waybill?tracking_references=["UASDKRRB"]`

**Base URLs:**

- Sandbox: `https://api.sandbox.bobgo.co.za`
- Production: `https://api.bobgo.co.za`

**Authentication:** Bearer token required (see the Authentication page).

## Example request

```bash
curl -g -X GET 'https://api.sandbox.bobgo.co.za/v2/shipments/waybill?tracking_references=["UASDKRRB"]' \
  -H "Authorization: Bearer <API_KEY>"
```

Generates the waybill PDF for one or more shipments and returns **a JSON
envelope with a link to it**, not the file itself.

## Parameters

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `tracking_references` | array of string | one of these | The shipments to print. Sent as a JSON array in the query string, with no spaces: `["UASDKRRB","UASDKRRC"]`. |
| `ids` | array of integer | one of these | Shipment ids. Sent with `tracking_references`, only shipments matching both are printed. |
| `paper_size` | string | no | `A4`, `A5` or `A6`: the sheet you are printing on. Defaults to your account's waybill setting. |
| `waybill_size` | string | no | `A5` or `A6`: the waybill itself on that sheet. It cannot be larger than `paper_size`. `A4` is accepted but printed as `A5`. Defaults to your account's waybill setting. |
| `show_email_address` | boolean | no | Has no effect. Whether the delivery contact's email is printed is an account setting. |

```
GET /v2/shipments/waybill?tracking_references=["UASDKRRB"]&paper_size=A4&waybill_size=A5
```

Cancelled shipments, and references that are not on your account, are skipped.
If that leaves nothing to print, the call fails with
`No shipments to generate a waybill for.`

## Response

```json
{
  "pdf_queued": false,
  "file_history_id": null,
  "download_url": "https://...",
  "waybills_ready": true,
  "shipments": [
    {
      "id": 4455123,
      "tracking_reference": "UASDKRRB",
      "submission_status": "success",
      "failed_reason": null
    }
  ]
}
```

Three outcomes, and you have to branch on them:

| `waybills_ready` | `pdf_queued` | What happened |
| --- | --- | --- |
| `true` | `false` | Generated inline. `download_url` is the PDF, fetch it. The link works for 24 hours. |
| `true` | `true` | Queued for batch generation. `download_url` is null; poll with `file_history_id`. |
| `false` | `false` | Nothing was generated, at least one shipment is not printable yet. |

**Inline generation only ever handles one shipment.** Ask for two or more
shipments, or for a single shipment with more than 20 parcels, and the request
is always queued. There is no size at which a multi-shipment request comes back
inline, so if you are printing a batch, write the polling path first: it is the
normal case, not the exception. Collect the finished file with
[`GET /v2/file-history`](file_history.md).

The third row is the one to handle properly. A waybill only exists once the
courier has accepted the shipment, so a shipment still submitting, or one that
failed, produces no label. `shipments[]` tells you which: read
`submission_status` and `failed_reason` per shipment rather than treating the
empty `download_url` as an error.