> ## Documentation Index > Fetch the complete documentation index at: https://docs.avatcado.com/llms.txt > Use this file to discover all available pages before exploring further. # Validate an EORI number > Check an EORI number (the customs identifier a business needs to import, export or move goods in transit) against the register that issued it. GB numbers are checked with HMRC; numbers from the 27 EU member states and XI (Northern Ireland) are checked with the European Commission's EORI validation service. Input is normalized automatically: spaces, dots, dashes and casing are handled for you (`"gb 123.456.789 000"` -> `"GB123456789000"`). A number neither register would accept is rejected with a 422 before any register is called, and does not count against your quota. company is null for many valid numbers: both registers publish a trader's name and address only when the trader agreed to it. Answers are cached. Every response carries meta.source (ec_eos or hmrc), meta.source_status (live, cached or unavailable), meta.cached and meta.stale. When the register is down, the most recent stored answer is served with source_status "unavailable"; with no stored answer the request ends in a 503 that is not counted. Pass cache=false to force a fresh check: the request then answers with a fresh check or a 503. An EORI number and a VAT number are separate registrations. A valid VAT number does not imply a valid EORI number. Use GET /v1/validate for VAT numbers. ## OpenAPI ````yaml /openapi/public.yaml get /v1/eori/validate openapi: 3.1.0 info: title: Avatcado API version: '1.0' description: >- Validate VAT and GST numbers across 32 countries with a single API call. Get company details, consultation numbers, and validity status from VIES, HMRC, BFS, BRREG, and ABR, with caching, rate limiting, and structured error responses built in. Also checks EORI numbers for the EU, Northern Ireland and Great Britain. contact: name: Avatcado url: https://docs.avatcado.com servers: - url: https://api.avatcado.com description: Production security: [] paths: /v1/eori/validate: get: tags: - EORI Validation summary: Validate an EORI number description: >- Check an EORI number (the customs identifier a business needs to import, export or move goods in transit) against the register that issued it. GB numbers are checked with HMRC; numbers from the 27 EU member states and XI (Northern Ireland) are checked with the European Commission's EORI validation service. Input is normalized automatically: spaces, dots, dashes and casing are handled for you (`"gb 123.456.789 000"` -> `"GB123456789000"`). A number neither register would accept is rejected with a 422 before any register is called, and does not count against your quota. company is null for many valid numbers: both registers publish a trader's name and address only when the trader agreed to it. Answers are cached. Every response carries meta.source (ec_eos or hmrc), meta.source_status (live, cached or unavailable), meta.cached and meta.stale. When the register is down, the most recent stored answer is served with source_status "unavailable"; with no stored answer the request ends in a 503 that is not counted. Pass cache=false to force a fresh check: the request then answers with a fresh check or a 503. An EORI number and a VAT number are separate registrations. A valid VAT number does not imply a valid EORI number. Use GET /v1/validate for VAT numbers. operationId: validateEoriNumber parameters: - schema: type: string minLength: 1 description: >- The EORI number to check: a two-letter country code followed by 1 to 15 letters or digits (GB numbers: 12 to 15 digits). Supports the 27 EU member states, XI and GB. Will be normalized to uppercase with spaces, dots and dashes removed, and the Greek VAT prefix EL is rewritten to the EORI prefix GR. example: GB123456789000 required: true description: >- The EORI number to check: a two-letter country code followed by 1 to 15 letters or digits (GB numbers: 12 to 15 digits). Supports the 27 EU member states, XI and GB. Will be normalized to uppercase with spaces, dots and dashes removed, and the Greek VAT prefix EL is rewritten to the EORI prefix GR. name: eori_number in: query - schema: type: string enum: - 'true' - 'false' description: >- Set to false to skip the cache and check the register again. The fresh answer is still stored for later requests. With the cache off, no stored answer is served when the register is down: the request answers with a fresh check or a 503. Defaults to true. example: 'true' required: false description: >- Set to false to skip the cache and check the register again. The fresh answer is still stored for later requests. With the cache off, no stored answer is served when the register is down: the request answers with a fresh check or a 503. Defaults to true. name: cache in: query responses: '200': description: EORI number checked content: application/json: schema: $ref: '#/components/schemas/EoriValidationSuccessResponse' '400': description: Missing required query parameter `eori_number` content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: missing_parameter message: 'Missing required query parameter: eori_number' docs_url: https://docs.avatcado.com/errors/missing_parameter meta: request_id: 550e8400-e29b-41d4-a716-446655440000 '401': description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthorized message: Missing or invalid API key docs_url: https://docs.avatcado.com/errors/unauthorized meta: request_id: 550e8400-e29b-41d4-a716-446655440000 '422': description: Invalid EORI number format or unsupported country content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: invalid_eori_format message: >- Invalid EORI number format: GB123. GB EORI numbers are GB followed by 12 to 15 digits docs_url: https://docs.avatcado.com/errors/invalid_eori_format eori_number: GB123 meta: request_id: 550e8400-e29b-41d4-a716-446655440000 '429': description: Monthly quota or burst rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: rate_limit_exceeded message: Monthly limit of 500 requests exceeded docs_url: https://docs.avatcado.com/errors/rate_limit_exceeded eori_number: GB123456789000 meta: request_id: 550e8400-e29b-41d4-a716-446655440000 '503': description: >- The register (HMRC or the EU EORI validation service) is unavailable and no stored answer exists content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: upstream_unavailable message: The HMRC EORI service is unavailable docs_url: https://docs.avatcado.com/errors/upstream_unavailable eori_number: GB123456789000 meta: request_id: 550e8400-e29b-41d4-a716-446655440000 security: - bearerAuth: [] components: schemas: EoriValidationSuccessResponse: type: object properties: data: $ref: '#/components/schemas/EoriValidationData' meta: $ref: '#/components/schemas/EoriValidationMeta' required: - data - meta ErrorResponse: type: object properties: error: $ref: '#/components/schemas/ErrorDetail' meta: $ref: '#/components/schemas/ErrorResponseMeta' required: - error - meta EoriValidationData: type: object properties: valid: type: boolean description: Whether the register lists the EORI number as valid example: true eori_number: type: string description: The normalized EORI number that was checked example: GB123456789000 country_code: type: string description: Two-letter prefix of the EORI number (XI for Northern Ireland) example: GB company: allOf: - $ref: '#/components/schemas/CompanyInfo' - description: >- Trader name and address from the register. Null when the number is not valid, and null for a valid number whose trader did not agree to publication, which is common. requested_at: type: string description: >- When the register was asked (for a cached answer: when it was first stored) example: '2026-11-13T09:19:29.000Z' required: - valid - eori_number - country_code - company - requested_at EoriValidationMeta: type: object properties: request_id: type: string example: 550e8400-e29b-41d4-a716-446655440000 description: Unique identifier for this request request_duration_ms: type: integer description: Total request processing time in milliseconds example: 120 mode: type: string enum: - test description: Present with value 'test' when using an avat_test_ API key source: type: string enum: - ec_eos - hmrc - test description: >- Register that produced the answer: ec_eos (the European Commission's EORI validation service, for EU and XI numbers), hmrc (for GB numbers), or test in test mode example: hmrc source_status: type: string enum: - live - cached - unavailable description: >- How the answer was obtained. 'live' = fresh check. 'cached' = served from the cache. 'unavailable' = the register was down and the most recent stored answer was served (check stale). example: live cached: type: boolean description: Whether this result was served from cache. Always present stale: type: boolean description: >- Whether the served stored answer is older than the cache window (only true when the register is down). Always present cached_at: type: string description: >- When the served row was originally fetched. Present only when cached is true required: - request_id - source - source_status - cached - stale ErrorDetail: type: object properties: code: type: string description: Machine-readable error code example: missing_parameter message: type: string description: Human-readable error message example: Query parameter 'vat_number' is required docs_url: type: string description: Link to documentation for this error code example: https://docs.avatcado.com/errors/missing_parameter vat_number: type: string description: >- The normalized VAT number from the request, echoed back when one was submitted example: SE556677889901 requester_vat_number: type: string description: >- The normalized requester VAT number from the request, echoed back when supplied example: NL861234567B01 eori_number: type: string description: >- The normalized EORI number from the request, echoed back on errors from the EORI endpoint example: GB123456789000 details: type: array items: type: object properties: field: type: string message: type: string required: - field - message description: Field-level issues for validation_error responses required: - code - message ErrorResponseMeta: type: object properties: request_id: type: string example: 550e8400-e29b-41d4-a716-446655440000 description: Unique identifier for this request validation_id: type: string description: >- Identifier of the recorded failed validation attempt. Present on upstream_unavailable and upstream_member_state_unavailable errors. example: 7c9e6679-7425-40de-944b-e07fc1f90ae7 required: - request_id CompanyInfo: type: object nullable: true properties: name: type: string example: Acme B.V. description: Registered company name address: type: string nullable: true example: Keizersgracht 123, Amsterdam description: Registered company address required: - name - address description: >- Company details returned by the upstream authority. Null if invalid, or if the registry publishes no company data (VIES returns none for DE and ES). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.