Connecting to HMRC (Agent Services Account)
To retrieve client VAT obligations, liabilities, and payments, the firm must link its HMRC credentials to Complyax.
HMRC integration is a firm-wide setting and can only be configured by a Firm Administrator in the Settings panel.
Connection Steps
To connect your firm’s HMRC credentials:
Open HMRC Settings
Navigate to Settings in the left menu. Scroll to the HMRC MTD Integration card.
Authorise via GOV.UK
Click Connect HMRC Portal. A secure popup window will open, redirecting you to the official GOV.UK Government Gateway login page.
Enter Gateway Credentials
Log in using your firm’s HMRC Agent Services Account (ASA) credentials or individual gateway credentials.
Grant Permission
Review the access permissions requested by Complyax and click Grant Authority.
Confirm Integration Status
Once authorised, the popup will close automatically, and the card in Complyax will update to display:
- Connection Status — ASA Connected or Individual Connected.
- ARN / Tenant ID — Your Agent Reference Number retrieved from HMRC.
- Expiration Timestamp — The date when the MTD token expires.
Synchronising Obligations and Data
Once connected, you can manage obligations:
- Sync Obligations — Click Sync APIs 🔄 in the Compliance Calendar or use the sync option on the settings page to fetch active VAT obligations and deadlines.
- Client Mapping — The system uses the client’s VAT Registration Number (VRN) to retrieve their tax obligations from your agent portfolio.
Re-Authentication
HMRC requires agent authorisations to be refreshed periodically (typically every 18 months).
- The MTD Integration card shows the token expiration date.
- If the token expires, a warning banner is shown. Click Reconnect to re-authorise via the steps above.
Revoking Connection
To disconnect Complyax from HMRC:
- Navigate to Settings > HMRC MTD Integration.
- Click Disconnect HMRC and confirm.
- The stored OAuth tokens are deleted from the database.