Skip to main content
POST
Fetch and store Gov Connect (HMRC) income data for an account
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 for more details.

Authorizations

Authorization
string
header
required

Bearer token for authentication. The token should be the one returned by the /user-tokens endpoint.

Headers

x-teal-authorisation-id
string<uuid>

Optional authorisation ID to associate with this request. If not provided, the system will attempt to resolve a valid authorisation for the user automatically.

Example:

"7f3b8c2a-1d4e-4f6a-8b8c-9a0b1c2d3e4f"

Body

application/json
account_id
string<uuid>
required

The Gov Connect (HMRC) account id to fetch income data for

Example:

"95a0e70b-fe02-4f47-aef9-2efff279df71"

Response

OK — no new income data was returned

account_id
string<uuid>
required

The account the income data belongs to

Example:

"95a0e70b-fe02-4f47-aef9-2efff279df71"

gov_connect_submissions
object[]
required
entry_id
string<uuid> | null

The ingestion entry created for this fetch. Null when no data was returned.

Example:

"1b2c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e"