Purpose of the API

The NL Official Documents API allows you to order, track, and download official documents from the Dutch Chamber of Commerce (KVK).

Instead of manually navigating the KVK website, you can programmatically discover available documents, place orders, monitor their processing status, and download the resulting files in multiple formats.
You can use this API to:

• Discover which official documents are available for a given organization or branch
• Order business register extracts (standard extracts)
• Track the asynchronous processing status of your orders
• Download completed documents in PDF, HTML, or JSON format
• Reuse previously ordered documents from cache without placing a new order

The API is ideal for KYC/KYB onboarding, compliance workflows, legal due diligence, financial audits, and any process that requires official Dutch trade register documents.

How to use?

📌 Overview of the Flow

1. Discover Supported Documents
   Start by calling
   GET /nl/organizations/official-documents/v1/
   to check which documents are available for a specific organization. The response includes document types, prices, expected delivery times, and available formats.

2. Place an Order
   Once you have identified the document you want, call:
   POST /nl/organizations/official-documents/v1/orders
   providing the documentType and organizationID (and optionally branchID).

3. Track Order Status
   Orders are processed asynchronously. Poll the order status by calling:
   GET /nl/organizations/official-documents/v1/orders/{order_id}
   until the status changes from pending to done.

4. Download the Document
   When the status is done, download the document by calling:
   GET /nl/organizations/official-documents/v1/orders/{order_id}/document
   Specify the desired format via the Accept header.

5. Reuse Existing Documents (Cache)
   Before placing a new order, you can check if a document is already available in the cache:
   GET /nl/organizations/official-documents/v1/documents
   If found, download it directly via:
   GET /nl/organizations/official-documents/v1/documents/{document_id}

🌀 Flow Behavior

• Orders are processed asynchronously. The POST call returns immediately with a pending status — you must poll until the order completes.
• If an order fails during processing, you can retry specific activities using
  POST /nl/organizations/official-documents/v1/orders/{order_id}.
• The cache endpoint (/v1/documents) returns documents previously ordered by any customer. Each document includes an upToDate flag indicating whether it reflects the latest KVK data.
• All list endpoints support pagination via page[number] and page[size].
• All responses follow JSON:API conventions for consistency.

🔢 Versioning

Current version prefix:
/nl/organizations/official-documents/v1/

Future versions will follow /v2/, /v3/, etc.

Base URL

https://api.company.info

🔑 Authentication

All requests must be authenticated using one of the following methods:

💡

You only need to provide one of these headers per request. If both are present, the bearer token takes precedence.

🧩 Core Concepts

Before diving into the endpoints it helps to understand the domain model:

All Endpoints

Below is a complete list of API endpoints.

All endpoint paths are relative to /nl/organizations/official-documents.

❗ These endpoints incur usage-based charges.

1. Discover Supported Documents

GET /nl/organizations/official-documents/v1/

Check which official documents are available for a specific organization.

Description

Returns the list of document types available for the given Organization ID (and optionally branch ID), including pricing, expected delivery time, available formats, and availability status.

Request Parameters

Headers

Query Parameters

Example Request

curl -X GET "https://api.company.info/nl/organizations/official-documents/v1/?filter[organizationID]=33302047" \
  -H "X-API-KEY: YOUR_API_KEY"

Example Response

{
  "data": {
    "type": "33302047",
    "attributes": {
      "organizationID": "33302047",
      "date": "2024-03-15T11:19:39+01:00",
      "documents": [
        {
          "documentType": "standardExtract",
          "mimeType": "text/html",
          "price": 2.95,
          "available": true,
          "expectedTime": 60,
          "description": "Business Register Extract"
        }
      ]
    }
  },
  "links": {
    "self": "https://api.company.info/nl/organizations/official-documents/v1/?filter[organizationID]=33302047"
  }
}

Response Fields — data.attributes

Response Fields — documents[]

2. 📝 Place an Order

POST /nl/organizations/official-documents/v1/orders

Place a new order for an official document.

Description

Creates a new document order. The order is processed asynchronously — the response will include an order ID and a pending status. You must poll the order status until it changes to done before downloading.

⁉️ Request Parameters

Headers

Request Body

The body must contain a data object with the following fields:

Example Request

curl -X POST "https://api.company.info/nl/organizations/official-documents/v1/orders" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "type": "orders",
          "attributes": {
            "documentType": "standardExtract",
            "organizationID": "33302047"
          }
        }
      }'

Example Response

{
  "data": {
    "id": "01HS0SZQECSKQ8NV20391MZ0R1",
    "type": "orders",
    "attributes": {
      "documentType": "standardExtract",
      "status": "pending",
      "organizationID": "33302047",
      "mimeTypes": [
        "text/html",
        "application/pdf",
        "application/json"
      ],
      "createdAt": "2024-03-15T11:19:39+01:00"
    },
    "relationships": {
      "histories": {
        "data": {
          "type": "histories",
          "id": "01HS0SZQFHRW8TCGRYW8536Z0X"
        }
      }
    },
    "links": {
      "self": "https://api.company.info/nl/organizations/official-documents/v1/orders/01HS0SZQECSKQ8NV20391MZ0R1"
    }
  },
  "included": [
    {
      "type": "histories",
      "id": "01HS0SZQFHRW8TCGRYW8536Z0X",
      "attributes": {
        "status": "pending",
        "title": "orderIsProcessing",
        "detail": "",
        "createdAt": "2024-03-15T11:19:39+01:00"
      }
    }
  ],
  "links": {
    "self": "https://api.company.info/nl/organizations/official-documents/v1/orders/01HS0SZQECSKQ8NV20391MZ0R1"
  }
}

