• Register
• Sign in

 

This version is in beta - expect some breaking changes.

VAT (MTD) API

Available in Sandbox	Yes
Sandbox base URL	https://test-api.service.hmrc.gov.uk
Available in Production	Yes
Production base URL	https://api.service.hmrc.gov.uk

Overview

Making Tax Digital introduces digital record-keeping for VAT-registered businesses. Those that are above the VAT threshold will be mandated to use this service from April 2019. Those that are below the threshold can use this service voluntarily. HMRC customers (and their agents) will use digital record-keeping software to interact directly with our systems via the MTD APIs.

The MTD VAT API allows software to supply business financial data to HMRC, so that clients can fulfil their obligations.

For more background on the VAT API, see the MTDfB VAT Guide for Vendors.

How it works

• The client (or their agent) enters their VAT account information into the software.
• The software updates HMRC via the API.
• The API submits this information to an HMRC systems database, where the client’s liability is stored to establish whether the client has met their obligations.

Fraud prevention

It will probably become compulsory to supply header information for this API to prevent fraud. We recommend that you include this now.

Technical support

Technical issues with the API can be raised via the Software Development Support Team (SDST). Technical support is also available via the API Github page. Please note that Github should be used for technical queries only.

Notes

• some APIs may be marked “test only” - this means that they are not available for use in production and may change
• some APIs may be marked “canned” - this means they will return a pre-defined response that may not align with the data provided

Testing

You can use the sandbox environment to test this API. You must use the Create Test User API to create test users.

It may not be possible to test all scenarios in the sandbox. You can test some scenarios by passing the Gov-Test-Scenario header. Documentation for each endpoint includes a Test data section, which explains the scenarios that you can simulate using the Gov-Test-Scenario header.

If you have a specific testing need that is not supported in the sandbox, contact our support team.

Versioning

When an API changes in a way that is backwards-incompatible, we increase the version number of the API. See our reference guide for more on versioning.

Errors

We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

• 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
• 400 to 499 if it failed because of a client error by your application
• 500 to 599 if it failed because of an error on our server

Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.

Back to top

Endpoints

/organisations/vat/{vrn}/obligations

Retrieve VAT obligations

GET

Retrieve VAT obligations

Authorisation

This endpoint is user-restricted - it requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:vat scope.

Path parameters

Name	Description
vrn string required	VAT registration number. A nine-digit number. For example: 123456789

Query parameters

Name	Description
from string required	Date from which to return obligations For example: 2017-01-25
to string required	Date to which to return obligations For example: 2017-01-25
status string optional	Which obligation statuses to return (O=Open, F=Fulfilled) For example: F

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Content-Type required	Specifies the format of the request body, which must be JSON. For example: application/json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the read:vat scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response headers

Name	Description
X-CorrelationId required	Unique id for operation tracking String, 36 characters. For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention for other request headers which will become mandatory.

Response

HTTP status: 200 (OK)

Quarterly obligations; one fulfilled

{
  "obligations": [
    {
      "start": "2017-01-01",
      "end": "2017-03-31",
      "due": "2017-05-07",
      "status": "F",
      "periodKey": "18A1",
      "received": "2017-05-06"
    },
    {
      "start": "2017-04-01",
      "end": "2017-06-30",
      "due": "2017-08-07",
      "status": "O",
      "periodKey": "18A2"
    }
  ]
}

Monthly obligations; one fulfilled

{
  "obligations": [
    {
      "start": "2017-01-01",
      "end": "2017-01-31",
      "due": "2017-03-07",
      "status": "F",
      "periodKey": "18AD",
      "received": "2017-03-06"
    },
    {
      "start": "2017-02-01",
      "end": "2017-02-28",
      "due": "2017-04-07",
      "status": "O",
      "periodKey": "18AE"
    }
  ]
}

