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

# Download documents

> Poll order status and download documents when ready.

To obtain the URL link to the PDF document, use the order status call. A specific order can be targeted using an order ID, or all orders within a certain time period can be retrieved.

[Order status API reference](/api-reference/orders/get-single-order)

### Polling

For documents with a delivery time, poll the system until the document becomes available. The order is ready when the `status` changes from `Pending` to `Complete`.

Polling once every minute is recommended, but more bespoke setups can be arranged depending on the jurisdictions and documents typically ordered.

### Document status

The `status` field describes the state of the document order.

| status     | Description                        |
| ---------- | ---------------------------------- |
| `Pending`  | Order in progress                  |
| `Complete` | Ready - Document ready to download |
| `Failed`   | Order failed                       |

### Order status

When retrieving a list of product orders, all orders can be fetched. Specific orders can also be found using `orderId`. The number of results returned can be controlled using pagination parameters (`pageNumber`, `pageSize`) and date filters (`startDate`, `endDate`).

Parameters:

* `orderId` (specified in the order response)
* `pageNumber` (page number for pagination, default: 1)
* `pageSize` (number of results per page, default: 100)
* `startDate` (filter orders from this date, format: YYYY-MM-DD)
* `endDate` (filter orders until this date, format: YYYY-MM-DD)
* `customerReference` (filter by customer reference provided when ordering)

#### Example request by orderId

The example below uses an order ID to check the status and retrieve download links

```curl theme={null}
curl --location 'https://api.kyckr.com/v2/orders/302151' \
--header 'Authorization: {{apiKey}}' \
--header 'Content-Type: application/json'
```

#### Example response

```json theme={null}
{
    "correlationId": "48b9e32527974ca0bc1f606d198669c8",
    "customerReference": "Example Ref",
    "timeStamp": "2024-01-25T12:55:22.351548Z",
    "details": "Success",
    "data": {
        "orderId": "302151",
        "orderDate": "2024-01-25T11:32:26.7086668Z",
        "customerReference": "Example Ref",
        "status": "Complete",
        "cost": {
            "creditCost": 1
        },
        "productDetails": {
            "productName": "CH_CompanyMortgages_1",
            "productId": "Q0hPTl9RMGhmUTI5dGNHRnVlVTF2Y25SbllXZGxjMTh4X01URTJOVFV5T1RBPQ==",
            "productCategory": "Company Mortgages"
        },
        "companyDetails": {
            "companyName": "Kyckr",
            "companyNumber": "11655290",
            "kyckrID": "GB|MTE2NTUyOTA"
        },
        "links": {
            "data": "/orders/302151/download?format=json",
            "document": "/orders/302151/download?format=pdf"
        }
    }
}
```

### Downloading documents

When the order status is `Complete`, the document can be downloaded using the URL provided in the `links.document` field. The download URL is a relative path that should be appended to the API base URL.

#### Example download request

```curl theme={null}
curl --location 'https://api.kyckr.com/v2/orders/302151/download?format=pdf' \
--header 'Authorization: {{apiKey}}' \
--output document.pdf
```

The download endpoint supports two formats:

* `format=pdf` - Returns the document in PDF format
* `format=json` - Returns structured data in JSON format (if available)