Bulk Data File List API
| REST | |
| Version 1.0 - beta | |
| 17 February 2026 | |
| Sandbox base URL | https://test-api.service.hmrc.gov.uk |
| Production base URL | https://api.service.hmrc.gov.uk |
Overview
The API lists the bulk data files available to download for a specific information type. For each file in list there will be a URL to download the file.
Available Information Types
| Information Type | Description | Content | Frequency |
|---|---|---|---|
| TARIFF-ANNUAL | Full extract of Taric3 and National Measures from database creation date to a certain point in time. | Full Taric3 data (excluding certain EU measures) and National Measures | Produced on 1st January every year at 00:30 and retained until 5th January the following year |
| TARIFF-DAILY | Delta of Taric3 and National Measures updates for that day. By the end of the month, there will be the number of files for the number of days in that month. The files will then be superseded by the monthly file in the next month. | Daily update of Taric3 data (excluding certain EU measures) and daily National Measures | Produced every day at 08:00 and retained until the 5th day of the following month |
| TARIFF-MONTHLY | Delta of Taric3 and National Measures updates for that month. A monthly file is a roll up of all the daily files for a month. By the end of each year, 12 monthly files will have been produced. | Monthly update of Taric3 data (excluding certain EU measures) and monthly National Measures | Produced on 2nd day of the month at 21:00 and retained until the 5th January the following year |
Usage Scenario (Production Environment Only)
On the 1st of January each year, the download pattern you need to follow is as below:
- Download annual file
- Download daily deltas to present date
- Continue with daily deltas from then on
The monthly roll-up files will be required if you sign up in the months after the annual file is first available:
- Download annual file.
- Download monthly file/s.
- Download daily files for the current month to bring it all up to date.
- Follow the standard download cycle of consuming daily files.
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.
Testing
You can use the HMRC Developer Sandbox to test the API. The Sandbox is an enhanced testing service that functions as a simulator of HMRC’s production environment.
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.
Endpoints
| Version | Environments | Endpoints |
|---|---|---|
|
Version 1.0 - beta
(opens in new tab) |
Sandbox and Production | 1.0 endpoints |