Skip to main content
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. 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. 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
ParameterRequiredDescription
isocodeYesTwo-digit ISO 3166-1 alpha-2 country code (e.g. GB).
codeFieldYesThe unique company identifier returned by the search endpoint.
Query parameters
ParameterRequiredDescription
ContinuationKeyNoSupplied 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
FieldDescription
idFieldUnique document identifier — required to place an order.
productTitleFieldHuman-readable document name as provided by the registry.
productCodeFieldThe registry’s own code for this document.
productFormatFieldThe format of the file that will be delivered (e.g. PDF).
tierValueFieldThe cost in Kyckr Credits to order this document.
deliveryTimeMinutesFieldExpected delivery time in minutes. 0 indicates real-time availability.
continuationKeyFieldPresent 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
FieldRequiredDescription
countryISOYesTwo-digit ISO 3166-1 alpha-2 country code for the jurisdiction.
productKeyYesThe idField value returned by the filing search.
companyNameNoThe name of the company.
orderRefNoYour 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
ParameterDescription
{days}The number of days of order history to return (e.g. 30 returns orders placed within the last 30 days).
Query parameters
ParameterDescription
orderRefFilter 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

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

​
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

1

Search for the company

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

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

Place an order

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

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

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.