openapi: 3.0.0
info:
  title: Vatstack API Specification Batches 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: Batches
paths:
  /batches:
    post:
      operationId: createBatch
      summary: Creates a batch object.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Descriptive name of the batch object. Give it any name you like to serve for your reference.
                queries:
                  type: array
                  description: Array of VAT numbers to be queried. Should be an array of strings.
                  items:
                    type: string
              required:
              - name
        required: true
      responses:
        '201':
          description: Batch object successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batch'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - secretKey: []
      tags:
      - Batches
    get:
      operationId: getAllBatches
      summary: Retrieves all batch objects in order of creation, with the latest appearing highest.
      parameters:
      - 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: status
        in: query
        description: Show only objects with the given `status`.
        schema:
          type: string
      responses:
        '200':
          description: Batch 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
                  batches_count:
                    type: integer
                    format: int32
                  batches:
                    items:
                      $ref: '#/components/schemas/batch'
                    type: array
                required:
                - has_more
                - batches_count
                - batches
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - secretKey: []
      tags:
      - Batches
  /batches/{id}:
    get:
      operationId: getBatchById
      summary: Retrieves a batch object by the {id} path parameter.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Batch object successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batch'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - secretKey: []
      tags:
      - Batches
    put:
      operationId: updateBatchById
      summary: Updates a batch object by the {id} path parameter.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                mode:
                  type: string
                  description: Either `append` to append an array of queries to the existing array of queries, or `replace` to empty the existing array of queries prior to adding. Defaults to `append`.
                  enum:
                  - append
                  - replace
                name:
                  type: string
                  description: Descriptive name of the batch object. Give it any name you like to serve for your reference.
                queries:
                  type: array
                  description: Array of VAT numbers to be added while considering the `mode`.
                  items:
                    type: string
                status:
                  type: string
                  description: Set it to `scheduled` once you want to schedule the validation process with the queries provided. It’s possible to add queries and change the status in one go.
                  enum:
                  - scheduled
        required: true
      responses:
        '200':
          description: Batch object successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batch'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - secretKey: []
      tags:
      - Batches
    delete:
      operationId: deleteBatchById
      summary: Deletes a batch object by the {id} path parameter.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Batch object successfully deleted.
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - secretKey: []
      tags:
      - Batches
components:
  schemas:
    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
    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
    batch:
      type: object
      description: Batch mass VAT number validations for due dates. Add VAT numbers in bulk or append VAT numbers incrementally to your existing batch process, then start it whenever required.
      properties:
        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
        name:
          type: string
          description: Descriptive name of the object.
        queries:
          type: array
          description: Array of all queries in the order of your input.
          items:
            type: string
        queries_ignored:
          type: array
          description: Array of all queries which are of invalid format. Ignored queries are automatically identified upon your input. Its items will not be validated.
          items:
            type: string
        scheduled:
          type: string
          description: ISO date at which the object status was changed to `scheduled`. Defaults to `null` while the status is `pending`.
          format: date-time
        succeeded_count:
          type: integer
          description: The number of `validations` where `valid` is `true` or `false`. It’s an indicator for how far the batch has progressed.
          format: int32
        updated:
          type: string
          description: ISO date at which the object was updated.
          format: date-time
        validations:
          type: array
          description: Array of the first 20 validation objects in the order of `queries`. If an `id` is shown in the object, it was created for the batch and you can retrieve it individually. See [validation object](https://vatstack.com/docs/validations) for reference.
          items:
            $ref: '#/components/schemas/validation'
      required:
      - name
  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