hmrclib

Comprehensive, typed Python client for the HMRC Developer Hub APIs (Making Tax Digital).

hmrclib is a PyPI package that wraps every REST API published on the HMRC Developer Hub with:

• Generated pydantic v2 models for every OpenAPI schema in every API
• Typed client classes — one per API, one method per endpoint
• Full OAuth2 support: client_credentials (application-restricted), authorization_code + refresh_token (user-restricted), with an optional FastAPI callback server for the browser redirect journey
• Strict typing — the package itself is mypy --strict clean and ruff clean

Installation

pip install hmrclib
# or, with the OAuth callback server extra:
pip install "hmrclib[server]"

Quick start

import os
from hmrclib import OAuth2Client, HMRCClient
from hmrclib.generated.clients import VatApiClient, VatRegisteredCompaniesApiClient

os.environ["HMRC_ENV"] = "sandbox"
os.environ["HMRC_CLIENT_ID"] = "..."
os.environ["HMRC_CLIENT_SECRET"] = "..."

oauth = OAuth2Client()
oauth.client_credentials("read:vat")

client = HMRCClient(oauth=oauth, scope="read:vat")
vat = VatApiClient(client)

# GET /organisations/vat/{vrn}/obligations
result = vat.get_organisations_vat_vrn_obligations(vrn="123456789")
print(result)

Supported APIs

All 73 REST APIs published on the HMRC Developer Hub are generated from their official OpenAPI specifications (vendored under specs/), including Making Tax Digital (Self Assessment, VAT, Property, CIS), Customs, Lifetime ISA, Agent Authorisation, and the test-support APIs.

OAuth2

from hmrclib import OAuth2Client

oauth = OAuth2Client()
oauth.client_credentials("read:vat")  # application-restricted

# user-restricted: build the authorize URL, then exchange the code
url = oauth.authorization_url("hello", state="abc123")
# ... user completes the browser journey ...
token = oauth.authorization_code("CODE_FROM_REDIRECT")
token = oauth.refresh(token.refresh_token)  # keep it alive

OAuth callback server (FastAPI)

uvicorn hmrclib.server:app --port 8300

Serve the registered redirect URI (e.g. https://baseframe.rodmena.co.uk/oauth/hmrc/callback), capture the code and exchange it for tokens:

curl https://baseframe.rodmena.co.uk/oauth/hmrc/result

Development

uv pip install -e ".[dev]"
ruff check .
mypy .
pytest

The generated code can be regenerated from the vendored specs:

python -m hmrclib.codegen --specs specs --out src/hmrclib/generated

License

MIT. hmrclib is not affiliated with HMRC; the API specifications it implements are © Crown copyright, available under the Open Government Licence v3.0.