GMC Registrant Lookup
PPP verifies UK doctors against the General Medical Council (GMC) register at signup and whenever a user edits their professional details. The lookup returns the doctor's name, profession, licence status, primary medical qualification, full-registration date, specialist register entries, and GP register status. PPP uses these fields to suggest a user type (consultant / GP / trainee / other) during onboarding and to keep a clean record of regulatory standing.
No official GMC API
There is no public GMC API. PPP fetches the public registrant page from www.gmc-uk.org/registrants/{number} and parses the HTML. This works reliably because GMC publishes the register as searchable public web pages — but it is tightly coupled to GMC's page structure and will break if they change their markup. Monitoring is in place (see Observability) and contract tests guard against silent regressions.
1. Purpose
| Feature | How it uses the GMC lookup |
|---|---|
| Signup | Pre-fills the user's name and profession; suggests user type (consultant/GP/trainee) |
| Profile completion prompt | Verifies the user's entered GMC number belongs to a real, licensed registrant |
| Admin verification workflows | Surfaces licence status changes during profile review |
| 360 peer review | Lets reviewers confirm the subject is on the Specialist Register |
The lookup is UK-only. AHPRA (Australia) verification is a separate integration tracked in a future issue; until then, AU doctors manually enter their AHPRA number with no external check.
2. Where it's wired
| File | Purpose |
|---|---|
api/backend-ppp/src/services/gmcRegistrantService/fetchGmcRegistrantDirect.ts | Fetches + parses the GMC public registrant HTML page |
api/backend-ppp/src/services/gmcRegistrantService/fetchGmcRegistrant.ts | Wraps the direct fetch and adds user-type classification |
api/backend-ppp/src/services/gmcRegistrantService/validateConsultantStatus.ts | Cross-checks claimed consultant status against the register |
api/backend-ppp/src/services/gmcRegistrantService/mock_gmc_register.csv | Offline-mode CSV for development without hitting GMC |
api/backend-ppp/src/services/userTypeClassification/classifyUserType.ts | Classifies consultant / gp / trainee / other from registrant data |
api/backend-ppp/src/routers/procedures/gmc/registrant/publicIndex.ts | Rate-limited public tRPC procedure |
tRPC procedure
The gmc.registrant entry is itself the query — there is no .lookup sub-procedure:
trpc.gmc.registrant.useQuery({ gmcNumber: '1234567' });Input (validated by fetchGmcRegistrantInputSchema):
{
gmcNumber: string; // must match /^\d+$/
}Response (GmcRegistrant):
{
source: 'gmc' | 'csv';
url: string;
name: string;
gmcReferenceNumber: string;
profession?: string;
licenceStatus?: string;
gender?: string;
registeredQualification?: string;
fullRegistrationDate?: string;
isConsultant?: boolean;
specialistRegisterEntries?: string[];
isOnGpRegister?: boolean;
suggestedUserType?: 'consultant' | 'gp' | 'trainee' | 'other' | null;
}The procedure uses rateLimitedSensitiveProcedure — 5 requests per minute per IP — to prevent enumeration of the public GMC register through PPP.
3. How the parser works
fetchGmcRegistrantDirect does a plain HTTPS GET to https://www.gmc-uk.org/registrants/{number} with:
Accept: text/html
User-Agent: Mozilla/5.0 (compatible; PPPBot/1.0)It then runs regex-based HTML extraction keyed on GMC's current class and tooltip identifiers:
| Field | Extracted by |
|---|---|
| Name | id="registrantNameId" |
| GMC reference number | id="gmcNumberId" |
| Licence status | data-simpletooltip-content-id="registration-status" |
| Profession | data-simpletooltip-content-id="profession-type" |
| Registered qualification | data-simpletooltip-content-id="primary-medical-qualification" |
| Full registration date | data-simpletooltip-content-id="full-registration-date" |
| Gender | Label-based extraction inside the details card |
| Specialist status description | data-simpletooltip-content-id="specialist-status-description" |
| Specialist register entries | <ul> following the specialist status section, each <li> parsed to specialty name by splitting on "from" |
| GP register status | data-simpletooltip-content-id="gp-status-description" |
The parser intentionally uses regexes rather than a full HTML parser so it is fast, dependency-free, and has predictable memory characteristics. It is brittle by design — we would rather break loudly when GMC changes their markup than silently return the wrong doctor.
Consultant detection
A doctor is classified as a consultant when the specialist status description is literally This doctor is on the Specialist Register. The classifier then captures the list of specialties (e.g. "General surgery"). For a Mohs surgeon or a paediatric surgeon, this list drives the specialist sub-classification.
GP register detection
A doctor is classified as on the GP register when the GP status description is This doctor is on the GP Register. A doctor can be both a consultant and on the GP register — the classifier handles this.
Validation against claimed status
The validateConsultantStatus helper takes a GMC registrant and a user's claimed status, and returns a discrepancy report when they disagree. This surfaces during admin profile review so a hospital admin can see when a doctor claims to be a consultant but does not appear on the Specialist Register.
4. User type classification
classifyGmcUserType maps the registrant shape to PPP's internal user-type taxonomy:
| Registrant shape | Suggested user type |
|---|---|
| Specialist Register + any specialty | consultant |
| GP Register (not on Specialist) | gp |
| Licensed, not on either register | trainee |
| No licence / erased / not found | other |
This suggestion is only ever a default — the user can override it during signup, and the admin can override it during profile review. Nothing in PPP is gated purely on the auto-classified type.
5. Configuration
Environment variables
The GMC lookup has no environment variables of its own. It uses globalThis.fetch with no credentials, since the GMC register is a public page.
However, rate limiting and observability are driven by the general backend configuration:
| Variable | Purpose |
|---|---|
RATE_LIMIT_SENSITIVE_REQUESTS_PER_MINUTE | Tunes the 5 rpm limit on the tRPC procedure |
Offline / mock mode
For local development without hitting the live GMC register, a small CSV fixture is shipped at mock_gmc_register.csv. It contains a handful of handcrafted registrants covering the main classification branches (consultant on specialist register, GP, trainee, erased licence). The CSV-backed path is used by tests and by some local development modes; in production the live scrape path is always used.
6. Failure modes
| Failure | User impact | Operator action |
|---|---|---|
| GMC page returns 404 | NOT_FOUND tRPC error; signup asks the user to check their number | None — expected for invalid numbers |
| GMC page returns 5xx | INTERNAL_SERVER_ERROR tRPC error; user can retry | Monitor GMC status; no direct fix |
| GMC markup changed | Parser returns empty fields → NOT_FOUND error | Update regexes in fetchGmcRegistrantDirect.ts; add contract test |
| GMC reference number mismatch | Parser detects gmcReferenceNumber !== requested and returns NOT_FOUND | None — self-healing safety check |
| Rate limited by PPP (>5 req/min/IP) | tRPC returns 429 | None — protecting against enumeration |
isNumericString fails | BAD_REQUEST with "GMC number must be numeric" | None — client-side validation catches this first |
Defensive checks
- Numeric input only — rejected early via
isNumericStringto prevent URL injection into the GMC base URL - URL encoding — the GMC number is passed through
encodeURIComponenteven though it's already numeric - Reference number cross-check — after parsing, the service re-compares the returned
gmcReferenceNumberagainst the requested number. If they disagree (which would be a catastrophic parser regression), the service throwsNOT_FOUNDrather than returning the wrong doctor. - Rate limit — 5 req/min per IP at the tRPC layer
7. Testing
Unit and integration tests
cd api/backend-ppp
pnpm test -- gmcRegistrant
pnpm test -- classifyUserType
pnpm test -- validateConsultantStatusThe test suite covers:
- Parser correctness — a large set of recorded HTML fixtures in
api/backend-ppp/src/__fixtures__/responses/gmc.tsandapi/backend-ppp/src/__fixtures__/handlers/gmc.tsthat mockfetchagainstgmc-uk.org - Consultant classification — Specialist Register entries parsed correctly, multiple specialties handled
- GP register detection — standalone GPs and consultant-GPs both resolved
- Erased / suspended licences — classified as
other - Edge cases — blank pages, missing tooltip elements, unusual whitespace
Live connectivity test
There is a requires-backend Vitest suite in api/backend-ppp/src/services/gmcRegistrantService/gmcConnectivity.integration.test.ts that hits the real GMC register in UAT to verify parser assumptions still hold. Run with:
cd api/backend-ppp
pnpm debug src/services/gmcRegistrantService/gmcConnectivity.integration.test.tsThis test should be run manually after any change to the parser regexes or whenever the monthly contract-test run flags a drift.
Contract tests
The api/backend-ppp/src/__fixtures__/external-services.contracts.test.ts suite exercises the full GMC scrape path against recorded fixtures and catches drift between the mock handlers and the shape expected by the service.
8. Observability
Every GMC fetch logs with module: 'gmcFetch'. Diagnose recent lookups with:
ContainerAppConsoleLogs_CL
| where Log_s contains "module=gmcFetch"
| project TimeGenerated, Log_s
| order by TimeGenerated desc
| take 200Metrics worth monitoring:
- Lookup success rate — percentage of non-400/404 responses that parse successfully
- Parser failure rate — lookups where the parser returns no name / no reference number (a leading indicator that GMC's markup changed)
- Rate-limit trips — if users are hitting the 5 rpm limit, it probably indicates scripted enumeration
- Response time — GMC is usually <500ms; anything over 2s is worth looking at
9. Cost and legal considerations
- No API cost — PPP makes plain HTTPS requests to a public register. GMC does not charge for access.
- No licensing fee — the content on a registrant page is published as a public good under UK transparency norms.
- Respectful scraping — PPP limits itself to 5 requests per minute per IP, identifies itself in the User-Agent string (
PPPBot/1.0), and only fetches pages the user explicitly requests by entering their own GMC number. There is no batch scraping, no cached copy of the register, and no background enumeration. - No commercial resale — PPP does not expose the GMC data to third parties or store it beyond what the user sees on their own profile.
If PPP scale grows and the current scrape starts putting meaningful load on GMC, the long-term plan is to reach out to GMC directly about a bulk agreement — but at current volumes this is unnecessary.
10. Related
- Integrations overview — the five external services PPP depends on
- Sign-up & Registration feature spec — where the GMC lookup surfaces in the signup flow
- Linked Sign-in Accounts feature spec — where a doctor's GMC number is verified during profile linking
api/backend-ppp/src/services/gmcRegistrantService/— the full service directory