HMRC VAT (Making Tax Digital) API

naftiko: 1.0.0-alpha2
info:
  label: HMRC VAT (Making Tax Digital) API
  description: The HMRC VAT Making Tax Digital (MTD) API enables VAT-registered businesses and agents to submit VAT returns,
    view VAT obligations, liabilities, and payments, in compliance with UK Making Tax Digital requirements. Requires OAuth
    2.0 authentication and mandatory fraud prevention headers on all requests.
  tags:
  - Hmrc
  - API
  created: '2026-05-06'
  modified: '2026-05-06'
capability:
  consumes:
  - type: http
    namespace: hmrc
    baseUri: https://api.service.hmrc.gov.uk
    description: HMRC VAT (Making Tax Digital) API HTTP API.
    authentication:
      type: bearer
      token: '{{HMRC_TOKEN}}'
    resources:
    - name: organisations-vat-vrn-obligations
      path: /organisations/vat/{vrn}/obligations
      operations:
      - name: getvatobligations
        method: GET
        description: Retrieve VAT obligations
        inputParameters:
        - name: vrn
          in: path
          type: string
          required: true
          description: VAT Registration Number (9 digits)
        - name: from
          in: query
          type: string
          required: true
          description: Obligation period start date (YYYY-MM-DD), minimum 2017-01-01
        - name: to
          in: query
          type: string
          required: true
          description: Obligation period end date (must be within 366 days of 'from')
        - name: status
          in: query
          type: string
        - name: Authorization
          in: header
          type: string
          required: true
          description: Bearer token (OAuth 2.0)
        - name: Gov-Client-Connection-Method
          in: header
          type: string
          required: true
          description: Fraud prevention header – client connection method
        - name: Gov-Vendor-Version
          in: header
          type: string
          required: true
          description: Fraud prevention header – vendor application version
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: organisations-vat-vrn-returns
      path: /organisations/vat/{vrn}/returns
      operations:
      - name: submitvatreturn
        method: POST
        description: Submit a VAT return
        inputParameters:
        - name: vrn
          in: path
          type: string
          required: true
        - name: Authorization
          in: header
          type: string
          required: true
        - name: Gov-Client-Connection-Method
          in: header
          type: string
          required: true
        - name: Gov-Vendor-Version
          in: header
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: organisations-vat-vrn-returns-periodkey
      path: /organisations/vat/{vrn}/returns/{periodKey}
      operations:
      - name: getvatreturn
        method: GET
        description: View a submitted VAT return
        inputParameters:
        - name: vrn
          in: path
          type: string
          required: true
        - name: periodKey
          in: path
          type: string
          required: true
          description: Period key from the obligation (e.g., "23AA")
        - name: Authorization
          in: header
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: organisations-vat-vrn-payments
      path: /organisations/vat/{vrn}/payments
      operations:
      - name: getvatpayments
        method: GET
        description: Retrieve VAT payments
        inputParameters:
        - name: vrn
          in: path
          type: string
          required: true
        - name: from
          in: query
          type: string
          required: true
        - name: to
          in: query
          type: string
          required: true
        - name: Authorization
          in: header
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: organisations-vat-vrn-liabilities
      path: /organisations/vat/{vrn}/liabilities
      operations:
      - name: getvatliabilities
        method: GET
        description: Retrieve VAT liabilities
        inputParameters:
        - name: vrn
          in: path
          type: string
          required: true
        - name: from
          in: query
          type: string
          required: true
        - name: to
          in: query
          type: string
          required: true
        - name: Authorization
          in: header
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: hmrc-rest
    description: REST adapter for HMRC VAT (Making Tax Digital) API.
    resources:
    - path: /organisations/vat/{vrn}/obligations
      name: getvatobligations
      operations:
      - method: GET
        name: getvatobligations
        description: Retrieve VAT obligations
        call: hmrc.getvatobligations
        with:
          vrn: rest.vrn
        outputParameters:
        - type: object
          mapping: $.
    - path: /organisations/vat/{vrn}/returns
      name: submitvatreturn
      operations:
      - method: POST
        name: submitvatreturn
        description: Submit a VAT return
        call: hmrc.submitvatreturn
        with:
          vrn: rest.vrn
        outputParameters:
        - type: object
          mapping: $.
    - path: /organisations/vat/{vrn}/returns/{periodKey}
      name: getvatreturn
      operations:
      - method: GET
        name: getvatreturn
        description: View a submitted VAT return
        call: hmrc.getvatreturn
        with:
          vrn: rest.vrn
          periodKey: rest.periodKey
        outputParameters:
        - type: object
          mapping: $.
    - path: /organisations/vat/{vrn}/payments
      name: getvatpayments
      operations:
      - method: GET
        name: getvatpayments
        description: Retrieve VAT payments
        call: hmrc.getvatpayments
        with:
          vrn: rest.vrn
        outputParameters:
        - type: object
          mapping: $.
    - path: /organisations/vat/{vrn}/liabilities
      name: getvatliabilities
      operations:
      - method: GET
        name: getvatliabilities
        description: Retrieve VAT liabilities
        call: hmrc.getvatliabilities
        with:
          vrn: rest.vrn
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: hmrc-mcp
    transport: http
    description: MCP adapter for HMRC VAT (Making Tax Digital) API for AI agent use.
    tools:
    - name: getvatobligations
      description: Retrieve VAT obligations
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: hmrc.getvatobligations
      with:
        vrn: tools.vrn
        from: tools.from
        to: tools.to
        status: tools.status
      inputParameters:
      - name: vrn
        type: string
        description: VAT Registration Number (9 digits)
        required: true
      - name: from
        type: string
        description: Obligation period start date (YYYY-MM-DD), minimum 2017-01-01
        required: true
      - name: to
        type: string
        description: Obligation period end date (must be within 366 days of 'from')
        required: true
      - name: status
        type: string
        description: status
      outputParameters:
      - type: object
        mapping: $.
    - name: submitvatreturn
      description: Submit a VAT return
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: hmrc.submitvatreturn
      with:
        vrn: tools.vrn
      inputParameters:
      - name: vrn
        type: string
        description: vrn
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: getvatreturn
      description: View a submitted VAT return
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: hmrc.getvatreturn
      with:
        vrn: tools.vrn
        periodKey: tools.periodKey
      inputParameters:
      - name: vrn
        type: string
        description: vrn
        required: true
      - name: periodKey
        type: string
        description: Period key from the obligation (e.g., "23AA")
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: getvatpayments
      description: Retrieve VAT payments
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: hmrc.getvatpayments
      with:
        vrn: tools.vrn
        from: tools.from
        to: tools.to
      inputParameters:
      - name: vrn
        type: string
        description: vrn
        required: true
      - name: from
        type: string
        description: from
        required: true
      - name: to
        type: string
        description: to
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: getvatliabilities
      description: Retrieve VAT liabilities
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: hmrc.getvatliabilities
      with:
        vrn: tools.vrn
        from: tools.from
        to: tools.to
      inputParameters:
      - name: vrn
        type: string
        description: vrn
        required: true
      - name: from
        type: string
        description: from
        required: true
      - name: to
        type: string
        description: to
        required: true
      outputParameters:
      - type: object
        mapping: $.
binds:
- namespace: env
  keys:
    HMRC_TOKEN: HMRC_TOKEN