{"openapi":"3.1.0","info":{"title":"AXITAM Public API","description":"Reference data (ISO, CLDR), Belgian enterprises, annual accounts and addresses, Peppol participants - built on community-maintained and official sources. See the data-sources API for each source's version and license. Beta.","version":"0.10.0"},"servers":[{"url":"/","description":"This server"}],"tags":[{"name":"KBO code lists","description":"Code lists of the KBO/BCE Open Data with their French and Dutch (sometimes German) descriptions: ActivityGroup, Classification, ContactType, EntityContact, JuridicalForm, JuridicalSituation, Language, Nace2003, Nace2008, Nace2025, Status, TypeOfAddress, TypeOfDenomination, TypeOfEnterprise."},{"name":"Enterprises","description":"Belgian enterprises registered in the Crossroads Bank for Enterprises (source: KBO/BCE Open Data, updated daily), to fill in and check forms: names, juridical form, addresses, contacts, NACE-BEL activities, establishment units and branches."},{"name":"Establishment units","description":"Places where Belgian enterprises operate (source: KBO/BCE Open Data). The units of one enterprise are listed under /api/v1/bel/enterprises/{number}/establishments."}],"paths":{"/api/v1/bel/kbo-codes/{category}":{"get":{"tags":["KBO code lists"],"summary":"List the codes of one category","description":"Ordered by code.","operationId":"findCategory","parameters":[{"name":"category","in":"path","description":"Code category, case-sensitive","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9]{1,50}$"},"example":"JuridicalForm"}],"responses":{"200":{"description":"The category's codes","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/KboCodeResponse"}}}}},"400":{"description":"Malformed category (code INVALID_REQUEST)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such category (code KBO_CODE_CATEGORY_NOT_FOUND); names are case-sensitive","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The X-API-Key header carries an unknown, revoked or malformed key (code INVALID_API_KEY). Leave the header out to call anonymously.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests from this client: the code is RATE_LIMITED, Retry-After says in how many seconds a request will pass again.","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Sustained requests per second allowed on this path","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current burst","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"apiKey":[]}]}},"/api/v1/bel/establishments/{number}":{"get":{"tags":["Establishment units"],"summary":"Read one establishment unit","description":"Owning enterprise, names, address, contacts and activities.","operationId":"findByNumber","parameters":[{"name":"number","in":"path","description":"Establishment unit number, with or without dots (2.000.000.339, 2000000339)","required":true,"schema":{"type":"string"},"example":"2.000.000.339"}],"responses":{"200":{"description":"Establishment unit found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/EstablishmentResponse"}}}},"400":{"description":"Not a well-formed establishment unit number (code INVALID_ESTABLISHMENT_NUMBER)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No establishment unit has this number (code ESTABLISHMENT_NOT_FOUND)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The X-API-Key header carries an unknown, revoked or malformed key (code INVALID_API_KEY). Leave the header out to call anonymously.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests from this client: the code is RATE_LIMITED, Retry-After says in how many seconds a request will pass again.","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Sustained requests per second allowed on this path","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current burst","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"apiKey":[]}]}},"/api/v1/bel/enterprises":{"get":{"tags":["Enterprises"],"summary":"Search enterprises by name","description":"Enterprises having a name (legal name, abbreviation or commercial name, any language) containing the text, accents and case ignored, most similar first - for autocompletion.","operationId":"searchByName","parameters":[{"name":"name","in":"query","description":"Text contained in the name, at least 3 characters","required":true,"schema":{"type":"string","maxLength":100,"minLength":0,"pattern":"^\\s*\\S.*\\S.*\\S.*$"},"example":"axitam"},{"name":"limit","in":"query","description":"Maximum number of enterprises returned","required":false,"schema":{"type":"integer","format":"int32","default":10,"maximum":20,"minimum":1},"example":10}],"responses":{"200":{"description":"Matching enterprises, possibly none","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EnterpriseSearchResultResponse"}}}}},"400":{"description":"Name shorter than 3 characters or limit out of 1-20 (code INVALID_REQUEST)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The X-API-Key header carries an unknown, revoked or malformed key (code INVALID_API_KEY). Leave the header out to call anonymously.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests from this client: the code is RATE_LIMITED, Retry-After says in how many seconds a request will pass again.","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Sustained requests per second allowed on this path","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current burst","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"apiKey":[]}]}},"/api/v1/bel/enterprises/{number}":{"get":{"tags":["Enterprises"],"summary":"Read one enterprise","description":"Status, juridical form, names, registered office, contacts and activities, plus the fields added by the modules deployed alongside (peppol: the Peppol registration looked up live, whose status says whether the lookup succeeded).","operationId":"findByNumber_1","parameters":[{"name":"number","in":"path","description":"Enterprise number, with or without dots, spaces or BE prefix (0420.254.973, 0420254973, 420254973, BE0420254973)","required":true,"schema":{"type":"string"},"example":"0420.254.973"}],"responses":{"200":{"description":"Enterprise found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/EnterpriseResponse"}}}},"400":{"description":"Not a well-formed enterprise number (code INVALID_ENTERPRISE_NUMBER)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No enterprise has this number (code ENTERPRISE_NOT_FOUND)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The X-API-Key header carries an unknown, revoked or malformed key (code INVALID_API_KEY). Leave the header out to call anonymously.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests from this client: the code is RATE_LIMITED, Retry-After says in how many seconds a request will pass again.","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Sustained requests per second allowed on this path","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current burst","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"apiKey":[]}]}},"/api/v1/bel/enterprises/{number}/validation":{"get":{"tags":["Enterprises"],"summary":"Validate an enterprise or VAT number","description":"Never an error for a bad value: tells whether it is well-formed (check digits), registered and active, and gives its normalized and VAT forms.","operationId":"validate","parameters":[{"name":"number","in":"path","description":"Any value typed as an enterprise or VAT number","required":true,"schema":{"type":"string","maxLength":30,"minLength":0},"example":"BE0420254973"}],"responses":{"200":{"description":"Result of the check","content":{"*/*":{"schema":{"$ref":"#/components/schemas/EnterpriseValidationResponse"}}}},"400":{"description":"Value longer than 30 characters (code INVALID_REQUEST)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The X-API-Key header carries an unknown, revoked or malformed key (code INVALID_API_KEY). Leave the header out to call anonymously.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests from this client: the code is RATE_LIMITED, Retry-After says in how many seconds a request will pass again.","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Sustained requests per second allowed on this path","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current burst","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"apiKey":[]}]}},"/api/v1/bel/enterprises/{number}/establishments":{"get":{"tags":["Enterprises"],"summary":"List the establishment units of an enterprise","description":"Ordered by number, each with its names, address, contacts and activities.","operationId":"findEstablishments","parameters":[{"name":"number","in":"path","description":"Enterprise number, with or without dots, spaces or BE prefix (0420.254.973, 0420254973, 420254973, BE0420254973)","required":true,"schema":{"type":"string"},"example":"0403.449.823"}],"responses":{"200":{"description":"The enterprise's establishment units, possibly none","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EstablishmentResponse"}}}}},"400":{"description":"Not a well-formed enterprise number (code INVALID_ENTERPRISE_NUMBER)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No enterprise has this number (code ENTERPRISE_NOT_FOUND)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The X-API-Key header carries an unknown, revoked or malformed key (code INVALID_API_KEY). Leave the header out to call anonymously.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests from this client: the code is RATE_LIMITED, Retry-After says in how many seconds a request will pass again.","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Sustained requests per second allowed on this path","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current burst","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"apiKey":[]}]}},"/api/v1/bel/enterprises/{number}/branches":{"get":{"tags":["Enterprises"],"summary":"List the Belgian branches of a foreign enterprise","description":"Ordered by number, each with its names, address, contacts and activities.","operationId":"findBranches","parameters":[{"name":"number","in":"path","description":"Enterprise number, with or without dots, spaces or BE prefix (0420.254.973, 0420254973, 420254973, BE0420254973)","required":true,"schema":{"type":"string"},"example":"0257.883.408"}],"responses":{"200":{"description":"The enterprise's branches, possibly none","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BranchResponse"}}}}},"400":{"description":"Not a well-formed enterprise number (code INVALID_ENTERPRISE_NUMBER)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No enterprise has this number (code ENTERPRISE_NOT_FOUND)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The X-API-Key header carries an unknown, revoked or malformed key (code INVALID_API_KEY). Leave the header out to call anonymously.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests from this client: the code is RATE_LIMITED, Retry-After says in how many seconds a request will pass again.","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Sustained requests per second allowed on this path","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current burst","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"apiKey":[]}]}}},"components":{"schemas":{"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"correlationId":{"type":"string"}}},"KboCodeResponse":{"type":"object","description":"A value of a KBO code list, with its descriptions","properties":{"code":{"type":"string","description":"The code","example":"014"},"descriptions":{"type":"object","additionalProperties":{"type":"string"},"description":"Description by language (FR, NL, sometimes DE); empty for a code the KBO uses without listing it (contact type FAX)","example":{"FR":"Société anonyme","NL":"Naamloze vennootschap"}}}},"ActivityResponse":{"type":"object","description":"An economic activity (NACE-BEL), as registered for one purpose","properties":{"group":{"$ref":"#/components/schemas/KboCodeResponse","description":"What the activity is registered for (ActivityGroup): 001 VAT, 006 social security..."},"naceVersion":{"type":"string","description":"NACE-BEL version of the code","enum":["2003","2008","2025"],"example":"2025"},"nace":{"$ref":"#/components/schemas/KboCodeResponse","description":"The NACE-BEL code"},"classification":{"$ref":"#/components/schemas/KboCodeResponse","description":"MAIN, SECO (secondary) or ANCI (ancillary) (Classification)"}}},"AddressResponse":{"type":"object","description":"An address, in French and Dutch where they differ","properties":{"type":{"$ref":"#/components/schemas/KboCodeResponse","description":"Kind of address (TypeOfAddress): REGO registered office, BAET establishment unit, ABBR branch"},"countryFr":{"type":["string","null"],"description":"Country in French; absent for Belgium"},"countryNl":{"type":["string","null"],"description":"Country in Dutch; absent for Belgium"},"zipcode":{"type":["string","null"],"description":"Postal code","example":"1000"},"municipalityFr":{"type":["string","null"],"description":"Municipality in French","example":"Bruxelles"},"municipalityNl":{"type":["string","null"],"description":"Municipality in Dutch","example":"Brussel"},"streetFr":{"type":["string","null"],"description":"Street in French"},"streetNl":{"type":["string","null"],"description":"Street in Dutch"},"houseNumber":{"type":["string","null"],"description":"House number"},"box":{"type":["string","null"],"description":"Box number"},"extraInfo":{"type":["string","null"],"description":"Additional information"},"strikingOffDate":{"type":["string","null"],"format":"date","description":"Date the address was struck off"}}},"ContactResponse":{"type":"object","description":"A way to reach the entity, as published by the KBO","properties":{"type":{"$ref":"#/components/schemas/KboCodeResponse","description":"Kind of contact (ContactType): EMAIL, TEL, WEB, FAX"},"value":{"type":"string","description":"The address or number, as published"}}},"DenominationResponse":{"type":"object","description":"A name, in one language","properties":{"type":{"$ref":"#/components/schemas/KboCodeResponse","description":"Kind of name (TypeOfDenomination): 001 name, 002 abbreviation, 003 commercial name"},"language":{"$ref":"#/components/schemas/KboCodeResponse","description":"Language (KBO Language code: 1 French, 2 Dutch, 3 German, 4 English)"},"value":{"type":"string","description":"The name","example":"AXITAM"}}},"EstablishmentResponse":{"type":"object","description":"An establishment unit: a place where an enterprise operates","properties":{"establishmentNumber":{"type":"string","description":"Establishment unit number, published form","example":"2.000.000.339"},"enterpriseNumber":{"type":"string","description":"Owning enterprise number","example":"0403.449.823"},"startDate":{"type":"string","format":"date","description":"Start date"},"denominations":{"type":"array","description":"Names of the unit","items":{"$ref":"#/components/schemas/DenominationResponse"}},"addresses":{"type":"array","description":"Address of the unit","items":{"$ref":"#/components/schemas/AddressResponse"}},"contacts":{"type":"array","description":"Contacts of the unit","items":{"$ref":"#/components/schemas/ContactResponse"}},"activities":{"type":"array","description":"Activities of the unit","items":{"$ref":"#/components/schemas/ActivityResponse"}}}},"EnterpriseSearchResultResponse":{"type":"object","description":"An enterprise whose name contains the searched text","properties":{"enterpriseNumber":{"type":"string","description":"Enterprise number, published form","example":"0420.254.973"},"name":{"type":"string","description":"The enterprise's name most similar to the searched text","example":"AXITAM"},"typeOfEnterprise":{"$ref":"#/components/schemas/KboCodeResponse","description":"Type of enterprise: 1 natural person, 2 legal person"},"juridicalForm":{"type":"null","$ref":"#/components/schemas/KboCodeResponse","description":"Juridical form; absent for natural persons"},"zipcode":{"type":["string","null"],"description":"Postal code of the registered office"},"municipalityFr":{"type":["string","null"],"description":"Municipality of the registered office in French"},"municipalityNl":{"type":["string","null"],"description":"Municipality of the registered office in Dutch"}}},"EnterpriseResponse":{"type":"object","description":"A registered Belgian enterprise (source: KBO/BCE Open Data)","properties":{"enterpriseNumber":{"type":"string","description":"Enterprise number, published form","example":"0420.254.973"},"vatNumber":{"type":"string","description":"VAT number built on the enterprise number","example":"BE0420254973"},"status":{"$ref":"#/components/schemas/KboCodeResponse","description":"Status (AC active - the KBO extracts only publish active enterprises)"},"juridicalSituation":{"$ref":"#/components/schemas/KboCodeResponse","description":"Juridical situation (JuridicalSituation): 000 normal situation..."},"typeOfEnterprise":{"$ref":"#/components/schemas/KboCodeResponse","description":"Type of enterprise (TypeOfEnterprise): 1 natural person, 2 legal person"},"juridicalForm":{"type":"null","$ref":"#/components/schemas/KboCodeResponse","description":"Juridical form (JuridicalForm); absent for natural persons"},"juridicalFormCac":{"type":"null","$ref":"#/components/schemas/KboCodeResponse","description":"Juridical form under the Code of companies and associations, when it differs"},"startDate":{"type":"string","format":"date","description":"Start date"},"denominations":{"type":"array","description":"Names of the enterprise","items":{"$ref":"#/components/schemas/DenominationResponse"}},"addresses":{"type":"array","description":"Addresses of the enterprise (registered office)","items":{"$ref":"#/components/schemas/AddressResponse"}},"contacts":{"type":"array","description":"Contacts of the enterprise","items":{"$ref":"#/components/schemas/ContactResponse"}},"activities":{"type":"array","description":"Activities of the enterprise, newest NACE version and main activities first","items":{"$ref":"#/components/schemas/ActivityResponse"}},"extensions":{"type":["object","null"],"additionalProperties":{},"description":"Fields added by the modules deployed alongside, serialized at the record's top level: peppol (Peppol registration, when the Belgian composition module is present)"}}},"EnterpriseValidationResponse":{"type":"object","description":"The check of a value typed as a Belgian enterprise or VAT number","properties":{"input":{"type":"string","description":"The value as received","example":"BE 0420.254.973"},"normalized":{"type":["string","null"],"description":"Published form; absent when not well-formed","example":"0420.254.973"},"vatNumber":{"type":["string","null"],"description":"VAT number built on it; absent when not well-formed","example":"BE0420254973"},"isWellFormed":{"type":"boolean","description":"10 digits starting with 0 or 1 and right check digits (modulo 97)"},"isRegistered":{"type":"boolean","description":"An enterprise with this number is in the loaded KBO extract"},"isActive":{"type":"boolean","description":"That enterprise is active"}}},"BranchResponse":{"type":"object","description":"A Belgian branch of a foreign company","properties":{"branchNumber":{"type":"string","description":"Branch number, published form","example":"9.000.006.626"},"enterpriseNumber":{"type":"string","description":"Owning enterprise number","example":"0257.883.408"},"startDate":{"type":"string","format":"date","description":"Start date"},"denominations":{"type":"array","description":"Names of the branch","items":{"$ref":"#/components/schemas/DenominationResponse"}},"addresses":{"type":"array","description":"Address of the branch","items":{"$ref":"#/components/schemas/AddressResponse"}},"contacts":{"type":"array","description":"Contacts of the branch","items":{"$ref":"#/components/schemas/ContactResponse"}},"activities":{"type":"array","description":"Activities of the branch","items":{"$ref":"#/components/schemas/ActivityResponse"}}}}},"securitySchemes":{"apiKey":{"type":"apiKey","description":"Optional. A key of a registered developer (portal: /account/) raises the request rate of the client from the anonymous per-IP limit to the plan's. Without it the request is anonymous; an unknown or revoked key is refused (401 INVALID_API_KEY).","name":"X-API-Key","in":"header"}}}}