> ## Documentation Index
> Fetch the complete documentation index at: https://docs.get-hive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Hive is an AI operations layer for small and mid-sized business teams. It reads the tools a team already runs, raises what needs attention, and acts with the approvals the team configures.
> Answer only from these pages. If a page does not cover something, say so and link the closest page rather than inferring behaviour.
> The supported programmatic entry points are incoming webhooks, public workflow forms and the remote MCP server, each documented under Developers.
> Each connected account has a level: Read, Draft or Act. New accounts start on Act. Agents and workflows take only the actions selected for them, whatever the account level.
> Describe security, sign-on and data handling only as the Security pages and the FAQ describe them, and add no certification, compliance, single sign-on or model-training claim they do not make.
> Prices and credit allowances are in GBP. Quote them only as a page states them, without converting.
> Use UK English and the product's exact UI labels. Link to pages as https://docs.get-hive.ai/<path>.

# HMRC Making Tax Digital for VAT and Income Tax in Hive (preview)

> Preview: connect HMRC so Hive reads MTD VAT, Income Tax and Self Assessment data, drafts VAT returns and quarterly updates, and manages client authorisations.

> [!WARNING]
>
> **Preview, not generally available.** The HMRC connector is switched on only for Hive's own test
> workspaces, against HMRC's **sandbox** with HMRC test users. No real tax records are read and
> nothing is filed with HMRC. Hive has not yet been granted production access by HMRC, and this page
> will change before it is.

