Obligations (MTD) API
| REST | |
| Version 3.0 - beta | |
| 15 May 2026 | |
| Sandbox base URL | https://test-api.service.hmrc.gov.uk |
| Production base URL | https://api.service.hmrc.gov.uk |
Overview
Use the Obligations API to retrieve information about different types of tax obligations for a customer’s self-employment or property business, or income tax account.
This API is related to the following customer journeys:
- Submit quarterly updates
- Submit annual updates
For information on how to connect to this API see the Income Tax MTD end-to-end service guide.
Errors
Errors returned by this API are listed in the Response section of each endpoint. Read the reference guide for more information about errors.
Testing
You can use the Sandbox environment to test this API. You can test different scenarios in the Sandbox by passing the Gov-Test-Scenario header. The Sandbox also allows you to perform stateful and dynamic testing for some APIs. The ‘Test data’ section under each endpoint explains the test scenarios that can be simulated.
If you have a specific testing need that is not supported in the Sandbox, contact our Software Developers Support Team. Some endpoints may be marked ‘[test only]’, which means that they are not available for use in Production and may change.
Fraud Prevention
HMRC monitors transactions to help protect your customers' confidential data from criminals and fraudsters.
Check the data you need to send. You can also use the Test API during initial development and as part of your quality assurance checks.
Versioning
When backwards-incompatible changes are made to this API, we release a new version. Read the reference guide for more information about API versioning. For updates about all our APIs, refer to the API changelog.
Endpoints
| Version | Environments | Endpoints |
|---|---|---|
|
Version 3.0 - beta
(opens in new tab) |
Sandbox and Production | 3.0 endpoints |