{
  "opencollection": "1.0.0",
  "info": {
    "name": "HMRC VAT (Making Tax Digital) API",
    "version": "1.0.0"
  },
  "request": {
    "auth": {
      "type": "oauth2",
      "flow": "authorization_code",
      "authorizationUrl": "https://api.service.hmrc.gov.uk/oauth/authorize",
      "accessTokenUrl": "https://api.service.hmrc.gov.uk/oauth/token",
      "credentials": {
        "clientId": "{{clientId}}",
        "clientSecret": "{{clientSecret}}"
      }
    }
  },
  "items": [
    {
      "info": {
        "name": "Obligations",
        "type": "folder"
      },
      "items": [
        {
          "info": {
            "name": "Retrieve VAT obligations",
            "type": "http"
          },
          "http": {
            "method": "GET",
            "url": "https://api.service.hmrc.gov.uk/organisations/vat/:vrn/obligations",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              },
              {
                "name": "Gov-Client-Connection-Method",
                "value": ""
              },
              {
                "name": "Gov-Vendor-Version",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "vrn",
                "value": "",
                "type": "path",
                "description": "VAT Registration Number (9 digits)"
              },
              {
                "name": "from",
                "value": "",
                "type": "query",
                "description": "Obligation period start date (YYYY-MM-DD), minimum 2017-01-01"
              },
              {
                "name": "to",
                "value": "",
                "type": "query",
                "description": "Obligation period end date (must be within 366 days of 'from')"
              },
              {
                "name": "status",
                "value": "",
                "type": "query"
              }
            ]
          },
          "docs": "Retrieves VAT return filing obligations for the specified VAT Registration Number (VRN). Returns periods for which returns must be filed, due dates, and status (Open, Fulfilled) within the requested date range."
        }
      ]
    },
    {
      "info": {
        "name": "Returns",
        "type": "folder"
      },
      "items": [
        {
          "info": {
            "name": "Submit a VAT return",
            "type": "http"
          },
          "http": {
            "method": "POST",
            "url": "https://api.service.hmrc.gov.uk/organisations/vat/:vrn/returns",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              },
              {
                "name": "Gov-Client-Connection-Method",
                "value": ""
              },
              {
                "name": "Gov-Vendor-Version",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "vrn",
                "value": "",
                "type": "path"
              }
            ],
            "body": {
              "type": "json",
              "data": "{}"
            }
          },
          "docs": "Submits a VAT return for the specified VRN and period key. The return must be for an open obligation. Duplicate submissions are rejected. Finalisation is indicated by the 'finalised' field being true."
        },
        {
          "info": {
            "name": "View a submitted VAT return",
            "type": "http"
          },
          "http": {
            "method": "GET",
            "url": "https://api.service.hmrc.gov.uk/organisations/vat/:vrn/returns/:periodKey",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "vrn",
                "value": "",
                "type": "path"
              },
              {
                "name": "periodKey",
                "value": "",
                "type": "path",
                "description": "Period key from the obligation (e.g., \"23AA\")"
              }
            ]
          },
          "docs": "Retrieves a previously submitted VAT return for the specified period key."
        }
      ]
    },
    {
      "info": {
        "name": "Payments",
        "type": "folder"
      },
      "items": [
        {
          "info": {
            "name": "Retrieve VAT payments",
            "type": "http"
          },
          "http": {
            "method": "GET",
            "url": "https://api.service.hmrc.gov.uk/organisations/vat/:vrn/payments",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "vrn",
                "value": "",
                "type": "path"
              },
              {
                "name": "from",
                "value": "",
                "type": "query"
              },
              {
                "name": "to",
                "value": "",
                "type": "query"
              }
            ]
          },
          "docs": "Retrieves a list of VAT payments made by the business to HMRC within the specified date range."
        }
      ]
    },
    {
      "info": {
        "name": "Liabilities",
        "type": "folder"
      },
      "items": [
        {
          "info": {
            "name": "Retrieve VAT liabilities",
            "type": "http"
          },
          "http": {
            "method": "GET",
            "url": "https://api.service.hmrc.gov.uk/organisations/vat/:vrn/liabilities",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "vrn",
                "value": "",
                "type": "path"
              },
              {
                "name": "from",
                "value": "",
                "type": "query"
              },
              {
                "name": "to",
                "value": "",
                "type": "query"
              }
            ]
          },
          "docs": "Retrieves VAT financial liabilities owed by the business to HMRC including amounts due, outstanding balances, and due dates."
        }
      ]
    }
  ],
  "bundled": true
}