{ "openapi": "3.1.0", "info": { "title": "BizStackData API", "version": "1.0.0", "description": "Dutch company data: free search and profiles, paid contact reveals.\n\nSend your API key as a bearer token: \"Authorization: Bearer bzd_live_...\". Keys starting with bzd_test_ return deterministic sandbox data, never consume credits and never call the live data source. Key secrets are shown once at creation and stored hashed.\n\nRate limit: 600 req/min per key. Errors return a JSON body with error.code, error.message and the error.request_id to quote to support. Every response also carries the request id in the X-Request-Id header." }, "servers": [ { "url": "https://api.dev-bizstackdata.storekeeper.software" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/companies/search": { "get": { "operationId": "companies_search", "summary": "Search companies", "description": "Returns companies that match all supplied filters. Comma-separate values to match any of them, e.g. province=Utrecht,Gelderland. Results are paginated: pass meta.next_cursor as cursor to get the next page. Searching is free and never returns contact values; the availability flags tell you which contact fields a reveal would return.\n\nCredits: Free.", "tags": [ "Companies" ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text match on legal and trade names, activity and registration number.", "schema": { "type": "string" }, "example": "bakkerij" }, { "name": "sbi", "in": "query", "required": false, "description": "SBI activity code or prefix. Dots are ignored. Comma-separated.", "schema": { "type": "string" }, "example": "1071" }, { "name": "province", "in": "query", "required": false, "description": "Province. Comma-separated.", "schema": { "type": "string", "description": "One or more of: Drenthe, Flevoland, Friesland, Gelderland, Groningen, Limburg, Noord-Brabant, Noord-Holland, Overijssel, Utrecht, Zeeland, Zuid-Holland" }, "example": "Utrecht" }, { "name": "city", "in": "query", "required": false, "description": "City name. Comma-separated.", "schema": { "type": "string" }, "example": "Amsterdam" }, { "name": "postal_code", "in": "query", "required": false, "description": "Postal code or prefix (1 to 4 digits, or 4 digits and letters). Comma-separated.", "schema": { "type": "string" }, "example": "1016" }, { "name": "size", "in": "query", "required": false, "description": "Employee band. Comma-separated.", "schema": { "type": "string", "description": "One or more of: 1, 2-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10001plus" }, "example": "2-10" }, { "name": "legal_form", "in": "query", "required": false, "description": "Legal form, e.g. besloten vennootschap. Comma-separated.", "schema": { "type": "string" }, "example": "besloten vennootschap" }, { "name": "founded_from", "in": "query", "required": false, "description": "Founded in or after this year.", "schema": { "type": "integer" }, "example": 2015 }, { "name": "founded_to", "in": "query", "required": false, "description": "Founded in or before this year.", "schema": { "type": "integer" }, "example": 2020 }, { "name": "has", "in": "query", "required": false, "description": "Only companies that have these contact fields available. Comma-separated.", "schema": { "type": "string", "description": "One or more of: email, phone, contact_person" }, "example": "email,phone" }, { "name": "status", "in": "query", "required": false, "description": "Registration status.", "schema": { "type": "string", "description": "One or more of: active, inactive, all", "default": "active" }, "example": "active" }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 50.", "schema": { "type": "integer", "default": 25 }, "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from meta.next_cursor. Do not combine with offset.", "schema": { "type": "string" }, "example": "eyJvIjoyNX0" }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based position of the first result. Use cursor for sequential paging.", "schema": { "type": "integer", "default": 0 }, "example": 0 } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "registration_number": "34512879", "legal_name": "Bakkerij Voorbeeld B.V.", "trade_names": [ "Bakkerij Voorbeeld" ], "legal_form": "Besloten Vennootschap", "employees": "2-10", "founded_year": 2014, "status": "active", "address": { "street": "Oudegracht", "house_number": "1", "house_number_addition": null, "postal_code": "3511AA", "city": "Utrecht", "municipality": "Utrecht", "province": "Utrecht", "country": "NL" }, "activity_description": "Ambachtelijke bakkerij.", "description": null, "availability": { "email": true, "phone": false, "website": true, "contact_person": false } } ], "meta": { "count": 1, "total": 34, "limit": 1, "offset": 0, "next_cursor": "eyJvIjoxfQ", "credits_charged": 0, "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } } }, "400": { "description": "invalid_parameter: A parameter is missing, malformed or not supported by this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_parameter", "message": "A parameter is missing, malformed or not supported by this endpoint.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } } }, "401": { "description": "key_invalid: No API key was sent, or the key is not recognised. key_revoked: The API key was revoked. Create or regenerate a key. key_expired: The API key passed its expiration date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "key_invalid", "message": "No API key was sent, or the key is not recognised.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } } }, "403": { "description": "account_disabled: Your organization is disabled. Contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "account_disabled", "message": "Your organization is disabled. Contact support.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } } }, "429": { "description": "rate_limit_exceeded: Too many requests. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests. Retry after the Retry-After header.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "503": { "description": "upstream_unavailable: The data source is temporarily unavailable. Safe to retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_unavailable", "message": "The data source is temporarily unavailable. Safe to retry with backoff.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } } } }, "/v1/companies/{registration_number}": { "get": { "operationId": "companies_get", "summary": "Get a company", "description": "Returns the free profile of one company, active or not. Contact values are not included; use POST /v1/companies/contacts to reveal them.\n\nCredits: Free.", "tags": [ "Companies" ], "parameters": [ { "name": "registration_number", "in": "path", "required": true, "description": "The 8-digit KVK number.", "schema": { "type": "string" }, "example": "34512879" } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Company" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "registration_number": "34512879", "legal_name": "Bakkerij Voorbeeld B.V.", "trade_names": [ "Bakkerij Voorbeeld" ], "legal_form": "Besloten Vennootschap", "employees": "2-10", "founded_year": 2014, "status": "active", "address": { "street": "Oudegracht", "house_number": "1", "house_number_addition": null, "postal_code": "3511AA", "city": "Utrecht", "municipality": "Utrecht", "province": "Utrecht", "country": "NL" }, "activity_description": "Ambachtelijke bakkerij.", "description": null, "availability": { "email": true, "phone": false, "website": true, "contact_person": false } }, "meta": { "credits_charged": 0, "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } } }, "400": { "description": "invalid_parameter: A parameter is missing, malformed or not supported by this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_parameter", "message": "A parameter is missing, malformed or not supported by this endpoint.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } } }, "401": { "description": "key_invalid: No API key was sent, or the key is not recognised. key_revoked: The API key was revoked. Create or regenerate a key. key_expired: The API key passed its expiration date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "key_invalid", "message": "No API key was sent, or the key is not recognised.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } } }, "403": { "description": "account_disabled: Your organization is disabled. Contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "account_disabled", "message": "Your organization is disabled. Contact support.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } } }, "404": { "description": "company_not_found: No company is registered under this registration number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "company_not_found", "message": "No company is registered under this registration number.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } } }, "429": { "description": "rate_limit_exceeded: Too many requests. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests. Retry after the Retry-After header.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "503": { "description": "upstream_unavailable: The data source is temporarily unavailable. Safe to retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_unavailable", "message": "The data source is temporarily unavailable. Safe to retry with backoff.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } } } }, "/v1/companies/contacts": { "post": { "operationId": "companies_contacts", "summary": "Reveal contacts", "description": "Reveals contact data and charges your organization's contact allowance: 1 credit per company that returns data. Companies your organization revealed before (in the portal or through the API) are free and are returned again. Unknown registration numbers come back with found=false and are not charged. If the request needs more credits than you have left this period, nothing is revealed and the API answers 402 allowance_exceeded.\n\nCredits: 1 per company returned with data; repeats are free.", "tags": [ "Companies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsRequest" }, "example": { "registration_numbers": [ "34512879", "12345678" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "registration_number": "34512879", "found": true, "email": "info@example.nl", "phone": "+31301234567", "website": "https://www.example.nl", "contact_person": "J. Jansen" }, { "registration_number": "12345678", "found": false, "email": null, "phone": null, "website": null, "contact_person": null } ], "meta": { "requested": 2, "credits_charged": 1, "credits_from_cache": 1, "already_owned": 0, "cap_remaining": 499, "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } } }, "400": { "description": "invalid_parameter: A parameter is missing, malformed or not supported by this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_parameter", "message": "A parameter is missing, malformed or not supported by this endpoint.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } } }, "401": { "description": "key_invalid: No API key was sent, or the key is not recognised. key_revoked: The API key was revoked. Create or regenerate a key. key_expired: The API key passed its expiration date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "key_invalid", "message": "No API key was sent, or the key is not recognised.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } } }, "402": { "description": "allowance_exceeded: The request needs more contact credits than your organization has left this period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "allowance_exceeded", "message": "The request needs more contact credits than your organization has left this period.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } } }, "403": { "description": "account_disabled: Your organization is disabled. Contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "account_disabled", "message": "Your organization is disabled. Contact support.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } } }, "429": { "description": "rate_limit_exceeded: Too many requests. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests. Retry after the Retry-After header.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "503": { "description": "upstream_unavailable: The data source is temporarily unavailable. Safe to retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_unavailable", "message": "The data source is temporarily unavailable. Safe to retry with backoff.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } } } }, "/v1/usage": { "get": { "operationId": "usage", "summary": "Usage", "description": "Returns the contact allowance (cap) of the current period, how much is used, by the portal and by the API, and when the period resets. A null cap means unlimited.\n\nCredits: Free.", "tags": [ "Account" ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Usage" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "period": "month", "period_start": "2026-09-30T22:00:00+00:00", "period_end": "2026-10-31T23:00:00+00:00", "cap": 500, "used": 12, "remaining": 488, "unlimited": false, "used_by_channel": { "ui": 10, "api": 2 } }, "meta": { "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } } }, "401": { "description": "key_invalid: No API key was sent, or the key is not recognised. key_revoked: The API key was revoked. Create or regenerate a key. key_expired: The API key passed its expiration date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "key_invalid", "message": "No API key was sent, or the key is not recognised.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } } }, "403": { "description": "account_disabled: Your organization is disabled. Contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "account_disabled", "message": "Your organization is disabled. Contact support.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } } }, "429": { "description": "rate_limit_exceeded: Too many requests. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests. Retry after the Retry-After header.", "request_id": "req_01K8ZQ4W3N7XG2B5HT9MV0A1BC" } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } } } }, "/v1/openapi.json": { "get": { "operationId": "openapi", "summary": "OpenAPI document", "description": "Machine-readable description of every endpoint. Does not need an API key.\n\nCredits: Free.", "tags": [ "Account" ], "security": [], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "openapi": "3.1.0", "info": { "title": "BizStackData API", "version": "1.0.0" } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "bzd_live_... or bzd_test_..." } }, "schemas": { "Company": { "type": "object", "properties": { "registration_number": { "type": "string", "description": "KVK number, 8 digits." }, "legal_name": { "type": "string" }, "trade_names": { "type": "array", "items": { "type": "string" } }, "legal_form": { "type": [ "string", "null" ] }, "employees": { "type": [ "string", "null" ], "description": "Employee band, e.g. 2-10." }, "founded_year": { "type": [ "integer", "null" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "address": { "type": "object", "properties": { "street": { "type": [ "string", "null" ] }, "house_number": { "type": [ "string", "null" ] }, "house_number_addition": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "municipality": { "type": [ "string", "null" ] }, "province": { "type": [ "string", "null" ] }, "country": { "type": "string" } } }, "activity_description": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "availability": { "type": "object", "description": "Which contact fields a reveal would return. Never the values themselves.", "properties": { "email": { "type": "boolean" }, "phone": { "type": "boolean" }, "website": { "type": "boolean" }, "contact_person": { "type": "boolean" } } } } }, "Contact": { "type": "object", "properties": { "registration_number": { "type": "string" }, "found": { "type": "boolean" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "contact_person": { "type": [ "string", "null" ] } } }, "ContactsRequest": { "type": "object", "required": [ "registration_numbers" ], "additionalProperties": false, "properties": { "registration_numbers": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "pattern": "^\\d{8}$" } } } }, "Usage": { "type": "object", "properties": { "period": { "type": "string", "enum": [ "week", "month" ] }, "period_start": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" }, "cap": { "type": [ "integer", "null" ], "description": "Null means unlimited." }, "used": { "type": "integer" }, "remaining": { "type": [ "integer", "null" ] }, "unlimited": { "type": "boolean" }, "used_by_channel": { "type": "object", "properties": { "ui": { "type": "integer" }, "api": { "type": "integer" } } } } }, "Meta": { "type": "object", "required": [ "request_id" ], "properties": { "request_id": { "type": "string" }, "count": { "type": "integer" }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "requested": { "type": "integer" }, "credits_charged": { "type": "integer" }, "credits_from_cache": { "type": "integer" }, "already_owned": { "type": "integer" }, "cap_remaining": { "type": [ "integer", "null" ] }, "sandbox": { "type": "boolean", "description": "Present and true for bzd_test_ keys." } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "enum": [ "invalid_parameter", "key_invalid", "key_revoked", "key_expired", "allowance_exceeded", "account_disabled", "endpoint_not_found", "company_not_found", "method_not_allowed", "rate_limit_exceeded", "internal_error", "upstream_unavailable" ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "parameter": { "type": "string" } } } } } }, "headers": { "X-Request-Id": { "description": "Request id (req_...), also in meta.request_id or error.request_id.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }