API Documentation

Agent Authorisation

For tax agents requesting authorisation to act on a client’s behalf. Replacing the 64-8 paper form, use this API to set up new authorisation requests and check the status, cancel or query a request.

Agent Authorisation Online

Technical specifications for software developers working with the Agent Authorisation Online service. This API is not part of the Making Tax Digital initiative.

Agent Authorisation Test Support

For testing only. Test accepting or rejecting an authorisation request created using the Agent Authorisation API.

Alcohol and Tobacco Warehouse Declaration Online

Excise Warehouses are premises authorised by HMRC to receive and store goods that are liable for excise duty without having to pay the duty. This API allows Excise Warehouses to Submit Excise warehouse returns (W1), Alcohol Remittance Warrants (W5), Alcohol deferment warrants (W5D), Tobacco remittance warrants (W6) and tobacco deferment warrants (W6D)

Automatic Exchange of Information

Automatic exchange of information agreements are made between UK and other countries to allow tax authorities to exchange information in order to stop tax avoidance. Banks and other financial institutions provide information to HMRC about their (non UK) customers which HMRC can then share internationally.

Bulk Data File List

This API lists the files available for download through the Secure Data Exchange Service (SDES) and provides a download URL.

Business Details (MTD)

Use this API to list all businesses associated with an individual and retrieve additional information each business.

Business Income Source Summary (MTD)

Retrieve a summary of income and expenditure for a specific self-employment, or property business.

Business Rates

This API allows users to search, view and manage property services in relation to business rates. Requires pre-registration with the Valuation Office Agency (VOA).

Business Source Adjustable Summary (MTD)

An API to access Business Source Adjustable Summary (BSAS) calculations for self-employment or a property business. Generate lists, request/provide a BSAS and adjustments.

CIS Deductions (MTD)

View and manage Construction Industry Scheme (CIS) deductions. Use this API to retrieve, create, remove and override information CIS contractors have submitted to HMRC.

CTC Guarantee Balance

Use the Common Transit Convention (CTC) API to tell traders their guarantee funds balance.

CTC Guarantee Balance roadmap

This document lists the past and planned changes made to the CTC Guarantee Balance API.

CTC Guarantee Balance service guide

This guide explains how to use the Common Transit Convention (CTC) Traders Guarantee Balance API with your software.

CTC Guarantee Balance testing guide

This testing guide helps to check your software is compatible with the Common Transit Convention (CTC) Guarantee Balance API.

CTC Traders

The Common Transit Convention (CTC) API sends departure and arrival notifications to the New Computerised Transit System (NCTS). It also retrieves messages from departure and destination customs offices.

CTC Traders phase 5 service guide

This service guide explains how to use the Phase 5 Common Transit Convention (CTC) API.

CTC Traders phase 5 technical interface specification

This document explains the processes involved in the message exchange between traders and the New Computerised Transit System (NCTS) at departure and arrival of transit movements.

CTC Traders phase 5 testing guide

This testing guide helps to check your software is compatible with the Common Transit Convention (CTC) Traders API.

CTC Traders roadmap

This document lists the past and planned changes made to the CTC Traders API.

CTC Traders service guide

This service guide explains how to use the Common Transit Convention (CTC) API.

CTC Traders technical interface specification

This document explains the processes involved in the message exchange between traders and the New Computerised Transit System (NCTS) at departure and arrival of transit movements.

CTC Traders testing guide

This testing guide helps to check your software is compatible with the Common Transit Convention (CTC) Traders API.

Charities Online

An API to allow charities and Community Amateur Sports Club (CASCs) to submit, amend and get information on Gift Aid claims.

Check a UK VAT number

Check the registration and company details for UK VAT numbers. This API also generates a reference to prove a check has been made.

Check an EORI Number

This API allows users to check if an importer/exporter’s UK Economic Operator Registration Identification (EORI) number is valid. This is for numbers beginning ‘GB’.

Construction Industry Scheme Online

The Construction Industry Scheme requires contractors in the construction Industry to deduct tax and national insurance from payments to subcontractors and send them to HMRC.This API allows contractors to verify the details of a subcontractor and submit monthly returns (CIS300) showing their payments to subcontractors.

Corporation Tax Online

An API that allows companies to submit or amend a corporation tax return (CT600).

Create Test User

Create dummy individual, agent, and organisation accounts for testing user-restricted endpoints in our sandbox.

Customs Declarations

An API to submit Union Custom Code (UCC) Declarations for processing and approval by the Customs Declaration Service. It allows users to cancel a pre-request while in pre-clearance, and provides a route to securely upload additional documentation.

Customs Declarations Information

Use this API to search and get details of a Customs Declaration. Users can search based on role, category, date, goods location code and status.

Customs Declarations end-to-end service guide

This guide explains how to integrate your software with our APIs to complete a customs declaration including various end-to-end user journeys.

Customs Inventory Linking Exports

