🇳🇱 NL Organizations API

💻 Purpose of the API

The NL Organizations API provides a unified way to search, discover, and retrieve detailed profiles for Dutch organizations.

It aggregates information from authoritative sources (such as Trade Register, tax and financial datasets) and exposes them using consistent JSON:API standards.
You can use this API to:

Search across millions of Dutch organizations and branches
Filter, sort, and aggregate results by attributes such as location, activities (SBI codes), financial fields, lifecycle events, and more
Retrieve complete organization profiles with extended information (e.g., ownership structure, financial figures, management)
Retrieve branch-level data for more granular use cases

The API is ideal for compliance screening, B2B onboarding, KYC/KYB processes, market research, sales enrichment, and internal data standardization.

🤔 How to use?

📌 Overview of the Flow

Search Entities
Start by calling
GET /nl/organizations/profiles/v1/entities
to find organizations or branches using:
- Full-text search (query)
- Structured filtering (filter)
- Structured matching (match)
- Sorting (sort)
- Aggregations (aggregate)
- Pagination (page[number], page[size])
Retrieve Organization Profile
Once you have an organization_id, call:
GET /nl/organizations/profiles/v1/organizations/{organization_id}
This returns a rich profile with identifiers, contact data, financial info, lifecycle, ownership, etc.
Optional: add extensions to retrieve additional blocks of data.
Retrieve Organization Branches
To fetch all branches for the organization, call:
GET /nl/organizations/profiles/v1/organizations/{organization_id}/branches
Retrieve a Single Branch
To retrieve full details for a specific branch:
GET /nl/organizations/profiles/v1/organizations/{organization_id}/branches/{branch_id}

🌀 Flow Behavior

If your search query does not match anything, the API returns an empty data: [] array --- this is normal and not an error.
Pagination allows you to iterate through all results efficiently.
Some endpoints support include to return related resources.
Profile endpoints support extensions to fetch optional, additional data blocks.
All responses follow JSON:API conventions for consistency.

🔢 Versioning

Current version prefix:
/nl/organizations/profiles/v1/

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

🌐 Base URL

https://api.company.info

📚 All Endpoints

Below is a complete list of API endpoints.

❗ These endpoints incur usage-based charges.

1. 🔍 Search Entities

GET /nl/organizations/profiles/v1/entities

Search for branches, legal entities, and transitioned organizations.

Description

Use this endpoint to perform full-text searches, structured filtering, prefix matching, sorting, and aggregations across all entity types.

⁉️ Request Parameters

Headers

Name	Type	Description
`X-API-KEY`	string	Required. Your API key.

Query Parameters (high-level)

Parameter	Location	Type	Description
`query`	query	string	Full-text search across multiple fields. Minimum 2 characters. Supports fuzzy search.
`filter[...]`	query	object (deepObject)	Exact and range filters for identity, status, classification, location, dates, personnel, financials.
`match[...]`	query	object (deepObject)	Partial/prefix-based matching on key attributes (e.g., city, tradeRegisterID, branchNumber).
`sort`	query	array (form)	Comma-separated list of sort fields. Prefix with `-` for descending. Defaults to `-id`.
`aggregate[...]`	query	object (deepObject)	Aggregation definition: fields and bucket sizes.
`fuzziness`	query	boolean	Enabling Fuzzy search
`page[number]`	query	integer	Page number.
`page[size]`	query	integer	Page size.

📘
All available parameters can also be found in our API Reference.

Example request

curl -X GET "https://api.company.info/nl/organizations/profiles/v1/entities?query=company&sort=-name&page[size]=10" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/vnd.api+json"

Example Response

