Quickstart — Python

1. Install httpx

Any HTTP client works. We use httpx for the timeouts and pleasant defaults.

pip install httpx

2. Send a request

import os
import httpx

RTW_KEY = os.environ["RTW_KEY"]  # rtw_test_… or rtw_live_…

resp = httpx.post(
    "https://api.rtwchecker.dev/api/check",
    json={
        "share_code": "AA1AA1AA1",   # sandbox: ACCEPTED fixture
        "date_of_birth": "1990-01-01",
        "company_name": "Acme Ltd",
    },
    headers={"authorization": f"Bearer {RTW_KEY}"},
    timeout=30.0,
)

if resp.status_code != 200:
    err = resp.json()["error"]
    raise RuntimeError(f"{err['code']}: {err['message']}")

data = resp.json()
print(data["outcome"], data["name"], data["expiry_date"])

3. Handle the photo and PDF

photo_data_url and pdf_data_url are base64 data URLs. Decode and persist if you need a record (subject to your retention rules — we don't keep them).

import base64
from urllib.parse import urlparse

if data["pdf_data_url"]:
    # "data:application/pdf;base64,JVBE..."
    _, b64 = data["pdf_data_url"].split(",", 1)
    with open(f"{data['reference']}.pdf", "wb") as f:
        f.write(base64.b64decode(b64))

4. Timeouts

A live check takes ~10–15 seconds. Use a 30s read timeout. The server returns 504 TIMEOUT if gov.uk takes longer than its own internal budget — safe to retry.