{ "openapi": "3.0.3", "info": { "title": "Belscope API", "version": "1.0.0", "description": "Information about every company in Belgium, by enterprise number. Documentation: https://docs.belscope.be. A request that ends in an error never counts towards the requests in your plan.", "contact": { "name": "Belscope", "email": "info@belscope.be", "url": "https://docs.belscope.be" } }, "servers": [ { "url": "https://api.belscope.be/v1" } ], "security": [ { "apiKey": [] } ], "paths": { "/companies/{number}": { "get": { "operationId": "getCompany", "summary": "Get the profile of a company: general facts, address, contacts and activities", "description": "Documentation: https://docs.belscope.be/company/profile/", "parameters": [ { "$ref": "#/components/parameters/number" } ], "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" }, "example": { "enterprise_number": "0123.456.749", "general": { "name": "Belscope", "entity_type": "Rechtspersoon", "legal_form": "Besloten Vennootschap", "legal_situation": "Normale toestand", "start_date": "2018-02-01" }, "address": { "full": "Voorbeeldstraat 12 bus B, 9000 Gent", "street": "Voorbeeldstraat", "house_number": "12", "box": "B", "postal_code": "9000", "municipality": "Gent", "country": "België", "struck_off_date": null }, "contacts": { "emails": [ "info@belscope.be" ], "phones": [ "09 123 45 67" ], "websites": [ "www.belscope.be" ] }, "activities": { "main": [ { "code": "62100", "description": "Ontwerpen van computerprogramma’s" }, { "code": "63100", "description": "Computerinfrastructuur, gegevensverwerking, hosting en aanverwante activiteiten" } ], "secondary": [ { "code": "58290", "description": "Uitgeven van overige software" }, { "code": "62200", "description": "Activiteiten op het gebied van computerconsultancy en beheer van computerfaciliteiten" }, { "code": "62900", "description": "Overige diensten op het gebied van informatietechnologie en computer" } ] } } } } }, "400": { "description": "invalid_enterprise_number: The enterprise number in your request is not valid. key_in_url: Your API key was sent in the address of the request. unknown_parameter: Your request has a parameter this address does not accept.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_enterprise_number": { "summary": "The enterprise number in your request is not valid.", "description": "What to do: Check the number you sent. It must be 10 digits, for example 0123.456.749. Dots, spaces and BE in front are fine. One wrong digit, for example a typo, makes the number invalid.", "value": { "error": { "code": "invalid_enterprise_number", "message": "The enterprise number in your request is not valid." } } }, "key_in_url": { "summary": "Your API key was sent in the address of the request.", "description": "What to do: Send the key only in the Authorization header. Anyone who sees the address can now see your key: revoke it in your account on belscope.be and create a new one.", "value": { "error": { "code": "key_in_url", "message": "Your API key was sent in the address of the request." } } }, "unknown_parameter": { "summary": "Your request has a parameter this address does not accept.", "description": "What to do: The error names the parameter (parameter). Remove it: the pages of these docs show exactly what each address accepts.", "value": { "error": { "code": "unknown_parameter", "message": "Your request has a parameter this address does not accept." } } } } } } }, "401": { "description": "invalid_key: Your API key is missing, wrong or no longer valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "summary": "Your API key is missing, wrong or no longer valid.", "description": "What to do: Send your API key with every request, in the header Authorization: Bearer YOUR_KEY. Check that you copied the whole key, without spaces. A revoked key, or an account that is not active (yet), also gives this error.", "value": { "error": { "code": "invalid_key", "message": "Your API key is missing, wrong or no longer valid." } } } } } } }, "404": { "description": "company_not_found: No company has this number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "company_not_found": { "summary": "No company has this number.", "description": "What to do: Check the number for a typo. If it is correct, the company has stopped or never existed. Sending it again gives the same answer.", "value": { "error": { "code": "company_not_found", "message": "No company has this number." } } } } } } }, "429": { "description": "rate_limited: You sent too many requests in a short time. quota_exceeded: You have used all requests in your plan for this month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "You sent too many requests in a short time.", "description": "What to do: Wait a few seconds, then send the request again. Spread your requests over time instead of sending them all at once.", "value": { "error": { "code": "rate_limited", "message": "You sent too many requests in a short time." } } }, "quota_exceeded": { "summary": "You have used all requests in your plan for this month.", "description": "What to do: Contact us if you need more requests.", "value": { "error": { "code": "quota_exceeded", "message": "You have used all requests in your plan for this month." } } } } } } }, "500": { "description": "internal_error: The API is up, but something broke while handling this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "The API is up, but something broke while handling this request.", "description": "What to do: If it keeps failing for this request, contact us.", "value": { "error": { "code": "internal_error", "message": "The API is up, but something broke while handling this request." } } } } } } }, "503": { "description": "unavailable: The API is down for everyone right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unavailable": { "summary": "The API is down for everyone right now.", "description": "What to do: Wait a few minutes, then send the request again.", "value": { "error": { "code": "unavailable", "message": "The API is down for everyone right now." } } } } } } } } } }, "/companies/{number}/address": { "get": { "operationId": "getAddress", "summary": "Get a company's registered address", "description": "Documentation: https://docs.belscope.be/company/address/", "parameters": [ { "$ref": "#/components/parameters/number" } ], "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" }, "example": { "enterprise_number": "0123.456.749", "address": { "full": "Voorbeeldstraat 12 bus B, 9000 Gent", "street": "Voorbeeldstraat", "house_number": "12", "box": "B", "postal_code": "9000", "municipality": "Gent", "country": "België", "struck_off_date": null } } } } }, "400": { "description": "invalid_enterprise_number: The enterprise number in your request is not valid. key_in_url: Your API key was sent in the address of the request. unknown_parameter: Your request has a parameter this address does not accept.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_enterprise_number": { "summary": "The enterprise number in your request is not valid.", "description": "What to do: Check the number you sent. It must be 10 digits, for example 0123.456.749. Dots, spaces and BE in front are fine. One wrong digit, for example a typo, makes the number invalid.", "value": { "error": { "code": "invalid_enterprise_number", "message": "The enterprise number in your request is not valid." } } }, "key_in_url": { "summary": "Your API key was sent in the address of the request.", "description": "What to do: Send the key only in the Authorization header. Anyone who sees the address can now see your key: revoke it in your account on belscope.be and create a new one.", "value": { "error": { "code": "key_in_url", "message": "Your API key was sent in the address of the request." } } }, "unknown_parameter": { "summary": "Your request has a parameter this address does not accept.", "description": "What to do: The error names the parameter (parameter). Remove it: the pages of these docs show exactly what each address accepts.", "value": { "error": { "code": "unknown_parameter", "message": "Your request has a parameter this address does not accept." } } } } } } }, "401": { "description": "invalid_key: Your API key is missing, wrong or no longer valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "summary": "Your API key is missing, wrong or no longer valid.", "description": "What to do: Send your API key with every request, in the header Authorization: Bearer YOUR_KEY. Check that you copied the whole key, without spaces. A revoked key, or an account that is not active (yet), also gives this error.", "value": { "error": { "code": "invalid_key", "message": "Your API key is missing, wrong or no longer valid." } } } } } } }, "404": { "description": "company_not_found: No company has this number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "company_not_found": { "summary": "No company has this number.", "description": "What to do: Check the number for a typo. If it is correct, the company has stopped or never existed. Sending it again gives the same answer.", "value": { "error": { "code": "company_not_found", "message": "No company has this number." } } } } } } }, "429": { "description": "rate_limited: You sent too many requests in a short time. quota_exceeded: You have used all requests in your plan for this month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "You sent too many requests in a short time.", "description": "What to do: Wait a few seconds, then send the request again. Spread your requests over time instead of sending them all at once.", "value": { "error": { "code": "rate_limited", "message": "You sent too many requests in a short time." } } }, "quota_exceeded": { "summary": "You have used all requests in your plan for this month.", "description": "What to do: Contact us if you need more requests.", "value": { "error": { "code": "quota_exceeded", "message": "You have used all requests in your plan for this month." } } } } } } }, "500": { "description": "internal_error: The API is up, but something broke while handling this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "The API is up, but something broke while handling this request.", "description": "What to do: If it keeps failing for this request, contact us.", "value": { "error": { "code": "internal_error", "message": "The API is up, but something broke while handling this request." } } } } } } }, "503": { "description": "unavailable: The API is down for everyone right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unavailable": { "summary": "The API is down for everyone right now.", "description": "What to do: Wait a few minutes, then send the request again.", "value": { "error": { "code": "unavailable", "message": "The API is down for everyone right now." } } } } } } } } } }, "/companies/{number}/contacts": { "get": { "operationId": "getContacts", "summary": "Get a company's email addresses, phone numbers and websites", "description": "Documentation: https://docs.belscope.be/company/contacts/", "parameters": [ { "$ref": "#/components/parameters/number" } ], "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contacts" }, "example": { "enterprise_number": "0123.456.749", "contacts": { "emails": [ "info@belscope.be" ], "phones": [ "09 123 45 67" ], "websites": [ "www.belscope.be" ] } } } } }, "400": { "description": "invalid_enterprise_number: The enterprise number in your request is not valid. key_in_url: Your API key was sent in the address of the request. unknown_parameter: Your request has a parameter this address does not accept.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_enterprise_number": { "summary": "The enterprise number in your request is not valid.", "description": "What to do: Check the number you sent. It must be 10 digits, for example 0123.456.749. Dots, spaces and BE in front are fine. One wrong digit, for example a typo, makes the number invalid.", "value": { "error": { "code": "invalid_enterprise_number", "message": "The enterprise number in your request is not valid." } } }, "key_in_url": { "summary": "Your API key was sent in the address of the request.", "description": "What to do: Send the key only in the Authorization header. Anyone who sees the address can now see your key: revoke it in your account on belscope.be and create a new one.", "value": { "error": { "code": "key_in_url", "message": "Your API key was sent in the address of the request." } } }, "unknown_parameter": { "summary": "Your request has a parameter this address does not accept.", "description": "What to do: The error names the parameter (parameter). Remove it: the pages of these docs show exactly what each address accepts.", "value": { "error": { "code": "unknown_parameter", "message": "Your request has a parameter this address does not accept." } } } } } } }, "401": { "description": "invalid_key: Your API key is missing, wrong or no longer valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "summary": "Your API key is missing, wrong or no longer valid.", "description": "What to do: Send your API key with every request, in the header Authorization: Bearer YOUR_KEY. Check that you copied the whole key, without spaces. A revoked key, or an account that is not active (yet), also gives this error.", "value": { "error": { "code": "invalid_key", "message": "Your API key is missing, wrong or no longer valid." } } } } } } }, "404": { "description": "company_not_found: No company has this number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "company_not_found": { "summary": "No company has this number.", "description": "What to do: Check the number for a typo. If it is correct, the company has stopped or never existed. Sending it again gives the same answer.", "value": { "error": { "code": "company_not_found", "message": "No company has this number." } } } } } } }, "429": { "description": "rate_limited: You sent too many requests in a short time. quota_exceeded: You have used all requests in your plan for this month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "You sent too many requests in a short time.", "description": "What to do: Wait a few seconds, then send the request again. Spread your requests over time instead of sending them all at once.", "value": { "error": { "code": "rate_limited", "message": "You sent too many requests in a short time." } } }, "quota_exceeded": { "summary": "You have used all requests in your plan for this month.", "description": "What to do: Contact us if you need more requests.", "value": { "error": { "code": "quota_exceeded", "message": "You have used all requests in your plan for this month." } } } } } } }, "500": { "description": "internal_error: The API is up, but something broke while handling this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "The API is up, but something broke while handling this request.", "description": "What to do: If it keeps failing for this request, contact us.", "value": { "error": { "code": "internal_error", "message": "The API is up, but something broke while handling this request." } } } } } } }, "503": { "description": "unavailable: The API is down for everyone right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unavailable": { "summary": "The API is down for everyone right now.", "description": "What to do: Wait a few minutes, then send the request again.", "value": { "error": { "code": "unavailable", "message": "The API is down for everyone right now." } } } } } } } } } }, "/companies/{number}/activities": { "get": { "operationId": "getActivities", "summary": "Get a company's activities", "description": "Documentation: https://docs.belscope.be/company/activities/", "parameters": [ { "$ref": "#/components/parameters/number" } ], "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Activities" }, "example": { "enterprise_number": "0123.456.749", "activities": { "main": [ { "code": "62100", "description": "Ontwerpen van computerprogramma’s" }, { "code": "63100", "description": "Computerinfrastructuur, gegevensverwerking, hosting en aanverwante activiteiten" } ], "secondary": [ { "code": "58290", "description": "Uitgeven van overige software" }, { "code": "62200", "description": "Activiteiten op het gebied van computerconsultancy en beheer van computerfaciliteiten" }, { "code": "62900", "description": "Overige diensten op het gebied van informatietechnologie en computer" } ] } } } } }, "400": { "description": "invalid_enterprise_number: The enterprise number in your request is not valid. key_in_url: Your API key was sent in the address of the request. unknown_parameter: Your request has a parameter this address does not accept.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_enterprise_number": { "summary": "The enterprise number in your request is not valid.", "description": "What to do: Check the number you sent. It must be 10 digits, for example 0123.456.749. Dots, spaces and BE in front are fine. One wrong digit, for example a typo, makes the number invalid.", "value": { "error": { "code": "invalid_enterprise_number", "message": "The enterprise number in your request is not valid." } } }, "key_in_url": { "summary": "Your API key was sent in the address of the request.", "description": "What to do: Send the key only in the Authorization header. Anyone who sees the address can now see your key: revoke it in your account on belscope.be and create a new one.", "value": { "error": { "code": "key_in_url", "message": "Your API key was sent in the address of the request." } } }, "unknown_parameter": { "summary": "Your request has a parameter this address does not accept.", "description": "What to do: The error names the parameter (parameter). Remove it: the pages of these docs show exactly what each address accepts.", "value": { "error": { "code": "unknown_parameter", "message": "Your request has a parameter this address does not accept." } } } } } } }, "401": { "description": "invalid_key: Your API key is missing, wrong or no longer valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "summary": "Your API key is missing, wrong or no longer valid.", "description": "What to do: Send your API key with every request, in the header Authorization: Bearer YOUR_KEY. Check that you copied the whole key, without spaces. A revoked key, or an account that is not active (yet), also gives this error.", "value": { "error": { "code": "invalid_key", "message": "Your API key is missing, wrong or no longer valid." } } } } } } }, "404": { "description": "company_not_found: No company has this number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "company_not_found": { "summary": "No company has this number.", "description": "What to do: Check the number for a typo. If it is correct, the company has stopped or never existed. Sending it again gives the same answer.", "value": { "error": { "code": "company_not_found", "message": "No company has this number." } } } } } } }, "429": { "description": "rate_limited: You sent too many requests in a short time. quota_exceeded: You have used all requests in your plan for this month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "You sent too many requests in a short time.", "description": "What to do: Wait a few seconds, then send the request again. Spread your requests over time instead of sending them all at once.", "value": { "error": { "code": "rate_limited", "message": "You sent too many requests in a short time." } } }, "quota_exceeded": { "summary": "You have used all requests in your plan for this month.", "description": "What to do: Contact us if you need more requests.", "value": { "error": { "code": "quota_exceeded", "message": "You have used all requests in your plan for this month." } } } } } } }, "500": { "description": "internal_error: The API is up, but something broke while handling this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "The API is up, but something broke while handling this request.", "description": "What to do: If it keeps failing for this request, contact us.", "value": { "error": { "code": "internal_error", "message": "The API is up, but something broke while handling this request." } } } } } } }, "503": { "description": "unavailable: The API is down for everyone right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unavailable": { "summary": "The API is down for everyone right now.", "description": "What to do: Wait a few minutes, then send the request again.", "value": { "error": { "code": "unavailable", "message": "The API is down for everyone right now." } } } } } } } } } }, "/companies/{number}/establishments": { "get": { "operationId": "getEstablishments", "summary": "Get a company's establishments", "description": "Documentation: https://docs.belscope.be/company/establishments/", "parameters": [ { "$ref": "#/components/parameters/number" } ], "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Establishments" }, "example": { "enterprise_number": "0123.456.749", "establishments": [ { "establishment_number": "2.123.456.791", "name": "Belscope Gent", "start_date": "2018-02-01", "address": { "full": "Voorbeeldstraat 12 bus B, 9000 Gent", "street": "Voorbeeldstraat", "house_number": "12", "box": "B", "postal_code": "9000", "municipality": "Gent", "country": "België", "struck_off_date": null }, "contacts": { "emails": [ "gent@belscope.be" ], "phones": [ "09 123 45 68" ], "websites": [ "www.belscope.be" ] }, "activities": { "main": [ { "code": "62100", "description": "Ontwerpen van computerprogramma’s" } ], "secondary": [] } } ] } } } }, "400": { "description": "invalid_enterprise_number: The enterprise number in your request is not valid. key_in_url: Your API key was sent in the address of the request. unknown_parameter: Your request has a parameter this address does not accept.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_enterprise_number": { "summary": "The enterprise number in your request is not valid.", "description": "What to do: Check the number you sent. It must be 10 digits, for example 0123.456.749. Dots, spaces and BE in front are fine. One wrong digit, for example a typo, makes the number invalid.", "value": { "error": { "code": "invalid_enterprise_number", "message": "The enterprise number in your request is not valid." } } }, "key_in_url": { "summary": "Your API key was sent in the address of the request.", "description": "What to do: Send the key only in the Authorization header. Anyone who sees the address can now see your key: revoke it in your account on belscope.be and create a new one.", "value": { "error": { "code": "key_in_url", "message": "Your API key was sent in the address of the request." } } }, "unknown_parameter": { "summary": "Your request has a parameter this address does not accept.", "description": "What to do: The error names the parameter (parameter). Remove it: the pages of these docs show exactly what each address accepts.", "value": { "error": { "code": "unknown_parameter", "message": "Your request has a parameter this address does not accept." } } } } } } }, "401": { "description": "invalid_key: Your API key is missing, wrong or no longer valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "summary": "Your API key is missing, wrong or no longer valid.", "description": "What to do: Send your API key with every request, in the header Authorization: Bearer YOUR_KEY. Check that you copied the whole key, without spaces. A revoked key, or an account that is not active (yet), also gives this error.", "value": { "error": { "code": "invalid_key", "message": "Your API key is missing, wrong or no longer valid." } } } } } } }, "404": { "description": "company_not_found: No company has this number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "company_not_found": { "summary": "No company has this number.", "description": "What to do: Check the number for a typo. If it is correct, the company has stopped or never existed. Sending it again gives the same answer.", "value": { "error": { "code": "company_not_found", "message": "No company has this number." } } } } } } }, "429": { "description": "rate_limited: You sent too many requests in a short time. quota_exceeded: You have used all requests in your plan for this month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "You sent too many requests in a short time.", "description": "What to do: Wait a few seconds, then send the request again. Spread your requests over time instead of sending them all at once.", "value": { "error": { "code": "rate_limited", "message": "You sent too many requests in a short time." } } }, "quota_exceeded": { "summary": "You have used all requests in your plan for this month.", "description": "What to do: Contact us if you need more requests.", "value": { "error": { "code": "quota_exceeded", "message": "You have used all requests in your plan for this month." } } } } } } }, "500": { "description": "internal_error: The API is up, but something broke while handling this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "The API is up, but something broke while handling this request.", "description": "What to do: If it keeps failing for this request, contact us.", "value": { "error": { "code": "internal_error", "message": "The API is up, but something broke while handling this request." } } } } } } }, "503": { "description": "unavailable: The API is down for everyone right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unavailable": { "summary": "The API is down for everyone right now.", "description": "What to do: Wait a few minutes, then send the request again.", "value": { "error": { "code": "unavailable", "message": "The API is down for everyone right now." } } } } } } } } } }, "/companies/{number}/branches": { "get": { "operationId": "getBranches", "summary": "Get a foreign company's branches", "description": "Documentation: https://docs.belscope.be/company/branches/", "parameters": [ { "$ref": "#/components/parameters/number" } ], "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Branches" }, "example": { "enterprise_number": "0123.456.749", "branches": [ { "branch_number": "9.123.456.744", "name": "Belscope Antwerpen", "start_date": "2020-06-01", "address": { "full": "Voorbeeldlaan 5 bus 2, 2000 Antwerpen", "street": "Voorbeeldlaan", "house_number": "5", "box": "2", "postal_code": "2000", "municipality": "Antwerpen", "country": "België", "struck_off_date": null } } ] } } } }, "400": { "description": "invalid_enterprise_number: The enterprise number in your request is not valid. key_in_url: Your API key was sent in the address of the request. unknown_parameter: Your request has a parameter this address does not accept.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_enterprise_number": { "summary": "The enterprise number in your request is not valid.", "description": "What to do: Check the number you sent. It must be 10 digits, for example 0123.456.749. Dots, spaces and BE in front are fine. One wrong digit, for example a typo, makes the number invalid.", "value": { "error": { "code": "invalid_enterprise_number", "message": "The enterprise number in your request is not valid." } } }, "key_in_url": { "summary": "Your API key was sent in the address of the request.", "description": "What to do: Send the key only in the Authorization header. Anyone who sees the address can now see your key: revoke it in your account on belscope.be and create a new one.", "value": { "error": { "code": "key_in_url", "message": "Your API key was sent in the address of the request." } } }, "unknown_parameter": { "summary": "Your request has a parameter this address does not accept.", "description": "What to do: The error names the parameter (parameter). Remove it: the pages of these docs show exactly what each address accepts.", "value": { "error": { "code": "unknown_parameter", "message": "Your request has a parameter this address does not accept." } } } } } } }, "401": { "description": "invalid_key: Your API key is missing, wrong or no longer valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "summary": "Your API key is missing, wrong or no longer valid.", "description": "What to do: Send your API key with every request, in the header Authorization: Bearer YOUR_KEY. Check that you copied the whole key, without spaces. A revoked key, or an account that is not active (yet), also gives this error.", "value": { "error": { "code": "invalid_key", "message": "Your API key is missing, wrong or no longer valid." } } } } } } }, "404": { "description": "company_not_found: No company has this number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "company_not_found": { "summary": "No company has this number.", "description": "What to do: Check the number for a typo. If it is correct, the company has stopped or never existed. Sending it again gives the same answer.", "value": { "error": { "code": "company_not_found", "message": "No company has this number." } } } } } } }, "429": { "description": "rate_limited: You sent too many requests in a short time. quota_exceeded: You have used all requests in your plan for this month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "You sent too many requests in a short time.", "description": "What to do: Wait a few seconds, then send the request again. Spread your requests over time instead of sending them all at once.", "value": { "error": { "code": "rate_limited", "message": "You sent too many requests in a short time." } } }, "quota_exceeded": { "summary": "You have used all requests in your plan for this month.", "description": "What to do: Contact us if you need more requests.", "value": { "error": { "code": "quota_exceeded", "message": "You have used all requests in your plan for this month." } } } } } } }, "500": { "description": "internal_error: The API is up, but something broke while handling this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "The API is up, but something broke while handling this request.", "description": "What to do: If it keeps failing for this request, contact us.", "value": { "error": { "code": "internal_error", "message": "The API is up, but something broke while handling this request." } } } } } } }, "503": { "description": "unavailable: The API is down for everyone right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unavailable": { "summary": "The API is down for everyone right now.", "description": "What to do: Wait a few minutes, then send the request again.", "value": { "error": { "code": "unavailable", "message": "The API is down for everyone right now." } } } } } } } } } }, "/companies/{number}/employees": { "get": { "operationId": "getEmployees", "summary": "Get a company's employees", "description": "Documentation: https://docs.belscope.be/employment/employees/", "parameters": [ { "$ref": "#/components/parameters/number" } ], "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Employees" }, "example": { "enterprise_number": "0123.456.749", "year_end": "2025-12-31", "fte": 27.9, "headcount": { "full_time": 25.8, "part_time": 2.9 }, "at_year_end": { "full_time": 27, "part_time": 3, "fte": 29.1, "white_collar": { "full_time": 13, "part_time": 2, "fte": 14.1 }, "blue_collar": { "full_time": 14, "part_time": 1, "fte": 15 } } } } } }, "400": { "description": "invalid_enterprise_number: The enterprise number in your request is not valid. key_in_url: Your API key was sent in the address of the request. unknown_parameter: Your request has a parameter this address does not accept.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_enterprise_number": { "summary": "The enterprise number in your request is not valid.", "description": "What to do: Check the number you sent. It must be 10 digits, for example 0123.456.749. Dots, spaces and BE in front are fine. One wrong digit, for example a typo, makes the number invalid.", "value": { "error": { "code": "invalid_enterprise_number", "message": "The enterprise number in your request is not valid." } } }, "key_in_url": { "summary": "Your API key was sent in the address of the request.", "description": "What to do: Send the key only in the Authorization header. Anyone who sees the address can now see your key: revoke it in your account on belscope.be and create a new one.", "value": { "error": { "code": "key_in_url", "message": "Your API key was sent in the address of the request." } } }, "unknown_parameter": { "summary": "Your request has a parameter this address does not accept.", "description": "What to do: The error names the parameter (parameter). Remove it: the pages of these docs show exactly what each address accepts.", "value": { "error": { "code": "unknown_parameter", "message": "Your request has a parameter this address does not accept." } } } } } } }, "401": { "description": "invalid_key: Your API key is missing, wrong or no longer valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "summary": "Your API key is missing, wrong or no longer valid.", "description": "What to do: Send your API key with every request, in the header Authorization: Bearer YOUR_KEY. Check that you copied the whole key, without spaces. A revoked key, or an account that is not active (yet), also gives this error.", "value": { "error": { "code": "invalid_key", "message": "Your API key is missing, wrong or no longer valid." } } } } } } }, "404": { "description": "company_not_found: No company has this number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "company_not_found": { "summary": "No company has this number.", "description": "What to do: Check the number for a typo. If it is correct, the company has stopped or never existed. Sending it again gives the same answer.", "value": { "error": { "code": "company_not_found", "message": "No company has this number." } } } } } } }, "429": { "description": "rate_limited: You sent too many requests in a short time. quota_exceeded: You have used all requests in your plan for this month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "You sent too many requests in a short time.", "description": "What to do: Wait a few seconds, then send the request again. Spread your requests over time instead of sending them all at once.", "value": { "error": { "code": "rate_limited", "message": "You sent too many requests in a short time." } } }, "quota_exceeded": { "summary": "You have used all requests in your plan for this month.", "description": "What to do: Contact us if you need more requests.", "value": { "error": { "code": "quota_exceeded", "message": "You have used all requests in your plan for this month." } } } } } } }, "500": { "description": "internal_error: The API is up, but something broke while handling this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "The API is up, but something broke while handling this request.", "description": "What to do: If it keeps failing for this request, contact us.", "value": { "error": { "code": "internal_error", "message": "The API is up, but something broke while handling this request." } } } } } } }, "503": { "description": "unavailable: The API is down for everyone right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unavailable": { "summary": "The API is down for everyone right now.", "description": "What to do: Wait a few minutes, then send the request again.", "value": { "error": { "code": "unavailable", "message": "The API is down for everyone right now." } } } } } } } } } }, "/companies/{number}/joint-committees": { "get": { "operationId": "getJointCommittees", "summary": "Get a company's joint committees", "description": "Documentation: https://docs.belscope.be/employment/joint-committees/", "parameters": [ { "$ref": "#/components/parameters/number" } ], "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JointCommittees" }, "example": { "enterprise_number": "0123.456.749", "year_end": "2025-12-31", "joint_committees": [ { "code": "100", "name": "Aanvullend Paritair Comité voor de werklieden" }, { "code": "200", "name": "Aanvullend Paritair Comité voor de bedienden" } ] } } } }, "400": { "description": "invalid_enterprise_number: The enterprise number in your request is not valid. key_in_url: Your API key was sent in the address of the request. unknown_parameter: Your request has a parameter this address does not accept.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_enterprise_number": { "summary": "The enterprise number in your request is not valid.", "description": "What to do: Check the number you sent. It must be 10 digits, for example 0123.456.749. Dots, spaces and BE in front are fine. One wrong digit, for example a typo, makes the number invalid.", "value": { "error": { "code": "invalid_enterprise_number", "message": "The enterprise number in your request is not valid." } } }, "key_in_url": { "summary": "Your API key was sent in the address of the request.", "description": "What to do: Send the key only in the Authorization header. Anyone who sees the address can now see your key: revoke it in your account on belscope.be and create a new one.", "value": { "error": { "code": "key_in_url", "message": "Your API key was sent in the address of the request." } } }, "unknown_parameter": { "summary": "Your request has a parameter this address does not accept.", "description": "What to do: The error names the parameter (parameter). Remove it: the pages of these docs show exactly what each address accepts.", "value": { "error": { "code": "unknown_parameter", "message": "Your request has a parameter this address does not accept." } } } } } } }, "401": { "description": "invalid_key: Your API key is missing, wrong or no longer valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "summary": "Your API key is missing, wrong or no longer valid.", "description": "What to do: Send your API key with every request, in the header Authorization: Bearer YOUR_KEY. Check that you copied the whole key, without spaces. A revoked key, or an account that is not active (yet), also gives this error.", "value": { "error": { "code": "invalid_key", "message": "Your API key is missing, wrong or no longer valid." } } } } } } }, "404": { "description": "company_not_found: No company has this number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "company_not_found": { "summary": "No company has this number.", "description": "What to do: Check the number for a typo. If it is correct, the company has stopped or never existed. Sending it again gives the same answer.", "value": { "error": { "code": "company_not_found", "message": "No company has this number." } } } } } } }, "429": { "description": "rate_limited: You sent too many requests in a short time. quota_exceeded: You have used all requests in your plan for this month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "You sent too many requests in a short time.", "description": "What to do: Wait a few seconds, then send the request again. Spread your requests over time instead of sending them all at once.", "value": { "error": { "code": "rate_limited", "message": "You sent too many requests in a short time." } } }, "quota_exceeded": { "summary": "You have used all requests in your plan for this month.", "description": "What to do: Contact us if you need more requests.", "value": { "error": { "code": "quota_exceeded", "message": "You have used all requests in your plan for this month." } } } } } } }, "500": { "description": "internal_error: The API is up, but something broke while handling this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "The API is up, but something broke while handling this request.", "description": "What to do: If it keeps failing for this request, contact us.", "value": { "error": { "code": "internal_error", "message": "The API is up, but something broke while handling this request." } } } } } } }, "503": { "description": "unavailable: The API is down for everyone right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unavailable": { "summary": "The API is down for everyone right now.", "description": "What to do: Wait a few minutes, then send the request again.", "value": { "error": { "code": "unavailable", "message": "The API is down for everyone right now." } } } } } } } } } }, "/companies/{number}/financials": { "get": { "operationId": "getFinancials", "summary": "Get a company's financials", "description": "Documentation: https://docs.belscope.be/financials/", "parameters": [ { "$ref": "#/components/parameters/number" } ], "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Financials" }, "example": { "enterprise_number": "0123.456.749", "year_start": "2025-01-01", "year_end": "2025-12-31", "filed_on": "2026-07-14", "model": "Volledig model voor kapitaalvennootschap", "currency": "EUR", "turnover": 1246789.58, "gross_margin": null, "operating_income": 1295803.23, "operating_costs": 1324263.97, "personnel_costs": 181285.52, "operating_result": -28460.73, "financial_income": 1895.6, "financial_costs": 9584.92, "result_before_tax": -36150.05, "taxes": -1929.24, "net_result": -34177.28, "fixed_assets": 220758.89, "current_assets": 467921.81, "cash": 29086.7, "total_assets": 688680.7, "equity": 129248.22, "debts": 559131.36, "debts_long_term": 79996.24, "debts_short_term": 478834.77 } } } }, "400": { "description": "invalid_enterprise_number: The enterprise number in your request is not valid. key_in_url: Your API key was sent in the address of the request. unknown_parameter: Your request has a parameter this address does not accept.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_enterprise_number": { "summary": "The enterprise number in your request is not valid.", "description": "What to do: Check the number you sent. It must be 10 digits, for example 0123.456.749. Dots, spaces and BE in front are fine. One wrong digit, for example a typo, makes the number invalid.", "value": { "error": { "code": "invalid_enterprise_number", "message": "The enterprise number in your request is not valid." } } }, "key_in_url": { "summary": "Your API key was sent in the address of the request.", "description": "What to do: Send the key only in the Authorization header. Anyone who sees the address can now see your key: revoke it in your account on belscope.be and create a new one.", "value": { "error": { "code": "key_in_url", "message": "Your API key was sent in the address of the request." } } }, "unknown_parameter": { "summary": "Your request has a parameter this address does not accept.", "description": "What to do: The error names the parameter (parameter). Remove it: the pages of these docs show exactly what each address accepts.", "value": { "error": { "code": "unknown_parameter", "message": "Your request has a parameter this address does not accept." } } } } } } }, "401": { "description": "invalid_key: Your API key is missing, wrong or no longer valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "summary": "Your API key is missing, wrong or no longer valid.", "description": "What to do: Send your API key with every request, in the header Authorization: Bearer YOUR_KEY. Check that you copied the whole key, without spaces. A revoked key, or an account that is not active (yet), also gives this error.", "value": { "error": { "code": "invalid_key", "message": "Your API key is missing, wrong or no longer valid." } } } } } } }, "404": { "description": "company_not_found: No company has this number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "company_not_found": { "summary": "No company has this number.", "description": "What to do: Check the number for a typo. If it is correct, the company has stopped or never existed. Sending it again gives the same answer.", "value": { "error": { "code": "company_not_found", "message": "No company has this number." } } } } } } }, "429": { "description": "rate_limited: You sent too many requests in a short time. quota_exceeded: You have used all requests in your plan for this month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "You sent too many requests in a short time.", "description": "What to do: Wait a few seconds, then send the request again. Spread your requests over time instead of sending them all at once.", "value": { "error": { "code": "rate_limited", "message": "You sent too many requests in a short time." } } }, "quota_exceeded": { "summary": "You have used all requests in your plan for this month.", "description": "What to do: Contact us if you need more requests.", "value": { "error": { "code": "quota_exceeded", "message": "You have used all requests in your plan for this month." } } } } } } }, "500": { "description": "internal_error: The API is up, but something broke while handling this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "The API is up, but something broke while handling this request.", "description": "What to do: If it keeps failing for this request, contact us.", "value": { "error": { "code": "internal_error", "message": "The API is up, but something broke while handling this request." } } } } } } }, "503": { "description": "unavailable: The API is down for everyone right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unavailable": { "summary": "The API is down for everyone right now.", "description": "What to do: Wait a few minutes, then send the request again.", "value": { "error": { "code": "unavailable", "message": "The API is down for everyone right now." } } } } } } } } } }, "/companies/{number}/directors": { "get": { "operationId": "getDirectors", "summary": "Get a company's directors", "description": "Documentation: https://docs.belscope.be/ownership/directors/", "parameters": [ { "$ref": "#/components/parameters/number" } ], "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Directors" }, "example": { "enterprise_number": "0123.456.749", "year_end": "2025-12-31", "directors": [ { "entity_type": "Natuurlijk Persoon", "name": "An Janssens", "first_name": "An", "last_name": "Janssens", "enterprise_number": null, "other_number": null, "address": { "full": "Molenstraat 8, 9050 Gent", "street": "Molenstraat", "house_number": "8", "box": null, "postal_code": "9050", "municipality": "Gent", "country": "België" }, "roles": [ { "role": "Bestuurder", "start_date": "2020-06-10", "end_date": "2030-06-10" } ], "representatives": [] }, { "entity_type": "Rechtspersoon", "name": "Belscope Holding", "first_name": null, "last_name": null, "enterprise_number": "0123.456.848", "other_number": null, "address": { "full": "Voorbeeldlaan 5, 2000 Antwerpen", "street": "Voorbeeldlaan", "house_number": "5", "box": null, "postal_code": "2000", "municipality": "Antwerpen", "country": "België" }, "roles": [ { "role": "Gedelegeerd bestuurder", "start_date": "2018-02-01", "end_date": "2030-06-10" } ], "representatives": [ { "name": "Jan Peeters", "first_name": "Jan", "last_name": "Peeters", "address": { "full": "Kerkstraat 3, 9000 Gent", "street": "Kerkstraat", "house_number": "3", "box": null, "postal_code": "9000", "municipality": "Gent", "country": "België" } } ] } ] } } } }, "400": { "description": "invalid_enterprise_number: The enterprise number in your request is not valid. key_in_url: Your API key was sent in the address of the request. unknown_parameter: Your request has a parameter this address does not accept.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_enterprise_number": { "summary": "The enterprise number in your request is not valid.", "description": "What to do: Check the number you sent. It must be 10 digits, for example 0123.456.749. Dots, spaces and BE in front are fine. One wrong digit, for example a typo, makes the number invalid.", "value": { "error": { "code": "invalid_enterprise_number", "message": "The enterprise number in your request is not valid." } } }, "key_in_url": { "summary": "Your API key was sent in the address of the request.", "description": "What to do: Send the key only in the Authorization header. Anyone who sees the address can now see your key: revoke it in your account on belscope.be and create a new one.", "value": { "error": { "code": "key_in_url", "message": "Your API key was sent in the address of the request." } } }, "unknown_parameter": { "summary": "Your request has a parameter this address does not accept.", "description": "What to do: The error names the parameter (parameter). Remove it: the pages of these docs show exactly what each address accepts.", "value": { "error": { "code": "unknown_parameter", "message": "Your request has a parameter this address does not accept." } } } } } } }, "401": { "description": "invalid_key: Your API key is missing, wrong or no longer valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "summary": "Your API key is missing, wrong or no longer valid.", "description": "What to do: Send your API key with every request, in the header Authorization: Bearer YOUR_KEY. Check that you copied the whole key, without spaces. A revoked key, or an account that is not active (yet), also gives this error.", "value": { "error": { "code": "invalid_key", "message": "Your API key is missing, wrong or no longer valid." } } } } } } }, "404": { "description": "company_not_found: No company has this number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "company_not_found": { "summary": "No company has this number.", "description": "What to do: Check the number for a typo. If it is correct, the company has stopped or never existed. Sending it again gives the same answer.", "value": { "error": { "code": "company_not_found", "message": "No company has this number." } } } } } } }, "429": { "description": "rate_limited: You sent too many requests in a short time. quota_exceeded: You have used all requests in your plan for this month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "You sent too many requests in a short time.", "description": "What to do: Wait a few seconds, then send the request again. Spread your requests over time instead of sending them all at once.", "value": { "error": { "code": "rate_limited", "message": "You sent too many requests in a short time." } } }, "quota_exceeded": { "summary": "You have used all requests in your plan for this month.", "description": "What to do: Contact us if you need more requests.", "value": { "error": { "code": "quota_exceeded", "message": "You have used all requests in your plan for this month." } } } } } } }, "500": { "description": "internal_error: The API is up, but something broke while handling this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "The API is up, but something broke while handling this request.", "description": "What to do: If it keeps failing for this request, contact us.", "value": { "error": { "code": "internal_error", "message": "The API is up, but something broke while handling this request." } } } } } } }, "503": { "description": "unavailable: The API is down for everyone right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unavailable": { "summary": "The API is down for everyone right now.", "description": "What to do: Wait a few minutes, then send the request again.", "value": { "error": { "code": "unavailable", "message": "The API is down for everyone right now." } } } } } } } } } }, "/companies/{number}/shareholders": { "get": { "operationId": "getShareholders", "summary": "Get a company's shareholders", "description": "Documentation: https://docs.belscope.be/ownership/shareholders/", "parameters": [ { "$ref": "#/components/parameters/number" } ], "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shareholders" }, "example": { "enterprise_number": "0123.456.749", "year_end": "2025-12-31", "shareholders": [ { "entity_type": "Rechtspersoon", "name": "Belscope Holding", "first_name": null, "last_name": null, "enterprise_number": "0123.456.848", "other_number": null, "address": { "full": "Voorbeeldlaan 5, 2000 Antwerpen", "street": "Voorbeeldlaan", "house_number": "5", "box": null, "postal_code": "2000", "municipality": "Antwerpen", "country": "België" }, "holdings": [ { "nature": "Aandelen", "percentage": 75, "voting_rights_with_securities": 750, "voting_rights_without_securities": 0 } ] }, { "entity_type": "Natuurlijk Persoon", "name": "Jan Peeters", "first_name": "Jan", "last_name": "Peeters", "enterprise_number": null, "other_number": null, "address": { "full": "Kerkstraat 3, 9000 Gent", "street": "Kerkstraat", "house_number": "3", "box": null, "postal_code": "9000", "municipality": "Gent", "country": "België" }, "holdings": [ { "nature": "Aandelen", "percentage": 25, "voting_rights_with_securities": 250, "voting_rights_without_securities": 0 } ] } ] } } } }, "400": { "description": "invalid_enterprise_number: The enterprise number in your request is not valid. key_in_url: Your API key was sent in the address of the request. unknown_parameter: Your request has a parameter this address does not accept.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_enterprise_number": { "summary": "The enterprise number in your request is not valid.", "description": "What to do: Check the number you sent. It must be 10 digits, for example 0123.456.749. Dots, spaces and BE in front are fine. One wrong digit, for example a typo, makes the number invalid.", "value": { "error": { "code": "invalid_enterprise_number", "message": "The enterprise number in your request is not valid." } } }, "key_in_url": { "summary": "Your API key was sent in the address of the request.", "description": "What to do: Send the key only in the Authorization header. Anyone who sees the address can now see your key: revoke it in your account on belscope.be and create a new one.", "value": { "error": { "code": "key_in_url", "message": "Your API key was sent in the address of the request." } } }, "unknown_parameter": { "summary": "Your request has a parameter this address does not accept.", "description": "What to do: The error names the parameter (parameter). Remove it: the pages of these docs show exactly what each address accepts.", "value": { "error": { "code": "unknown_parameter", "message": "Your request has a parameter this address does not accept." } } } } } } }, "401": { "description": "invalid_key: Your API key is missing, wrong or no longer valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "summary": "Your API key is missing, wrong or no longer valid.", "description": "What to do: Send your API key with every request, in the header Authorization: Bearer YOUR_KEY. Check that you copied the whole key, without spaces. A revoked key, or an account that is not active (yet), also gives this error.", "value": { "error": { "code": "invalid_key", "message": "Your API key is missing, wrong or no longer valid." } } } } } } }, "404": { "description": "company_not_found: No company has this number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "company_not_found": { "summary": "No company has this number.", "description": "What to do: Check the number for a typo. If it is correct, the company has stopped or never existed. Sending it again gives the same answer.", "value": { "error": { "code": "company_not_found", "message": "No company has this number." } } } } } } }, "429": { "description": "rate_limited: You sent too many requests in a short time. quota_exceeded: You have used all requests in your plan for this month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "You sent too many requests in a short time.", "description": "What to do: Wait a few seconds, then send the request again. Spread your requests over time instead of sending them all at once.", "value": { "error": { "code": "rate_limited", "message": "You sent too many requests in a short time." } } }, "quota_exceeded": { "summary": "You have used all requests in your plan for this month.", "description": "What to do: Contact us if you need more requests.", "value": { "error": { "code": "quota_exceeded", "message": "You have used all requests in your plan for this month." } } } } } } }, "500": { "description": "internal_error: The API is up, but something broke while handling this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "The API is up, but something broke while handling this request.", "description": "What to do: If it keeps failing for this request, contact us.", "value": { "error": { "code": "internal_error", "message": "The API is up, but something broke while handling this request." } } } } } } }, "503": { "description": "unavailable: The API is down for everyone right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unavailable": { "summary": "The API is down for everyone right now.", "description": "What to do: Wait a few minutes, then send the request again.", "value": { "error": { "code": "unavailable", "message": "The API is down for everyone right now." } } } } } } } } } }, "/companies/{number}/participations": { "get": { "operationId": "getParticipations", "summary": "Get a company's participations", "description": "Documentation: https://docs.belscope.be/ownership/participations/", "parameters": [ { "$ref": "#/components/parameters/number" } ], "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Participations" }, "example": { "enterprise_number": "0123.456.749", "year_end": "2025-12-31", "participations": [ { "name": "Belscope Data", "enterprise_number": "0123.456.947", "other_number": null, "address": { "full": "Voorbeeldstraat 12, 9000 Gent", "street": "Voorbeeldstraat", "house_number": "12", "box": null, "postal_code": "9000", "municipality": "Gent", "country": "België" }, "holdings": [ { "nature": "Aandelen", "number": 100, "percentage_direct": 100, "percentage_through_subsidiaries": null } ] } ] } } } }, "400": { "description": "invalid_enterprise_number: The enterprise number in your request is not valid. key_in_url: Your API key was sent in the address of the request. unknown_parameter: Your request has a parameter this address does not accept.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_enterprise_number": { "summary": "The enterprise number in your request is not valid.", "description": "What to do: Check the number you sent. It must be 10 digits, for example 0123.456.749. Dots, spaces and BE in front are fine. One wrong digit, for example a typo, makes the number invalid.", "value": { "error": { "code": "invalid_enterprise_number", "message": "The enterprise number in your request is not valid." } } }, "key_in_url": { "summary": "Your API key was sent in the address of the request.", "description": "What to do: Send the key only in the Authorization header. Anyone who sees the address can now see your key: revoke it in your account on belscope.be and create a new one.", "value": { "error": { "code": "key_in_url", "message": "Your API key was sent in the address of the request." } } }, "unknown_parameter": { "summary": "Your request has a parameter this address does not accept.", "description": "What to do: The error names the parameter (parameter). Remove it: the pages of these docs show exactly what each address accepts.", "value": { "error": { "code": "unknown_parameter", "message": "Your request has a parameter this address does not accept." } } } } } } }, "401": { "description": "invalid_key: Your API key is missing, wrong or no longer valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "summary": "Your API key is missing, wrong or no longer valid.", "description": "What to do: Send your API key with every request, in the header Authorization: Bearer YOUR_KEY. Check that you copied the whole key, without spaces. A revoked key, or an account that is not active (yet), also gives this error.", "value": { "error": { "code": "invalid_key", "message": "Your API key is missing, wrong or no longer valid." } } } } } } }, "404": { "description": "company_not_found: No company has this number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "company_not_found": { "summary": "No company has this number.", "description": "What to do: Check the number for a typo. If it is correct, the company has stopped or never existed. Sending it again gives the same answer.", "value": { "error": { "code": "company_not_found", "message": "No company has this number." } } } } } } }, "429": { "description": "rate_limited: You sent too many requests in a short time. quota_exceeded: You have used all requests in your plan for this month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "You sent too many requests in a short time.", "description": "What to do: Wait a few seconds, then send the request again. Spread your requests over time instead of sending them all at once.", "value": { "error": { "code": "rate_limited", "message": "You sent too many requests in a short time." } } }, "quota_exceeded": { "summary": "You have used all requests in your plan for this month.", "description": "What to do: Contact us if you need more requests.", "value": { "error": { "code": "quota_exceeded", "message": "You have used all requests in your plan for this month." } } } } } } }, "500": { "description": "internal_error: The API is up, but something broke while handling this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "The API is up, but something broke while handling this request.", "description": "What to do: If it keeps failing for this request, contact us.", "value": { "error": { "code": "internal_error", "message": "The API is up, but something broke while handling this request." } } } } } } }, "503": { "description": "unavailable: The API is down for everyone right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unavailable": { "summary": "The API is down for everyone right now.", "description": "What to do: Wait a few minutes, then send the request again.", "value": { "error": { "code": "unavailable", "message": "The API is down for everyone right now." } } } } } } } } } }, "/companies": { "get": { "operationId": "searchCompanies", "summary": "Search companies", "description": "Documentation: https://docs.belscope.be/search/search-companies/", "parameters": [ { "name": "activity", "in": "query", "required": false, "description": "What the company does, as an activity code of NACE-BEL 2025 (older NACE 2008 codes find nothing). A short code covers everything under it: 62 finds every IT company (62100, 62900 and so on). Several codes: separate them with commas.", "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "62", "631" ], "style": "form", "explode": false }, { "name": "activity_type", "in": "query", "required": false, "description": "main: only the company's main activities count. all: its secondary activities count too. Default: main.", "schema": { "type": "string", "enum": [ "main", "all" ] }, "example": "all" }, { "name": "joint_committee", "in": "query", "required": false, "description": "The joint committee (paritair comité) number, such as 200 or 149.01. 149 does not include 149.01: to get both, ask for 149,149.01.", "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "200", "124" ], "style": "form", "explode": false }, { "name": "min_fte", "in": "query", "required": false, "description": "At least this many employees, in full-time equivalents. Companies whose number is not known are left out.", "schema": { "type": "number" }, "example": 10 }, { "name": "max_fte", "in": "query", "required": false, "description": "At most this many employees, in full-time equivalents. Companies whose number is not known are left out.", "schema": { "type": "number" }, "example": 50 }, { "name": "legal_form", "in": "query", "required": false, "description": "The legal form, as its code, such as 610 for a BV.", "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "610", "014" ], "style": "form", "explode": false }, { "name": "legal_situation", "in": "query", "required": false, "description": "The legal situation, as its code. 000 means active as normal: not dissolved, not bankrupt.", "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "000" ], "style": "form", "explode": false }, { "name": "min_age", "in": "query", "required": false, "description": "At least this many years old, counted in full years since the start date, like a person's age. Companies without a known start date are left out.", "schema": { "type": "number" }, "example": 1 }, { "name": "max_age", "in": "query", "required": false, "description": "At most this many years old, in full years: 0 is less than 1 year old, so max_age=0 finds the companies that started in the last 12 months.", "schema": { "type": "number" }, "example": 2 }, { "name": "limit", "in": "query", "required": false, "description": "How many companies per page, from 1 to 100. Every company in the answer counts as 1 request. Default: 100.", "schema": { "type": "number" }, "example": 50 }, { "name": "next", "in": "query", "required": false, "description": "For the next page: take next from the answer and send the same request again with it.", "schema": { "type": "string" }, "example": "eyJhZnRlciI6IjAxMjMuNDU2Ljc0OSJ9" } ], "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Search" }, "example": { "total": 1284, "results": [ { "enterprise_number": "0123.456.749", "general": { "name": "Belscope", "entity_type": "Rechtspersoon", "legal_form": "Besloten Vennootschap", "legal_situation": "Normale toestand", "start_date": "2018-02-01" }, "address": { "full": "Voorbeeldstraat 12 bus B, 9000 Gent", "street": "Voorbeeldstraat", "house_number": "12", "box": "B", "postal_code": "9000", "municipality": "Gent", "country": "België", "struck_off_date": null }, "contacts": { "emails": [ "info@belscope.be" ], "phones": [ "09 123 45 67" ], "websites": [ "www.belscope.be" ] }, "activities": { "main": [ { "code": "62100", "description": "Ontwerpen van computerprogramma’s" }, { "code": "63100", "description": "Computerinfrastructuur, gegevensverwerking, hosting en aanverwante activiteiten" } ], "secondary": [ { "code": "58290", "description": "Uitgeven van overige software" }, { "code": "62200", "description": "Activiteiten op het gebied van computerconsultancy en beheer van computerfaciliteiten" }, { "code": "62900", "description": "Overige diensten op het gebied van informatietechnologie en computer" } ] } } ], "next": "eyJhZnRlciI6IjAxMjM0NTY3NDkifQ" } } } }, "400": { "description": "key_in_url: Your API key was sent in the address of the request. unknown_parameter: Your request has a parameter this address does not accept. invalid_parameter: A parameter in your request has a value this address does not accept, or is sent twice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "key_in_url": { "summary": "Your API key was sent in the address of the request.", "description": "What to do: Send the key only in the Authorization header. Anyone who sees the address can now see your key: revoke it in your account on belscope.be and create a new one.", "value": { "error": { "code": "key_in_url", "message": "Your API key was sent in the address of the request." } } }, "unknown_parameter": { "summary": "Your request has a parameter this address does not accept.", "description": "What to do: The error names the parameter (parameter). Remove it: the pages of these docs show exactly what each address accepts.", "value": { "error": { "code": "unknown_parameter", "message": "Your request has a parameter this address does not accept." } } }, "invalid_parameter": { "summary": "A parameter in your request has a value this address does not accept, or is sent twice.", "description": "What to do: The error names the parameter (parameter). Check its value against the parameters on the page of this address, for example a number where a number is expected, a code written as in the lists, or a search without any filter.", "value": { "error": { "code": "invalid_parameter", "message": "A parameter in your request has a value this address does not accept, or is sent twice." } } } } } } }, "401": { "description": "invalid_key: Your API key is missing, wrong or no longer valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "summary": "Your API key is missing, wrong or no longer valid.", "description": "What to do: Send your API key with every request, in the header Authorization: Bearer YOUR_KEY. Check that you copied the whole key, without spaces. A revoked key, or an account that is not active (yet), also gives this error.", "value": { "error": { "code": "invalid_key", "message": "Your API key is missing, wrong or no longer valid." } } } } } } }, "429": { "description": "rate_limited: You sent too many requests in a short time. quota_exceeded: You have used all requests in your plan for this month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "You sent too many requests in a short time.", "description": "What to do: Wait a few seconds, then send the request again. Spread your requests over time instead of sending them all at once.", "value": { "error": { "code": "rate_limited", "message": "You sent too many requests in a short time." } } }, "quota_exceeded": { "summary": "You have used all requests in your plan for this month.", "description": "What to do: Contact us if you need more requests.", "value": { "error": { "code": "quota_exceeded", "message": "You have used all requests in your plan for this month." } } } } } } }, "500": { "description": "internal_error: The API is up, but something broke while handling this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "The API is up, but something broke while handling this request.", "description": "What to do: If it keeps failing for this request, contact us.", "value": { "error": { "code": "internal_error", "message": "The API is up, but something broke while handling this request." } } } } } } }, "503": { "description": "unavailable: The API is down for everyone right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unavailable": { "summary": "The API is down for everyone right now.", "description": "What to do: Wait a few minutes, then send the request again.", "value": { "error": { "code": "unavailable", "message": "The API is down for everyone right now." } } } } } } } } } }, "/companies/batch": { "get": { "operationId": "getCompanies", "summary": "Get multiple companies", "description": "Documentation: https://docs.belscope.be/search/multiple-companies/", "parameters": [ { "name": "numbers", "in": "query", "required": true, "description": "Up to 100 enterprise numbers, separated by commas. Every spelling that works for one company works here. One number that is not a valid enterprise number makes the whole request fail with invalid_enterprise_number.", "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "0400378485", "0123456749" ], "style": "form", "explode": false } ], "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" }, "example": { "companies": [ { "enterprise_number": "0123.456.749", "general": { "name": "Belscope", "entity_type": "Rechtspersoon", "legal_form": "Besloten Vennootschap", "legal_situation": "Normale toestand", "start_date": "2018-02-01" }, "address": { "full": "Voorbeeldstraat 12 bus B, 9000 Gent", "street": "Voorbeeldstraat", "house_number": "12", "box": "B", "postal_code": "9000", "municipality": "Gent", "country": "België", "struck_off_date": null }, "contacts": { "emails": [ "info@belscope.be" ], "phones": [ "09 123 45 67" ], "websites": [ "www.belscope.be" ] }, "activities": { "main": [ { "code": "62100", "description": "Ontwerpen van computerprogramma’s" }, { "code": "63100", "description": "Computerinfrastructuur, gegevensverwerking, hosting en aanverwante activiteiten" } ], "secondary": [ { "code": "58290", "description": "Uitgeven van overige software" }, { "code": "62200", "description": "Activiteiten op het gebied van computerconsultancy en beheer van computerfaciliteiten" }, { "code": "62900", "description": "Overige diensten op het gebied van informatietechnologie en computer" } ] } } ], "not_found": [ "0403.170.897" ] } } } }, "400": { "description": "invalid_enterprise_number: The enterprise number in your request is not valid. key_in_url: Your API key was sent in the address of the request. unknown_parameter: Your request has a parameter this address does not accept. invalid_parameter: A parameter in your request has a value this address does not accept, or is sent twice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_enterprise_number": { "summary": "The enterprise number in your request is not valid.", "description": "What to do: Check the number you sent. It must be 10 digits, for example 0123.456.749. Dots, spaces and BE in front are fine. One wrong digit, for example a typo, makes the number invalid.", "value": { "error": { "code": "invalid_enterprise_number", "message": "The enterprise number in your request is not valid." } } }, "key_in_url": { "summary": "Your API key was sent in the address of the request.", "description": "What to do: Send the key only in the Authorization header. Anyone who sees the address can now see your key: revoke it in your account on belscope.be and create a new one.", "value": { "error": { "code": "key_in_url", "message": "Your API key was sent in the address of the request." } } }, "unknown_parameter": { "summary": "Your request has a parameter this address does not accept.", "description": "What to do: The error names the parameter (parameter). Remove it: the pages of these docs show exactly what each address accepts.", "value": { "error": { "code": "unknown_parameter", "message": "Your request has a parameter this address does not accept." } } }, "invalid_parameter": { "summary": "A parameter in your request has a value this address does not accept, or is sent twice.", "description": "What to do: The error names the parameter (parameter). Check its value against the parameters on the page of this address, for example a number where a number is expected, a code written as in the lists, or a search without any filter.", "value": { "error": { "code": "invalid_parameter", "message": "A parameter in your request has a value this address does not accept, or is sent twice." } } } } } } }, "401": { "description": "invalid_key: Your API key is missing, wrong or no longer valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "summary": "Your API key is missing, wrong or no longer valid.", "description": "What to do: Send your API key with every request, in the header Authorization: Bearer YOUR_KEY. Check that you copied the whole key, without spaces. A revoked key, or an account that is not active (yet), also gives this error.", "value": { "error": { "code": "invalid_key", "message": "Your API key is missing, wrong or no longer valid." } } } } } } }, "429": { "description": "rate_limited: You sent too many requests in a short time. quota_exceeded: You have used all requests in your plan for this month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "You sent too many requests in a short time.", "description": "What to do: Wait a few seconds, then send the request again. Spread your requests over time instead of sending them all at once.", "value": { "error": { "code": "rate_limited", "message": "You sent too many requests in a short time." } } }, "quota_exceeded": { "summary": "You have used all requests in your plan for this month.", "description": "What to do: Contact us if you need more requests.", "value": { "error": { "code": "quota_exceeded", "message": "You have used all requests in your plan for this month." } } } } } } }, "500": { "description": "internal_error: The API is up, but something broke while handling this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "The API is up, but something broke while handling this request.", "description": "What to do: If it keeps failing for this request, contact us.", "value": { "error": { "code": "internal_error", "message": "The API is up, but something broke while handling this request." } } } } } } }, "503": { "description": "unavailable: The API is down for everyone right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unavailable": { "summary": "The API is down for everyone right now.", "description": "What to do: Wait a few minutes, then send the request again.", "value": { "error": { "code": "unavailable", "message": "The API is down for everyone right now." } } } } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Your API key, in the header Authorization: Bearer YOUR_KEY. Never in the address." } }, "parameters": { "number": { "name": "number", "in": "path", "required": true, "description": "The enterprise number: 10 digits, with or without dots, spaces or BE in front (0123456749, 0123.456.749, BE0123456749, BE 0123.456.749).", "schema": { "type": "string", "maxLength": 32 }, "example": "0123456749" } }, "schemas": { "Company": { "type": "object", "required": [ "enterprise_number", "general", "address", "contacts", "activities" ], "properties": { "enterprise_number": { "type": "string", "description": "The enterprise number, always as 0123.456.749." }, "general": { "type": "object", "required": [ "name", "entity_type", "legal_form", "legal_situation", "start_date" ], "properties": { "name": { "type": "string", "description": "The official name." }, "entity_type": { "type": "string", "description": "Rechtspersoon for a company, Natuurlijk Persoon for a sole trader." }, "legal_form": { "type": "string", "description": "The legal form, such as Besloten Vennootschap. Null for a sole trader.", "nullable": true }, "legal_situation": { "type": "string", "description": "The current legal state, such as Normale toestand, or a dissolution or bankruptcy." }, "start_date": { "type": "string", "format": "date", "description": "The day the company started. Null when it is not known.", "nullable": true } }, "additionalProperties": false, "description": "Who the company is." }, "address": { "type": "object", "required": [ "full", "street", "house_number", "box", "postal_code", "municipality", "country", "struck_off_date" ], "properties": { "full": { "type": "string", "description": "The whole address on one line, ready to show. The country is only added abroad. Null when the address is not known.", "nullable": true }, "street": { "type": "string", "description": "The street. Null when it is not known.", "nullable": true }, "house_number": { "type": "string", "description": "The house number. Null when there is none.", "nullable": true }, "box": { "type": "string", "description": "The box number. Null when there is none.", "nullable": true }, "postal_code": { "type": "string", "description": "The postal code. Null when it is not known.", "nullable": true }, "municipality": { "type": "string", "description": "The municipality. Null when it is not given.", "nullable": true }, "country": { "type": "string", "description": "België in Belgium, otherwise the country. Null when it is not known.", "nullable": true }, "struck_off_date": { "type": "string", "format": "date", "description": "The day the address was officially struck off. Null when not struck off.", "nullable": true } }, "additionalProperties": false, "description": "The registered address. Null for a sole trader.", "nullable": true }, "contacts": { "type": "object", "required": [ "emails", "phones", "websites" ], "properties": { "emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses. Empty list when none." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Phone numbers. Empty list when none." }, "websites": { "type": "array", "items": { "type": "string" }, "description": "Websites. Empty list when none." } }, "additionalProperties": false, "description": "How to reach the company." }, "activities": { "type": "object", "required": [ "main", "secondary" ], "properties": { "main": { "type": "array", "items": { "type": "object", "required": [ "code", "description" ], "properties": { "code": { "type": "string", "description": "The activity code." }, "description": { "type": "string", "description": "What the code means." } }, "additionalProperties": false }, "description": "The main activities. Empty list when none." }, "secondary": { "type": "array", "items": { "type": "object", "required": [ "code", "description" ], "properties": { "code": { "type": "string", "description": "The activity code." }, "description": { "type": "string", "description": "What the code means." } }, "additionalProperties": false }, "description": "The secondary activities, with the same fields as main. A code that is in main is not repeated here. Empty list when none." } }, "additionalProperties": false, "description": "What the company does, as activity codes (NACE-BEL 2025)." } }, "additionalProperties": false }, "Address": { "type": "object", "required": [ "enterprise_number", "address" ], "properties": { "enterprise_number": { "type": "string", "description": "The enterprise number, always as 0123.456.749." }, "address": { "type": "object", "required": [ "full", "street", "house_number", "box", "postal_code", "municipality", "country", "struck_off_date" ], "properties": { "full": { "type": "string", "description": "The whole address on one line, ready to show. The country is only added abroad. Null when the address is not known.", "nullable": true }, "street": { "type": "string", "description": "The street. Null when it is not known.", "nullable": true }, "house_number": { "type": "string", "description": "The house number. Null when there is none.", "nullable": true }, "box": { "type": "string", "description": "The box number. Null when there is none.", "nullable": true }, "postal_code": { "type": "string", "description": "The postal code. Null when it is not known.", "nullable": true }, "municipality": { "type": "string", "description": "The municipality. Null when it is not given.", "nullable": true }, "country": { "type": "string", "description": "België in Belgium, otherwise the country. Null when it is not known.", "nullable": true }, "struck_off_date": { "type": "string", "format": "date", "description": "The day the address was officially struck off. Null when not struck off.", "nullable": true } }, "additionalProperties": false, "description": "The registered address. Null for a sole trader.", "nullable": true } }, "additionalProperties": false }, "Contacts": { "type": "object", "required": [ "enterprise_number", "contacts" ], "properties": { "enterprise_number": { "type": "string", "description": "The enterprise number, always as 0123.456.749." }, "contacts": { "type": "object", "required": [ "emails", "phones", "websites" ], "properties": { "emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses. Empty list when none." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Phone numbers. Empty list when none." }, "websites": { "type": "array", "items": { "type": "string" }, "description": "Websites. Empty list when none." } }, "additionalProperties": false, "description": "How to reach the company." } }, "additionalProperties": false }, "Activities": { "type": "object", "required": [ "enterprise_number", "activities" ], "properties": { "enterprise_number": { "type": "string", "description": "The enterprise number, always as 0123.456.749." }, "activities": { "type": "object", "required": [ "main", "secondary" ], "properties": { "main": { "type": "array", "items": { "type": "object", "required": [ "code", "description" ], "properties": { "code": { "type": "string", "description": "The activity code." }, "description": { "type": "string", "description": "What the code means." } }, "additionalProperties": false }, "description": "The main activities. Empty list when none." }, "secondary": { "type": "array", "items": { "type": "object", "required": [ "code", "description" ], "properties": { "code": { "type": "string", "description": "The activity code." }, "description": { "type": "string", "description": "What the code means." } }, "additionalProperties": false }, "description": "The secondary activities, with the same fields as main. A code that is in main is not repeated here. Empty list when none." } }, "additionalProperties": false, "description": "What the company does, as activity codes (NACE-BEL 2025)." } }, "additionalProperties": false }, "Establishments": { "type": "object", "required": [ "enterprise_number", "establishments" ], "properties": { "enterprise_number": { "type": "string", "description": "The enterprise number of the company the establishments belong to." }, "establishments": { "type": "array", "items": { "type": "object", "required": [ "establishment_number", "name", "start_date", "address", "contacts", "activities" ], "properties": { "establishment_number": { "type": "string", "description": "The establishment's own number, always as 2.123.456.791." }, "name": { "type": "string", "description": "The establishment's name. Null when it has none (about 1 in 4).", "nullable": true }, "start_date": { "type": "string", "format": "date", "description": "The day the establishment started. Null when it is not known.", "nullable": true }, "address": { "type": "object", "required": [ "full", "street", "house_number", "box", "postal_code", "municipality", "country", "struck_off_date" ], "properties": { "full": { "type": "string", "description": "The whole address on one line, ready to show. The country is only added abroad. Null when the address is not known.", "nullable": true }, "street": { "type": "string", "description": "The street. Null when it is not known.", "nullable": true }, "house_number": { "type": "string", "description": "The house number. Null when there is none.", "nullable": true }, "box": { "type": "string", "description": "The box number. Null when there is none.", "nullable": true }, "postal_code": { "type": "string", "description": "The postal code. Null when it is not known.", "nullable": true }, "municipality": { "type": "string", "description": "The municipality. Null when it is not given.", "nullable": true }, "country": { "type": "string", "description": "België in Belgium, otherwise the country. Null when it is not known.", "nullable": true }, "struck_off_date": { "type": "string", "format": "date", "description": "The day the address was officially struck off. Null when not struck off.", "nullable": true } }, "additionalProperties": false, "description": "The establishment's address. Null when the establishment has no address.", "nullable": true }, "contacts": { "type": "object", "required": [ "emails", "phones", "websites" ], "properties": { "emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses. Empty list when none." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Phone numbers. Empty list when none." }, "websites": { "type": "array", "items": { "type": "string" }, "description": "Websites. Empty list when none." } }, "additionalProperties": false, "description": "How to reach the establishment." }, "activities": { "type": "object", "required": [ "main", "secondary" ], "properties": { "main": { "type": "array", "items": { "type": "object", "required": [ "code", "description" ], "properties": { "code": { "type": "string", "description": "The activity code. An establishment can have a more precise KBO code of 7 digits; search takes codes of up to 5." }, "description": { "type": "string", "description": "What the code means." } }, "additionalProperties": false }, "description": "The main activities. Empty list when none." }, "secondary": { "type": "array", "items": { "type": "object", "required": [ "code", "description" ], "properties": { "code": { "type": "string", "description": "The activity code. An establishment can have a more precise KBO code of 7 digits; search takes codes of up to 5." }, "description": { "type": "string", "description": "What the code means." } }, "additionalProperties": false }, "description": "The secondary activities, with the same fields as main. A code that is in main is not repeated here. Empty list when none." } }, "additionalProperties": false, "description": "What is done at the establishment, as codes from the Belgian activity list (NACE-BEL 2025)." } }, "additionalProperties": false }, "description": "The company's establishments: the places where it works, such as shops and offices. The newest first; one without a known start date last. Empty list when the company has none." } }, "additionalProperties": false }, "Branches": { "type": "object", "required": [ "enterprise_number", "branches" ], "properties": { "enterprise_number": { "type": "string", "description": "The enterprise number of the foreign company the branches belong to." }, "branches": { "type": "array", "items": { "type": "object", "required": [ "branch_number", "name", "start_date", "address" ], "properties": { "branch_number": { "type": "string", "description": "The branch's own number, always as 9.123.456.744." }, "name": { "type": "string", "description": "The branch's name. Null for most branches.", "nullable": true }, "start_date": { "type": "string", "format": "date", "description": "The day the branch started. Null when it is not known.", "nullable": true }, "address": { "type": "object", "required": [ "full", "street", "house_number", "box", "postal_code", "municipality", "country", "struck_off_date" ], "properties": { "full": { "type": "string", "description": "The whole address on one line, ready to show. The country is only added abroad. Null when the address is not known.", "nullable": true }, "street": { "type": "string", "description": "The street. Null when it is not known.", "nullable": true }, "house_number": { "type": "string", "description": "The house number. Null when there is none.", "nullable": true }, "box": { "type": "string", "description": "The box number. Null when there is none.", "nullable": true }, "postal_code": { "type": "string", "description": "The postal code. Null when it is not known.", "nullable": true }, "municipality": { "type": "string", "description": "The municipality. Null when it is not given.", "nullable": true }, "country": { "type": "string", "description": "België in Belgium, otherwise the country. Null when it is not known.", "nullable": true }, "struck_off_date": { "type": "string", "format": "date", "description": "The day the address was officially struck off. Null when not struck off.", "nullable": true } }, "additionalProperties": false, "description": "The branch's address." } }, "additionalProperties": false }, "description": "The foreign company's branches in Belgium. The newest first; one without a known start date last. Empty list when the company has none (only foreign companies have branches)." } }, "additionalProperties": false }, "Employees": { "type": "object", "required": [ "enterprise_number", "year_end", "fte", "headcount", "at_year_end" ], "properties": { "enterprise_number": { "type": "string", "description": "The enterprise number, always as 0123.456.749." }, "year_end": { "type": "string", "format": "date", "description": "The last day of the financial year these numbers come from: the newest annual account with figures (a year filed only as a PDF has none). Check it to know how recent the numbers are. Null when the company has no annual account with figures.", "nullable": true }, "fte": { "type": "number", "description": "The size of the company: the average number of employees over the financial year, in full-time equivalents (a part-timer counts for less than 1), such as 27.9. Checked against the company's other figures. Null when the annual account has no FTE, or when the company's own figures clearly contradict it.", "nullable": true }, "headcount": { "type": "object", "required": [ "full_time", "part_time" ], "properties": { "full_time": { "type": "number", "description": "Full-time employees, in persons. Null when it is not given.", "nullable": true }, "part_time": { "type": "number", "description": "Part-time employees, in persons. Null when it is not given.", "nullable": true } }, "additionalProperties": false, "description": "The number of people (not in full-time equivalents), on average over the financial year. Together they are usually a little more than fte: a part-timer is one person but less than one full-time job. Null when the annual account does not give it.", "nullable": true }, "at_year_end": { "type": "object", "required": [ "full_time", "part_time", "fte", "white_collar", "blue_collar" ], "properties": { "full_time": { "type": "number", "description": "All employees working full-time, in persons. Null when it is not given.", "nullable": true }, "part_time": { "type": "number", "description": "All employees working part-time, in persons. Null when it is not given.", "nullable": true }, "fte": { "type": "number", "description": "All employees, in full-time equivalents. White-collar and blue-collar are part of it; the rest is management and others, such as interns. Null when it is not given.", "nullable": true }, "white_collar": { "type": "object", "required": [ "full_time", "part_time", "fte" ], "properties": { "full_time": { "type": "number", "description": "Full-time, in persons. Null when it is not given.", "nullable": true }, "part_time": { "type": "number", "description": "Part-time, in persons. Null when it is not given.", "nullable": true }, "fte": { "type": "number", "description": "In full-time equivalents. Null when it is not given.", "nullable": true } }, "additionalProperties": false, "description": "Bedienden: white-collar employees. Null when the annual account does not give them.", "nullable": true }, "blue_collar": { "type": "object", "required": [ "full_time", "part_time", "fte" ], "properties": { "full_time": { "type": "number", "description": "Full-time, in persons. Null when it is not given.", "nullable": true }, "part_time": { "type": "number", "description": "Part-time, in persons. Null when it is not given.", "nullable": true }, "fte": { "type": "number", "description": "In full-time equivalents. Null when it is not given.", "nullable": true } }, "additionalProperties": false, "description": "Arbeiders: blue-collar employees. Null when the annual account does not give them.", "nullable": true } }, "additionalProperties": false, "description": "On the last day of the financial year (op de afsluitingsdatum van het boekjaar), the only moment the annual account splits white-collar and blue-collar employees. Null when the annual account does not give it.", "nullable": true } }, "additionalProperties": false }, "JointCommittees": { "type": "object", "required": [ "enterprise_number", "year_end", "joint_committees" ], "properties": { "enterprise_number": { "type": "string", "description": "The enterprise number, always as 0123.456.749." }, "year_end": { "type": "string", "format": "date", "description": "The last day of the financial year these numbers come from: the newest annual account with figures (a year filed only as a PDF has none). Check it to know how recent the numbers are. Null when the company has no annual account with figures.", "nullable": true }, "joint_committees": { "type": "array", "items": { "type": "object", "required": [ "code", "name" ], "properties": { "code": { "type": "string", "description": "The committee number, such as 200." }, "name": { "type": "string", "description": "The committee's official name." } }, "additionalProperties": false }, "description": "The joint committees the newest annual account lists, each once. Empty list when the newest annual account lists none." } }, "additionalProperties": false }, "Financials": { "type": "object", "required": [ "enterprise_number", "year_start", "year_end", "filed_on", "model", "currency", "turnover", "gross_margin", "operating_income", "operating_costs", "personnel_costs", "operating_result", "financial_income", "financial_costs", "result_before_tax", "taxes", "net_result", "fixed_assets", "current_assets", "cash", "total_assets", "equity", "debts", "debts_long_term", "debts_short_term" ], "properties": { "enterprise_number": { "type": "string", "description": "The enterprise number, always as 0123.456.749." }, "year_start": { "type": "string", "format": "date", "description": "The first day of the financial year. Null when the company has no annual account, or when it is not given.", "nullable": true }, "year_end": { "type": "string", "format": "date", "description": "The last day of the financial year these figures come from: the newest annual account with figures (a year filed only as a PDF has none). Check it to know how recent the figures are. Null when the company has no annual account with figures.", "nullable": true }, "filed_on": { "type": "string", "format": "date", "description": "The day the annual account was filed. Null when the company has no annual account, or when it is not given.", "nullable": true }, "model": { "type": "string", "description": "The official model of the annual account, such as Verkort model voor kapitaalvennootschap. Smaller companies file a shorter model with fewer figures. Null when the company has no annual account.", "nullable": true }, "currency": { "type": "string", "description": "The currency of every amount, such as EUR. Null when the company has no annual account, or when it is not given.", "nullable": true }, "turnover": { "type": "number", "description": "Omzet: what the company sold. Null when the annual account does not have it, or the company has none. Smaller companies may leave it out.", "nullable": true }, "gross_margin": { "type": "number", "description": "Brutomarge: sales and other operating income minus the cost of goods and services. Only in the shorter models. Null in the full model, which shows operating income and costs instead.", "nullable": true }, "operating_income": { "type": "number", "description": "Bedrijfsopbrengsten: all operating income. Only in the full model. Null in the shorter models, which show the gross margin instead.", "nullable": true }, "operating_costs": { "type": "number", "description": "Bedrijfskosten: all operating costs. Only in the full model. Null in the shorter models, which show the gross margin instead.", "nullable": true }, "personnel_costs": { "type": "number", "description": "Bezoldigingen, sociale lasten en pensioenen: wages and everything on top of them. Null when the annual account does not have it, or the company has none.", "nullable": true }, "operating_result": { "type": "number", "description": "Bedrijfswinst (Bedrijfsverlies): the result of the operations. Negative for a loss. Null when the annual account does not have it, or the company has none.", "nullable": true }, "financial_income": { "type": "number", "description": "Financiële opbrengsten. Null when the annual account does not have it, or the company has none.", "nullable": true }, "financial_costs": { "type": "number", "description": "Financiële kosten. Null when the annual account does not have it, or the company has none.", "nullable": true }, "result_before_tax": { "type": "number", "description": "Winst (Verlies) van het boekjaar vóór belasting. Negative for a loss. Null when the annual account does not have it, or the company has none.", "nullable": true }, "taxes": { "type": "number", "description": "Belastingen op het resultaat. Negative when the company got tax back. Null when the annual account does not have it, or the company has none.", "nullable": true }, "net_result": { "type": "number", "description": "Winst (Verlies) van het boekjaar: the profit or loss of the year. Negative for a loss. Null when the annual account does not have it, or the company has none.", "nullable": true }, "fixed_assets": { "type": "number", "description": "Vaste activa: what the company owns for the long term. Null when the annual account does not have it, or the company has none.", "nullable": true }, "current_assets": { "type": "number", "description": "Vlottende activa: stock, money owed to the company and cash. Null when the annual account does not have it, or the company has none.", "nullable": true }, "cash": { "type": "number", "description": "Liquide middelen: cash and bank balances. Null when the annual account does not have it, or the company has none.", "nullable": true }, "total_assets": { "type": "number", "description": "Totaal van de activa: the balance sheet total. Null when the annual account does not have it, or the company has none.", "nullable": true }, "equity": { "type": "number", "description": "Eigen vermogen. Negative when the losses are larger than what was put in. Null when the annual account does not have it, or the company has none.", "nullable": true }, "debts": { "type": "number", "description": "Schulden: all debts. Null when the annual account does not have it, or the company has none.", "nullable": true }, "debts_long_term": { "type": "number", "description": "Schulden op meer dan één jaar. Null when the annual account does not have it, or the company has none.", "nullable": true }, "debts_short_term": { "type": "number", "description": "Schulden op ten hoogste één jaar. Null when the annual account does not have it, or the company has none.", "nullable": true } }, "additionalProperties": false }, "Directors": { "type": "object", "required": [ "enterprise_number", "year_end", "directors" ], "properties": { "enterprise_number": { "type": "string", "description": "The enterprise number, always as 0123.456.749." }, "year_end": { "type": "string", "format": "date", "description": "The last day of the financial year these numbers come from: the newest annual account with figures (a year filed only as a PDF has none). Check it to know how recent the numbers are. Null when the company has no annual account with figures.", "nullable": true }, "directors": { "type": "array", "items": { "type": "object", "required": [ "entity_type", "name", "first_name", "last_name", "enterprise_number", "other_number", "address", "roles", "representatives" ], "properties": { "entity_type": { "type": "string", "description": "Natuurlijk Persoon for a person, Rechtspersoon for a company." }, "name": { "type": "string", "description": "The full name of the person, or the name of the company, as written in the annual account." }, "first_name": { "type": "string", "description": "The first name. Null for a company.", "nullable": true }, "last_name": { "type": "string", "description": "The last name. Null for a company.", "nullable": true }, "enterprise_number": { "type": "string", "description": "The Belgian enterprise number of a company director, as 0123.456.749. Ask for that company with it. Null for a person, or for a company without a valid Belgian number.", "nullable": true }, "other_number": { "type": "string", "description": "The number of a company director that is not a valid Belgian enterprise number, such as a foreign registration number, as written. Null when there is none.", "nullable": true }, "address": { "type": "object", "required": [ "full", "street", "house_number", "box", "postal_code", "municipality", "country" ], "properties": { "full": { "type": "string", "description": "The whole address on one line, ready to show. The country is only added abroad. Null when the annual account gives too little of the address to write it.", "nullable": true }, "street": { "type": "string", "description": "The street. Null when it is not given.", "nullable": true }, "house_number": { "type": "string", "description": "The house number. Null when there is none.", "nullable": true }, "box": { "type": "string", "description": "The box number. Null when there is none.", "nullable": true }, "postal_code": { "type": "string", "description": "The postal code. Null when it is not given.", "nullable": true }, "municipality": { "type": "string", "description": "The municipality. Null when it is not given.", "nullable": true }, "country": { "type": "string", "description": "The country, such as België. Null when it is not given.", "nullable": true } }, "additionalProperties": false, "description": "The address of the director, as written in the annual account. Null when the annual account gives none.", "nullable": true }, "roles": { "type": "array", "items": { "type": "object", "required": [ "role", "start_date", "end_date" ], "properties": { "role": { "type": "string", "description": "The role, such as Bestuurder, Gedelegeerd bestuurder or Zaakvoerder. Null when the annual account gives no role, or a role that is not one of the official roles.", "nullable": true }, "start_date": { "type": "string", "format": "date", "description": "The day the mandate started. Null when it is not given.", "nullable": true }, "end_date": { "type": "string", "format": "date", "description": "The day the mandate ends or ended. Often a planned date in the future. Null when it is not given.", "nullable": true } }, "additionalProperties": false }, "description": "The mandates of this director, in the order of the annual account. Empty list when the annual account gives no mandate." }, "representatives": { "type": "array", "items": { "type": "object", "required": [ "name", "first_name", "last_name", "address" ], "properties": { "name": { "type": "string", "description": "The full name." }, "first_name": { "type": "string", "description": "The first name." }, "last_name": { "type": "string", "description": "The last name." }, "address": { "type": "object", "required": [ "full", "street", "house_number", "box", "postal_code", "municipality", "country" ], "properties": { "full": { "type": "string", "description": "The whole address on one line, ready to show. The country is only added abroad. Null when the annual account gives too little of the address to write it.", "nullable": true }, "street": { "type": "string", "description": "The street. Null when it is not given.", "nullable": true }, "house_number": { "type": "string", "description": "The house number. Null when there is none.", "nullable": true }, "box": { "type": "string", "description": "The box number. Null when there is none.", "nullable": true }, "postal_code": { "type": "string", "description": "The postal code. Null when it is not given.", "nullable": true }, "municipality": { "type": "string", "description": "The municipality. Null when it is not given.", "nullable": true }, "country": { "type": "string", "description": "The country, such as België. Null when it is not given.", "nullable": true } }, "additionalProperties": false, "description": "The address of the representative, as written in the annual account. Null when the annual account gives none.", "nullable": true } }, "additionalProperties": false }, "description": "For a company director: the person who acts for it. Empty list for a person, or when none is given." } }, "additionalProperties": false }, "description": "Everyone the annual account lists as director: first the people, then the companies, each in alphabetical order. Empty list when it lists none, or when the company has no annual account." } }, "additionalProperties": false }, "Shareholders": { "type": "object", "required": [ "enterprise_number", "year_end", "shareholders" ], "properties": { "enterprise_number": { "type": "string", "description": "The enterprise number, always as 0123.456.749." }, "year_end": { "type": "string", "format": "date", "description": "The last day of the financial year these numbers come from: the newest annual account with figures (a year filed only as a PDF has none). Check it to know how recent the numbers are. Null when the company has no annual account with figures.", "nullable": true }, "shareholders": { "type": "array", "items": { "type": "object", "required": [ "entity_type", "name", "first_name", "last_name", "enterprise_number", "other_number", "address", "holdings" ], "properties": { "entity_type": { "type": "string", "description": "Natuurlijk Persoon for a person, Rechtspersoon for a company." }, "name": { "type": "string", "description": "The full name of the person, or the name of the company, as written in the annual account." }, "first_name": { "type": "string", "description": "The first name. Null for a company.", "nullable": true }, "last_name": { "type": "string", "description": "The last name. Null for a company.", "nullable": true }, "enterprise_number": { "type": "string", "description": "The Belgian enterprise number of a company shareholder, as 0123.456.749. Null for a person, or for a company without a valid Belgian number.", "nullable": true }, "other_number": { "type": "string", "description": "A number that is not a valid Belgian enterprise number, such as a foreign registration number, as written. Null when there is none.", "nullable": true }, "address": { "type": "object", "required": [ "full", "street", "house_number", "box", "postal_code", "municipality", "country" ], "properties": { "full": { "type": "string", "description": "The whole address on one line, ready to show. The country is only added abroad. Null when the annual account gives too little of the address to write it.", "nullable": true }, "street": { "type": "string", "description": "The street. Null when it is not given.", "nullable": true }, "house_number": { "type": "string", "description": "The house number. Null when there is none.", "nullable": true }, "box": { "type": "string", "description": "The box number. Null when there is none.", "nullable": true }, "postal_code": { "type": "string", "description": "The postal code. Null when it is not given.", "nullable": true }, "municipality": { "type": "string", "description": "The municipality. Null when it is not given.", "nullable": true }, "country": { "type": "string", "description": "The country, such as België. Null when it is not given.", "nullable": true } }, "additionalProperties": false, "description": "The address of the shareholder, as written in the annual account. Null when the annual account gives none.", "nullable": true }, "holdings": { "type": "array", "items": { "type": "object", "required": [ "nature", "percentage", "voting_rights_with_securities", "voting_rights_without_securities" ], "properties": { "nature": { "type": "string", "description": "The kind of share, as written, such as Aandelen or Aandelen op naam. Null when it is not given.", "nullable": true }, "percentage": { "type": "number", "description": "The share of the company held, as written in the annual account, such as 75 for 75%. Never worked out by Belscope. Null when the annual account does not give it.", "nullable": true }, "voting_rights_with_securities": { "type": "number", "description": "The number of voting rights attached to securities. Null when it is not given.", "nullable": true }, "voting_rights_without_securities": { "type": "number", "description": "The number of voting rights not attached to securities. Null when it is not given.", "nullable": true } }, "additionalProperties": false }, "description": "What this shareholder holds: one entry per line of the annual account, usually one per kind of share. Empty list when the annual account gives no details." } }, "additionalProperties": false }, "description": "The shareholders the annual account lists: first the companies, then the people, each in the order of the annual account. Empty list when it lists none. The shortest annual accounts (micro model) never list shareholders." } }, "additionalProperties": false }, "Participations": { "type": "object", "required": [ "enterprise_number", "year_end", "participations" ], "properties": { "enterprise_number": { "type": "string", "description": "The enterprise number, always as 0123.456.749." }, "year_end": { "type": "string", "format": "date", "description": "The last day of the financial year these numbers come from: the newest annual account with figures (a year filed only as a PDF has none). Check it to know how recent the numbers are. Null when the company has no annual account with figures.", "nullable": true }, "participations": { "type": "array", "items": { "type": "object", "required": [ "name", "enterprise_number", "other_number", "address", "holdings" ], "properties": { "name": { "type": "string", "description": "The name of the company held, as written in the annual account." }, "enterprise_number": { "type": "string", "description": "Its Belgian enterprise number, as 0123.456.749. Ask for that company with it. Null when it has no valid Belgian number, as for a foreign company.", "nullable": true }, "other_number": { "type": "string", "description": "A number that is not a valid Belgian enterprise number, such as a foreign registration number, as written. Null when there is none.", "nullable": true }, "address": { "type": "object", "required": [ "full", "street", "house_number", "box", "postal_code", "municipality", "country" ], "properties": { "full": { "type": "string", "description": "The whole address on one line, ready to show. The country is only added abroad. Null when the annual account gives too little of the address to write it.", "nullable": true }, "street": { "type": "string", "description": "The street. Null when it is not given.", "nullable": true }, "house_number": { "type": "string", "description": "The house number. Null when there is none.", "nullable": true }, "box": { "type": "string", "description": "The box number. Null when there is none.", "nullable": true }, "postal_code": { "type": "string", "description": "The postal code. Null when it is not given.", "nullable": true }, "municipality": { "type": "string", "description": "The municipality. Null when it is not given.", "nullable": true }, "country": { "type": "string", "description": "The country, such as België. Null when it is not given.", "nullable": true } }, "additionalProperties": false, "description": "The address of the company held, as written in the annual account. Null when the annual account gives none.", "nullable": true }, "holdings": { "type": "array", "items": { "type": "object", "required": [ "nature", "number", "percentage_direct", "percentage_through_subsidiaries" ], "properties": { "nature": { "type": "string", "description": "The kind of share, as written, such as Aandelen. Null when it is not given.", "nullable": true }, "number": { "type": "number", "description": "How many are held. Null when it is not given.", "nullable": true }, "percentage_direct": { "type": "number", "description": "The share held directly, as written in the annual account, such as 100 for 100%. Null when it is not given.", "nullable": true }, "percentage_through_subsidiaries": { "type": "number", "description": "The share held through subsidiaries, as written. Null when it is not given.", "nullable": true } }, "additionalProperties": false }, "description": "What is held: one entry per line of the annual account, usually one per kind of share. Empty list when the annual account gives no details." } }, "additionalProperties": false }, "description": "The companies this company holds shares in, as the annual account lists them. Empty list when it lists none." } }, "additionalProperties": false }, "Search": { "type": "object", "required": [ "total", "results", "next" ], "properties": { "total": { "type": "number", "description": "How many companies match your search in total, over all pages." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Company" }, "description": "The companies on this page, by enterprise number from low to high, each exactly as GET /companies/{number} gives it. Empty list when nothing matches." }, "next": { "type": "string", "description": "Send this as the parameter next to get the following page. Null on the last page.", "nullable": true } }, "additionalProperties": false }, "Batch": { "type": "object", "required": [ "companies", "not_found" ], "properties": { "companies": { "type": "array", "items": { "$ref": "#/components/schemas/Company" }, "description": "Every company found, exactly as GET /companies/{number} gives it, in the order you sent the numbers. Empty list when none was found." }, "not_found": { "type": "array", "items": { "type": "string" }, "description": "The numbers you sent for which no company was found, as 0123.456.749. Empty list when every company was found." } }, "additionalProperties": false }, "Error": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "invalid_enterprise_number", "key_in_url", "unknown_parameter", "invalid_parameter", "invalid_key", "company_not_found", "not_found", "method_not_allowed", "rate_limited", "quota_exceeded", "internal_error", "unavailable" ], "description": "What went wrong, as a fixed code. Codes never change once published." }, "message": { "type": "string", "description": "The same in one sentence." }, "parameter": { "type": "string", "description": "The parameter that is the problem, when there is one (invalid_parameter, unknown_parameter). Not there otherwise." } } } } } } } }