openapi: 3.0.0
info:
  title: Vatstack API Specification Batches Validations API
  description: A suite of VAT APIs which let you validate VAT numbers with government services, look up VAT rates by ISO country code, calculate price quotes with centralized VAT rules and store transactions with each sale for VAT reporting.
  contact:
    email: team@vatstack.com
  version: 1.3.0
servers:
- url: https://api.vatstack.com/{basePath}
  description: Production API server.
  variables:
    basePath:
      default: v1
tags:
- name: Validations
paths:
  /validations:
    post:
      operationId: createValidation
      summary: Creates a validation object.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: Restrict validation to a region. If not provided, the type is automatically determined based on the VAT number given.
                  enum:
                  - au_gst
                  - ch_vat
                  - eu_oss_vat
                  - eu_vat
                  - gb_vat
                  - no_vat
                  - sg_gst
                query:
                  type: string
                  description: VAT number that you want to validate.
              required:
              - query
        required: true
      responses:
        '201':
          description: Validation object successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validation'
        '202':
          description: Validation request was accepted and will resume asynchronously.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validation'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - publicKey: []
        secretKey: []
      tags:
      - Validations
    get:
      operationId: getAllValidations
      summary: Retrieves all validation objects in order of creation, with the most recent appearing highest.
      parameters:
      - name: batch
        in: query
        description: Show only objects that belong to a batch with the given identifier.
        schema:
          type: string
          format: uuid
      - name: limit
        in: query
        description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
        schema:
          type: integer
          format: int32
      - name: page
        in: query
        description: Integer for the current page.
        schema:
          type: integer
          format: int32
      - name: query
        in: query
        description: The VAT number you want to search in the `query` field of your records.
        schema:
          type: string
      - name: requested_since
        in: query
        description: Show only objects where the `requested` date is this date or later. Format `YYYY-MM-DD`.
        schema:
          type: string
          format: date
      - name: requested_until
        in: query
        description: Show only objects where the `requested` date is this date or earlier. Format `YYYY-MM-DD`.
        schema:
          type: string
          format: date
      - name: type
        in: query
        description: Show only objects of specified type field.
        schema:
          type: string
          enum:
          - au_gst
          - ch_vat
          - eu_oss_vat
          - eu_vat
          - gb_vat
          - no_vat
          - sg_gst
      responses:
        '200':
          description: Validation objects successfully retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  has_more:
                    description: True if this list has another page of items after this one that can be fetched.
                    type: boolean
                  validations_count:
                    type: integer
                    format: int32
                  validations:
                    items:
                      $ref: '#/components/schemas/validation'
                    type: array
                required:
                - has_more
                - validations_count
                - validations
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - secretKey: []
      tags:
      - Validations
  /validations/{id}:
    get:
      operationId: getValidationById
      summary: Retrieves a validation object.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Validation object successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validation'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - publicKey: []
        secretKey: []
      tags:
      - Validations
components:
  schemas:
    error:
      type: object
      description: Error response from the Vatstack API.
      properties:
        code:
          type: string
          description: For validations, a short string indicating the [error code](https://vatstack.com/docs/validations).
          maxLength: 50
        message:
          type: string
          description: Human-readable message providing more details about the error.
          maxLength: 250
    validation:
      type: object
      description: Validate your business customer’s VAT number against official government servers in real-time. The API asynchronously validates VAT numbers for you if government services experience downtime.
      properties:
        active:
          type: boolean
          description: Boolean indicating whether the company exists and is active. Use `valid` to check whether the business is also VAT-registered.
          default: null
        code:
          type: string
          description: In the event of an error, this field will contain the error code.
        company_address:
          type: string
          description: Address of the company the VAT number is associated with. Servers of Germany and Spain won’t return a value for privacy reasons and will default to `null`.
          default: null
        company_name:
          type: string
          description: Name of the company the VAT number is associated with. Servers of Germany and Spain won’t return a value for privacy reasons and will default to `null`.
          default: null
        company_type:
          type: string
          description: Type of the company entity returned by the respective government service (where available).
          default: null
        consultation_number:
          type: string
          description: If you save your own VAT number in your dashboard, the reply will contain a unique consultation number. The consultation number enables you to prove to a tax administration of a Member State that you have checked a VAT number at the `requested` date, and obtained a validation result.
          default: null
        country_code:
          type: string
          description: 2-letter ISO country code. Note that while Greek VAT numbers contain the `EL` country code, our response will return the ISO country code `GR`.
          maxLength: 2
          minLength: 2
        created:
          type: string
          description: ISO date at which the object was created.
          format: date-time
        id:
          type: string
          description: Unique identifier for the object.
          format: uuid
        query:
          type: string
          description: Your original query.
        requested:
          type: string
          description: ISO date at which the validation request was originally performed. Types `eu_vat` and `gb_vat` do not specify a time.
          format: date-time
        type:
          type: string
          description: Type of VAT number.
          enum:
          - au_gst
          - ch_vat
          - eu_oss_vat
          - eu_vat
          - gb_vat
          - no_vat
          - sg_gst
        updated:
          type: string
          description: ISO date at which the object was updated.
          format: date-time
        valid:
          type: boolean
          description: Boolean indicating whether the vat_number is registered for VAT. If government services are down, the value will be `null` and re-checked automatically for you.
          default: null
        valid_format:
          type: boolean
          description: Boolean indicating whether the VAT number contained in `query` is in a valid format.
        vat_number:
          type: string
          description: VAT number extracted from your query without the country code.
      required:
      - query
  securitySchemes:
    publicKey:
      type: apiKey
      name: X-API-KEY
      in: header
    secretKey:
      type: apiKey
      name: X-API-KEY
      in: header
externalDocs:
  description: Vatstack API Reference
  url: https://vatstack.com/docs