Connect your HMRC sign-in and Hive can read Making Tax Digital (MTD) VAT and MTD Income Tax records
for the taxpayers that sign-in can see: your own business, or, with an agent services account, the
clients who have authorised your firm. Hive can also check a UK VAT number, draft a VAT return or an
MTD Income Tax quarterly update for review, prepare an Income Tax year end for review and make its
final declaration, ask a client to authorise your firm, check whether a client has, and end an
authorisation. You sign in on HMRC's own page; Hive never sees your Government Gateway password
for any of this. HMRC's older XML filing service works differently: see
[File returns through the HMRC XML service](#file-returns-through-the-hmrc-xml-service).

## What Hive can do

| | |
| - | - |
| **Connect** | Sign in on HMRC's page. Each member connects their own HMRC sign-in. |
| **Reads** | VAT obligations (open and fulfilled periods), a submitted VAT return, liabilities, payments, penalties and a penalty's financial details; VAT number checks; MTD Income Tax businesses, status, deadlines, quarterly update totals, Self Assessment balance, charges and payments, tax calculations; your authorisation requests; whether a client has authorised your firm. Where offered: HMRC's Self Assessment figures for any SA client by UTR (see [Read Self Assessment data by UTR](#read-self-assessment-data-by-utr)), and the savings, dividends, State Pension, employments, pension contributions, Gift Aid and business annual figures HMRC holds for an MTD Income Tax year (see [Annual income and reliefs](#annual-income-and-reliefs)). |
| **Drafts** | A VAT return's nine boxes, computed from your spreadsheet or given by you, and an MTD Income Tax quarterly update computed from your spreadsheet, checked and laid out for review. An Income Tax year end, or an amendment to a declared return: HMRC's tax calculation, shown like an SA302 (HMRC's sandbox only). Where offered: a Self Assessment return (SA100), checked against HMRC's schema (see [Prepare and file a Self Assessment return](#prepare-and-file-a-self-assessment-return-sa100)). None of them files anything. |
| **Actions** | Submit a VAT return, file an MTD Income Tax quarterly update, file the annual return's other income, reliefs and business annual figures, make an Income Tax final declaration or amend a declared return (an admin's approval only, and only when the workspace allows HMRC submissions; Income Tax filings in HMRC's sandbox only for now); request or cancel a client's MTD VAT or MTD Income Tax authorisation; end a client's authorisation (an admin's approval only). |
| **Signals** | — |

## Connect HMRC

**1. Open the tile**

In **Integrations**, find **HMRC (Making Tax Digital)** and select **Connect**.

**2. Sign in at HMRC**

HMRC's own sign-in page opens. Sign in with the right Government Gateway account (see [Which
HMRC sign-in to use](#which-hmrc-sign-in-to-use)), complete HMRC's 2-step check, and give Hive
permission.

**3. Back in Hive**

Hive finishes the connection while you are signed in to Hive and returns you to **Integrations**
with HMRC connected.

Only the member who selected **Connect** can finish that sign-in, and each connection is the
member's own. Finish it in the workspace you started it in: if Hive is open in another workspace
when HMRC sends you back, Hive says the sign-in was started in a different workspace. Switch to that
workspace and connect HMRC again. HMRC lets a sign-in last 18 months; after that, connect again. HMRC may ask you to
confirm your identity during sign-in, depending on your account type and on Income Tax access.

### Which HMRC sign-in to use

Sign in with the Government Gateway account HMRC knows the tax records under, never a personal one:

* **Your own business's VAT:** the business's **VAT Government Gateway organisation account**, the
  one its VAT registration and Making Tax Digital sign-up belong to.
* **Your clients, as an accounting firm:** your firm's **Agent Services Account**. HMRC then shows
  Hive the clients who have authorised your firm.

Do not sign in with a personal or individual Government Gateway account: HMRC links Making Tax
Digital for VAT to the business or the agent, so a personal sign-in sees no VAT records. The HMRC
card on the **Integrations** page and the HMRC tile say the same.

### Check your connection

The **HMRC (Making Tax Digital)** card on the **Integrations** page shows whether your own HMRC
sign-in is connected and, when it is, the date it lasts until: 18 months after you signed in, when
HMRC asks you to sign in again. The card links to this page.

### Disconnect HMRC

Disconnect from the HMRC tile on the **Integrations** page. Hive deletes your stored HMRC sign-in
(the access and refresh tokens it kept encrypted) and the HMRC tools you had, so it can no longer
reach HMRC for you. HMRC gives software no way to end a sign-in early, so nothing is sent to HMRC
when you disconnect.

If you connected HMRC before Income Tax was added, disconnect and connect again so HMRC grants Hive
read access to Income Tax and Hive offers the Income Tax tools.

If you connected HMRC before 5 November 2026, disconnect and connect again before you check or end a
client's authorisation: HMRC grants that permission only at sign-in. Until you do, Hive tells you to
reconnect.

If you connected HMRC before Hive could file Income Tax quarterly updates, disconnect and connect
again before you file one: HMRC grants that permission only at sign-in. Until you do, the HMRC card
on the **Integrations** page asks you to reconnect, and Hive refuses to prepare or file an update,
sending nothing to HMRC.

The same applies to the Income Tax year end: if you connected HMRC before 6 November 2026, disconnect
and connect again before you prepare a year end or make a final declaration, so HMRC grants Hive
permission to ask for the year-end calculation and to declare it.

And to the Self Assessment reads by UTR: if you connected HMRC before your workspace was offered
them, disconnect and connect again so HMRC grants Hive read access to them. Until you do, Hive tells
you to reconnect and sends nothing to HMRC.

### Sandbox and live HMRC

A connection belongs to the HMRC it was made with. When Hive moves a workspace from HMRC's sandbox to
live HMRC, a sandbox connection stops working: Hive asks you to connect again, and sends nothing to
live HMRC with the old sign-in. The sandbox note on the **Integrations** page shows only while Hive
uses HMRC's sandbox.

HMRC approves software one service at a time, starting with MTD VAT. Against live HMRC, until HMRC
approves Hive for MTD Income Tax, Hive asks your HMRC sign-in for VAT and client authorisation
access only, and does not offer the Income Tax reads or Income Tax authorisation requests. The
Income Tax note on the **Integrations** page is hidden while they are not offered.
Once Hive offers Income Tax against live HMRC, a sign-in made before then does not include Income
Tax access: HMRC refuses the Income Tax reads for it. Disconnect HMRC and connect it again to grant
that access.

The Income Tax year end (preparing it and making the final declaration) is offered in HMRC's sandbox
only. Against live HMRC, Hive does not offer it.

## Read VAT records

Ask in plain words, giving the VAT registration number (nine digits):

* *"Which VAT returns are open for 123456789?"*
* *"Show the VAT return for period 24A1 for 123456789"*
* *"What VAT does 123456789 owe, and what has it paid this year?"*
* *"Does 123456789 have any VAT penalty points?"*
* *"Show the financial details of VAT penalty XP123456789012 for 123456789"*
* *"Check VAT number 553557881"*

Liabilities and payments are read up to 366 days at a time. HMRC only shows returns submitted
through Making Tax Digital, for up to four years back.

A penalty's financial details are the amounts charged, paid and still outstanding, any interest,
and any Time to Pay arrangement. Hive reads them by the charge reference HMRC gives with the
penalties: a late-submission penalty's charge reference, or a late-payment penalty's penalty charge
reference. A late-payment penalty that is still building up has no charge reference until HMRC
posts it.

## Read MTD Income Tax records

For a taxpayer signed up to Making Tax Digital for Income Tax, ask in plain words, giving the
National Insurance number:

* *"Which businesses does AA123456A have at HMRC?"*
* *"When are AA123456A's next quarterly updates due?"*
* *"Is AA123456A's final declaration for 2025-26 still open?"*
* *"Is AA123456A mandated for MTD Income Tax in 2026-27?"*
* *"What does AA123456A owe on their Self Assessment account?"*
* *"List AA123456A's Self Assessment payments since April 2024"*
* *"Show AA123456A's latest tax calculation for 2024-25"*

HMRC's MTD Income Tax status for a tax year is one of MTD Mandated, MTD Voluntary, Annual, MTD
Exempt, Digitally Exempt, Dormant or No Status, with HMRC's reason and the business income from two
years before that HMRC used. This read is in HMRC's sandbox only for now.

Quarterly deadlines are read up to 366 days at a time, and Self Assessment account ranges up to 732
days. A long tax calculation is cut at 40,000 characters. As a supporting agent, HMRC shows you
less: supporting agents cannot see tax calculations.

Hive also drafts and files quarterly updates for self-employment and UK property businesses (see
[Draft and file an MTD Income Tax quarterly update](#draft-and-file-an-mtd-income-tax-quarterly-update)),
and prepares and makes the year's final declaration (see
[Prepare and make an Income Tax final declaration](#prepare-and-make-an-income-tax-final-declaration)).

## Read Self Assessment data by UTR

> [!NOTE]
>
> Offered to selected test workspaces only, in HMRC's **sandbox** only, and still being rolled out.
> The HMRC card on the **Integrations** page says when your workspace has it.

For any Self Assessment taxpayer, not only those signed up to Making Tax Digital, Hive can read the
figures HMRC holds for preparing the tax return (SA100) and the taxpayer's Self Assessment account.
Ask in plain words, giving the Self Assessment UTR (ten digits) and, for the return figures, the tax
year:

* *"What employment income does HMRC hold for UTR 2234567890 in 2025-26?"*
* *"List 2234567890's employers for 2025-26, and whether any work was off-payroll"*
* *"How much tax was taken off 2234567890's pay in 2025-26?"*
* *"What benefits in kind did 2234567890's employers report for 2025-26?"*
* *"Show 2234567890's National Insurance for 2025-26"*
* *"What does UTR 2234567890 owe on their Self Assessment account?"*

| Read | What HMRC returns |
| - | - |
| **Income** | Pay from each employment (from the P60 or P45, by employer PAYE reference), and income from pensions and retirement annuities, taxable state benefits and SEISS grants. |
| **Employments** | Each employer's name and PAYE reference, and whether the work was flagged as off-payroll. |
| **Tax** | Tax taken off pay per employment, tax on pensions and Incapacity Benefit, and tax refunded or set off. |
| **Benefits in kind** | Company cars and vans and their fuel, private medical insurance, vouchers and credit cards, goods, accommodation, other benefits and expenses payments, per employment. |
| **National Insurance** | Total Class 1 NICable earnings, Class 2 contributions due, and whether the annual maximum was reached. |
| **Self Assessment account** | The balance (overdue, due within 30 days, due later, and any credit), and the charges, refunds and payments behind it, for the current and previous tax years or from a start date. |

These are reads only: Hive files, submits and changes nothing at HMRC with them. Each read is made
with your own HMRC sign-in and carries the same device details as the VAT and Income Tax reads (see
[Device details HMRC requires](#device-details-hmrc-requires)).

What HMRC holds, and who can see it:

* **Agents** sign in with their Agent Services Account and see their existing **64-8 clients** that
  are linked to that account, for the **last 2 tax years**. A taxpayer signed in as themself sees
  their own records.
* The return figures exist only for taxpayers registered for Self Assessment. Most appear once
  HMRC's PAYE reconciliation has run for the person, which starts around 6 June and is usually done
  by the end of November.
* HMRC removes the return figures once it has processed that year's return. When HMRC has nothing
  for a UTR and tax year, Hive says so rather than showing an empty answer.
* For an MTD Income Tax taxpayer, the Self Assessment account can still be read by National
  Insurance number, as in [Read MTD Income Tax records](#read-mtd-income-tax-records).

## File returns through the HMRC XML service

> [!NOTE]
>
> Available in Hive's own test workspaces only, and only to HMRC's **test service**: Self Assessment
> (SA100), CIS monthly returns and verifications, PAYE (FPS, EPS and P11D) and Corporation Tax
> (CT600). HMRC's test service accepts only the test Government Gateway user IDs and passwords
> HMRC's Software Developer Support Team issues. No return reaches HMRC's live service until HMRC
> issues Hive's software Vendor ID and recognises Hive for each return type.

HMRC files Self Assessment, Construction Industry Scheme (CIS) and Corporation Tax returns through
its older XML service (the Transaction Engine), not through Making Tax Digital. That service does not
use the HMRC sign-in you connect above: it asks for the **Government Gateway user ID and password**
of the person filing with every return. For an agent, that is the firm's own agent sign-in, and the
client must have authorised the firm (for example with a 64-8).

So when a return filed this way is ready, Hive asks for them at the moment you approve it:

1. A workspace **owner or admin** opens the return's approval. **Allow HMRC submissions** must be
   on (see [Connect HMRC](#connect-hmrc)). Automations, schedules and AI clients connected to Hive
   can never approve or file one.
2. They check the return and type their Government Gateway user ID and password into the approval
   dialog, then choose **Approve and file with HMRC**.
3. Hive sends the return once. It never sends the same return twice, even if HMRC's answer is slow
   or does not arrive; in that case Hive says the outcome is unknown so you can check with HMRC
   before filing again.
4. Hive waits for HMRC's answer and shows it: **accepted**, with HMRC's receipt and the return's
   **IRmark** (the 32-character code HMRC prints on its receipt, which proves what was filed),
   **rejected**, with each of HMRC's reasons in plain English, or **not filed**.

Each return put up this way has its own page in Hive, **HMRC filing**, at `/hmrc/filings/` followed
by the filing's id. Hive links to it from the chat answer or approval card that put the return up.
The page shows the return type, whether it goes to HMRC's test service, where it is (waiting for
approval, sent, accepted, rejected or not filed), the IRmark and HMRC's errors, and for a return
waiting for approval, **Review and approve**. Only a workspace owner or admin can open it.

The return itself, the figures you reviewed and a CIS verification's results are personal tax data:
Hive keeps them for 90 days after HMRC answers (or after a return is marked not filed), then clears
them. The filing's page keeps the return type, its status and dates, the IRmark and HMRC's errors
as the record of what was filed.

Your Government Gateway user ID and password are used for that one submission only. Hive sends them
with your approval, uses them for the one message to HMRC, and forgets them. They are never saved,
never written to a log, never shown to Hive's AI, and never filled in for you next time. If the
return changes after you open the approval (a figure, the client, or test changed to live), Hive
refuses the approval and you review it again.

Hive helped prepare the return, but you are responsible for its accuracy, and an approved return
cannot be recalled.

### Corporation Tax returns (CT600)

> [!NOTE]
>
> Available in Hive's own test workspaces only. A return goes to HMRC's **test service** only; Hive
> cannot file a Corporation Tax return with live HMRC yet.

HMRC's free service for filing company accounts and Company Tax Returns closed on 31 March 2026, so
every company now files with software. Hive prepares the return for a **small UK trading company**
that prepares **micro-entity accounts (FRS 105)**:

* the **CT600** form, for one accounting period of up to 12 months starting on or after 1 April
  2015;
* the **tax computation** in inline XBRL (iXBRL), tagged with HMRC's Corporation Tax computational
  taxonomy;
* the **accounts** in iXBRL: the balance sheet, the profit and loss account and the statements, with
  the same company number as the CT600.

Ask works out the return from the accounts figures you give it, the way HMRC checks it:

| Step | What Hive does |
| - | - |
| Trading profit | Profit before tax, plus depreciation and expenses tax does not allow, less interest received (taxed separately), less capital allowances, plus balancing charges |
| Losses | Sets trading losses brought forward against this period's trading profit, and carries a loss of the period forward |
| Rate | Splits the profits between financial years by days. From 1 April 2023: 19% up to £50,000, 25% from £250,000, and 25% less marginal relief in between. The limits are shared with associated companies and reduced for a period shorter than 12 months |
| Tax | Works out each line to the penny, the Corporation Tax, the marginal relief and the tax payable |

To work one out, ask Ask in your own chat, for example "Work out the Corporation Tax return for Acme
Ltd for the year to 31 March 2026", and give it the accounts figures. Ask shows each CT600 box and
the tax payable. Nothing is saved or sent to HMRC. Automations, schedules and AI clients connected to
Hive cannot use it.

When the figures are right, a workspace **owner or admin** can ask Ask to put the return up for
approval. Ask checks the whole return against HMRC's CT600 schema, keeps it, and links to its
**HMRC filing** page, where the owner or admin sees every CT600 box and the tax payable and approves
it with their Government Gateway sign-in, as described above. **Test in Live**, which checks the
return and your sign-in with HMRC without filing anything, comes with live filing.

Not covered yet:

* accounting periods ending after 31 March 2026, until HMRC publishes the taxonomy it needs for
  their computations;
* groups and group relief, close company loans (CT600A), research and development claims,
  chargeable gains, property income, charities and amended returns;
* accounts other than micro-entity accounts, such as FRS 102 section 1A small company accounts.

## Prepare and file a Self Assessment return (SA100)

> [!NOTE]
>
> Available in Hive's own test workspaces only. Hive checks and lays out a 2025-26 SA100 for review,
> and an approved return goes to HMRC's **test service** only, until HMRC issues Hive's software
> Vendor ID and recognises Hive for Self Assessment. Partnership (SA800) and trust (SA900) returns
> are not covered yet.

Hive can prepare an individual's **2025-26 Self Assessment tax return (SA100)** with these pages:

| Page | What it covers |
| - | - |
| **SA100** | The main return: personal details, UK interest and dividends, pensions and benefits, other income, pension and Gift Aid reliefs, student loans, High Income Child Benefit Charge, Marriage Allowance, repayment details and your tax adviser. |
| **SA102** | Employment, one page per job (up to 50). |
| **SA103S** | Self-employment (short), one page per business (up to 50). |
| **SA105** | UK property. |
| **SA110** | Tax calculation summary: the totals from your own tax calculation. |

Ask Hive in plain English, for example *"Prepare Ann Example's 2025-26 tax return from HMRC's
figures and the workings in her Library spreadsheet"*. Hive uses three steps:

1. **Prefill from HMRC.** Where Hive reads HMRC's Self Assessment figures by UTR (see
   [Read Self Assessment data by UTR](#read-self-assessment-data-by-utr)), Hive lays out what HMRC
   holds as return boxes: one SA102 page per employer with pay, tax taken off, the PAYE reference
   and benefits in kind, plus pensions, taxable benefits and refunds. It lists what HMRC does not
   hold, such as whether the client was a company director.
2. **Prepare for review.** Hive checks every figure against HMRC's rule for its box, checks the
   whole return against HMRC's own SA100 schema, and shows it page by page and box by box (by
   HMRC's box numbers, such as **INC2** or **EMP1**). It flags self-employment figures that do not
   add up, such as total expenses that are not the sum of the expense boxes. Nothing is sent to
   HMRC.
3. **File.** A workspace owner or admin approves the return's card in Hive, with **Allow HMRC
   submissions** on. That makes the return ready to file and links to its **HMRC filing** page,
   where they type their Government Gateway user ID and password for that one submission, as
   described in [File returns through the HMRC XML service](#file-returns-through-the-hmrc-xml-service).

To **amend** a return you already filed, prepare the whole return again with the corrected figures
and mark it as an amendment. HMRC takes an amendment online within 12 months of the filing deadline,
up to 9 times.

> [!WARNING]
>
> **Hive does not calculate the tax.** The SA110 figures (the total due, Class 4 National Insurance,
> student loan repayments and the rest) come from your own tax calculation. HMRC works out the tax
> from the return and refuses a return whose total does not match its own calculation, so check them
> in your tax software first.

Hive helped prepare the return, but you are responsible for every figure, and filing it is a legal
declaration made by you or, as an agent, on your client's behalf.

## Verify subcontractors and file CIS monthly returns

> [!NOTE]
>
> Available in Hive's own test workspaces only, through HMRC's **test service**. No CIS return
> reaches HMRC's live service until HMRC recognises Hive for CIS.

For a contractor in the Construction Industry Scheme (CIS), Ask can verify subcontractors with HMRC
and prepare the contractor's monthly return (CIS300), including a nil return. Both are filed through
the [HMRC XML service](#file-returns-through-the-hmrc-xml-service), so a workspace owner or admin
approves each one with their Government Gateway user ID and password.

You need the contractor's:

* **UTR** (Unique Taxpayer Reference);
* **Accounts Office reference** (13 characters, such as `123PA12345678`);
* **employer PAYE reference** (tax office number and reference, such as `123/R229`).

### Verify subcontractors

Ask Hive, for example: *"Verify our new subcontractors Sidney James (UTR 1234567882, NI number
YW000009A) and Denby Roofing Ltd for Harrow Builders."* Up to 100 subcontractors go in one request.

* Use **match** for a subcontractor you have not paid before. HMRC then needs their UTR (and, for a
  partner, the partnership's name and UTR).
* Use **verify** to check again a subcontractor HMRC has verified for you before.

Hive checks the request against HMRC's rules first, then shows it on an approval card. Once an admin
approves it and HMRC accepts it, ask *"What did HMRC say about that verification?"*. Hive shows, for
each subcontractor:

* whether HMRC matched them;
* their tax treatment: **gross** (no deduction), **net** (20%) or **unmatched** (30%);
* the verification number to quote on your monthly return.

### Prepare a monthly return

Ask Hive, for example: *"Prepare the CIS return for the month ending 5 November 2026 from the
Payments sheet of CIS payments November.xlsx."* You can also give the payments in the chat, or say
that no subcontractors were paid, for a nil return.

A payments spreadsheet has one row per subcontractor and a heading over each column. Hive reads the
values in the cells (never formulas) and recognises headings like these:

| Column | Headings Hive recognises |
| - | - |
| Subcontractor (required) | Subcontractor, Name, Trading name, or First name and Surname |
| Total payments (required) | Total payments, Gross payment, Payment, Amount paid |
| Materials | Materials, Cost of materials |
| Tax deducted | CIS deducted, Tax deducted, Deducted |
| UTR | UTR |
| Verification number | Verification number |
| Tax treatment | Tax treatment, Rate (gross, net or 20%, unmatched or 30%) |

Hive checks the return against HMRC's rules before it shows you anything:

* the month ending is the 5th of a month, and at most 3 months ahead;
* payments and materials are whole pounds, and materials are not more than the payment;
* each subcontractor has a UTR, unless the unmatched 30% rate applies;
* a nil return lists no payments.

It then shows, for each subcontractor, the payment, materials, labour (payment less materials), the
tax you deducted, and the tax the verified rate implies on the labour. Where the two differ, the
return carries a warning for you to check. Hive does not change your figures.

### Approve and file

When you are happy with the figures, ask Hive to put the return or verification up for approval.
The approval card shows the figures, the declaration HMRC asks the contractor to make, and a notice
that Hive used AI to prepare it and you are responsible for what is filed. An owner or admin chooses
**Review and approve**, types their Government Gateway user ID and password, and chooses **Approve
and file with HMRC**. Nothing is sent before that.

HMRC does not offer a "test in live" check for CIS, so the first live submission is a real filing.

## File PAYE returns: FPS, EPS and P11D

> [!NOTE]
>
> Available in Hive's own test workspaces only, through the [HMRC XML
> service](#file-returns-through-the-hmrc-xml-service). An approved return goes to HMRC's **test
> service** only until HMRC recognises Hive for PAYE.

Hive files an employer's PAYE returns from the figures your payroll software or spreadsheet
already holds. **Hive does not run payroll**: it never works out anyone's pay, tax, National
Insurance or student loan. It checks your figures against HMRC's own rules, shows them for review,
and files them once an admin approves.

| Return | Tax years | What it reports |
| - | - | - |
| **Full Payment Submission (FPS)** | 2026-27 | Each employee's pay, tax, National Insurance and year-to-date figures for a pay date, starters and leavers, and the final FPS of the year |
| **Employer Payment Summary (EPS)** | 2026-27 | No employees paid in a period, a period of inactivity, the Employment Allowance, statutory payments recovered, CIS deductions suffered, the Apprenticeship Levy, and the final EPS of the year |
| **P11D and P11D(b)** | 2025-26 and 2026-27 | Each employee's expenses and benefits (sections A to N: cars, vans, loans, medical, living accommodation and the rest) and the Class 1A National Insurance total |

### Check and lay out a return

Ask Hive to prepare the return, for example "prepare this month's FPS for 123/AB456 from the
attached payroll export". Hive checks the figures before anything is filed:

* every field against HMRC's published schema for that return and tax year;
* HMRC's business rules, such as a National Insurance letter that suits the employee, two address
  lines for an employee without a National Insurance number, a starter declaration for every
  starter, and no-payment dates that run from the 6th of one month to the 5th of a later one;
* the rules that depend on the day you file, such as a leaving date at most 30 days ahead, and a
  P11D only after its tax year has ended on 5 April.

Hive shows the employer PAYE reference, the tax year and the totals (pay, tax and National
Insurance for the period on an FPS; the Class 1A benefits and National Insurance on a P11D(b)), and
the return's IRmark. Nothing is sent to HMRC. If HMRC would refuse the return, Hive names the rule
instead.

On a P11D, Hive works out only what HMRC defines from your other figures: each cash equivalent as
the cost less any amount made good, the car totals, the number of P11Ds, and the Class 1A
National Insurance at 15% with HMRC's rounding. Car, van, loan and accommodation cash equivalents
are your own figures.

### File a return

1. Hive proposes the filing as an approval card. Only a workspace **owner or admin** can approve
   it, and only when **Allow HMRC submissions** is on. Automations, schedules and AI clients
   connected to Hive can never approve or file one.
2. Approving the card makes the return ready to file. Nothing is sent to HMRC yet.
3. The admin opens its **HMRC filing** page (Hive links to it), checks it again and types their
   **Government Gateway user ID and password** for this one submission, as in
   [File returns through the HMRC XML service](#file-returns-through-the-hmrc-xml-service). For an
   agent, that is the firm's own PAYE agent sign-in.
4. Hive sends the return once and shows HMRC's answer. Ask for a PAYE filing's status at any time.

The employer PAYE reference (for example `123/AB456`) and the Accounts Office reference (for
example `123PA00045678`) come from the employer's HMRC letters. An EPS that reports CIS deductions
suffered also needs the company's Corporation Tax UTR.

## Draft and file an MTD Income Tax quarterly update

Making Tax Digital for Income Tax applies to sole traders and landlords whose qualifying income
(self-employment and property turnover, before expenses) is over £50,000 from 6 April 2026, over
£30,000 from 6 April 2027 and over £20,000 from 6 April 2028. See HMRC's guide to
[who must use Making Tax Digital for Income Tax](https://www.gov.uk/guidance/check-if-youre-eligible-for-making-tax-digital-for-income-tax).
Each self-employment and UK property business sends HMRC a quarterly update, due by 7 August,
7 November, 7 February and 7 May.

Each update is **cumulative**: it holds the business's income and expenses from the start of the
tax year (6 April, or 1 April for a business that reports by calendar quarters) to the end of the
latest quarter, and replaces the business's earlier update for the year. A correction to an earlier
quarter goes into the next update. Hive files updates for tax years from 2025-26.

> [!WARNING]
>
> Hive files Income Tax quarterly updates in HMRC's **sandbox only** for now, with HMRC test users.
> Against live HMRC, Hive refuses to make the approval card and files nothing.

### Compute the update from a spreadsheet

Upload or attach the spreadsheet that holds the business's records for the tax year so far (CSV or
Excel), or select it from your Library, and ask Hive to compute the update, for example *"Compute
the self-employment update from Sole trader 2025-26.xlsx and prepare it for AA123456A, business
XAIS12345678910, to 5 October 2025"*. Hive reads the figures itself; the AI never types them. It
reads either layout:

* **A summary sheet**: each figure's name in a cell, with the figure to its right on the same row.
  If a row has several numbers (a column for each quarter, say), Hive reads the one in the column
  headed "Year to date", "YTD", "Cumulative" or "Total". With no such column it refuses rather than
  file one quarter as the year to date.
* **A ledger**: columns headed by the figures' names. Hive adds up each column over every row, so
  the sheet must hold only the transactions; it refuses a ledger with a row labelled "Total" or
  "Subtotal" rather than count it twice.

Hive knows these names, as well as HMRC's own field names (such as `costOfGoods`):

| Business | Income | Expenses |
| - | - | - |
| Self-employment | Turnover (or Sales, Takings), Other business income, Tax taken off trading income | Cost of goods, Payments to subcontractors, Wages and staff costs, Car, van and travel expenses, Premises running costs, Repairs and maintenance, Admin costs, Business entertainment costs, Advertising costs, Interest on bank and other loans, Finance charges, Irrecoverable debts, Professional fees, Depreciation, Other expenses, or Consolidated expenses. Add "disallowable" for the disallowable part of a category, for example "Admin costs disallowable". |
| UK property | Rents received, Premiums for the grant of a lease, Reverse premiums, Other property income, Tax deducted, Rent a room rents received | Premises running costs, Repairs and maintenance, Financial costs, Professional fees, Cost of services, Travel costs, Other property expenses, or Consolidated expenses; and Residential finance costs, Residential finance costs carried forward, Rent a room amount claimed |

HMRC needs income and expenses in every update, even when they are zero. A self-employment's
turnover and other income, and a property business's rents, are filed as 0 when the spreadsheet has
none, marked "not in workbook". Expenses must be in the spreadsheet: put 0 against a category when
there were none. Figures are to the penny. Hive reads the values your spreadsheet saved and never
runs its formulas. When several sheets hold figures, tell Hive which sheet to use.

Each figure keeps the cells it came from, shown on the draft and on the approval card as its
**digital link**. Hive refuses to prepare or file an update whose figures differ from the ones it
computed, so a figure cannot be changed on the way to HMRC. To file different figures, correct the
spreadsheet and compute the update again. While Hive works, the answer's steps show **Computing an
Income Tax quarterly update**.

### Prepare the update

Ask Hive to prepare the update with the National Insurance number, the business id (from the
business list), the tax year, the dates and the computed figures. Before laying it out for review,
Hive checks HMRC's rules and refuses, sending nothing, when:

* the update has both consolidated expenses and expenses by category;
* it uses consolidated expenses for a business whose turnover so far is over £90,000;
* it does not start on 6 April (1 April for calendar quarters) or ends outside the tax year;
* HMRC lists no open quarterly period for that business that the end date falls in;
* HMRC already holds an update for that business that runs to a later date.

The draft shows the period and its due date, HMRC's latest update for the business, every figure
with its cells, and the totals so far. Preparing an update sends nothing to HMRC beyond reading the
open periods and the latest update, and it is not an approval card. Because preparing checks the
National Insurance number and business at HMRC, you can ask Hive to file the prepared update
straight away, in the same message or the next one, without first asking it to show the business.

> [!NOTE]
>
> **HMRC's sandbox and test businesses.** HMRC's sandbox keeps no quarterly obligations for the
> self-employment and UK property businesses you create with HMRC's Self Assessment Test Support
> API, so it never lists an open period for them. For a business the sandbox lists no obligations
> for at all, Hive checks the end date against the tax year's own quarters instead (6 April to 5
> July and so on, or 1 April to 30 June and so on for calendar quarters), and the draft says it did.
> In the sandbox, Hive also reads and files these businesses' details and updates in HMRC's stateful
> test data, so an update you file is the one HMRC holds afterwards. Against live HMRC, Hive always
> needs HMRC's own open period.

### File the update

Filing works like [submitting a VAT return](#submit-a-return): it needs **Allow HMRC submissions**
on, a request to file puts it on an approval card in the chat and your **Inbox**, and only a
**workspace admin** can approve it, on their own HMRC connection. Agents, workflows and an account
set to Act never file one. The card shows the National Insurance number, business, tax year, dates,
every figure and the digital link with each figure's cells.

Once HMRC accepts the update, Hive asks HMRC for an in-year tax calculation for the year. The card
shows the receipt in full: the National Insurance number, business and period, HMRC's correlation
id, the calculation id (read the calculation a few seconds later by asking Hive to show it), and the
income and expense totals HMRC now holds. If HMRC accepts the update but the
calculation cannot be asked for just then, the card says the update was filed. If HMRC refuses the
update, the card says why in plain words, for example that HMRC does not take an update more than
10 days before the period ends, or that it already holds an update to a later date.

## Prepare and make an Income Tax final declaration

> [!NOTE]
>
> HMRC's sandbox only, with HMRC test users. Hive does not offer the final declaration against live
> HMRC.

At the end of a tax year, a taxpayer in Making Tax Digital for Income Tax agrees HMRC's year-end
tax calculation and declares it: the final declaration. Hive does this in two steps.

### Prepare the year end

Ask in plain words, giving the National Insurance number and the tax year, for example *"Prepare
AA123456A's final declaration for 2025-26"*. Hive:

1. checks HMRC has every quarterly update for the tax year. If one is still open, Hive names the
   business and the quarter, and asks HMRC for nothing more: send the update first;
2. asks HMRC for the year-end calculation, waits for HMRC to work it out (about 5 to 15 seconds),
   and reads it;
3. shows it like an SA302: taxable profit for each self-employment and property business, total
   income, the personal allowance and other allowances, taxable income, Income Tax, Class 2 and
   Class 4 National Insurance, any Capital Gains Tax, tax already deducted, and the total due, with
   any warnings HMRC gives. It also shows the calculation id and the declaration to make.

If HMRC's calculation has errors, Hive shows the errors and no figures, because it cannot be
declared. Correct the records at HMRC and prepare the year end again. Preparing declares nothing,
and the prepared year end is not an approval card.

If HMRC answers with a different calculation from the one Hive asked for, or with one that is not a
year-end calculation, Hive says there is no usable year-end calculation and shows no figures. That
is not a temporary fault, so asking again usually gets the same answer: check the client's year at
HMRC first. Nothing is declared.

If you ask Hive to make the final declaration when there is no usable year-end calculation, it says
so plainly and prepares no card. It does not ask you for the National Insurance number or postcode
again.

As an accounting firm, give the client's postcode too, for example *"Prepare the 2025-26 final
declaration for our client AA123456A, postcode TF3 4ER"*. Hive first checks with HMRC that your firm
is the client's **main** agent, using the Firm ARN unless you name another. HMRC does not let a
supporting agent see the year-end calculation or declare it, so Hive stops there for a supporting
agent.

### Make the final declaration

The final declaration is a legal filing, so it works like a [VAT return
submission](#submit-a-return):

* it needs **Allow HMRC submissions** on the **Integrations** page;
* asking Hive to make it, for example *"Make the final declaration for that calculation, for my
  approval"*, puts it on an approval card in the chat and your **Inbox**. The card shows the
  National Insurance number, the tax year, the calculation id, the summary of figures and HMRC's
  declaration, word for word. Signed in as the taxpayer, that is: *"I declare that the information
  and tax return I have submitted are (taken together) correct and complete to the best of my
  knowledge. I understand that I may have to pay financial penalties and face prosecution if I give
  false information."* As an agent, it is: *"I confirm that my client has received a copy of all
  the information being filed and approved the information as being correct and complete to the
  best of their knowledge and belief. My client understands that they may have to pay financial
  penalties and face prosecution if they give false information."*
* only a **workspace admin** can approve it, on their own HMRC connection. Hive makes no card for a
  member who is not an admin, and agents, workflows and an account set to Act never make one.

When the admin approves, Hive checks again before declaring anything: the calculation must still be
HMRC's latest for the year and a year-end one, and its figures must be exactly the ones on the card.
If HMRC has worked out a newer calculation since, or the figures differ, Hive declares nothing and
asks you to prepare the year end again. An agent must still be the client's main agent.

Once HMRC accepts it, the card shows Hive's confirmation with the calculation id and the declared
figures. HMRC can take up to an hour to show the year's final declaration obligation as fulfilled.
To change a declared return, see [Amend a declared return](#amend-a-declared-return).

Where your workspace has the annual return (see
[Annual income and reliefs](#annual-income-and-reliefs)), the prepared year end also lists the
other income and reliefs HMRC holds for the year (savings interest, UK dividends, state benefits,
employments and pensions, pension contributions, and Gift Aid), each marked as holding figures or
empty, and the sources Hive does not cover. Check that nothing is missing before you declare.

## Annual income and reliefs

> [!NOTE]
>
> Offered to selected test workspaces only, in HMRC's **sandbox** only, and still being rolled out.
> HMRC has closed new production access for 2026-27 software, so Hive does not offer this against
> live HMRC.

Besides the quarterly updates, an MTD Income Tax return includes the taxpayer's other income and
reliefs for the year. Hive reads and files the ones a typical sole trader or landlord needs. Ask in
plain words, giving the National Insurance number and the tax year:

* *"What other income and reliefs does HMRC hold for AA123456A in 2025-26?"*
* *"File £120.50 untaxed interest from TEST Bank for AA123456A, 2025-26"*
* *"File £900 of UK dividends for AA123456A, 2025-26, for my approval"*

| Source | What Hive reads and files |
| - | - |
| **Savings interest** | UK bank and building society accounts, and each account's taxed and untaxed interest for the year. Filing to an account HMRC does not hold yet adds the account first. |
| **UK dividends** | Dividends from UK companies, and other UK dividends (unit trusts and open-ended investment companies). |
| **State Pension** | The State Pension received and any tax paid on it. When HMRC holds no State Pension for the year, Hive creates it and needs its start date. HMRC takes it once the year has ended. |
| **Employments and pensions** | Read only: the PAYE employments and occupational pensions HMRC holds, with pay, tax deducted and benefits in kind. |
| **Pension contributions** | Regular and one-off contributions, retirement annuity payments, payments to an employer's scheme with no tax relief, and overseas pension scheme contributions. |
| **Gift Aid** | Gift Aid payments (in the year, one-off, carried back to the previous year, and paid after the year but treated as in it), and gifts of land, buildings, shares or securities to charity. |

The read marks each source as holding figures, empty, or not read (with the reason), and says when
the year has already been declared. An agent gives the client's postcode too: Hive checks with HMRC
that your firm is the client's **main** agent, because HMRC does not let a supporting agent use
these sources.

Hive does not cover foreign income and pensions, foreign and stock dividends, securities and foreign
interest, capital gains, employment expenses, life insurance policy gains, partnership income,
investment and other reliefs, Marriage Allowance and other disclosures, pension and High Income
Child Benefit charges, losses, CIS deductions, or year-end accounting adjustments. Send those to HMRC
through HMRC's online services.

### Business annual submissions

For each self-employment and UK property business, Hive reads and files the annual allowances and
adjustments, for tax years from 2025-26:

* **Self-employment**: annual investment allowance, main pool, special rate pool and single asset
  pool allowances, zero-emission car allowance, business premises renovation allowance, enhanced
  capital allowance, allowance on sale or cessation, trading income allowance; non-taxable profits
  included, accounting adjustment, outstanding business income, balancing charges, and goods and
  services for own use.
* **UK property**: annual investment allowance, business premises renovation allowance, other
  capital allowances, replacement of domestic items, zero-emission car allowance, property income
  allowance; balancing charge, private use adjustment, and business premises renovation balancing
  charges.

Ask, for example, *"What annual allowances does HMRC hold for AA123456A's self-employment XAIS12345678910
in 2025-26?"* The answer also names the other fields HMRC holds, such as structures and buildings
allowances, which Hive keeps unchanged when it files.

### File annual figures

HMRC replaces the whole submission for a source each time, so Hive reads what HMRC holds first,
changes only the figures you give and sends everything else back unchanged. Filing works like
[filing a quarterly update](#file-the-update): it needs **Allow HMRC submissions** on, the request
puts it on an approval card in the chat and your **Inbox**, and only a **workspace admin** can
approve it. Agents, workflows and an account set to Act never file one.

The card shows the National Insurance number, the tax year, HMRC's current figure for each field
and the new one. When the admin approves, Hive reads HMRC again and files nothing if HMRC's figures
have changed since the card was made: read them again and ask once more. After filing, Hive reads
the figures back from HMRC and the receipt shows them before and after. If the year has already
been declared, the receipt says the change takes effect only once you
[amend the declared return](#amend-a-declared-return).

## Amend a declared return

> [!NOTE]
>
> HMRC's sandbox only, with HMRC test users, where your workspace has the annual return. Tax years
> from 2025-26.

HMRC takes an amendment until 12 months after the 31 January filing deadline: for 2025-26, until
31 January 2028. After that the taxpayer must contact HMRC. To amend:

1. File the changed figures (see [File annual figures](#file-annual-figures)).
2. Ask Hive to prepare the amendment, for example *"Prepare an amendment to AA123456A's 2025-26
   return"*. Hive checks that HMRC holds a declared return for the year and that the window is open,
   asks HMRC for the amended calculation (about 5 to 15 seconds), and shows it like an SA302 with
   the calculation id, the date of the declared return and the declaration to make. Preparing
   amends nothing and is not an approval card.
3. Ask Hive to amend the return for your approval. The card works like the
   [final declaration's](#make-the-final-declaration): the same declaration words, **Allow HMRC
   submissions** on, and a **workspace admin's** approval. Before sending, Hive checks the window is
   still open, that the calculation is still HMRC's latest and an amendment calculation, and that
   its figures are exactly the ones on the card. Otherwise it amends nothing and asks you to prepare
   the amendment again.

As with the final declaration, an agent gives the client's postcode and must be the client's main
agent.

> [!NOTE]
>
> **HMRC's sandbox.** HMRC's sandbox does not keep the calculations, so the year-end and amendment
> calculations it returns are its fixed test data. They show the steps work, not the arithmetic. The
> savings, dividends, benefits, reliefs and business annual figures are kept, so a figure you file
> is the one HMRC reads back.

## Draft and submit a VAT return

Ask Hive to prepare a return with the nine box figures. Hive checks the boxes add up (box 3 is box
1 plus box 2; box 5 is the difference between boxes 3 and 4) and that HMRC lists the period as open,
then lays the return out for review. Preparing a return sends nothing to HMRC, and a prepared
return is not an approval card: nothing waits for approval until you ask Hive to submit it.

### Compute the boxes from a spreadsheet

Making Tax Digital asks for the figures on a return to travel digitally from your records to HMRC,
without being typed again. Upload or attach the spreadsheet that holds your VAT workings (CSV or
Excel), or select it from your Library, and ask Hive to compute the return from it, for example
*"Compute the VAT return from VAT Q1.xlsx and prepare it for period 24A1"*. Hive reads the figures
itself; the AI never types them. It reads either layout:

* **A VAT summary sheet**: a cell starting "Box 1" to "Box 9" (for example "Box 6 - total sales
  excluding VAT"), with the box's figure in the first number to its right on the same row.
* **A ledger with tagged columns**: columns headed "Box 1", "Box 4", "Box 6", "Box 7" and so on.
  Hive adds up each column over every row, so the sheet must hold only the transactions. Hive
  refuses a ledger with a total row (a row labelled "Total" or "Subtotal", or a last row holding
  the sum of the rows above it) rather than count it twice, and names the row: remove it, or keep
  the totals on another sheet.

Boxes 1, 4, 6 and 7 must be in the spreadsheet. Hive works out box 3 (box 1 plus box 2) and box 5
(the difference between boxes 3 and 4) when they are missing, and checks them when they are there.
Boxes 2, 8 and 9 are 0 when missing (they only apply to Northern Ireland trade with the EU). Boxes
1 to 5 are to the penny; boxes 6 to 9 are whole pounds, with the pence left out as HMRC asks. Hive
reads the values your spreadsheet saved: it never runs the spreadsheet's formulas. When several
sheets hold VAT boxes, tell Hive which sheet to use.

Each box keeps the cells it came from (for example `VAT summary!C5`, or `D2:D40` for a ledger
column), and these are shown on the prepared return and on the submission's approval card as its
**digital link**. Hive refuses to prepare or submit a return whose figures differ from the ones it
computed for that link, so a figure cannot be changed on the way to HMRC. To file different
figures, correct the spreadsheet and compute the return again.

Computing a return is offered only in workspaces where HMRC is available, and sends nothing to
HMRC. While Hive works, the answer's steps show **Computing a VAT return**.

### Submit a return

Submitting a VAT return is a legal filing that **cannot be undone**, so:

* It is **off by default**. A workspace admin turns on **Allow HMRC submissions** on the
  **Integrations** page. Until then, asking Hive to submit a return makes no approval card: Hive
  says straight away, before reading or preparing anything, that submissions are off and that an
  admin can turn on **Allow HMRC submissions** in Integrations.
* With submissions on, asking Hive to submit a return (for example *"Submit the VAT return for
  123456789, period 24A1, for my approval"*) puts it on an approval card in the chat and your
  **Inbox**. The period on the card must be one Hive read from HMRC in the same chat, for example
  by listing the open periods or preparing the return; Hive uses what it already read rather than
  reading HMRC again. The card shows the VAT number, period, all nine box figures, the digital link
  when the figures were computed from a spreadsheet, and HMRC's declaration:
  *"When you submit this VAT information you are making a legal declaration that the information
  is true and complete. A false declaration can result in prosecution."* Hive always files the
  figures as final.
* Only a **workspace admin** can approve it, on their own HMRC connection. Agents and workflows can
  propose a return but never submit one, and an account set to Act does not submit it either.
* Once HMRC accepts it, the approval card shows HMRC's receipt: the form bundle number, the
  processing date and, when HMRC gives them, the charge reference and payment indicator. The
  receipt is also kept with the approval.
* If HMRC refuses the return (for example because a return for that period was already
  submitted), the card says so in plain words, with HMRC's error code, and that nothing was filed.

Preparing a return is a read: Hive never puts a prepared return on an approval card, because
approving it would file nothing. Ask Hive to submit the return to get its approval card.

## Ask a client to authorise your firm

With an agent services account, Hive can create HMRC's request for a client to authorise your firm:

* for **MTD VAT**, using the client's VAT number and VAT registration date;
* for **MTD Income Tax**, using the client's National Insurance number and postcode, as their main
  agent (the default) or a supporting agent.

Hive gives you HMRC's link to send to the client, who accepts on HMRC's own site; Hive does not
contact the client. Once you approve the request's card, the card shows the new request's id and
the client's link to accept it on HMRC's site. You
can list your recent requests, check one's status, or cancel a pending one.

## Check or end a client authorisation

Ask whether a client has authorised your firm, for example *"Is 123456789 authorised to us for MTD
VAT? Their VAT registration date is 2020-01-31"* or *"Are we AA123456A's supporting agent for MTD
Income Tax? Their postcode is TF3 4ER"*. HMRC checks the same details it asks for in a request: the
VAT registration date for MTD VAT, the postcode for MTD Income Tax. Hive answers yes or no in plain
words and changes nothing at HMRC. When HMRC refuses the check, Hive says why: for example, the
VAT registration date or postcode does not match HMRC's record, HMRC has no record of the client,
or you are signed in to HMRC as a different agent.

You can also end your firm's authorisation for a client, for MTD VAT or for MTD Income Tax as their
main or supporting agent. Your firm loses access at once, and only the client can authorise it
again, so:

* asking Hive to end one puts it on an approval card in the chat and your **Inbox**;
* only a **workspace admin** can approve it, on their own HMRC connection. Hive makes no card for a
  member who is not an admin, and agents, workflows and an account set to Act never end an
  authorisation;
* **Allow HMRC submissions** does not affect it: that switch covers VAT returns and Income Tax final
  declarations only.

If there was no authorisation to end, the card says so, and that nothing changed at HMRC.

### Firm ARN

Every authorisation request and check names your agent services account's Agent Reference Number
(ARN), for example AARN1234567. A workspace admin can save it as **Firm ARN** in the HMRC settings
on the **Integrations** page, and every member sees it there. When you ask a client to authorise
your firm, list, check or cancel your requests, or check or end a client's authorisation without
naming an ARN, Hive uses the Firm ARN. Leave the field empty and save to clear it.

## In practice agent templates

Two of Hive's [UK accounting templates](https://docs.get-hive.ai/agents/build-an-agent.md#uk-accounting-templates) read HMRC
through the runner's own HMRC connection, attached to the agent with no actions:

* **Statutory Deadline Chaser** lists each client's open VAT return periods and Making Tax Digital
  Income Tax quarterly and final declaration deadlines, labelled **HMRC**, next to their Companies
  House dates. It reads HMRC's own MTD Income Tax status for each client with an NI number, ahead
  of the cohort it estimates from your Client register (see
  [Making Tax Digital for Income Tax cohorts](https://docs.get-hive.ai/use-cases/accounting-and-client-services.md#making-tax-digital-for-income-tax-cohorts)).
* **New Client Onboarding Pack** checks whether a new client has already authorised your firm for
  MTD VAT or MTD Income Tax, and gives the exact authorisation request to make for each one still
  missing. It never makes the request: you make it in Ask, where it waits on an approval card when
  your HMRC account is set to **Draft**.

A template cannot select an HMRC action, and a scheduled run cannot read HMRC (see
[Device details HMRC requires](#device-details-hmrc-requires)).

## When HMRC says no

When HMRC refuses a request, Hive tells you in plain words what went wrong and what to do next,
followed by HMRC's error code, for example:

| HMRC code | What Hive tells you |
| - | - |
| `DUPLICATE_SUBMISSION` | A return for this period has already been submitted. View it; to correct it, follow HMRC's error-correction process. |
| `TAX_PERIOD_NOT_ENDED` | The VAT period has not ended yet. HMRC accepts the return from the day after the period ends. |
| `NOT_SIGNED_UP_TO_MTD` | The business is not signed up to Making Tax Digital for VAT. It signs up on GOV.UK first. |
| `CLIENT_OR_AGENT_NOT_AUTHORISED` | The business has not authorised this HMRC sign-in, is not signed up to Making Tax Digital, or (for an agent) has not authorised your firm. |
| `INSOLVENT_TRADER` | HMRC records the business as insolvent, so it does not accept this through Making Tax Digital. |
| `DATE_RANGE_TOO_LARGE` | The date range is too long. Ask for at most a year at a time. |
| `INVALID_MONETARY_AMOUNT` | An amount was refused: pounds and pence for boxes 1 to 5, whole pounds for boxes 6 to 9. |
| `MATCHING_RESOURCE_NOT_FOUND` | HMRC has no matching record. Check the reference and the period. |
| `RESOURCE_FORBIDDEN` | Hive's HMRC application is not yet set up for that HMRC service. It is not your sign-in or a client's authorisation: contact Hive support. |
| `RULE_EARLY_DATA_SUBMISSION_NOT_ACCEPTED` | HMRC does not take an Income Tax update more than 10 days before the period ends. Try again nearer the end of the period. |
| `RULE_SUBMISSION_END_DATE_CANNOT_MOVE_BACKWARDS` | HMRC already holds an Income Tax update to a later date for this business. An update must run to that date or later. |
| `RULE_OUTSIDE_AMENDMENT_WINDOW` | HMRC no longer takes changes to this tax year's quarterly updates. Make corrections in the final declaration. |
| `RULE_FINAL_DECLARATION_RECEIVED` | HMRC already has a final declaration for this tax year, so nothing more was declared. |
| `RULE_RECENT_SUBMISSIONS_EXIST` | HMRC has newer information for the tax year than the calculation. Prepare the year end again and review the new calculation. |

Hive covers the other codes HMRC documents for VAT, Income Tax and client authorisation the same
way, including the reason HMRC gives inside a general `BUSINESS_ERROR` or `INVALID_REQUEST`
answer. Hive never repeats HMRC's own error text. On an approval card, a change HMRC refused says
so and that nothing was changed; only when HMRC could not be reached, or answered with its own
fault, does the card say Hive cannot confirm whether the change went through.

Hive keeps your HMRC sign-in renewed as you use it. When several HMRC reads run at once, for example
a balance and payments in the same Ask answer, they share one renewal, so one read never tells you
to reconnect while the other works. Hive tells you to reconnect only when HMRC refuses your latest
sign-in.

HMRC limits how many requests each piece of software may make, so Hive spaces its HMRC requests out
and, if HMRC still asks it to slow down, waits as long as HMRC asks and tries once more. If HMRC is
still busy after 30 seconds, Hive tells you to try again in a minute.

## Device details HMRC requires

UK law requires software that connects to Making Tax Digital to send HMRC details about the device
and connection behind every request, so HMRC can spot fraud. These are HMRC's fraud prevention
headers. Hive sends them with every VAT and Income Tax request it makes for you, and makes no such
request without them.

While HMRC is connected and Hive is open in your browser, Hive records these details when the tab
opens, whenever you come back to it, every 10 minutes while it is in view, and just before you ask
Hive something or approve a card:

* your browser's user agent (the browser and operating system it reports);
* your screen size, scaling and colour depth, and the size of the Hive window;
* your timezone;
* a random device identifier that Hive creates and keeps in your browser;
* the public IP address your browser connected from when it sent these details, and when;
* if you signed in to Hive with a second step, such as a code from an authenticator app or a code
  sent by text message or email, when you completed it.

With them, Hive sends:

* your Hive user ID (an internal ID, not your name or email address);
* Hive's own details: the product name, the versions of the Hive server and web app that handled
  the request, and the public IP address your browser connected to. The web app's version is the
  one your browser reports, which can be older than the server's, and Hive leaves a version out
  rather than send a placeholder;
* if you used a second sign-in step: its type (an authenticator app, a code sent to you, or
  another kind), the minute you completed it, and a coded reference that tells HMRC it is the same
  step each time without revealing it. Hive does not send your phone number or email address. If
  you signed in without a second step, Hive leaves this out.

Hive keeps only your latest details, in your settings for the workspace, and sends them only to
HMRC.

The details must describe the request being made, so Hive makes a VAT or Income Tax request only
while you are using Hive in your browser:

* **Details older than 15 minutes are not used.** If Hive's copy is older, or Hive has not seen it
  yet, the request is refused and nothing is sent to HMRC. Open Hive and ask again.
* **No unattended requests.** A scheduled agent, a workflow, Slack or Teams, or an AI client
  connected over Hive's MCP server cannot make a VAT or Income Tax request, because nobody is at a
  Hive browser for HMRC to check. Ask in Hive itself instead.

Agent authorisation requests and VAT number checks need no device details, so these limits do not
apply to them.

Hive does not send two of the headers HMRC lists, because it cannot collect them:

* **Your network port.** Hive's hosting provider does not pass on the port your connection came
  from.
* **Licence IDs.** Hive is an online service with no licence keys.

### Check your device details with HMRC

In HMRC's sandbox, a workspace admin can select **Check device details with HMRC** on the HMRC card
in **Integrations**. Hive builds the headers for your browser exactly as it would for a VAT or
Income Tax request, and asks HMRC's test service whether they are complete and well formed. Hive
shows what HMRC found as header names and HMRC's codes, for example
`gov-client-public-port: MISSING_HEADER`; it never shows the values themselves. If Hive has not yet
seen your device details, reload Hive in that browser and check again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.