Retrieve a Document - Kyckr Developer Portal

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:

List documents — discover which documents are available for a specific company
Create order — place an order for a chosen document
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 or Global Search. 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

curl --location 'https://api.kyckr.com/v2/companies/{kyckrId}/documents' \
--header 'Authorization: {{apiKey}}'

Path parameters

	Parameter	Required	Description
`kyckrId`	Yes

Response

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

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.

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

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.

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

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

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

Complete workflow

Obtain a kyckrId

Run a Company Search or Global Search to confirm the entity and retrieve its kyckrId.

List available documents

Call GET /v2/companies/{kyckrId}/documents to retrieve the document catalogue for that company. Note the id of the document you need.

Place an order

Call POST /v2/orders with the kyckrId, productId, and an optional customerReference. Store the orderId from the response.

Poll for completion

Call GET /v2/orders/{orderId} repeatedly until status is Complete or Failed. Polling once per minute is recommended.

Download the document

Use the path in links.document to download the file. Append ?format=pdf or ?format=json depending on the output you need.

API reference

List documents

Retrieve available documents for a company

Create order

Place an order for a specific document

Get order

Retrieve order status and download links

Documentation Index

​How it works

​Before you begin

​Step 1: List available documents

​Request

​Response

​Delivery times

​Step 2: Place an order

​Request

​Response

​Step 3: Check order status

​Request by orderId

​Request with filters

​Response

​Order status values

​Polling guidance

​Step 4: Download the document

​Request

​Complete workflow

​API reference

List documents

Create order

Get order

How it works

Before you begin

Step 1: List available documents

Request

Response

Delivery times

Step 2: Place an order

Request

Response

Step 3: Check order status

Request by orderId

Request with filters

Response

Order status values

Polling guidance

Step 4: Download the document

Request

Complete workflow

API reference