Enables functionality for the Inventory Linking Export process to control and monitor cargo in transit. This API supports three functional areas: consolidation, movement and query.

EC Sales List Online

The XML ECSL Declaration Service is a reliable channel for VAT registered traders and their appointed agents to submit EC Sales Lists (ECSL) directly via commercial or bespoke software packages. Since Brexit VAT registered businesses supplying goods from NI to VAT registered customers in EU must tell HMRC about those supplies.

Excise Movement Control System

Submit information to the Excise Movement Control System (EMCS) including movement notices, view messages from EMCS and retrieve information about traders.

Excise Movement Control System service guide

The Excise Movement Control System (EMCS) API is used to submit movement information to the EMCS system, and retrieve information about movements. This guide explains how to use EMCS with your software.

Excise Movement Control System service guide FS 4.2

The Excise Movement Control System (EMCS) API is used to submit movement information to the EMCS system, and retrieve information about movements. This guide explains how to use EMCS with your software.

Excise Movement Control System technical interface specification

This document explains the processes involved in exchanging messages between traders and the Excise Movement and Control System (EMCS). It provides definitions, explains formats and validations.

Excise Movement Control System technical interface specification FS 4.2

This document explains the processes involved in exchanging messages between traders and the Excise Movement and Control System (EMCS). It provides definitions, explains formats and validations.

Excise Movement Control System testing guide

This guide explains how to test your software’s compatibility with the Excise Movement Control System (EMCS) API.

Excise Movement Control System testing guide FS 4.2

This guide explains how to test your software’s compatibility with the Excise Movement Control System (EMCS) API.

Goods Vehicle Movements

This API creates, updates and deletes Goods Movement Records (GMRs). It lists active GMRs and notifies users when inbound goods have successfully cleared UK HMRC systems.

Goods Vehicle Movements service guide

This guide explains how to use the Goods Vehicle Movement Service (GVMS) APIs with your software.

Hello World

A 'hello world' example of an API on the HMRC API Developer Hub.

ISA Returns

Submit monthly reports of current tax year ISA subscription data. Only HMRC-approved ISA managers can use this API. In future, enrolment for digital ISA reporting will also be required.

Import Control Presentation of Goods

Supporting the process of goods arriving in Northern Ireland, this API allows users to submit presentation notifications to Customs, check inspection dates and notify Customs where goods don’t need inspection.

Import Control System

The Import Control System is used to perform risk analyses of goods entering the EU or Northern Ireland before they leave their country of departure.This API allows traders to submit Entry Summary declaration (ENS) about their goods to ICS and get information about the decision on whether or not to allow those goods to enter the EU or Northern Ireland.

Import Control System 2 Presentation of Goods service guide

This guide explains how to integrate your software to submit a presentation of goods notification to, and receive a control notification from, HMRC.

Income Tax (MTD) end-to-end service guide

This service guide explains HMRC's Making Tax Digital (MTD) for Income Tax, including how to connect software to MTD APIs.

Income Tax (MTD) roadmap

This document lists the past and planned changes made to the Income Tax (Making Tax Digital) APIs.

Individual Benefits

Provide information about an employee, or director’s benefits, as reported to HMRC by the employer. This API is designed to pre-populate an individual’s Self-Assessment tax return.

Individual Calculations (MTD)

Use this API to trigger, list, retrieve and submit a customer’s self-assessment tax calculation.

Individual Employment

This API shares information HMRC holds including; employment history, employer PAYE reference, employer’s name and an off payroll work flag where applicable.

Individual Income

This API shares information HMRC holds including; employment history, employer PAYE reference, employer’s name and an off payroll work flag where applicable.

Individual Losses (MTD)

This API provides financial data and allows users to create, show, update and delete Brought Forward Losses and Loss Claims.

Individual PAYE Test Support

Set up test data for use with individual PAYE APIs including Individual Benefits, Individual Employment, Individual Income and Individual Tax.

Individual Tax

Retrieve the information HMRC holds about an individual’s tax affairs including; tax deducted from their annual gross income, pensions, incapacity benefit, and tax refunds.

Individuals Capital Gains Income (MTD)

An API for providing individuals capital gains data

Individuals Charges (MTD)

An API to provide financial data for pensions charges. Use this API to retrieve, create, amend and delete pension charges.

Individuals Disclosures (MTD)

This API creates, amends, retrieves and deletes data relating to Marriage Allowance and Individuals Disclosures.

Individuals Dividends Income (MTD)

An API for providing individual dividends income data

Individuals Employments Income (MTD)

An API for providing individual employments income data

Individuals Expenses (MTD)

This API creates, amends, retrieves and deletes data relating to Trade Union income, Patent Royalties and existing employment expenses.

Individuals Foreign Income (MTD)

An API for providing individual foreign income data

Individuals Insurance Policies Income (MTD)

An API for providing insurance policy income data

Individuals Other Income (MTD)

An API for providing individual other income data

Individuals Partner Income (MTD)

An API for providing partner income data

