{ "openapi": "3.0.1", "info": { "title": "Checked.be API", "description": "Belgian company data: identity, status, risk band, insolvency events and mandates. Send your key in the X-Api-Key header; create one at https://checked.be/account/api-keys. 60 requests per minute per key. Null means the source did not answer, never zero.", "version": "v1" }, "servers": [ { "url": "https://checked.be" } ], "paths": { "/api/v1/companies/{kbo}": { "get": { "tags": [ "Companies" ], "summary": "Company dossier", "description": "Identity, status, risk band, insolvency rollup and mandates. Fields fed by a source that did not answer are null, and coverage says which.", "operationId": "GetCompanyDossier", "parameters": [ { "name": "kbo", "in": "path", "description": "Enterprise number: 0400378485, 0400.378.485 or BE0400378485.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyApiResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/companies/{kbo}/lifecycle": { "get": { "tags": [ "Companies" ], "summary": "Legal lifecycle events", "description": "Bankruptcy, reorganisation, interim measures and register notices. An empty array means none; 503 means the source did not answer.", "operationId": "GetCompanyLifecycle", "parameters": [ { "name": "kbo", "in": "path", "description": "Enterprise number: 0400378485, 0400.378.485 or BE0400378485.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LifecycleEventDto" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/companies/{kbo}/rollup": { "get": { "tags": [ "Companies" ], "summary": "Insolvency rollup", "description": "Counts and dates of insolvency events. 404 means nothing on record; 503 means the source did not answer.", "operationId": "GetCompanyRollup", "parameters": [ { "name": "kbo", "in": "path", "description": "Enterprise number: 0400378485, 0400.378.485 or BE0400378485.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RollupDto2" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/search": { "get": { "tags": [ "Companies" ], "summary": "Search companies", "description": "By name, enterprise number, VAT number or NACE code. A blank query returns an empty array.", "operationId": "SearchCompanies", "parameters": [ { "name": "q", "in": "query", "description": "Name, enterprise number, VAT number or NACE code.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum hits, 1 to 50. Default 20.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SearchHitDto" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "components": { "schemas": { "AddressDto": { "required": [ "street", "zip", "city" ], "type": "object", "properties": { "street": { "type": "string", "nullable": true }, "zip": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true } }, "nullable": true }, "ApiError": { "required": [ "error" ], "type": "object", "properties": { "error": { "type": "string", "description": "What went wrong, in English." } } }, "CompanyApiResponse": { "required": [ "enterprise_number", "legal_name", "legal_form", "primary_nace", "status", "address", "risk", "rollup", "insolvency_event_count", "admin_event_count", "mandates", "coverage", "as_of", "register_situation_code" ], "type": "object", "properties": { "enterprise_number": { "type": "string" }, "legal_name": { "type": "string" }, "legal_form": { "type": "string", "nullable": true }, "primary_nace": { "type": "string", "nullable": true }, "status": { "type": "string", "description": "Registration in the KBO register, not solvency: filter on register_situation_code." }, "address": { "$ref": "#/components/schemas/AddressDto" }, "risk": { "$ref": "#/components/schemas/RiskDto" }, "rollup": { "$ref": "#/components/schemas/RollupDto" }, "insolvency_event_count": { "type": "integer", "description": "Null when the source did not answer.", "format": "int32", "nullable": true }, "admin_event_count": { "type": "integer", "description": "Null when the source did not answer.", "format": "int32", "nullable": true }, "mandates": { "type": "array", "items": { "$ref": "#/components/schemas/MandateDto" }, "description": "Current directors first, then former ones, then court-appointed roles. Null when no mandate source answered.", "nullable": true }, "coverage": { "$ref": "#/components/schemas/CoverageDto" }, "as_of": { "type": "string", "description": "When this answer was composed.", "format": "date-time" }, "register_situation_code": { "type": "string", "description": "The register's own legal-situation code: 000 ordinary, 050 open bankruptcy, 012 voluntary dissolution. Null when the register was not read.", "nullable": true } } }, "CoverageDto": { "required": [ "insolvency_timeline_read", "risk_scored", "stages_degraded" ], "type": "object", "properties": { "insolvency_timeline_read": { "type": "boolean" }, "risk_scored": { "type": "boolean" }, "stages_degraded": { "type": "array", "items": { "type": "string" } } }, "description": "What this answer is built on. Read it first." }, "LifecycleEventDto": { "required": [ "source", "severity", "numac", "pub_date", "event_kind", "court", "event_date", "detail" ], "type": "object", "properties": { "source": { "type": "string" }, "severity": { "type": "string" }, "numac": { "type": "string" }, "pub_date": { "type": "string", "format": "date", "nullable": true }, "event_kind": { "type": "string", "nullable": true }, "court": { "type": "string", "nullable": true }, "event_date": { "type": "string", "format": "date", "nullable": true }, "detail": { "type": "string", "nullable": true } } }, "MandateDto": { "required": [ "role", "role_kind", "name", "address", "from", "to", "source", "source_numac" ], "type": "object", "properties": { "role": { "type": "string" }, "role_kind": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string", "nullable": true }, "from": { "type": "string", "format": "date", "nullable": true }, "to": { "type": "string", "format": "date", "nullable": true }, "source": { "type": "string" }, "source_numac": { "type": "string" } } }, "RiskDto": { "required": [ "band", "score_out_of100", "probability", "altman_z", "model_version", "evaluated_at" ], "type": "object", "properties": { "band": { "type": "string", "description": "Follows the probability. Unknown when there is no current score." }, "score_out_of100": { "type": "integer", "description": "100 minus the twelve-month bankruptcy probability in percent: higher is safer. Null when unscored.", "format": "int32", "nullable": true }, "probability": { "type": "number", "format": "double", "nullable": true }, "altman_z": { "type": "number", "format": "double", "nullable": true }, "model_version": { "type": "string", "nullable": true }, "evaluated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "RollupDto": { "required": [ "total_events", "interim_signals", "reorg_events", "faillissement_events", "first_signal_date", "last_signal_date", "has_open_faillissement" ], "type": "object", "properties": { "total_events": { "type": "integer", "format": "int32" }, "interim_signals": { "type": "integer", "format": "int32" }, "reorg_events": { "type": "integer", "format": "int32" }, "faillissement_events": { "type": "integer", "format": "int32" }, "first_signal_date": { "type": "string", "format": "date", "nullable": true }, "last_signal_date": { "type": "string", "format": "date", "nullable": true }, "has_open_faillissement": { "type": "boolean" } }, "nullable": true }, "RollupDto2": { "required": [ "total_events", "interim_signals", "reorg_events", "faillissement_events", "first_signal_date", "last_signal_date", "has_open_faillissement" ], "type": "object", "properties": { "total_events": { "type": "integer", "format": "int32" }, "interim_signals": { "type": "integer", "format": "int32" }, "reorg_events": { "type": "integer", "format": "int32" }, "faillissement_events": { "type": "integer", "format": "int32" }, "first_signal_date": { "type": "string", "format": "date", "nullable": true }, "last_signal_date": { "type": "string", "format": "date", "nullable": true }, "has_open_faillissement": { "type": "boolean" } } }, "SearchHitDto": { "required": [ "enterprise_number", "legal_name", "slug", "city", "primary_nace", "match_kind", "matched_address", "kind", "href", "subtitle", "not_in_register" ], "type": "object", "properties": { "enterprise_number": { "type": "string" }, "legal_name": { "type": "string" }, "slug": { "type": "string" }, "city": { "type": "string", "nullable": true }, "primary_nace": { "type": "string", "nullable": true }, "match_kind": { "type": "string", "default": "name" }, "matched_address": { "type": "string", "default": null, "nullable": true }, "kind": { "type": "string", "default": "company" }, "href": { "type": "string", "default": null, "nullable": true }, "subtitle": { "type": "string", "default": null, "nullable": true }, "not_in_register": { "type": "boolean", "default": false } } } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "description": "Create it in your account.", "name": "X-Api-Key", "in": "header" } } }, "security": [ { "ApiKey": [ ] } ], "tags": [ { "name": "Companies" } ] }