{
  "data": [
    {
      "type": "branches",
      "id": "112233445566",
      "attributes": {
        "name": "company.info",
        "type": "branch",
        "branch": {
          "name": "company.info",
          "isMain": true
        },
        "identifiers": {
          "organization": {
            "tradeRegister": {
              "system": "tradeRegister",
              "value": "12345678"
            }
          },
          "branch": {
            "tradeRegister": {
              "system": "tradeRegister",
              "value": "112233445566"
            }
          }
        },
        "contact": {
          "address": {
            "city": "City A",
            "street": "Street B"
          }
        }
      },
      "links": {
        "self": "/nl/organizations/profiles/v1/organizations/12345678/branches/112233445566"
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organizations",
            "id": "12345678"
          }
        }
      }
    }
  ],
  "included": [
    {
      "type": "organizations",
      "id": "12345678",
      "attributes": {
        "tradeRegisterID": "12345678",
        "name": "company.info"
      },
      "links": {
        "self": "/nl/organizations/profiles/v1/organizations/12345678"
      }
    }
  ],
  "meta": {
    "totalResults": 500,
    "totalPages": 50,
    "aggregations": {
      "contact.address.city": [
        {
          "value": "Amsterdam",
          "count": 750028
        }
      ],
      "legalForm": [
        {
          "value": "Eenmanszaak",
          "count": 7451727
        }
      ],
      "financials.bankGroup": [
        {
          "value": "Rabobank",
          "count": 24249
        }
      ]
    }
  },
  "links": {
    "self": "/nl/organizations/profiles/v1/entities?query=company&sort=-name&page[size]=10&page[number]=1",
    "last": "/nl/organizations/profiles/v1/entities?query=company&sort=-name&page[size]=10&page[number]=50",
    "next": "/nl/organizations/profiles/v1/entities?query=company&sort=-name&page[size]=10&page[number]=2"
  }
}

2. 🏢 Get Organization

GET /nl/organizations/profiles/v1/organizations/{organization_id}

Retrieve a full organization profile.

Description

This endpoint returns a detailed profile for a specific organization, including identifiers, legal form, contact details, lifecycle events, activities (SBI), and optional extensions such as financials, ownership structure, management, etc.

Request Parameters

Path

Name	Type	Description
`organization_id`	string	Required. Organization identifier.

Headers

Name	Type	Description
`Accept-Language`	string	Optional. Determines the language of descriptions. Example: `nl`. Defaults to `en`.
`X-API-KEY`	string	Required. Your API key.

Query

Name	Type	Description
`extensions`	array (form, comma-separated)	Optional. Comma-separated list of extensions to enrich the profile (see below).

Available extensions values (enum):

sizeIndicators
activities
financials
ownershipStructures
management
contactPerson

Example request

curl -X GET "https://api.company.info/nl/organizations/profiles/v1/organizations/12345678?extensions=activities" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/vnd.api+json" \
  -H "Accept-Language: en"

Example Response

