--- updatedAt: 2026-05-04T11:46:08.000Z agentTools: projectIndex: https://docs.company.info/llms.txt --- # Search for branches, legal entities, and transitioned organizations. Use this endpoint to perform full-text searches, structured filtering, prefix matching, sorting, and aggregations across all entity types. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "NL Organizations", "description": "The NL Organizations API provides search and profiling capabilities for organizations and their branches.\n", "version": "v0.1.0" }, "servers": [ { "url": "https://api.company.info", "description": "Production Server" } ], "security": [ { "authToken": [] }, { "jwtAuth": [] } ], "tags": [ { "name": "Entities", "description": "Operations related to searching for different entity types." } ], "paths": { "/nl/organizations/profiles/v1/entities": { "get": { "operationId": "searchOrganizationEntities", "tags": [ "Entities" ], "summary": "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.", "parameters": [ { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/entityFilter" }, { "$ref": "#/components/parameters/entityMatch" }, { "$ref": "#/components/parameters/entitySort" }, { "$ref": "#/components/parameters/aggregate" }, { "$ref": "#/components/parameters/Fuzziness" }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "OK", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" } }, "content": { "application/vnd.api+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ResponseList" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "branches", "organizations" ] }, "id": { "type": "string" }, "attributes": { "oneOf": [ { "$ref": "#/components/schemas/BranchAttributes" }, { "$ref": "#/components/schemas/LegalEntityAttributes" }, { "$ref": "#/components/schemas/TransitionedOrganizationAttributes" } ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "format": "uri-reference" } } }, "relationships": { "type": "object", "required": [ "organization" ], "properties": { "organization": { "$ref": "#/components/schemas/RelationshipToOne" } } } } } }, "included": { "type": "array", "uniqueItems": true, "items": { "type": "object", "properties": { "type": { "type": "string", "example": "organizations" }, "id": { "type": "string" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "example": "Company A" } } }, "links": { "type": "object", "properties": { "self": { "type": "string", "format": "uri-reference" } } } } } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/meta" }, { "type": "object", "properties": { "aggregations": { "$ref": "#/components/schemas/aggregationResult" } } } ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "format": "uri-reference" }, "first": { "type": "string", "format": "uri-reference" }, "last": { "type": "string", "format": "uri-reference" }, "prev": { "type": "string", "format": "uri-reference" }, "next": { "type": "string", "format": "uri-reference" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "500": { "$ref": "#/components/responses/500" } } } } }, "components": { "securitySchemes": { "authToken": { "description": "API Key Authentication", "type": "apiKey", "in": "header", "name": "X-API-KEY" }, "jwtAuth": { "description": "JWT Authentication", "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "entityFilterQuery": { "type": "object", "properties": { "identifiers": { "type": "object", "properties": { "tradeRegister": { "type": "string", "example": "332292790000", "description": "The branch numbers." } } }, "name": { "type": "string", "example": "company.info", "description": "The registered name of the entity." }, "isActive": { "type": "boolean", "example": true, "description": "Indicates if the branch is currently active." }, "isMain": { "type": "boolean", "example": true, "description": "Indicates if the branch is the main." }, "legalForm": { "description": "The legal form of the organization.", "type": "string", "example": "Besloten Vennootschap" }, "tradeNames": { "description": "Filter by active and/or expired trade names.", "oneOf": [ { "type": "string", "example": "company.info" }, { "type": "object", "properties": { "active": { "type": "string", "example": "company.info" }, "expired": { "type": "string", "example": "company.info" } } } ] }, "organization": { "type": "object", "properties": { "name": { "type": "string", "example": "company.info", "description": "The primary name or display name of the organization." }, "identifiers": { "type": "object", "properties": { "tradeRegister": { "type": "string", "example": "33229279", "description": "The trade register IDs." } } } } }, "type": { "description": "Type of the organization or unit.", "type": "string", "enum": [ "branch", "legalEntity", "transitionedOrganization" ] }, "ownershipStructures": { "type": "object", "properties": { "hasNationalUltimateParent": { "type": "boolean", "example": true }, "hasInternationalUltimateParent": { "type": "boolean", "example": false }, "ultimateParentIsNaturalPerson": { "type": "boolean", "example": true, "description": "Indicates if the ultimate parent is a natural person." } } }, "activities": { "type": "object", "properties": { "sbi": { "type": "object", "properties": { "code": { "description": "Filter on main and/or secondary SBI codes.", "oneOf": [ { "type": "string", "example": "78202" }, { "type": "object", "properties": { "main": { "type": "string", "example": "70102" }, "secondary": { "type": "string", "example": "78202" } } } ] } } } } }, "contact": { "type": "object", "properties": { "address": { "type": "object", "description": "Filter by elements of the visiting address.", "properties": { "province": { "type": "string", "example": "Zuid-Holland" }, "city": { "type": "string", "example": "Amsterdam" }, "municipality": { "type": "string", "example": "Amsterdam" }, "postalCode": { "oneOf": [ { "type": "string", "example": "1231RV" }, { "type": "object", "properties": { "range": { "type": "string", "example": "1231RV,1431RV" } } } ] }, "street": { "type": "string", "example": "Veilingstraat" }, "houseNumber": { "type": "integer", "example": 12 }, "houseNumberAddition": { "type": "string", "example": "A" } } }, "excludeFromMailing": { "type": "boolean", "example": true, "description": "True if the address should not be used for mailing." }, "excludeFromMarketing": { "type": "boolean", "example": true, "description": "True if the organization opted out of marketing." }, "website": { "type": "string", "example": "company.info" } } }, "lifecycle": { "type": "object", "properties": { "firstRegistration": { "description": "Date of registration or a date range.", "oneOf": [ { "type": "string", "example": "2002-02-05" }, { "type": "object", "properties": { "range": { "type": "string", "example": "2002-02-05,2003-02-05" } } } ] } } }, "personnel": { "type": "object", "properties": { "tradeRegister": { "type": "object", "properties": { "class": { "type": "integer", "example": 5 } } }, "companyInfo": { "type": "object", "properties": { "class": { "type": "integer", "example": 5 } } } } }, "financials": { "type": "object", "properties": { "bankGroup": { "type": "string", "example": "RaboBank" }, "profit": { "type": "object", "properties": { "range": { "type": "string", "example": "3000000,4000000" } } }, "assets": { "type": "object", "properties": { "range": { "type": "string", "example": "580000,590000" } } }, "turnover": { "type": "object", "properties": { "range": { "type": "string", "example": "1000000,2000000" } } } } } } }, "entityMatchQuery": { "type": "object", "properties": { "identifiers": { "type": "object", "properties": { "tradeRegister": { "type": "string", "example": "332292790000", "description": "The branch numbers." } } }, "name": { "type": "string", "example": "company.info", "description": "The registered name of the entity." }, "legalForm": { "description": "The legal form of the organization.", "type": "string", "example": "Besloten Vennootschap" }, "tradeNames": { "description": "Filter by active and/or expired trade names.", "oneOf": [ { "type": "string", "example": "company.info" }, { "type": "object", "properties": { "active": { "type": "string", "example": "company.info" }, "expired": { "type": "string", "example": "company.info" } } } ] }, "organization": { "type": "object", "properties": { "name": { "type": "string", "example": "company.info", "description": "The primary name or display name of the organization." }, "identifiers": { "type": "object", "properties": { "tradeRegister": { "type": "string", "example": "33229279", "description": "The trade register IDs." } } } } }, "activities": { "type": "object", "properties": { "sbi": { "type": "object", "properties": { "code": { "description": "Filter on main and/or secondary SBI codes.", "oneOf": [ { "type": "string", "example": "78202" }, { "type": "object", "properties": { "main": { "type": "string", "example": "70102" }, "secondary": { "type": "string", "example": "78202" } } } ] } } } } }, "contact": { "type": "object", "properties": { "address": { "type": "object", "description": "Filter by elements of the visiting address.", "properties": { "province": { "type": "string", "example": "Zuid-Holland" }, "city": { "type": "string", "example": "Amsterdam" }, "municipality": { "type": "string", "example": "Amsterdam" }, "postalCode": { "type": "string", "example": "1231RV" }, "street": { "type": "string", "example": "Veilingstraat" } } }, "website": { "type": "string", "example": "company.info" } } }, "lifecycle": { "type": "object", "properties": { "firstRegistration": { "description": "Date of registration or a date range.", "type": "string", "example": "2002-02-05" } } }, "financials": { "type": "object", "properties": { "bankGroup": { "type": "string", "example": "RaboBank" } } } } }, "aggregationQuery": { "type": "object", "description": "Defines fields and size buckets for aggregation.", "properties": { "fields": { "type": "array", "description": "Comma-separated list of fields to aggregate.", "items": { "$ref": "#/components/schemas/aggregationType" } }, "size": { "type": "object", "description": "Aggregation result bucket sizes per dimension.", "properties": { "contact": { "type": "object", "properties": { "address": { "type": "object", "properties": { "city": { "type": "integer" }, "street": { "type": "integer" }, "province": { "type": "integer" }, "municipality": { "type": "integer" } } } } }, "legalForm": { "type": "integer" }, "financials": { "type": "object", "properties": { "bankGroups": { "type": "integer" } } } } } }, "example": { "fields": [ "contact.address.city", "contact.address.street", "contact.address.province", "contact.address.municipality", "legalForm", "financials.bankGroup" ], "size": { "contact": { "address": { "city": 10, "street": 10, "province": 10, "municipality": 10 } }, "legalForm": 5, "financials": { "bankGroups": 20 } } } }, "sortType": { "type": "string", "enum": [ "type", "organization.identifiers.tradeRegister", "identifiers.tradeRegister", "name", "tradeNames.active", "tradeNames.expired", "organization.name", "lifecycle.firstRegistration", "contact.address.postalCode", "contact.address.city", "activities.sbi.code.main", "activities.sbi.code.secondary", "personnel.tradeRegister.class", "personnel.companyInfo.class", "legalForm", "financials.bankGroup", "financials.profit", "financials.assets", "financials.turnover" ] }, "aggregationType": { "type": "string", "enum": [ "contact.address.city", "legalForm", "financials.bankGroup", "contact.address.street", "contact.address.province", "contact.address.municipality" ] }, "aggregationResult": { "description": "Aggregated search results for organization-related fields.\n", "type": "object", "properties": { "contact.address.city": { "type": "array", "items": { "$ref": "#/components/schemas/valueCount" } }, "legalForm": { "type": "array", "items": { "$ref": "#/components/schemas/valueCount" } }, "financials.bankGroup": { "type": "array", "items": { "$ref": "#/components/schemas/valueCount" } } } }, "BranchAttributes": { "type": "object", "properties": { "name": { "type": "string", "example": "Company A" }, "type": { "type": "string", "enum": [ "branch" ], "example": "branch" }, "isMain": { "type": "boolean", "example": true }, "identifiers": { "type": "object", "properties": { "tradeRegister": { "type": "object", "properties": { "system": { "type": "string", "example": "tradeRegister" }, "value": { "type": "string", "example": "138579830001" } } } } }, "organization": { "type": "object", "properties": { "name": { "type": "string", "example": "Company A" }, "identifiers": { "type": "object", "properties": { "tradeRegister": { "type": "object", "properties": { "system": { "type": "string", "example": "tradeRegister" }, "value": { "type": "string", "example": "13857983" } } } } } } }, "contact": { "$ref": "#/components/schemas/visitingAddress" } }, "additionalProperties": false }, "LegalEntityAttributes": { "type": "object", "properties": { "name": { "type": "string", "example": "Company A" }, "type": { "type": "string", "enum": [ "legalEntity" ], "example": "legalEntity" }, "organization": { "type": "object", "properties": { "name": { "type": "string", "example": "Company A" }, "identifiers": { "type": "object", "properties": { "tradeRegister": { "type": "object", "properties": { "system": { "type": "string", "example": "tradeRegister" }, "value": { "type": "string", "example": "13857983" } } } } } } }, "contact": { "$ref": "#/components/schemas/visitingAddress" } } }, "TransitionedOrganizationAttributes": { "type": "object", "properties": { "name": { "type": "string", "example": "Company A" }, "type": { "type": "string", "enum": [ "transitionedOrganization" ], "example": "transitionedOrganization" }, "organization": { "type": "object", "properties": { "name": { "type": "string", "example": "Company A" }, "identifiers": { "type": "object", "properties": { "tradeRegister": { "type": "object", "properties": { "system": { "type": "string", "example": "tradeRegister" }, "value": { "type": "string", "example": "13857983" } } } } } } } } }, "visitingAddress": { "type": "object", "properties": { "address": { "type": "object", "properties": { "city": { "type": "string", "example": "Harlingen" }, "street": { "type": "string", "example": "Voorstraat" } } } } }, "valueCount": { "description": "Represents a single aggregation bucket with a value and its count.\n", "type": "object", "properties": { "value": { "type": "string", "example": "Haarlem" }, "count": { "type": "integer", "example": 125, "minimum": 0 } } }, "meta": { "type": "object", "properties": { "totalResults": { "type": "integer", "description": "The total number of results found across all pages.", "example": 500, "minimum": 0 }, "totalPages": { "type": "integer", "description": "The total number of pages available based on the current page size." } }, "additionalProperties": false }, "Resource": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string" }, "id": { "type": "string" } } }, "ResponseList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Resource" } } } }, "RelationshipToOne": { "type": "object", "properties": { "data": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/Resource" } ], "nullable": true } }, "minProperties": 1 }, "ErrorResource": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "title": "An array of Error objects", "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "status", "code", "title", "detail" ], "properties": { "status": { "description": "the HTTP status code applicable to this problem", "type": "string", "minLength": 3, "maxLength": 3 }, "code": { "description": "an application-specific error code. It can be the same as 'status'", "type": "string" }, "title": { "description": "a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization", "type": "string" }, "detail": { "description": "a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized", "type": "string" } } } } } } }, "parameters": { "query": { "name": "query", "in": "query", "description": "Searches across multiple fields. Results are ranked by relevance, with exact identifier and company name matches prioritized over phrase, full-text, and prefix matches. Supports fuzzy matching for text fields. Minimum length: 2 characters.\n", "required": false, "schema": { "type": "string", "example": "company" } }, "entityFilter": { "name": "filter", "in": "query", "description": "Enables filtering of entities based on exact values and range conditions. Supports structured fields such as address, financials, and metadata.\n", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/entityFilterQuery" }, "example": { "name": "company.info", "isActive": true, "legalForm": "Besloten Vennootschap", "type": "branch", "identifiers": { "tradeRegister": "332292790000" }, "organization": { "identifiers": { "tradeRegister": "33229279" } }, "contact": { "address": { "province": "Zuid-Holland", "city": "Amsterdam", "postalCode": "1231RV" } }, "activities": { "sbi": { "code": { "main": "70102" } } }, "financials": { "bankGroup": "RaboBank", "turnover": { "range": "1000000,2000000" } } } }, "entityMatch": { "name": "match", "in": "query", "description": "Supports partial or prefix-based text matching across key entity attributes. Prefix search is applied to fields like `city` and `identifiers`, while general matching is used for `postalCode`, `street`, `name`, and `tradeNames`. Supports fuzzy matching for text fields.\n", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/entityMatchQuery" }, "example": { "name": "company.info", "legalForm": "Besloten Vennootschap", "identifiers": { "tradeRegister": "332292790000" }, "organization": { "name": "company.info" }, "contact": { "address": { "city": "Amsterdam", "postalCode": "1231RV", "street": "Veilingstraat" } }, "lifecycle": { "firstRegistration": "2002-02-05" } } }, "entitySort": { "name": "sort", "in": "query", "description": "Comma-separated list of fields used to sort the results, following JSON:API sorting conventions. Prefix a field with `-` to sort in descending order (default is ascending).
Defaults to sorting by `-id` (descending).\n", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/sortType" } }, "example": [ "financials.turnover", "name" ] }, "aggregate": { "name": "aggregate", "in": "query", "description": "A query parameter that defines the data aggregation to be performed on the search results. It allows you to specify a comma-separated list of fields to group by and to define the size of each aggregation bucket.\n", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/aggregationQuery" }, "example": { "fields": [ "contact.address.city", "contact.address.province", "legalForm", "financials.bankGroup" ], "size": { "contact": { "address": { "city": 10, "province": 10 } }, "legalForm": 5, "financials": { "bankGroups": 20 } } } }, "Fuzziness": { "name": "fuzziness", "in": "query", "description": "Enables fuzzy search when set to `true`.\n", "required": false, "example": true, "schema": { "type": "boolean" } }, "Page": { "name": "page", "in": "query", "description": "Controls pagination for a collection of resources, allowing clients to request a specific page and specify the number of resources per page.", "required": false, "allowEmptyValue": false, "style": "deepObject", "explode": true, "allowReserved": false, "schema": { "type": "object", "properties": { "number": { "type": "integer", "description": "The page number to retrieve.", "default": 1, "minimum": 1 }, "size": { "type": "integer", "description": "The number of records per page.", "default": 10, "maximum": 20 } } } } }, "headers": { "X-Correlation-Id": { "description": "Unique request identifier", "schema": { "type": "string", "format": "uuid" } } }, "examples": { "BadRequestExample": { "value": { "errors": [ { "status": "400", "code": "bad-request", "title": "Bad Request", "detail": "The request payload contains an invalid or missing field." } ] } }, "ForbiddenExample": { "value": { "errors": [ { "status": "403", "code": "forbidden", "title": "Forbidden", "detail": "You do not have permission to access this resource." } ] } }, "NotFoundExample": { "value": { "errors": [ { "status": "404", "code": "not-found", "title": "Resource Not Found", "detail": "The requested resource does not exist." } ] } }, "InternalServerErrorExample": { "value": { "errors": [ { "status": "500", "code": "internal-server-error", "title": "Internal Server Error", "detail": "An unexpected server error occurred." } ] } } }, "responses": { "400": { "description": "Bad Request", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResource" }, "examples": { "badRequest": { "$ref": "#/components/examples/BadRequestExample" } } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResource" }, "examples": { "forbidden": { "$ref": "#/components/examples/ForbiddenExample" } } } } }, "404": { "description": "Not Found", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResource" }, "examples": { "notFound": { "$ref": "#/components/examples/NotFoundExample" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResource" }, "examples": { "internalServerError": { "$ref": "#/components/examples/InternalServerErrorExample" } } } } } } }, "x-readme": { "proxy-enabled": false } } ```