Name	Description
obligations array required	Obligation
start string required	The start date of this obligation period Date in the format YYYY-MM-DD For example: 2017-01-25
end string required	The end date of this obligation period Date in the format YYYY-MM-DD For example: 2017-01-25
due string required	The due date for this obligation period, in the format YYYY-MM-DD. For example: 2017-01-25. The due date for monthly/quarterly obligations is one month and seven days from the end date. The due date for Payment On Account customers is the last working day of the month after the end date. For example if the end date is 2018-02-28, the due date is 2018-03-29 (because the 31 March is a Saturday and the 30 March is Good Friday).
status string required	Which obligation statuses to return (O = Open, F = Fulfilled) For example: F
received string optional	The obligation received date, is returned when status is (F = Fulfilled) Date in the format YYYY-MM-DD For example: 2017-01-25
periodKey string required	The ID code for the period that this obligation belongs to. The format is a string of four alphanumeric characters. Occasionally the format includes the # symbol. For example: 18AD, 18A1, #001

Error scenarios

Scenario	HTTP status	Code
Invalid VRN	400 (Bad Request)	VRN_INVALID
Invalid date from	400 (Bad Request)	INVALID_DATE_FROM
Invalid date to	400 (Bad Request)	INVALID_DATE_TO
Invalid date range	400 (Bad Request)	INVALID_DATE_RANGE
Invalid status	400 (Bad Request)	INVALID_STATUS
The remote endpoint has indicated that no associated data is found	404 (Not Found)	NOT_FOUND
The client and/or agent is not authorised.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers are only available in sandbox environment

Header Value (Gov-Test-Scenario)	Scenario
Default (No header value)	Simulates the scenario where the client has quarterly obligations and one is fulfilled
QUARTERLY_NONE_MET	Simulates the scenario where the client has quarterly obligations and none are fulfilled
QUARTERLY_ONE_MET	Simulates the scenario where the client has quarterly obligations and one is fulfilled
QUARTERLY_TWO_MET	Simulates the scenario where the client has quarterly obligations and two are fulfilled
QUARTERLY_THREE_MET	Simulates the scenario where the client has quarterly obligations and three are fulfilled
QUARTERLY_FOUR_MET	Simulates the scenario where the client has quarterly obligations and four are fulfilled
MONTHLY_NONE_MET	Simulates the scenario where the client has monthly obligations and none are fulfilled
MONTHLY_ONE_MET	Simulates the scenario where the client has monthly obligations and one month is fulfilled
MONTHLY_TWO_MET	Simulates the scenario where the client has monthly obligations and two months are fulfilled
MONTHLY_THREE_MET	Simulates the scenario where the client has monthly obligations and three months are fulfilled
NOT_FOUND	Simulates the scenario where no data is found

Close section

/organisations/vat/{vrn}/returns

Submit VAT return for period

POST

Submit VAT return for period

Authorisation

This endpoint is user-restricted - it requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:vat scope.

Path parameters

Name	Description
vrn string required	VAT registration number. A nine-digit number. For example: 123456789

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Content-Type required	Specifies the format of the request body, which must be JSON. For example: application/json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the write:vat scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Request

{
  "periodKey": "#001",
  "vatDueSales": 100.00,
  "vatDueAcquisitions": 100.00,
  "totalVatDue": 200.00,
  "vatReclaimedCurrPeriod": 100.00,
  "netVatDue": 100.00,
  "totalValueSalesExVAT": 500,
  "totalValuePurchasesExVAT": 500,
  "totalValueGoodsSuppliedExVAT": 500,
  "totalAcquisitionsExVAT": 500,
  "finalised": true
}

Name	Description
periodKey string required	The ID code for the period that this obligation belongs to. The format is a string of four alphanumeric characters. Occasionally the format includes the # symbol. For example: 18AD, 18A1, #001
vatDueSales number required	VAT due on sales and other outputs. This corresponds to box 1 on the VAT Return form. The value must be between -9999999999999.99 and 9999999999999.99.
vatDueAcquisitions number required	VAT due on acquisitions from other EC Member States. This corresponds to box 2 on the VAT Return form. The value must be between -9999999999999.99 and 9999999999999.99.
totalVatDue number required	Total VAT due (the sum of vatDueSales and vatDueAcquisitions). This corresponds to box 3 on the VAT Return form. The value must be between -9999999999999.99 and 9999999999999.99.
vatReclaimedCurrPeriod number required	VAT reclaimed on purchases and other inputs (including acquisitions from the EC). This corresponds to box 4 on the VAT Return form. The value must be between -9999999999999.99 and 9999999999999.99.
netVatDue number required	The difference between totalVatDue and vatReclaimedCurrPeriod. This corresponds to box 5 on the VAT Return form. The value must be between 0.00 and 99999999999.99
totalValueSalesExVAT number required	Total value of sales and all other outputs excluding any VAT. This corresponds to box 6 on the VAT Return form. The value must be between -9999999999999 and 9999999999999.
totalValuePurchasesExVAT number required	Total value of purchases and all other inputs excluding any VAT (including exempt purchases). This corresponds to box 7 on the VAT Return form. The value must be between -9999999999999 and 9999999999999.
totalValueGoodsSuppliedExVAT number required	Total value of all supplies of goods and related costs, excluding any VAT, to other EC member states. This corresponds to box 8 on the VAT Return form. The value must be between -9999999999999 and 9999999999999.
totalAcquisitionsExVAT number required	Total value of acquisitions of goods and related costs excluding any VAT, from other EC member states. This corresponds to box 9 on the VAT Return form. The value must be between -9999999999999 and 9999999999999.
finalised boolean required	Declaration that the user has finalised their VAT return. For example: true