{
  "data": {
    "type": "organizations",
    "id": "string",
    "attributes": {
      "identifiers": {
        "tradeRegister": {
          "system": "tradeRegister",
          "value": "12345678"
        },
        "rsin": {
          "system": "taxOffice",
          "value": "110011000"
        }
      },
      "name": "Company A",
      "statutorySeat": "Amsterdam",
      "logoURL": "https://company.info/1.png",
      "legalForm": {
        "code": "private-limited-company",
        "description": "Besloten Vennootschap (blijkens statuten structuurvennootschap)",
        "shortDescription": "Besloten Vennootschap"
      },
      "contact": {
        "excludeFromMailing": false,
        "excludeFromMarketing": false,
        "address": {
          "formatted": "Postbus 123456 1111AB Amsterdam",
          "street": "Postbus 123456",
          "houseNumber": "12",
          "houseNumberAddition": "A",
          "houseLetter": "A",
          "postalCode": "1111AB",
          "city": "Amsterdam",
          "country": "NLD",
          "coordinates": {
            "latitude": 52.33348150746084,
            "longitude": 52.33348150746084
          },
          "countrySpecific": {
            "identifiers": {
              "bag": {
                "system": "BAG",
                "value": {
                  "addressableObjectID": 363010000157216,
                  "numberIndicationID": 363010012157000
                }
              }
            }
          },
          "registrationDate": "1979-01-01"
        },
        "correspondenceAddress": {
          "formatted": "Postbus 123456 1111AB Amsterdam",
          "street": "Postbus 123456",
          "houseNumber": "12",
          "houseNumberAddition": "A",
          "houseLetter": "A",
          "postalCode": "1111AB",
          "city": "Amsterdam",
          "country": "NLD",
          "coordinates": {
            "latitude": 52.33348150746084,
            "longitude": 52.33348150746084
          },
          "countrySpecific": {
            "identifiers": {
              "bag": {
                "system": "BAG",
                "value": {
                  "addressableObjectID": 363010012157000,
                  "numberIndicationID": 363010012157000
                }
              }
            }
          },
          "registrationDate": "1979-01-01"
        },
        "phoneNumbers": [
          {
            "source": "tradeRegister",
            "number": "+311100110011"
          }
        ],
        "websites": [
          {
            "source": "tradeRegister",
            "value": "sample.com"
          }
        ],
        "emails": [
          {
            "source": "tradeRegister",
            "value": "[email protected]"
          }
        ]
      },
      "activities": {
        "sbi": [
          {
            "isMain": true,
            "source": "tradeRegister",
            "system": "SBI",
            "code": "1071",
            "description": "Manufacture of bread and fresh pastry"
          }
        ]
      },
      "lifecycle": {
        "registration": {
          "isActive": true,
          "type": "registration",
          "startDate": "1971-05-06",
          "endDate": "1971-05-06"
        },
        "liquidation": {
          "isActive": true,
          "type": "registration",
          "startDate": "1971-05-06",
          "endDate": "1971-05-06"
        },
        "dissolution": {
          "isActive": true,
          "type": "registration",
          "startDate": "1971-05-06",
          "endDate": "1971-05-06",
          "description": "string"
        },
        "events": {
          "firstRegistration": {
            "date": "1971-05-06",
            "type": "registration"
          },
          "deedOfIncorporation": {
            "date": "1971-05-06",
            "type": "registration"
          }
        },
        "insolvency": {
          "isActive": true,
          "debtRestructuring": {
            "isActive": true,
            "type": "registration",
            "startDate": "1971-05-06",
            "endDate": "1971-05-06"
          },
          "suspensionOfPayments": {
            "isActive": true,
            "type": "registration",
            "startDate": "1971-05-06",
            "endDate": "1971-05-06"
          },
          "bankrupt": {
            "isActive": true,
            "type": "registration",
            "startDate": "1971-05-06",
            "endDate": "1971-05-06"
          },
          "publications": [
            {
              "identifier": {
                "system": "tradeRegister",
                "value": "id"
              },
              "court": {
                "name": "Rechtbank Noord-Nederland",
                "code": 43
              },
              "description": "sample text",
              "AvailableUntil": "1971-05-06"
            }
          ]
        }
      },
      "capital": {
        "issued": {
          "amount": "18000",
          "currency": "EUR"
        },
        "authorized": {
          "amount": "18000",
          "currency": "EUR"
        },
        "contributed": {
          "amount": "18000",
          "currency": "EUR"
        }
      },
      "branch": {
        "id": "123456780000",
        "isMain": true,
        "names": {
          "main": "Test B.V.",
          "tradeNames": [
            {
              "isActive": true,
              "isMain": true,
              "name": "Test B.V."
            }
          ]
        },
        "lifecycle": {
          "registration": {
            "isActive": true,
            "type": "registration",
            "startDate": "1980-05-06",
            "endDate": "1980-05-06"
          },
          "events": {
            "continuation": {
              "date": "1980-05-06",
              "type": "continuation"
            }
          }
        },
        "personnel": {
          "fullTime": {
            "value": 23,
            "class": {
              "code": "6",
              "description": "class description"
            }
          },
          "partTime": {
            "value": 23,
            "class": {
              "code": "6",
              "description": "class description"
            }
          },
          "total": {
            "value": 23,
            "class": {
              "code": "6",
              "description": "class description"
            }
          },
          "source": "tradeRegister"
        },
        "contact": {
          "excludeFromMailing": false,
          "excludeFromMarketing": false,
          "address": {
            "formatted": "Postbus 123456 1111AB Amsterdam",
            "street": "Postbus 123456",
            "houseNumber": "12",
            "houseNumberAddition": "A",
            "houseLetter": "A",
            "postalCode": "1111AB",
            "city": "Amsterdam",
            "country": "NLD",
            "coordinates": {
              "latitude": 52.33348150746084,
              "longitude": 52.33348150746084
            },
            "countrySpecific": {
              "identifiers": {
                "bag": {
                  "system": "BAG",
                  "value": {
                    "addressableObjectID": 363010012157000,
                    "numberIndicationID": 363010012157000
                  }
                }
              }
            },
            "registrationDate": "1979-01-01"
          },
          "correspondenceAddress": {
            "formatted": "Postbus 123456 1111AB Amsterdam",
            "street": "Postbus 123456",
            "houseNumber": "12",
            "houseNumberAddition": "A",
            "houseLetter": "A",
            "postalCode": "1111AB",
            "city": "Amsterdam",
            "country": "NLD",
            "coordinates": {
              "latitude": 52.33348150746084,
              "longitude": 52.33348150746084
            },
            "countrySpecific": {
              "identifiers": {
                "bag": {
                  "system": "BAG",
                  "value": {
                    "addressableObjectID": 363010012157000,
                    "numberIndicationID": 363010012157000
                  }
                }
              }
            },
            "registrationDate": "1979-01-01"
          },
          "phoneNumbers": [
            {
              "source": "tradeRegister",
              "number": "+311100110011"
            }
          ],
          "websites": [
            {
              "source": "tradeRegister",
              "value": "sample.com"
            }
          ],
          "emails": [
            {
              "source": "tradeRegister",
              "value": "[email protected]"
            }
          ]
        },
        "activities": {
          "sbi": [
            {
              "isMain": true,
              "source": "tradeRegister",
              "system": "SBI",
              "code": "1071",
              "description": "Manufacture of bread and fresh pastry"
            }
          ]
        }
      },
      "extensions": {
        "activities": {
          "summary": "sample summary",
          "sbi": [
            {
              "code": "62100",
              "isMain": true,
              "system": "SBI",
              "source": "tradeRegister",
              "description": "Computer programming activities"
            }
          ],
          "nace": [
            {
              "code": "6210",
              "isMain": true,
              "system": "NACE",
              "source": "tradeRegister",
              "description": "Computer programming activities"
            }
          ]
        }
      }
    },
    "links": {
      "self": "/nl/organizations/profiles/v1/organizations/12345678?extensions=activities"
    }
  }
}

