This version is in beta - expect some breaking changes.

Bulk Data File List API

Dates and amounts
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.

Skip to main content

Endpoints

/bulk-data-download/list/{fileType}

List available files
GET

List the files of the given type that are available for download.

Authorisation

This endpoint is application-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token.

Path parameters

Path parameters table
Name Description
fileType
string
required

A type of the information files to download e.g. TARIFF-DAILY, TARIFF-MONTHLY, TARIFF-ANNUAL.

Request headers

Request headers Table
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
Authorization
required
An OAuth 2.0 Bearer Token.

For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2

See also fraud prevention.

Response

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

Skip to main content