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

<Info>
  Documents are sourced at the point of request from the originating company registry. Availability and format vary by jurisdiction.
</Info>

***

## How it works

Retrieving a document involves three sequential API calls:

1. **Filing search** — discover which documents are available for a specific company
2. **Place an order** — order a chosen document from the registry
3. **Check order status** — poll until the document is ready, then download

***

## Before you begin

You will need the company's `codeField` — a unique identifier returned by a [Company Search](/api-reference/company-search/search-by-name). If you do not yet have a `codeField`, run a company search first.

***

## Step 1: Search for available documents

Call the filing search endpoint to retrieve the full catalogue of documents available for a given company from its registry.

### Request

```bash theme={null}
curl --location 'https://rest.kyckr.com/core/filing/search/{isocode}/{codeField}' \
--header 'Authorization: {{apiKey}}'
```

**Path parameters**

| Parameter   | Required | Description                                                    |
| ----------- | -------- | -------------------------------------------------------------- |
| `isocode`   | Yes      | Two-digit ISO 3166-1 alpha-2 country code (e.g. `GB`).         |
| `codeField` | Yes      | The unique company identifier returned by the search endpoint. |

**Query parameters**

| Parameter         | Required | Description                                                                                                                                       |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ContinuationKey` | No       | Supplied when there are multiple pages of results. Pass the value of `continuationKeyField` from the previous response to retrieve the next page. |

### Example request

```bash theme={null}
curl --location 'https://rest.kyckr.com/core/filing/search/GB/11655290' \
--header 'Authorization: {{apiKey}}'
```

### Response

```json theme={null}
{
    "productsField": [
        {
            "idField": "CHON_Q0hfQ29tcGFueU1vcnRnYWdlc18x_MTE2NTUyOTA=",
            "priceTagField": "CH_CM",
            "priceField": "0",
            "vatChargeField": "0",
            "currencyField": "€",
            "productCodeField": "CH_CompanyMortgages_1",
            "companyCodeField": "11655290",
            "productFormatField": "PDF",
            "productTitleField": "Company Mortgages",
            "tierCodeField": "A",
            "tierValueField": "1.00"
        },
        {
            "idField": "CHON_Q0hfQ29tcGFueU9mZmljaWFsc18x_MTE2NTUyOTA=",
            "priceTagField": "CH_CO",
            "priceField": "0",
            "vatChargeField": "0",
            "currencyField": "€",
            "productCodeField": "CH_CompanyOfficials_1",
            "companyCodeField": "11655290",
            "productFormatField": "PDF",
            "productTitleField": "Company Officials",
            "tierCodeField": "A",
            "tierValueField": "1.00"
        }
    ]
}
```

**Key response fields**

| Field                      | Description                                                                                                                             |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `idField`                  | Unique document identifier — required to place an order.                                                                                |
| `productTitleField`        | Human-readable document name as provided by the registry.                                                                               |
| `productCodeField`         | The registry's own code for this document.                                                                                              |
| `productFormatField`       | The format of the file that will be delivered (e.g. `PDF`).                                                                             |
| `tierValueField`           | The cost in Kyckr Credits to order this document.                                                                                       |
| `deliveryTimeMinutesField` | Expected delivery time in minutes. `0` indicates real-time availability.                                                                |
| `continuationKeyField`     | Present when there are additional pages of results. Pass this value as the `ContinuationKey` query parameter to retrieve the next page. |

### Delivery times

Some documents — such as company profiles — are available in real time and will show a `deliveryTimeMinutesField` 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 `idField` from the filing search response as the `productKey`.

### Request

```bash theme={null}
curl --location 'https://rest.kyckr.com/core/filing/order' \
--header 'Authorization: {{apiKey}}' \
--header 'Content-Type: application/json' \
--data '{
    "countryISO": "GB",
    "productKey": "CHON_Q0hfQ29tcGFueU1vcnRnYWdlc18x_MTE2NTUyOTA=",
    "companyName": "Kyckr UK LTD",
    "orderRef": "Example 1"
}'
```

**Request body**

| Field         | Required | Description                                                                  |
| ------------- | -------- | ---------------------------------------------------------------------------- |
| `countryISO`  | Yes      | Two-digit ISO 3166-1 alpha-2 country code for the jurisdiction.              |
| `productKey`  | Yes      | The `idField` value returned by the filing search.                           |
| `companyName` | No       | The name of the company.                                                     |
| `orderRef`    | No       | Your own reference for this order — can be used to retrieve the order later. |

<Tip>
  Always supply an `orderRef`. It gives you a stable, human-readable identifier for each order and makes it easy to retrieve orders without needing to track internal order IDs.
</Tip>

### Response

A successful order returns a confirmation along with the `orderRef` you supplied.

```json theme={null}
{
    "Result": true,
    "Message": "Order Successful",
    "orderRef": "Example 1"
}
```

***

## Step 3: Check order status

Use the order status endpoint to check whether the document is ready. When the order is complete, the response includes a download URL for the file.

### Request by orderRef

```bash theme={null}
curl --location 'https://rest.kyckr.com/core/filing/order-status/30?orderRef=Example%201' \
--header 'Authorization: {{apiKey}}'
```

**Path parameters**

| Parameter | Description                                                                                              |
| --------- | -------------------------------------------------------------------------------------------------------- |
| `{days}`  | The number of days of order history to return (e.g. `30` returns orders placed within the last 30 days). |

**Query parameters**

| Parameter  | Description                                                                             |
| ---------- | --------------------------------------------------------------------------------------- |
| `orderRef` | Filter results to a specific order using the reference supplied when placing the order. |

### Response

```json theme={null}
{
    "aVAILABLEField": 1,
    "aWAITING_DELIVERYField": 0,
    "dELIVERY_ERRORField": 0,
    "orderDateTimeField": "2023-02-21T09:25:44.417",
    "orderReferenceField": "Example 1",
    "descriptionField": "Company Mortgages",
    "productOrderIdField": 2573359,
    "statusField": 3,
    "urlField": "https://data.kyckr.com/integration/1603863699",
    "formatField": "",
    "filingOrderIdField": "CHON_Q0hfQ29tcGFueU1vcnRnYWdlc18x_MTE2NTUyOTA="
}
```

### Order status values

| `statusField`  | Description                               |
| -------------- | ----------------------------------------- |
| `1`            | Pending — order is in progress.           |
| `2`, `21`, `3` | Complete — document is ready to download. |
| `5`            | Failed — order could not be fulfilled.    |
| `9`            | Cancelled.                                |

### Polling guidance

For documents that are not delivered in real time, poll the order status endpoint until `statusField` changes from `1` to a completion value (`2`, `21`, or `3`). Polling once per minute is recommended.

<Warning>
  Do not attempt to download the document until `statusField` indicates the order is complete. The `urlField` is only populated once the document is ready.
</Warning>

***

## Step 4: Download the document

When `statusField` indicates the order is complete, download the document using the URL in `urlField`.

### Request

```bash theme={null}
curl --location '{{urlField value}}' \
--header 'Authorization: {{apiKey}}' \
--output document.pdf
```

***

## Complete workflow

<Steps>
  <Step title="Search for the company">
    Run a Company Search to confirm the entity and retrieve its `codeField`.
  </Step>

  <Step title="Search for available documents">
    Call `GET /core/filing/search/{isocode}/{codeField}` to retrieve the document catalogue for that company. Note the `idField` of the document you need.
  </Step>

  <Step title="Place an order">
    Call `POST /core/filing/order` with the `countryISO`, `productKey`, and an optional `orderRef`. Confirm the order was successful from the response.
  </Step>

  <Step title="Poll for completion">
    Call `GET /core/filing/order-status/{days}` with your `orderRef` until `statusField` is `2`, `21`, or `3`. Polling once per minute is recommended.
  </Step>

  <Step title="Download the document">
    Use the URL in `urlField` to download the file.
  </Step>
</Steps>

***

## API reference

<CardGroup cols={3}>
  <Card title="Filing Search" icon="magnifying-glass" href="/api-reference/registry-documents/filing-search">
    Retrieve available documents for a company.
  </Card>

  <Card title="Place an Order" icon="cart-shopping" href="/api-reference/registry-documents/product-order">
    Order a specific document from the registry.
  </Card>

  <Card title="Order Status" icon="circle-check" href="/api-reference/registry-documents/order-status">
    Retrieve order status and the document download URL.
  </Card>
</CardGroup>