3. 🌿 Get Organization Branches

GET /nl/organizations/profiles/v1/organizations/{organization_id}/branches

Retrieve all branches for a given organization.

Description

This endpoint returns a list of branches belonging to the specified organization. You can use include to retrieve related resources in the included section, following JSON:API conventions.

Request Parameters

Path

Name	Type	Description
`organization_id`	string	Required. Organization identifier.

Query

Name	Type	Description
`include`	array (form, comma-separated)	Optional. Comma-separated list of relationship paths to compound in the response (e.g., `organizations`).

Example Request

curl -X GET "https://api.company.info/nl/organizations/profiles/v1/organizations/12345678/branches?include=organizations" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/vnd.api+json"

Example Response

{
  "data": [
    {
      "type": "branches",
      "id": "112233445566",
      "attributes": {
        "isMain": true,
        "names": {
          "main": "branch A"
        },
        "lifecycle": {
          "registration": {
            "isActive": true,
            "startDate": "1980-01-02",
            "type": "registration"
          }
        },
        "contact": {
          "address": {
            "street": "Street A",
            "houseNumber": 10,
            "houseNumberAddition": "A",
            "houseLetter": "A",
            "postalCode": "1212PA",
            "city": "Amsterdam",
            "country": "NLD"
          }
        }
      },
      "links": {
        "self": "/nl/organizations/profiles/v1/organizations/12345678/branches/112233445566"
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organizations",
            "id": "12345678"
          }
        }
      }
    }
  ],
  "included": [
    {
      "type": "organizations",
      "id": "12345678",
      "attributes": {
        "name": "Company A",
        "country": "NLD"
      },
      "links": {
        "self": "/nl/organizations/profiles/v1/organizations/12345678"
      }
    }
  ],
  "links": {
    "self": "/nl/organizations/profiles/v1/organizations/12345678/branches?include=organizations"
  }
}