Individuals Pensions Income (MTD)

An API for providing individual pensions income data

Individuals Reliefs (MTD)

Create, amend, retrieve and delete data relating to relief from investments and subscriptions.

Individuals Savings Income (MTD)

An API for providing individuals savings income data

Individuals State Benefits (MTD)

Create, amend and retrieve information relating to an individual’s State Benefits.

Individuals Tax Liability Adjustments (MTD)

An API for providing individual tax liability adjustments data

Initiate payment

This API allows users to trigger an HMRC payment journey from their software.

Interest Restriction Return (IRR)

Appoint or revoke a Reporting Company’s access to submit Interest Restriction Returns (IRR). This API also enables submission of full or abbreviated Interest Restriction Returns.

Interest Restriction Return (IRR) service guide

This guide explains how to use the Interest Restriction Return (IRR) API with your software. It is for all roles involved in creating or integrating software connected to this API.

Lifetime ISA

Create and manage lifetime ISA (LISA) accounts including requesting and transferring event details, withdrawals and debt information.

Marriage Allowance

An API to get Marriage Allowance status and check eligibility.

Marriage Allowance Test Support

Create test data for the Marriage Allowance API.

National Insurance

View earnings subject to National Insurance (NI) and payments due. This API is primarily used to calculate a taxpayer’s NI liability within Self Assessment.

National Insurance Test Support

Set up test data to use with the National Insurance API.

New Computerised Transit System

The New Computerised Transit System (NCTS) is a European wide system, based upon electronic declaration and processing, designed to provide better management and control of Community and Common Transit.

Notification of Presentation Waiver Checker

This API enables Community System Providers (CSPs) to verify traders' Notification of Presentation (NOP) waiver using their Economic Operators Registration and Identification (EORI) number.

Notification of Presentation Waiver Checker Roadmap

A roadmap that shares the key dates for the Notification of Presentation (NOP) waiver checker API.

Notification of Presentation Waiver Checker Service Guide

Learn how, as a Community System Provider (CSP), to use the Notification of Presentation (NOP) waiver checker API.

Obligations (MTD)

This API retrieves obligations for business income sources, final declaration and the End of Period Statement.

Other Deductions (MTD)

This API creates, amends, retrieves and deletes deductions.

PAYE Online

Technical specifications for software developers working with the PAYE online service.

Pension Schemes Online

Pension schemes online is a service for registering pension scheme administrators and practitioners. It is used for filing a scheme administrator's declaration, event reports, accounting for tax returns

Pillar 2 API

An API for managing and retrieving Pillar 2 data

Pillar 2 API Roadmap

A roadmap that shares the key dates for the Pillar2 API.

Pillar 2 API Service Guide

This service guide explains how you can integrate your software with the Pillar 2 API.

Post and Parcels Service Guide

This guide explains how to integrate HMRC’s Secure Data Exchange Service (SDES) with your software, key for sharing information about parcel movements to Northern Ireland.

Property Business (MTD)

An API that allows users to manage UK, Foreign, Historic and Non-Furnished Holiday Let (FHL) submission and summaries.

Pull Notifications

Allows for retrieval of notifications

Push Pull Notifications

Send (push) and get (pull) notifications using this API.

Real Time Information online

Technical specifications for software developers working with the Real Time Information online service.

Relief At Source

Check a pension scheme member’s residency for tax purposes and making relief at source claims.

Safety and Security Import Declarations

This API is used to set up new, and amend existing Entry Summary Declarations (ENS) submissions.

Safety and Security Import Notifications

This API will generate a list of, acknowledge and retrieve Entry Summary Declarations (ENS) notifications.

Safety and Security Import Outcomes

This API will list, retrieve and acknowledge Safety and Security Import Outcomes.

Safety and security import declarations service guide

This guide explains how to use Safety and Security (S&S GB) APIs with your software to submit an Entry Summary Declaration to import food into Great Britain.

Secure Data Exchange File Upload API

This API creates URLs for uploading one or multiple files to HMRC’s Secure Data Exchange Service (SDES). It is designed for use with Web Forms.

Secure Data Exchange Service (SDES) - Pillar 2 Service Guide

This guide explains the taxes applicable under the Pillar 2 agreement and how to use the SDES File Upload API for sharing documentation and ensuring compliance.

Self Assessment Accounts (MTD)

Retrieve overall liability broken down into overdue, payable and pending amounts.

Self Assessment Assist (MTD)

This API manages generating the HMRC Assist Report.

Self Assessment Individual Details (MTD)

Perform operations related to Individuals/Taxable Entities for Income Tax Self Assessment.

Self Assessment Online

API for the old, pre-MTD ITSA self assessment service. Supports returns for individual, partnership, trust and estate returns. The person completing the form gets data to help complete it from a number of REST APIs (individual benefits, individual employments, national insurance etc.) but the self assessment tax return (SA100) is submitted through this XML API.

Filters

Filter by document type

Filter by API category