> ## 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.
# Retrieve a Document
> Search for available registry documents, place an order, and download the file.
Kyckr provides access to official documents sourced directly from company registries across 100+ countries. This guide covers the complete workflow: searching for available documents, placing an order, polling for completion, and downloading the file.
Documents are sourced at the point of request from the originating company registry. Availability and format vary by jurisdiction.
***
## How it works
Retrieving a document involves three sequential API calls:
1. **List documents** — discover which documents are available for a specific company
2. **Create order** — place an order for a chosen document
3. **Check order status** — poll until the document is ready, then download
***
## Before you begin
You will need the company's `kyckrId` — a unique identifier returned by a [Company Search](/documentation/features/search-for-a-company-v2) or [Global Search](/documentation/features/search-for-a-company-v2). The `kyckrId` takes the format `{countryISO}|{companyId}`, for example `GB|MTE2NTUyOTA`.
If you do not yet have a `kyckrId`, run a company search first.
***
## Step 1: List available documents
Call the documents endpoint to retrieve the full catalogue of documents available for a given company from its registry.
### Request
```bash theme={null}
curl --location 'https://api.kyckr.com/v2/companies/{kyckrId}/documents' \
--header 'Authorization: {{apiKey}}'
```
**Path parameters**
| | Parameter | Required | Description |
| --------- | --------- | -------- | ----------- |
| `kyckrId` | Yes | | |
### Response
```json theme={null}
{
"correlationId": "019ce19d-8fce-719c-947c-c2ddef9725e4",
"cost": {
"type": "credit",
"value": 0
},
"timeStamp": "2026-03-12T10:35:26.012603Z",
"details": "Success",
"data": [
{
"id": "Q0hPTnwxMTY1NTI5MHxHQl9DSF9DUHwxMDJ8Q29tcGFueSBQcm9maWxl",
"cost": {
"type": "credit",
"value": 1.00
},
"name": "Company Profile",
"category": "Extract",
"deliveryTimeMinutes": 0,
"documentFormat": [
"application/pdf"
]
},
{
"id": "Q0hPTnwxMTY1NTI5MHxHQl9DSF9DT3wxMDJ8Q29tcGFueSBPZmZpY2lhbHM=",
"cost": {
"type": "credit",
"value": 1.00
},
"name": "Company Officials",
"category": "Extract",
"deliveryTimeMinutes": 0,
"documentFormat": [
"application/pdf"
]
}
]
}
```
**Key response fields**
| Field | Description |
| --------------------- | ----------------------------------------------------------------------- |
| `id` | Unique document identifier — required to place an order |
| `name` | Human-readable document name as provided by the registry |
| `cost.value` | Cost in Kyckr Credits to order this document |
| `deliveryTimeMinutes` | Expected delivery time in minutes; `0` indicates real-time availability |
| `documentFormat` | MIME type of the file that will be delivered |
### Delivery times
Some documents — such as company profiles — are available in real time and will show a `deliveryTimeMinutes` of `0`. Others require retrieval by Kyckr's operations team and carry a non-zero delivery estimate. Close to 90% of available documents are delivered within 15 minutes or less.
***
## Step 2: Place an order
Once you have identified the document you need, place an order using the `id` from the documents list as the `productId`. You can also supply a `customerReference` to help organise and retrieve orders later.
### Request
```bash theme={null}
curl --location 'https://api.kyckr.com/v2/orders?customerReference=my-ref-001' \
--header 'Authorization: {{apiKey}}' \
--header 'Content-Type: application/json' \
--data '{
"kyckrId": "GB|MTE2NTUyOTA",
"productId": "Q0hPTl9RMGhmUTI5dGNHRnVlVTF2Y25SbllXZGxjMTh4X01URTJOVFV5T1RBPQ=="
}'
```
**Query parameters**
| Parameter | Required | Description |
| ------------------- | -------- | --------------------------------------------------------------------- |
| `customerReference` | No | Your own reference for this order; can be used to filter orders later |
**Request body**
| Field | Required | Description |
| ----------- | -------- | --------------------------------------------- |
| `kyckrId` | Yes | Unique company identifier |
| `productId` | Yes | The `id` value returned by the documents list |
Always supply a `customerReference`. It gives you a stable, human-readable identifier for each order and makes it easy to filter your order history without needing to track internal order IDs.
### Response
A successful order returns a confirmation and a unique `orderId` that you will use to track and retrieve the document.
```json theme={null}
{
"correlationId": "4ca0f21f4b6b4b93a9f64a040914ea4a",
"customerReference": "my-ref-001",
"timeStamp": "2024-01-25T11:32:26.7086668Z",
"details": "Success",
"data": {
"status": "Pending",
"orderId": 302151
}
}
```
***
## Step 3: Check order status
Use the orders endpoint to check whether the document is ready. When the order is complete, the response includes download links for the file.
### Request by orderId
```bash theme={null}
curl --location 'https://api.kyckr.com/v2/orders/{orderId}' \
--header 'Authorization: {{apiKey}}' \
--header 'Content-Type: application/json'
```
### Request with filters
To retrieve multiple orders, omit the `orderId` path parameter and use query parameters to scope the results.
```bash theme={null}
curl --location 'https://api.kyckr.com/v2/orders?pageNumber=1&pageSize=100&startDate=2024-01-20&endDate=2024-01-26' \
--header 'Authorization: {{apiKey}}' \
--header 'Content-Type: application/json'
```
**Query parameters**
| Parameter | Description |
| ------------------- | ---------------------------------------------------------- |
| `pageNumber` | Page number for pagination (default: `1`) |
| `pageSize` | Number of results per page (default: `100`) |
| `startDate` | Return orders placed on or after this date (`YYYY-MM-DD`) |
| `endDate` | Return orders placed on or before this date (`YYYY-MM-DD`) |
| `customerReference` | Filter by the reference supplied when placing the order |
### Response
```json theme={null}
{
"correlationId": "48b9e32527974ca0bc1f606d198669c8",
"customerReference": "my-ref-001",
"timeStamp": "2024-01-25T12:55:22.351548Z",
"details": "Success",
"data": {
"orderId": "302151",
"orderDate": "2024-01-25T11:32:26.7086668Z",
"customerReference": "my-ref-001",
"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"
}
}
}
```
### Order status values
| `status` | Description |
| ---------- | ---------------------------------------------------- |
| `Pending` | Order has been placed and is in progress |
| `Complete` | Document is ready — use `links.document` to download |
| `Failed` | Order could not be fulfilled |
### Polling guidance
For documents that are not delivered in real time, poll the order status endpoint until `status` changes from `Pending` to `Complete` or `Failed`. Polling once per minute is a sensible default. Depending on the jurisdictions and document types your integration relies on, a more tailored interval may be appropriate.
Do not attempt to download the document until `status` is `Complete`. The `links` object is only present in the response once the order has been fulfilled.
***
## Step 4: Download the document
When `status` is `Complete`, download the document using the path from `links.document`, appended to the API base URL. Two download formats are available.
| Format | Description |
| ------------- | ------------------------------------------------------- |
| `format=pdf` | Returns the document as a PDF file |
| `format=json` | Returns structured data in JSON format, where available |
### Request
```bash theme={null}
curl --location 'https://api.kyckr.com/v2/orders/302151/download?format=pdf' \
--header 'Authorization: {{apiKey}}' \
--output document.pdf
```
***
## Complete workflow
Run a Company Search or Global Search to confirm the entity and retrieve its `kyckrId`.
Call `GET /v2/companies/{kyckrId}/documents` to retrieve the document catalogue for that company. Note the `id` of the document you need.
Call `POST /v2/orders` with the `kyckrId`, `productId`, and an optional `customerReference`. Store the `orderId` from the response.
Call `GET /v2/orders/{orderId}` repeatedly until `status` is `Complete` or `Failed`. Polling once per minute is recommended.
Use the path in `links.document` to download the file. Append `?format=pdf` or `?format=json` depending on the output you need.
***
## API reference
Retrieve available documents for a company
Place an order for a specific document
Retrieve order status and download links