4. 🌿 Get Organization Branch

Get /nl/organizations/profiles/v1/organizations/{organization_id}/branches/{branch_id}

Retrieve one branch profile in detail.

Description

Fetches detailed information for a single branch of a given organization, including identification, lifecycle, personnel, contact, and activities. Optional include allows compound documents with related resources.

Request Parameters

Path

Name	Type	Description
`organization_id`	string	Required. Organization identifier.
`branch_id`	string	Required. Branch identifier.

Headers

Name	Type	Description
`Accept-Language`	string	Optional. Example: `nl`.
`X-API-KEY`	string	Required. Your API key.

Query

Name	Type	Description
`include`	array (form, comma-separated)	Optional. Relationship paths to include.

Example Request

curl -X GET "https://api.company.info/nl/organizations/profiles/v1/organizations/12345678/branches/123456780000?include=organizations" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/vnd.api+json"

Example Response

{
  "data": {
    "type": "branches",
    "id": "string",
    "attributes": {
      "identifiers": {
        "tradeRegister": {
          "system": "tradeRegister",
          "value": "123456780000"
        }
      },
      "isMain": true,
      "names": {
        "main": "Test B.V.",
        "tradeNames": [
          {
            "isActive": true,
            "isMain": true,
            "name": "Test B.V."
          }
        ]
      },
      "lifecycle": {
        "registration": {
          "isActive": true,
          "type": "registration",
          "startDate": "1989-05-06",
          "endDate": "1989-05-06"
        },
        "events": {
          "continuation": {
            "date": "1989-05-06",
            "type": "continuation"
          }
        }
      },
      "personnel": {
        "fullTime": {
          "value": 23,
          "class": {
            "code": "6",
            "description": "sample description"
          }
        },
        "partTime": {
          "value": 23,
          "class": {
            "code": "6",
            "description": "sample description"
          }
        },
        "total": {
          "value": 23,
          "class": {
            "code": "6",
            "description": "sample description"
          }
        },
        "source": "tradeRegister"
      },
      "contact": {
        "excludeFromMailing": false,
        "excludeFromMarketing": false,
        "address": {
          "formatted": "Postbus 123456 1111AB Amsterdam",
          "street": "Postbus 123456",
          "houseNumber": "12",
          "houseNumberAddition": "A",
          "houseLetter": "A",
          "postalCode": "1111AB",
          "city": "Amsterdam",
          "country": "NLD",
          "coordinates": {
            "latitude": 52.33348150746084,
            "longitude": 52.33348150746084
          },
          "countrySpecific": {
            "identifiers": {
              "bag": {
                "system": "BAG",
                "value": {
                  "addressableObjectID": 363010012157000,
                  "numberIndicationID": 363010012157000
                }
              }
            }
          },
          "registrationDate": "1979-01-01"
        },
        "correspondenceAddress": {
          "formatted": "Postbus 123456 1111AB Amsterdam",
          "street": "Postbus 123456",
          "houseNumber": "12",
          "houseNumberAddition": "A",
          "houseLetter": "A",
          "postalCode": "1111AB",
          "city": "Amsterdam",
          "country": "NLD",
          "coordinates": {
            "latitude": 52.33348150746084,
            "longitude": 52.33348150746084
          },
          "countrySpecific": {
            "identifiers": {
              "bag": {
                "system": "BAG",
                "value": {
                  "addressableObjectID": 363010012157000,
                  "numberIndicationID": 363010012157000
                }
              }
            }
          },
          "registrationDate": "1979-01-01"
        },
        "phoneNumbers": [
          {
            "source": "tradeRegister",
            "number": "+311122334455"
          }
        ],
        "websites": [
          {
            "source": "tradeRegister",
            "value": "sample.com"
          }
        ],
        "emails": [
          {
            "source": "tradeRegister",
            "value": "[email protected]"
          }
        ]
      },
      "activities": {
        "sbi": [
          {
            "isMain": true,
            "source": "tradeRegister",
            "system": "SBI",
            "code": "1071",
            "description": "Manufacture of bread and fresh pastry"
          }
        ]
      }
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "12345678"
        }
      }
    },
    "links": {
      "self": "/nl/organizations/profiles/v1/organizations/12345678/branches/123456780000?include=organizations"
    }
  },
  "included": [
    {
      "type": "organizations",
      "id": "12345678",
      "attributes": {
        "name": "company A",
        "country": "NLD",
      },
      "links": {
        "self": "/nl/organizations/profiles/v1/organizations/12345678"
      }
    }
  ]
}

