Retrieve a Document

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:

Filing search — discover which documents are available for a specific company
Place an order — order a chosen document from the registry
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. 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

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

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

Response

{
    "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

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.

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.

Response

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

{
    "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

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

{
    "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.

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

Step 4: Download the document

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

Request

curl --location '{{urlField value}}' \
--header 'Authorization: {{apiKey}}' \
--output document.pdf

Complete workflow

Search for the company

Run a Company Search to confirm the entity and retrieve its codeField.

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.

Place an order

Call POST /core/filing/order with the countryISO, productKey, and an optional orderRef. Confirm the order was successful from the response.

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.

Download the document

Use the URL in urlField to download the file.

API reference

Filing Search

Retrieve available documents for a company.

Place an Order

Order a specific document from the registry.

Order Status

Retrieve order status and the document download URL.

Getting Started

Useful Information

Features

Platform Details

How it works

Before you begin

Step 1: Search for available documents

Request

Example request

Response

Delivery times

Step 2: Place an order

Request

Response

Step 3: Check order status

Request by orderRef

Response

Order status values

Polling guidance

Step 4: Download the document

Request

Complete workflow

API reference

Filing Search

Place an Order

Order Status

​How it works

​Before you begin

​Step 1: Search for available documents

​Request

​Example request

​Response

​Delivery times

​Step 2: Place an order

​Request

​Response

​Step 3: Check order status

​Request by orderRef

​Response

​Order status values

​Polling guidance

​Step 4: Download the document

​Request

​Complete workflow

​API reference

Filing Search

Place an Order

Order Status

How it works

Before you begin

Step 1: Search for available documents

Request

Example request

Response

Delivery times

Step 2: Place an order

Request

Response

Step 3: Check order status

Request by orderRef

Response

Order status values

Polling guidance

Step 4: Download the document

Request

Complete workflow

API reference