Response headers

Name	Description
X-CorrelationId required	Unique id for operation tracking String, 36 characters. For example: c75f40a6-a3df-4429-a697-471eeec46435
Receipt-ID required	Unique reference number returned for a submission String, 36 characters. For example: 2dd537bc-4244-4ebf-bac9-96321be13cdc
Receipt-Timestamp required	The timestamp from the signature, in ISO8601 format For example: 2018-02-14T09:32:15Z
Receipt-Signature required	This header is not currently used For example: DO NOT USE

See also fraud prevention for other request headers which will become mandatory.

Response

HTTP status: 201 (Created)

{
  "processingDate": "2018-01-16T08:20:27.895+0000",
  "paymentIndicator": "BANK",
  "formBundleNumber": "256660290587",
  "chargeRefNumber": "aCxFaNx0FZsCvyWF"
}

Name	Description
processingDate string required	The time that the message was processed in the system.
formBundleNumber string required	Unique number that represents the form bundle. The system stores VAT Return data in forms, which are held in a unique form bundle. Must conform to the regular expression ^[0-9]{12}$
paymentIndicator string optional	Is DD if the netVatDue value is a debit and HMRC holds a Direct Debit Instruction for the client. Is BANK if the netVatDue value is a credit and HMRC holds the client’s bank data. Otherwise not present. Limited to the following possible values: DD BANK
chargeRefNumber string optional	The charge reference number is returned, only if the netVatDue value is a debit. Between 1 and 16 characters.

Error scenarios

Scenario	HTTP status	Code
Invalid VRN	400 (Bad Request)	VRN_INVALID
Invalid period key	400 (Bad Request)	PERIOD_KEY_INVALID
Invalid request	400 (Bad Request)	INVALID_REQUEST
totalVatDue should be equal to the sum of vatDueSales and vatDueAcquisitions	400 (Bad Request)	VAT_TOTAL_VALUE
netVatDue should be the difference between the largest and the smallest values among totalVatDue and vatReclaimedCurrPeriod	400 (Bad Request)	VAT_NET_VALUE
please provide a numeric field	400 (Bad Request)	INVALID_NUMERIC_VALUE
amounts should be a non-negative number less than 9999999999999.99 with up to 2 decimal places	400 (Bad Request)	INVALID_MONETARY_AMOUNT
The value must be between -9999999999999 and 9999999999999	400 (Bad Request)	INVALID_MONETARY_AMOUNT
amount should be a monetary value (to 2 decimal places), between 0 and 99999999999.99	400 (Bad Request)	INVALID_MONETARY_AMOUNT
User has not declared VAT return as final	403 (Forbidden)	NOT_FINALISED
User has has already submitted a VAT return for the given period	403 (Forbidden)	DUPLICATE_SUBMISSION
The client and/or agent is not authorised.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers are only available in sandbox environment

Header Value (Gov-Test-Scenario)	Scenario
INVALID_VRN	Submission has not passed validation. Invalid parameter VRN.
INVALID_PERIODKEY	Submission has not passed validation. Invalid parameter PERIODKEY.
INVALID_PAYLOAD	Submission has not passed validation. Invalid parameter Payload
DUPLICATE_SUBMISSION	The remote endpoint has indicated that VAT has already been submitted for that period.

