Bulk Data File List API
| Date | Amount |
|---|---|
| Version and status | |
| 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
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 Type
| 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 |
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.
Testing the API
You can use the sandbox environment to test this API. Please note that due to the size of the files, we have been unable to integrate these to our sandbox environment, however this environment can be used to test your integration with the API.
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.
Endpoints
/bulk-data-download/list/{fileType}
List available files
GET
List the files of the given type that are available for download.
Path parameters
| Name | Description |
|---|---|
|
fileType
string
required
|
A type of the information files to download e.g.
|
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.1.0+json
|
|
Authorization
required
|
An OAuth 2.0 Bearer Token.
For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
List the files of the given type that are available for download.
[
{ "filename": "xyz.xml.gz", "downloadURL": "https://some.sdes.domain?token=abc123", "fileSize": 1234 }
]
No files available for download.
[ ]
Close Section