🔢 Pagination

The API uses JSON:API-style pagination with meta and links objects.

Request Parameters

Parameter	Type	Description
`page[number]`	integer	The page index you want to retrieve.
`page[size]`	integer	How many records per page.

Response Fields

"meta": {
  "totalResults": 500,
  "totalPages": 50
},
"links": {
  "first": "https://.../entities?page[number]=1&page[size]=10",
  "last": "https://.../entities?page[number]=10&page[size]=10",
  "self": "https://.../entities?page[number]=2&page[size]=10",
  "next": "https://.../entities?page[number]=3&page[size]=10",
  "prev": "https://.../entities?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.

⚠️ Rate Limiting / Other Limitations

Some environments may enforce rate limits per API key.
Highly fuzzy or unbounded queries may have higher latency.
Wherever possible:
- Narrow your search using filters and match fields
- Use reasonable page[size] values instead of attempting huge single-page responses.

❗️
This API has a rate limit of 30 requests per second.

⚠️ Possible errors / unexpected behavior

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

Status	Error	Description	How to solve
400	Bad Request	Invalid query/match/filter/sort parameters	Validate parameter names and formats. Check deepObject structure for `filter`/`match` and that enums are valid.
403	Forbidden	Missing or invalid API key	Ensure `X-API-KEY` is present, not expired, and has sufficient permissions.
404	Not Found	Entity or endpoint not found	Confirm the `organization_id` / `branch_id` exists and you are using the correct path.
500	Internal Server Error	Unexpected server error	Retry the request after some time. If it persists, contact support with `X-Correlation-Id`.

Example Error Response

{
  "errors": [
    {
      "status": "400",
      "title": "Invalid parameter",
      "detail": "The value for filter.activities.sbi.code is invalid"
    }
  ]
}

🛠️ Try it 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

Term	Definition
Branch	A physical or legal subdivision of an organization, often with its own trade register number.
Legal Entity	A company formally registered with its own legal and tax identifiers.
Transitioned Organization	An organization that has moved between legal forms or identifiers, but is still tracked historically.
Trade Register ID	Official identifier issued by the Dutch Chamber of Commerce (KvK).
RSIN	Dutch Tax Identification Number for legal entities.
SBI Code	Dutch industry classification code (equivalent to NACE in the EU context).
JSON:API	A specification for building APIs in JSON with consistent structure for `data`, `included`, `meta`, `links`, and `errors`.
Aggregation	A grouped summary of values (e.g., organizations per city or legal form).
Extensions	Optional blocks of extra profile data that can be included on demand, such as financials or ownership structures.
Ultimate Parent	The highest-level parent organization within an ownership structure.