> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goteal.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Query Gov Connection
Retrieves the most recent income data for the account's authorisation. May return an empty result if no new income is found.
This endpoint requires a valid authorisation for the user. If no active authorisation exists, the request will be rejected.
You can optionally pass the `x-teal-authorisation-id` header to specify which authorisation to use; otherwise the system will resolve a valid authorisation automatically.
See [Authorisations](/authorisations) for more details.
## OpenAPI
````yaml POST /gov-connect/entries/connections
openapi: 3.0.1
info:
title: Payroll API
description: A full flagged payroll api provided by Teal
version: 1.0.0
servers:
- url: https://api.sandbox.goteal.co
description: Sandbox server for experiments
- url: https://api.goteal.co
description: Production server
security:
- ApiKeyAuth: []
- MemberBearerAuth: []
paths:
/gov-connect/entries/connections:
description: >-
For a Gov Connect (HMRC) account, a call to the
`/gov-connect/entries/connections` endpoint fetches the latest income data
from HMRC for that account and persists it on Teal's storage. The stored
data can subsequently be retrieved using the `GET /gov-connect/{user_id}`
endpoint. The account must have been established via a Gov Connect
connection (e.g. the `hmrc` provider) and the user must have HMRC enabled
and a valid authorisation.
post:
summary: Fetch and store Gov Connect (HMRC) income data for an account
parameters:
- $ref: '#/components/parameters/XAuthorisationId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GovConnectEntriesRequest'
responses:
'200':
description: OK — no new income data was returned
content:
application/json:
schema:
$ref: '#/components/schemas/GovConnectData'
'201':
description: Created — income data was fetched and stored
content:
application/json:
schema:
$ref: '#/components/schemas/GovConnectData'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/UnauthorizedBearer'
'403':
description: Forbidden — the user does not have a valid authorisation
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- BearerAuth: []
components:
parameters:
XAuthorisationId:
name: x-teal-authorisation-id
in: header
required: false
description: >-
Optional authorisation ID to associate with this request. If not
provided, the system will attempt to resolve a valid authorisation for
the user automatically.
schema:
type: string
format: uuid
example: 7f3b8c2a-1d4e-4f6a-8b8c-9a0b1c2d3e4f
schemas:
GovConnectEntriesRequest:
type: object
required:
- account_id
properties:
account_id:
type: string
format: uuid
description: The Gov Connect (HMRC) account id to fetch income data for
example: 95a0e70b-fe02-4f47-aef9-2efff279df71
GovConnectData:
type: object
required:
- account_id
- gov_connect_submissions
properties:
account_id:
type: string
format: uuid
description: The account the income data belongs to
example: 95a0e70b-fe02-4f47-aef9-2efff279df71
entry_id:
type: string
format: uuid
nullable: true
description: >-
The ingestion entry created for this fetch. Null when no data was
returned.
example: 1b2c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e
gov_connect_submissions:
type: array
items:
$ref: '#/components/schemas/GovConnectSubmission'
Error:
required:
- errors
type: object
properties:
errors:
type: array
items:
type: string
description: An array of messages describing the errors
example:
- The request is missing the required field `name`
GovConnectSubmission:
type: object
description: >-
A single Gov Connect (HMRC) income submission in the Making Tax Digital
(MTD) shape. Only the fields present for the taxpayer are returned;
empty fields are omitted. All monetary values are returned as strings.
required:
- id
- account_id
- entry_id
- authorisation_id
properties:
id:
type: string
format: uuid
description: The submission id
example: 3f1c0b9a-1e2d-4a5b-9c8d-0e1f2a3b4c5d
account_id:
type: string
format: uuid
example: 95a0e70b-fe02-4f47-aef9-2efff279df71
entry_id:
type: string
format: uuid
example: 1b2c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e
authorisation_id:
type: string
format: uuid
example: 9f8e7d6c-5b4a-3210-fedc-ba9876543210
income_id:
type: string
description: Stable identifier for the income record
example: 2025-26:emp:se:prop
identity:
type: object
properties:
name:
type: string
example: Fred Bloggs
date_of_birth:
type: string
example: '1980-02-20'
ni_number:
type: string
example: QQ000001A
employments:
type: array
items:
type: object
properties:
employment:
type: object
properties:
employer_name:
type: string
example: NEW CORP
paye_reference:
type: string
example: 120/NC15208
status:
type: string
example: active
start_date:
type: string
example: 2024-06-10T00:00Z
leave_date:
type: string
nullable: true
tax_code:
type: string
nullable: true
income:
type: object
properties:
tax_year:
type: string
example: 2024-25
taxable_income:
type: string
example: '28100.91'
tax_paid:
type: string
example: '3611.40'
updated_at:
type: string
example: '2026-06-05 13:03:39'
self_employments:
type: array
items:
type: object
properties:
business:
type: object
properties:
business_id:
type: string
example: XBIS1
income:
type: object
properties:
tax_year:
type: string
example: 2024-25
turnover:
type: string
example: '92500.00'
other_income:
type: string
example: '1200.00'
tax_deducted_at_source:
type: string
example: '0.00'
properties:
type: array
items:
type: object
properties:
property_id:
type: string
example: XPIS1
tax_year:
type: string
example: 2024-25
rent_received:
type: string
example: '747.45'
UnauthorizedBarer:
type: object
properties:
errors:
type: array
items:
type: string
description: An array of messages describing the errors
example:
- 'Not Authorization: Bearer provided or wrong value'
responses:
BadRequest:
description: Bad request if one of the required parameters is missing
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
UnauthorizedBearer:
description: Unauthorized if the X-API-KEY is not provided or is wrong
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedBarer'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
MemberBearerAuth:
type: http
scheme: bearer
description: >-
Bearer token for authentication. The token should be the one returned by
the "/members/signin"
BearerAuth:
type: http
scheme: bearer
description: >-
Bearer token for authentication. The token should be the one returned by
the /user-tokens endpoint.
````