Close section

/organisations/vat/{vrn}/returns/{periodKey}

View VAT Return

GET

Retrieve a submitted VAT return

Authorisation

This endpoint is user-restricted - it requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:vat scope.

Path parameters

Name	Description
vrn string required	VAT registration number. A nine-digit number. For example: 123456789
periodKey string required	The ID code for the period that this obligation belongs to. The format is a string of four alphanumeric characters. Occasionally the format includes the “#” symbol, which must be URL-encoded. For example: 18AD, 18A1, #001

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Content-Type required	Specifies the format of the request body, which must be JSON. For example: application/json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the read:vat scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response headers

Name	Description
X-CorrelationId required	Unique id for operation tracking String, 36 characters. For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention for other request headers which will become mandatory.

Response

HTTP status: 200 (OK)

{
  "periodKey": "#001",
  "vatDueSales": 100.00,
  "vatDueAcquisitions": 100.00,
  "totalVatDue": 200,
  "vatReclaimedCurrPeriod": 100.00,
  "netVatDue": 100,
  "totalValueSalesExVAT": 500,
  "totalValuePurchasesExVAT": 500,
  "totalValueGoodsSuppliedExVAT": 500,
  "totalAcquisitionsExVAT": 500
}

Name	Description
periodKey string required	The ID code for the period that this obligation belongs to. The format is a string of four alphanumeric characters. Occasionally the format includes the # symbol. For example: 18AD, 18A1, #001
vatDueSales number required	VAT due on sales and other outputs. This corresponds to box 1 on the VAT Return form. The value must be between -9999999999999.99 and 9999999999999.99.
vatDueAcquisitions number required	VAT due on acquisitions from other EC Member States. This corresponds to box 2 on the VAT Return form. The value must be between -9999999999999.99 and 9999999999999.99.
totalVatDue number required	Total VAT due (the sum of vatDueSales and vatDueAcquisitions). This corresponds to box 3 on the VAT Return form. The value must be between -9999999999999.99 and 9999999999999.99.
vatReclaimedCurrPeriod number required	VAT reclaimed on purchases and other inputs (including acquisitions from the EC). This corresponds to box 4 on the VAT Return form. The value must be between -9999999999999.99 and 9999999999999.99.
netVatDue number required	The difference between totalVatDue and vatReclaimedCurrPeriod. This corresponds to box 5 on the VAT Return form. The value must be between 0.00 and 99999999999.99
totalValueSalesExVAT number required	Total value of sales and all other outputs excluding any VAT. This corresponds to box 6 on the VAT Return form. The value must be between -9999999999999 and 9999999999999.
totalValuePurchasesExVAT number required	Total value of purchases and all other inputs excluding any VAT (including exempt purchases). This corresponds to box 7 on the VAT Return form. The value must be between -9999999999999 and 9999999999999.
totalValueGoodsSuppliedExVAT number required	Total value of all supplies of goods and related costs, excluding any VAT, to other EC member states. This corresponds to box 8 on the VAT Return form. The value must be between -9999999999999 and 9999999999999.
totalAcquisitionsExVAT number required	Total value of acquisitions of goods and related costs excluding any VAT, from other EC member states. This corresponds to box 9 on the VAT Return form. The value must be between -9999999999999 and 9999999999999.

Error scenarios

Scenario	HTTP status	Code
The provided VRN is invalid	400 (Bad Request)	VRN_INVALID
Invalid period key	400 (Bad Request)	PERIOD_KEY_INVALID
The date of the requested return cannot be more than four years from the current date	403 (Forbidden)	DATE_RANGE_TOO_LARGE
The client and/or agent is not authorised.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers are only available in sandbox environment

Header Value (Gov-Test-Scenario)	Scenario
DATE_RANGE_TOO_LARGE	The date of the requested return cannot be further than four years from the current date.

Close section

/organisations/vat/{vrn}/liabilities

Retrieve VAT liabilities

GET

Retrieve VAT liabilities

Authorisation

This endpoint is user-restricted - it requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:vat scope.

Path parameters

Name	Description
vrn string required	VAT registration number. A nine-digit number. For example: 123456789

Query parameters

