{"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.12.0"},"servers":[{"url":"/","description":"This server"}],"tags":[{"name":"EU VAT numbers","description":"Checks an EU VAT identification number live in VIES, the VAT Information Exchange System of the European Commission, which queries the member state's register: valid or not, the name and address the state publishes, and the VIES consultation number when you give your own VAT number. Source: VIES, European Commission. As VIES states, the answer is not legal advice, does not by itself entitle an intra-Community supply to a VAT exemption, and VIES may only be used to confirm the VAT numbers of your own customers and suppliers. Nothing is stored."}],"paths":{"/api/v1/vat-numbers/{countryCode}/{vatNumber}":{"get":{"tags":["EU VAT numbers"],"summary":"Check an EU VAT number","description":"Asks VIES, live, whether the member state's register holds the number as a valid VAT number. countryCode is the VIES code: the member state's VAT prefix (EL for Greece) or XI for Northern Ireland. vatNumber may be typed as people write it: case, spaces, dots and hyphens are ignored and a leading country prefix is dropped (VIES itself answers \"not valid\" to a prefixed number). valid false is a normal answer. Give your own VAT number as requester (both parameters) to get the VIES consultation number, the proof of the check to keep in your records. Every call is a new check: nothing is cached.","operationId":"check","parameters":[{"name":"countryCode","in":"path","description":"VIES country code: AT, BE, BG, CY, CZ, DE, DK, EE, EL (Greece), ES, FI, FR, HR, HU, IE, IT, LT, LU, LV, MT, NL, PL, PT, RO, SE, SI, SK or XI (Northern Ireland)","required":true,"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"name":"vatNumber","in":"path","description":"The VAT number, with or without its country prefix, spaces, dots or hyphens","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9 .\\-]{2,24}$"}},{"name":"requesterCountryCode","in":"query","description":"Your own VIES country code, with requesterVatNumber, to get a consultation number","required":false,"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"name":"requesterVatNumber","in":"query","description":"Your own VAT number, with requesterCountryCode, to get a consultation number","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9 .\\-]{2,24}$"}}],"responses":{"200":{"description":"The answer of VIES, valid or not","content":{"*/*":{"schema":{"$ref":"#/components/schemas/VatCheckResponse"}}}},"400":{"description":"countryCode not two letters or vatNumber with other characters than letters, digits, spaces, dots and hyphens (code INVALID_REQUEST); a country VIES does not check - Greece is EL, not GR (code VAT_COUNTRY_NOT_SUPPORTED); a number that is not 2 to 12 letters or digits once cleaned (code INVALID_VAT_NUMBER); only one of the requester parameters, or VIES refusing the request (code INVALID_ARGUMENT); a requester that is not a VAT number VIES accepts (code INVALID_REQUESTER)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The member state does not allow this number to be checked (code VAT_NUMBER_BLOCKED)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The member state's register did not answer VIES, retry later (code MEMBER_STATE_UNAVAILABLE); VIES did not answer, or answered an error or an unexpected document (code UPSTREAM_UNAVAILABLE)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"VIES reports too many concurrent requests, or too many requests towards it are in flight, retry later (code UPSTREAM_BUSY)","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/vat-numbers/member-states":{"get":{"tags":["EU VAT numbers"],"summary":"Availability of the member states' registers","description":"Relays VIES's own status: whether VIES answers and, for each member state and XI, whether VIES can reach its register now. A check on an unavailable state answers MEMBER_STATE_UNAVAILABLE.","operationId":"fetchMemberStates","responses":{"200":{"description":"The availability reported by VIES","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ViesStatusResponse"}}}},"502":{"description":"VIES did not answer, or answered an error or an unexpected document (code UPSTREAM_UNAVAILABLE)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"VIES reports too many concurrent requests, or too many requests towards it are in flight, retry later (code UPSTREAM_BUSY)","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"}}},"VatCheckResponse":{"type":"object","description":"The answer of VIES to one check of an EU VAT number, as published","properties":{"countryCode":{"type":"string","description":"VIES country code checked (EL for Greece, XI for Northern Ireland)","example":"BE"},"vatNumber":{"type":"string","description":"The number as sent to VIES: upper case, without separators or country prefix"},"valid":{"type":"boolean","description":"Whether the member state's register holds the number as a valid VAT number at requestDate; false is a normal answer, not an error"},"requestDate":{"type":"string","format":"date-time","description":"When VIES answered (UTC)"},"name":{"type":["string","null"],"description":"Name published by the member state, null when the state withholds it"},"address":{"type":["string","null"],"description":"Address published by the member state, lines separated by a line feed, null when the state withholds it"},"consultationNumber":{"type":["string","null"],"description":"VIES consultation number, the proof of this check to keep in your records; null unless requesterCountryCode and requesterVatNumber were given"}}},"MemberStateStatusResponse":{"type":"object","description":"Whether VIES can reach a member state's register now","properties":{"countryCode":{"type":"string","description":"VIES country code","example":"BE"},"availability":{"type":"string","description":"AVAILABLE, UNAVAILABLE (checks answer MEMBER_STATE_UNAVAILABLE), MONITORING_DISABLED (VIES does not watch that register)","enum":["AVAILABLE","UNAVAILABLE","MONITORING_DISABLED"]}}},"ViesStatusResponse":{"type":"object","description":"The availability of VIES and of each member state's register, as VIES reports it","properties":{"available":{"type":"boolean","description":"Whether VIES itself answers"},"memberStates":{"type":"array","description":"The 27 member states and XI (Northern Ireland), in VIES's order","items":{"$ref":"#/components/schemas/MemberStateStatusResponse"}}}}},"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"}}}}