Table of contents

Self Assessment end-to-end service guide

Version 1.0 issued 9 May 2019

This guide explains how you can integrate your software with our APIs to help complete and submit Self Assessment returns. It shows how the APIs fit into various end-to-end user journeys.

The intended audience is software developers, designers, product owners and business analysts.

The user journeys in this guide are only examples - other use cases are also possible.

This guide relates to the annual Self Assessment process, not the Making Tax Digital quarterly Income Tax process.


Self Assessment is a system we use to collect Income Tax.

Tax is usually deducted automatically from wages, pensions and savings via Pay As You Earn (PAYE). People and businesses with other income must report it in a Self Assessment tax return.

Some people and businesses submit their own Self Assessment return. Others have an agent who submits it on their behalf.

It is possible to submit Self Assessment returns using commercial software. To support this, we provide APIs to:

  • get details from us to help complete a Self Assessment return
  • submit a Self Assessment return

To use these APIs, the end user must:

  • be an individual or an agent
  • be registered for Self Assessment as an individual or an agent
  • have an appropriate HMRC online account

End-to-end user journeys

These journeys show examples of how to use the APIs:

These journeys are only examples - other use cases are also possible.

Help complete a Self Assessment return

Submit a Self Assessment return


Version 1.0

9 May 2019

What changed:

  • Guide first issued