Name	Description
from string required	Liabilities to return from date For example: 2017-01-25
to string required	Liabilities to return up to date For example: 2017-01-25

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Content-Type required	Specifies the format of the request body, which must be JSON. For example: application/json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the read:vat scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response headers

Name	Description
X-CorrelationId required	Unique id for operation tracking String, 36 characters. For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention for other request headers which will become mandatory.

Response

HTTP status: 200 (OK)

{
  "liabilities": [{
    "taxPeriod": {
      "from": "2017-04-06",
      "to": "2017-07-06"
    },
    "type": "VAT ...",
    "originalAmount": 6000.00,
    "outstandingAmount": 100.00,
    "due": "2017-07-06"
  }]
}

Name	Description
liabilities array required	Liability
taxPeriod object optional	The tax period
from string required	The from date of this tax period Date in the format YYYY-MM-DD For example: 2017-01-25
to string required	The to date of this tax period Date in the format YYYY-MM-DD For example: 2017-01-25
type string required	The charge type of this liability. Max length, 30 characters. For example: VAT ...
originalAmount number required	The original liability value. Defines a monetary value (to 2 decimal places), between -9,999,999,999,999.99 and 9,999,999,999,999.99
outstandingAmount number optional	The outstanding liability value. Defines a monetary value (to 2 decimal places), between -9,999,999,999,999.99 and 9,999,999,999,999.99
due string optional	Liability due date Date in the format YYYY-MM-DD For example: 2017-01-25

Error scenarios

Scenario	HTTP status	Code
Invalid VRN	400 (Bad Request)	VRN_INVALID
Invalid date from	400 (Bad Request)	DATE_FROM_INVALID
Invalid date to	400 (Bad Request)	DATE_TO_INVALID
Invalid date range	400 (Bad Request)	DATE_RANGE_INVALID
The remote endpoint has indicated that no associated data is found	404 (Not Found)	NOT_FOUND
The client and/or agent is not authorised.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers are only available in sandbox environment

Header Value (Gov-Test-Scenario)	Scenario
SINGLE_LIABILITY	Returns a single valid liability when used with dates from 2017-01-02 and to 2017-02-02.
MULTIPLE_LIABILITIES	Returns multiple valid liabilities when used with dates from 2017-04-05 and to 2017-12-21.

The 'to' date of the liability must fall within the date range provided.

Close section

/organisations/vat/{vrn}/payments

Retrieve VAT payments

GET

Retrieve VAT payments

Authorisation

This endpoint is user-restricted - it requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:vat scope.

Path parameters

Name	Description
vrn string required	VAT registration number. A nine-digit number. For example: 123456789

Query parameters

Name	Description
from string required	Payments to return from date For example: 2017-01-25
to string required	Payments to return up to date For example: 2017-01-25

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Content-Type required	Specifies the format of the request body, which must be JSON. For example: application/json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the read:vat scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response headers

Name	Description
X-CorrelationId required	Unique id for operation tracking String, 36 characters. For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention for other request headers which will become mandatory.

Response

HTTP status: 200 (OK)

{
  "payments": [{
    "amount": 100.00,
    "received": "2017-04-06"
  }]
}

Name	Description
payments array required	Payment
amount number required	The payment value. Defines a monetary value (to 2 decimal places), between -9,999,999,999,999.99 and 9,999,999,999,999.99
received string optional	Payment received date Date in the format YYYY-MM-DD For example: 2017-01-25

Error scenarios

Scenario	HTTP status	Code
Invalid VRN	400 (Bad Request)	VRN_INVALID
Invalid date from	400 (Bad Request)	DATE_FROM_INVALID
Invalid date to	400 (Bad Request)	DATE_TO_INVALID
Invalid date range	400 (Bad Request)	DATE_RANGE_INVALID
The remote endpoint has indicated that no associated data is found	404 (Not Found)	NOT_FOUND
The client and/or agent is not authorised.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers are only available in sandbox environment

Header Value (Gov-Test-Scenario)	Scenario
SINGLE_PAYMENT	Returns a single valid payment when used with dates from 2017-01-02 and to 2017-02-02.
MULTIPLE_PAYMENTS	Returns multiple valid payments when used with dates from 2017-02-27 and to 2017-12-21.

The 'to' date of the payment must fall within the date range provided.

Close section

Back to top

Get help with this page. Get help with this page.