Skip to main content

​
Overview

Teal’s HMRC integration enables you to retrieve verified income and self-employment data directly from His Majesty’s Revenue and Customs. This provides a reliable, government-sourced view of a user’s financial history, ideal for income verification, lending decisions, and affordability assessments.

​
Data Available

Through the HMRC integration, you can access:
Data TypeDescription
Employment IncomeTotal income and earnings from each employer
Tax PaidTax deducted at source for each employment
Employer DetailsNames of employers on record
Income PeriodThe tax year or period the data covers

​
Use Cases

Confirm employment income directly from HMRC records rather than relying on payroll or payslips alone.

​
How It Works

  1. Create an account connection with payroll_provider set to hmrc
  2. The user authenticates via the HMRC Government Gateway
  3. Teal retrieves income submissions across available tax years
  4. Access the data via GET /hmrc/{user_id} or manage entries via /hmrc/entries

​
Creating an HMRC Connection

To establish an HMRC connection, call POST /accounts with payroll_provider set to hmrc. HMRC requires additional authentication parameters in extra_login_params.

​
Required Parameters

ParameterDescription
unique_tax_referenceThe user’s UTR is a 10 or 13-digit number. They can find it on their Business Tax Account, the HMRC app, tax returns, or other documents from HMRC. It may appear as ‘UTR’, ‘reference’, or ‘official use’.
ni_numberThe user’s National Insurance number. They can find it on their payslip, P60, or letters from HMRC.

​
Example Request

curl --request POST \
  --url https://api.sandbox.goteal.co/accounts \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
  "user_id": "95a0e70b-fe02-4f47-aef9-2efff279df71",
  "payroll_provider": "hmrc",
  "extra_login_params": {
    "unique_tax_reference": "2622992714",
    "ni_number": "GJ458274B"
  }
}'
Once the account is created, the response will include an authorisation_url. The user must complete OAuth authentication via this URL, which redirects them to the HMRC Government Gateway. After successful authentication, you can fetch and retrieve income data using the /hmrc endpoints.

​
Webhook

You can subscribe to the user-hmrc-data-submitted webhook to recieve updates on new HMRC data being retrieved.