Skip to content

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 ​

FeatureHow it uses the GMC lookup
SignupPre-fills the user's name and profession; suggests user type (consultant/GP/trainee)
Profile completion promptVerifies the user's entered GMC number belongs to a real, licensed registrant
Admin verification workflowsSurfaces licence status changes during profile review
360 peer reviewLets 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 ​

FilePurpose
api/backend-ppp/src/services/gmcRegistrantService/fetchGmcRegistrantDirect.tsFetches + parses the GMC public registrant HTML page
api/backend-ppp/src/services/gmcRegistrantService/fetchGmcRegistrant.tsWraps the direct fetch and adds user-type classification
api/backend-ppp/src/services/gmcRegistrantService/validateConsultantStatus.tsCross-checks claimed consultant status against the register
api/backend-ppp/src/services/gmcRegistrantService/mock_gmc_register.csvOffline-mode CSV for development without hitting GMC
api/backend-ppp/src/services/userTypeClassification/classifyUserType.tsClassifies consultant / gp / trainee / other from registrant data
api/backend-ppp/src/routers/procedures/gmc/registrant/publicIndex.tsRate-limited public tRPC procedure

tRPC procedure ​

The gmc.registrant entry is itself the query — there is no .lookup sub-procedure:

ts
trpc.gmc.registrant.useQuery({ gmcNumber: '1234567' });

Input (validated by fetchGmcRegistrantInputSchema):

ts
{
  gmcNumber: string; // must match /^\d+$/
}

Response (GmcRegistrant):

ts
{
  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:

FieldExtracted by
Nameid="registrantNameId"
GMC reference numberid="gmcNumberId"
Licence statusdata-simpletooltip-content-id="registration-status"
Professiondata-simpletooltip-content-id="profession-type"
Registered qualificationdata-simpletooltip-content-id="primary-medical-qualification"
Full registration datedata-simpletooltip-content-id="full-registration-date"
GenderLabel-based extraction inside the details card
Specialist status descriptiondata-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 statusdata-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 shapeSuggested user type
Specialist Register + any specialtyconsultant
GP Register (not on Specialist)gp
Licensed, not on either registertrainee
No licence / erased / not foundother

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:

VariablePurpose
RATE_LIMIT_SENSITIVE_REQUESTS_PER_MINUTETunes 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 ​

FailureUser impactOperator action
GMC page returns 404NOT_FOUND tRPC error; signup asks the user to check their numberNone — expected for invalid numbers
GMC page returns 5xxINTERNAL_SERVER_ERROR tRPC error; user can retryMonitor GMC status; no direct fix
GMC markup changedParser returns empty fields → NOT_FOUND errorUpdate regexes in fetchGmcRegistrantDirect.ts; add contract test
GMC reference number mismatchParser detects gmcReferenceNumber !== requested and returns NOT_FOUNDNone — self-healing safety check
Rate limited by PPP (>5 req/min/IP)tRPC returns 429None — protecting against enumeration
isNumericString failsBAD_REQUEST with "GMC number must be numeric"None — client-side validation catches this first

Defensive checks ​

  1. Numeric input only — rejected early via isNumericString to prevent URL injection into the GMC base URL
  2. URL encoding — the GMC number is passed through encodeURIComponent even though it's already numeric
  3. Reference number cross-check — after parsing, the service re-compares the returned gmcReferenceNumber against the requested number. If they disagree (which would be a catastrophic parser regression), the service throws NOT_FOUND rather than returning the wrong doctor.
  4. Rate limit — 5 req/min per IP at the tRPC layer

7. Testing ​

Unit and integration tests ​

bash
cd api/backend-ppp
pnpm test -- gmcRegistrant
pnpm test -- classifyUserType
pnpm test -- validateConsultantStatus

The test suite covers:

  • Parser correctness — a large set of recorded HTML fixtures in api/backend-ppp/src/__fixtures__/responses/gmc.ts and api/backend-ppp/src/__fixtures__/handlers/gmc.ts that mock fetch against gmc-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:

bash
cd api/backend-ppp
pnpm debug src/services/gmcRegistrantService/gmcConnectivity.integration.test.ts

This 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:

kql
ContainerAppConsoleLogs_CL
| where Log_s contains "module=gmcFetch"
| project TimeGenerated, Log_s
| order by TimeGenerated desc
| take 200

Metrics 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
  • 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.

Internal documentation — org members only