openapi: 3.0.3
info:
  title: Check a UK VAT number
  description: |
    # Overview
    
    <div class="govuk-warning-text">
      <span class="govuk-warning-text__icon" aria-hidden="true">!</span>
      <strong class="govuk-warning-text__text">
        <span class="govuk-visually-hidden">Warning</span>
        Version 2 is the recommended version of this API. Version 1 was removed on 17 February 2025.
      </strong>
    </div>
    
    The Check a UK VAT Number API is for the sole purpose of allowing traders to do due diligence on VAT-registered businesses. The Check a UK VAT Number API lets your application:

    * check if a UK VAT number is registered
    * view the name and address of the related business
    * get a reference number to prove you checked the UK VAT number

    This API works in two modes:

    1. Simple unverified check, which does not provide a reference number.
    2. Verified check, which provides a reference number.
    
    # About version 2
    Version 2 moved the Check a UK VAT Number API behind authentication. We moved the API behind authentication so we can fully understand our users.
    
    Version 1 was removed on 17 February 2025. You need to register to have access to Version 2.
    
    # Register for version 2
    [Register for the new API using HMRC’s Software Developer Hub](https://developer.service.hmrc.gov.uk/api-documentation/docs/using-the-hub).
    
    Registering should take around 2 weeks. It may take longer if we need more information.
    
    You will get production credentials once you have tested in the Sandbox environment and accepted the Terms of Use 2.0.

    # Errors
    We use standard HTTP status codes:
    * 200 to 299 if the request succeeded. This includes code 202 if the API needs to wait for further action
    * 400 to 499 if the request failed because of a client error by your application
    * 500 to 599 if the request failed because of an error on our server

    Errors specific to each API are shown in the Endpoints section, under Response. For more on errors see our [HMRC Developer Hub Reference guide](https://developer.service.hmrc.gov.uk/api-documentation/docs/reference-guide#errors).

    # Testing
    You can [test this API in the sandbox environment](https://developer.service.hmrc.gov.uk/api-documentation/docs/testing). Use these [mock VAT registration numbers](https://github.com/hmrc/vat-registered-companies-api/tree/master/public/api/conf/2.0/test-data).
    
    # Versioning
    We release backwards-incompatible changes in a new version. There is more about versioning in the [HMRC Developer Hub Reference guide](https://developer.service.hmrc.gov.uk/api-documentation/docs/reference-guide#versioning).

  contact: {}
  version: '2.0'
servers:
  - url: https://api.service.hmrc.gov.uk/
    variables: {}
paths:
  /organisations/vat/check-vat-number/lookup/{targetVrn}:
    get:
      tags:
        - organisations
      summary: Get a VAT registration
      description: Allows retrieval of name and address of a VAT registered company
      operationId: GetaVATregistration
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/authorizationReadScopeHeader'
        - name: targetVrn
          in: path
          description: UK VAT registration number you wish to check. <br> A 9-digit or 12-digit number.
          required: true
          style: simple
          schema:
            type: string
            example: '123456789'
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/OrganisationsVatCheckVatNumberLookupresponse'
                  - example:
                      target:
                        name: Credite Sberger Donal Inc.
                        vatNumber: '553557881'
                        address:
                          line1: 131B Barton Hamlet
                          postcode: SW97 5CK
                          countryCode: GB
                      processingDate: 2019-01-31T12:43:17+00:00
              example:
                target:
                  name: Credite Sberger Donal Inc.
                  vatNumber: '553557881'
                  address:
                    line1: 131B Barton Hamlet
                    postcode: SW97 5CK
                    countryCode: GB
                processingDate: 2019-01-31T12:43:17+00:00
        '400':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error1'
                  - description: Invalid request
                    example:
                      code: INVALID_REQUEST
                      message: Invalid targetVrn - Vrn parameters should be 9 or 12 digits
              example:
                code: INVALID_REQUEST
                message: Invalid targetVrn - Vrn parameters should be 9 or 12 digits
        '404':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error1'
                  - description: Not found
                    example:
                      code: NOT_FOUND
                      message: targetVrn does not match a registered company
              example:
                code: NOT_FOUND
                message: targetVrn does not match a registered company
        '500':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error1'
                  - description: Internal server error
                    example:
                      code: INTERNAL_SERVER_ERROR
                      message: Unknown error
              example:
                code: INTERNAL_SERVER_ERROR
                message: Unknown error
      deprecated: false
      security:
        - applicationRestricted: []
  /organisations/vat/check-vat-number/lookup/{targetVrn}/{requesterVrn}:
    get:
      tags:
        - organisations
      summary: Get a VAT registration with a reference number
      description: Retrieves the name and address of a UK VAT-registered business, if the business exists.
      operationId: GetaVATregistrationwithareferencenumber
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/authorizationReadScopeHeader'
        - name: targetVrn
          in: path
          description: UK VAT registration number you want to check. <br> A 9-digit or 12-digit number.
          required: true
          style: simple
          schema:
            type: string
            example: '123456789'
        - name: requesterVrn
          in: path
          description: Your VAT registration number. <br> A 9-digit or 12-digit number.
          required: true
          style: simple
          schema:
            type: string
            example: '123456789'
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/OrganisationsVatCheckVatNumberLookupresponse1'
                  - example:
                      target:
                        name: Credite Sberger Donal Inc.
                        vatNumber: '553557881'
                        address:
                          line1: 131B Barton Hamlet
                          postcode: SW97 5CK
                          countryCode: GB
                      requester: '146295999727'
                      consultationNumber: ypAeKRPlW
                      processingDate: 2019-01-31T12:53:05+00:00
              example:
                target:
                  name: Credite Sberger Donal Inc.
                  vatNumber: '553557881'
                  address:
                    line1: 131B Barton Hamlet
                    postcode: SW97 5CK
                    countryCode: GB
                requester: '146295999727'
                consultationNumber: ypAeKRPlW
                processingDate: 2019-01-31T12:53:05+00:00
        '400':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error1'
                  - description: Invalid request
                    example:
                      code: INVALID_REQUEST
                      message: Invalid requesterVrn - Vrn parameters should be 9 or 12 digits
              example:
                code: INVALID_REQUEST
                message: Invalid requesterVrn - Vrn parameters should be 9 or 12 digits
        '403':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error1'
                  - description: Invalid request
                    example:
                      code: INVALID_REQUEST
                      message: requesterVrn does not match a registered company
              example:
                code: INVALID_REQUEST
                message: requesterVrn does not match a registered company
        '404':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error1'
                  - description: Not found
                    example:
                      code: NOT_FOUND
                      message: targetVrn does not match a registered company
              example:
                code: NOT_FOUND
                message: targetVrn does not match a registered company
        '500':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error1'
                  - description: Internal server error
                    example:
                      code: INTERNAL_SERVER_ERROR
                      message: Unknown error
              example:
                code: INTERNAL_SERVER_ERROR
                message: Unknown error
      deprecated: false
      security:
        - applicationRestricted: []
components:
  securitySchemes:
    applicationRestricted:
      type: oauth2
      description: HMRC supports OAuth 2.0 for authenticating app-restricted API requests
      flows:
        clientCredentials:
          tokenUrl: https://api.service.hmrc.gov.uk/oauth/token
          scopes:
            read:vat: Grant read access
  parameters:
    acceptHeader:
      name: Accept
      in: header
      schema:
        type: string
        enum: [
          "application/vnd.hmrc.2.0+json",
        ]
      required: true
    authorizationReadScopeHeader:
      name: "Authorization"
      in: header
      description: |
        An OAuth 2.0 Bearer Token with the *read:vat* scope.
      schema:
        type: string
        example: Bearer bb7fed3fe10dd235a2ccda3d50fb
      required: true
  schemas:
    errorResponse:
      title: errorResponse
      required:
        - code
      type: object
      properties:
        code:
          type: string
    Address:
      title: Address
      required:
        - line1
        - postcode
        - countryCode
      type: object
      properties:
        line1:
          type: string
        postcode:
          type: string
        countryCode:
          type: string
      example:
        line1: 131B Barton Hamlet
        postcode: SW97 5CK
        countryCode: GB
    Error1:
      title: Error1
      required:
        - message
        - code
      type: object
      properties:
        message:
          type: string
        code:
          type: string
    OrganisationsVatCheckVatNumberLookupresponse:
      title: OrganisationsVatCheckVatNumberLookupresponse
      required:
        - target
        - processingDate
      type: object
      properties:
        target:
          $ref: '#/components/schemas/Target'
        processingDate:
          type: string
      example:
        target:
          name: Credite Sberger Donal Inc.
          vatNumber: '553557881'
          address:
            line1: 131B Barton Hamlet
            postcode: SW97 5CK
            countryCode: GB
        processingDate: 2019-01-31T12:43:17+00:00
    OrganisationsVatCheckVatNumberLookupresponse1:
      title: OrganisationsVatCheckVatNumberLookupresponse1
      required:
        - target
        - requester
        - consultationNumber
        - processingDate
      type: object
      properties:
        target:
          $ref: '#/components/schemas/Target'
        requester:
          type: string
        consultationNumber:
          type: string
        processingDate:
          type: string
      example:
        target:
          name: Credite Sberger Donal Inc.
          vatNumber: '553557881'
          address:
            line1: 131B Barton Hamlet
            postcode: SW97 5CK
            countryCode: GB
        requester: '146295999727'
        consultationNumber: ypAeKRPlW
        processingDate: 2019-01-31T12:53:05+00:00
    Target:
      title: Target
      required:
        - name
        - vatNumber
        - address
      type: object
      properties:
        name:
          type: string
        vatNumber:
          type: string
        address:
          $ref: '#/components/schemas/Address'
      example:
        name: Credite Sberger Donal Inc.
        vatNumber: '553557881'
        address:
          line1: 131B Barton Hamlet
          postcode: SW97 5CK
          countryCode: GB
tags:
  - name: organisations
    description: ''