Response Fields — data

Response Fields — included[]

Processing history records are side-loaded in the included array.

3. 📋 List Orders

GET /nl/organizations/official-documents/v1/orders

Retrieve a paginated list of previously placed orders.

Description

Returns all orders matching the specified filters. Useful for finding a previously placed order or auditing your order history.

⁉️ Request Parameters

Headers

Query Parameters

Example Request

curl -X GET "https://api.company.info/nl/organizations/official-documents/v1/orders?filter[status]=done&filter[organizationID]=33302047" \
  -H "X-API-KEY: YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "01HS0SZQECSKQ8NV20391MZ0R1",
      "type": "orders",
      "attributes": {
        "documentType": "standardExtract",
        "status": "done",
        "organizationID": "33302047",
        "mimeTypes": [
          "text/html",
          "application/pdf",
          "application/json"
        ],
        "createdAt": "2024-03-15T11:19:39+01:00"
      },
      "relationships": {
        "histories": {
          "data": {
            "type": "histories",
            "id": "01HS0SZQFHRW8TCGRYW8536Z0X"
          }
        }
      },
      "links": {
        "self": "https://api.company.info/nl/organizations/official-documents/v1/orders/01HS0SZQECSKQ8NV20391MZ0R1"
      }
    }
  ],
  "included": [
    {
      "type": "histories",
      "id": "01HS0SZQFHRW8TCGRYW8536Z0X",
      "attributes": {
        "status": "done",
        "title": "orderIsDone",
        "detail": "",
        "createdAt": "2024-03-15T11:20:15+01:00"
      }
    }
  ],
  "links": {
    "first": "...?page[number]=1&page[size]=10",
    "last": "...?page[number]=1&page[size]=10",
    "self": "...?page[number]=1&page[size]=10"
  },
  "meta": {
    "totalResults": 1,
    "totalPages": 1
  }
}

4. 📄 Get a Single Order

GET /nl/organizations/official-documents/v1/orders/{order_id}

Retrieve a specific order by its ID.

Description

Returns the full details of the specified order, including its current status and processing history. Use this to poll order status until it reaches done.

⁉️ Request Parameters

Path

Headers

Example Request

curl -X GET "https://api.company.info/nl/organizations/official-documents/v1/orders/01HS0SZQECSKQ8NV20391MZ0R1" \
  -H "X-API-KEY: YOUR_API_KEY"

Example Response

{
  "data": {
    "id": "01HS0SZQECSKQ8NV20391MZ0R1",
    "type": "orders",
    "attributes": {
      "documentType": "standardExtract",
      "status": "done",
      "organizationID": "33302047",
      "mimeTypes": [
        "text/html",
        "application/pdf",
        "application/json"
      ],
      "createdAt": "2024-03-15T11:19:39+01:00"
    },
    "relationships": {
      "histories": {
        "data": {
          "type": "histories",
          "id": "01HS0SZQFHRW8TCGRYW8536Z0X"
        }
      }
    },
    "links": {
      "self": "https://api.company.info/nl/organizations/official-documents/v1/orders/01HS0SZQECSKQ8NV20391MZ0R1"
    }
  },
  "included": [
    {
      "type": "histories",
      "id": "01HS0SZQFHRW8TCGRYW8536Z0X",
      "attributes": {
        "status": "done",
        "title": "orderIsDone",
        "detail": "",
        "createdAt": "2024-03-15T11:20:15+01:00"
      }
    }
  ],
  "links": {
    "self": "https://api.company.info/nl/organizations/official-documents/v1/orders/01HS0SZQECSKQ8NV20391MZ0R1"
  }
}

Order Statuses

5. 🔄 Retry a Failed Order Activity

POST /nl/organizations/official-documents/v1/orders/{order_id}

Retry a specific activity on a failed order.

Description

If an order fails during the ordering or conversion step, you can retry the failed activity without placing a new order. This is useful for transient failures.

⁉️ Request Parameters

Path

Headers

Request Body

Example Request

curl -X POST "https://api.company.info/nl/organizations/official-documents/v1/orders/01HS0SZQECSKQ8NV20391MZ0R1" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "type": "orders",
          "attributes": {
            "activity": "convert"
          }
        }
      }'

Example Response

204 No Content — the activity has been retried successfully.

6. 📥 Download a Document (from Order)

GET /nl/organizations/official-documents/v1/orders/{order_id}/document

Download the document associated with a completed order.

Description

Returns the document content in the format specified by the Accept header. The order must have a status of done before the document can be downloaded.

