api-ninjas-com VAT Validation API

openapi: 3.2.0
info:
  title: Ninjas VAT Validation API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: VAT Validation
  description: The VAT Validation API validates EU VAT numbers with instant format and checksum checks and live EU registry status. It always returns an answer — cached last-known-good results are served when a national registry is down, and unresolved numbers are re-checked automatically in the background. Premium plans include company name, company address, and audit-ready consultation numbers.
paths:
  /v1/vatvalidation:
    get:
      summary: Validate an EU VAT number
      description: Validates an EU VAT number by format, checksum, and live EU registry status. Requires a `vat` with country prefix. Company name and address require a premium plan.
      operationId: validateVATNumber
      tags:
      - VAT Validation
      parameters:
      - name: vat
        in: query
        required: true
        schema:
          type: string
        description: The VAT number to validate, with 2-letter country prefix (e.g. FR40303265045). Spaces, dots, and hyphens are tolerated. May omit the prefix when the country parameter is set.
      - name: country
        in: query
        schema:
          type: string
        description: Two-letter country code (e.g. DE). Optional when the vat parameter includes a country prefix. GR is accepted and canonicalized to EL.
      - name: requester_vat
        in: query
        schema:
          type: string
        description: Your own company's EU VAT number (with country prefix). Forces a live registry check and returns an official consultation_number as audit evidence. Premium only.
      responses:
        '200':
          $ref: '#/components/responses/VATValidationResponse'
        '400':
          $ref: '#/components/responses/VatValidationOpenapi_BadRequest'
        '401':
          $ref: '#/components/responses/VatValidationOpenapi_Unauthorized'
        '500':
          $ref: '#/components/responses/VatValidationOpenapi_InternalServerError'
      security:
      - ApiKeyAuth: []
components:
  schemas:
    VATValidationResult:
      type: object
      properties:
        vat:
          type: string
          description: The normalized VAT number including country prefix, e.g. FR40303265045.
        country:
          type: string
          description: Two-letter registry country code. Greece is EL; Northern Ireland is XI.
        number:
          type: string
          description: The national part of the VAT number (no country prefix).
        format_valid:
          type: boolean
          description: Whether the number matches the country's VAT number format.
        checksum_valid:
          type: boolean
          description: Whether the number passes the country's checksum algorithm.
        status:
          type: string
          description: Validation verdict. 'valid' = registered for VAT; 'invalid' = failed format/checksum or confirmed not registered; 'unknown' = well-formed but the registry is temporarily unreachable and no cached answer exists (the number is re-checked automatically in the background).
          enum:
          - valid
          - invalid
          - unknown
        source:
          type:
          - string
          - 'null'
          description: 'Where the answer came from: ''vies'' (the official EU registry) or ''seed'' (national open-registry snapshot).'
        cached:
          type: boolean
          description: True when the answer was served from the validation cache rather than a live registry check.
        checked_at:
          type:
          - string
          - 'null'
          description: UTC timestamp of the registry answer (ISO 8601). For cached results, the time the number was last confirmed.
        company_name:
          type:
          - string
          - 'null'
          description: Registered company name. Premium only.
        company_address:
          type:
          - string
          - 'null'
          description: Registered company address. Premium only.
        consultation_number:
          type:
          - string
          - 'null'
          description: Official EU consultation number. Premium only.
        message:
          type: string
          description: Human-readable note about the validation result.
      required:
      - vat
      - country
      - number
      - format_valid
      - checksum_valid
      - status
      - cached
  responses:
    VATValidationResponse:
      description: The validation result.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VATValidationResult'
    VatValidationOpenapi_BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    VatValidationOpenapi_Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    VatValidationOpenapi_InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api