⁉️ Request Parameters

Path

Headers

Example Request

curl -X GET "https://api.company.info/nl/organizations/official-documents/v1/orders/01HS0SZQECSKQ8NV20391MZ0R1/document" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/pdf" \
  --output document.pdf

Example Response

The response body contains the document content in the requested format.

7. 📋 List Cached Documents

GET /nl/organizations/official-documents/v1/documents

Retrieve a paginated list of previously ordered documents available in cache.

Description

Returns documents that have been previously ordered (by you or another customer) and are available for immediate download. This allows you to reuse existing documents without placing a new order and incurring additional charges. Each document includes an upToDate flag indicating whether it reflects the latest KVK data.

⁉️ Request Parameters

Headers

Query Parameters

Example Request

curl -X GET "https://api.company.info/nl/organizations/official-documents/v1/documents?filter[organizationID]=33302047" \
  -H "X-API-KEY: YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "MDFLRVI5TldFMkdHN0I1Nkc1MENSQ1hRV0s...",
      "type": "documents",
      "attributes": {
        "documentType": "standardExtract",
        "organizationID": "33302047",
        "mimeTypes": [
          "text/html",
          "application/pdf",
          "application/json"
        ],
        "createdAt": "2024-03-15T11:20:15+01:00",
        "upToDate": true
      },
      "links": {
        "self": "https://api.company.info/nl/organizations/official-documents/v1/documents/MDFLRVI5TldFMkdHN0I1Nkc1MENSQ1hRV0s..."
      }
    }
  ],
  "links": {
    "first": "...?page[number]=1&page[size]=10",
    "last": "...?page[number]=1&page[size]=10",
    "self": "...?page[number]=1&page[size]=10"
  },
  "meta": {
    "totalResults": 1,
    "totalPages": 1
  }
}

Response Fields — data[]

8. 📥 Download a Cached Document

GET /nl/organizations/official-documents/v1/documents/{document_id}

Download a document directly from cache.

Description

Returns the document content in the format specified by the Accept header. This allows downloading without placing a new order.

⁉️ Request Parameters

Path

Headers

Example Request

curl -X GET "https://api.company.info/nl/organizations/official-documents/v1/documents/MDFLRVI5TldFMkdHN0I1Nkc1MENSQ1hRV0s.../document" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/pdf" \
  --output cached_document.pdf

Example Response

The response body contains the document content in the requested format (same as Endpoint 6).

📑 Document Types

Document-Specific Attributes

Some attributes are optional when placing an order:

📤 Supported Formats

Documents can be downloaded in the following formats via the Accept header:

⚠️

Not all formats may be available for every document type. Check

the mimeTypes field in the order or document response to see which formats are supported.

🔢 Pagination

The API uses JSON:API-style pagination with meta and links objects on list endpoints (GET /v1/orders and GET /v1/documents).

Request Parameters

Response Fields

"meta": {
  "totalResults": 150,
  "totalPages": 15
},
"links": {
  "first": "...?page[number]=1&page[size]=10",
  "last": "...?page[number]=15&page[size]=10",
  "self": "...?page[number]=2&page[size]=10",
  "next": "...?page[number]=3&page[size]=10",
  "prev": "...?page[number]=1&page[size]=10"
}

• Use links.next until it no longer appears or until you have all records.
• Use totalResults and totalPages to build progress indicators or pagination controls in your UI.

🔄 Typical Order Workflow

Here is a recommended workflow for ordering and downloading documents:

1. Discover available documents (Endpoint 1) — check what is available for the target organization.
2. Check cache first (Endpoint 7) — see if the document you need has already been ordered and is available for immediate download.
3. Download from cache (Endpoint 8) — if found and upToDate is true, download directly and skip ordering.
4. Place an order (Endpoint 2) — if not cached or out of date, place a new order.
5. Poll for completion (Endpoint 4) — periodically check the order status until it is done.
6. Download the document (Endpoint 6) — download in your preferred format.

Example Polling Loop

# Poll every 10 seconds until status is "done"
curl -X GET "https://api.company.info/nl/organizations/official-documents/v1/orders/01HS0SZQECSKQ8NV20391MZ0R1" \
  -H "X-API-KEY: YOUR_API_KEY"

⚠️ Rate Limiting / Other Limitations

• Some environments may enforce rate limits per API key.
• Document ordering is subject to KVK processing times — the expectedTime field in the discovery response gives an estimate.
• Wherever possible, check the cache before placing new orders to avoid unnecessary charges.

⚠️ Possible errors / unexpected behavior

Below is a table with the most common HTTP error responses.

Example Error Response

{
  "errors": [
    {
      "status": "423",
      "code": "423",
      "title": "failed on downloading document",
      "detail": "the requested document is not ready yet"
    }
  ]
}

🛠️ Try it yourself!

✅

Ready to try it out? Head over to our API reference where you can easily test the API yourself.

From there, you can:

• Explore endpoints
• Play with example requests and responses
• See schemas and parameter details
• Use your own API key to test real responses

🔤 Glossary

Processing History Titles