Overview

A stateless REST API that takes a single convention-booth attendee and tries to identify them as a true Healthcare Professional (HCP) — returning degree and specialty when possible.

The upstream pipeline has two earlier identification stages: Level 1 matches against a pharma customer database (CDMI), and Level 2 attempts a direct NPI Registry exact match. This screener is Level 3 — the fallback when both upstream tiers fail.

What "HCP" means here

Any licensed clinician identifiable via degree (MD / DO / DDS / DMD / DPM / DPT / PharmD / DNP / OD) or credential string (RN / NP / PA / CNM / CRNA / RPh, etc.). NPI is a strong corroborating signal but not a hard requirement — research nurses, educators, and pharmacists in non-billing roles can be HCPs without being enumerated in NPPES.

Endpoint

POST https://nni-ma-hcp-screener.netlify.app/api/screen

Also reachable directly at POST /.netlify/functions/screen (the /api/screen path is a Netlify redirect).

Quickstart

Identify a single attendee with one HTTP call.

curl -X POST "https://nni-ma-hcp-screener.netlify.app/api/screen" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -d '{
        "firstName":      "Ilene",
        "lastName":       "Friedman",
        "state":          "NY",
        "city":           "Northport",
        "postalCode":     "11768",
        "specialty_hint": "Internal Medicine"
      }'

const res = await fetch('https://nni-ma-hcp-screener.netlify.app/api/screen', {
  method:  'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key':    'YOUR_API_KEY_HERE'
  },
  body: JSON.stringify({
    firstName:      'Ilene',
    lastName:       'Friedman',
    state:          'NY',
    city:           'Northport',
    postalCode:     '11768',
    specialty_hint: 'Internal Medicine'
  })
});
const data = await res.json();
console.log(data.match.status, data.match.confidence, data.match.npi);

import requests

resp = requests.post(
  "https://nni-ma-hcp-screener.netlify.app/api/screen",
  headers={
    "Content-Type": "application/json",
    "X-API-Key":    "YOUR_API_KEY_HERE",
  },
  json={
    "firstName":      "Ilene",
    "lastName":       "Friedman",
    "state":          "NY",
    "city":           "Northport",
    "postalCode":     "11768",
    "specialty_hint": "Internal Medicine",
  },
  timeout=30,
)
data = resp.json()
print(data["match"]["status"], data["match"]["confidence"], data["match"].get("npi"))

A successful response (HTTP 200) wraps the result in a small envelope:

{
  "ok": true,
  "match":      { "status": "matched", "confidence": 0.95, ... },
  "alternates": [ ... ],
  "tiers_run":  ["A"],
  "input_echo": { "firstName": "Ilene", "lastName": "Friedman", "state": "NY", "city": "Northport" }
}

Authentication

Every request must carry an X-API-Key header.

X-API-Key: 449ba0...e74650ebad948

Without the header (or with a wrong value) the function returns HTTP 401 with { "ok": false, "error": "Invalid or missing X-API-Key header." }.

The key is stored as the SCREENER_API_KEY env var on the Netlify site. To rotate: generate a new value, PUT it to the same env var via the Netlify API, redeploy, notify upstream.

Request schema

JSON body, application/json. Only first + last name are strictly required. The richer the input, the better the disambiguation.

Minimum vs. recommended input

Minimum: { "firstName": "...", "lastName": "..." } — works but low-confidence (no geo signals).

Recommended: First + Last + postalCode + state + city + organization (+ specialty_hint when known). For common names — and for non-HCPs at small specialized meetings with no badge data — organization is the single most valuable disambiguator.

Response schema

Every successful response shares a common envelope. Status-specific fields nest under match.

{
  "ok": true,
  "match": {
    "status":     "matched" | "inconclusive" | "not_hcp" | "unknown",
    "confidence": 0.0 - 1.0,
    "source":     "npi_direct" | "npi_fuzzy" | "npi_fuzzy_spell_corrected" | "tier_b_web_search",
    "tier":       "A" | "B",
    // ... status-specific fields below ...
    "match_reasoning": "human-readable string explaining why this disposition"
  },
  "alternates": [ /* up to 4 runner-up matches */ ],
  "tiers_run":  ["A"] | ["A", "B"] | ["A", "B", "A-retry"],
  "input_echo": { "firstName": "...", "lastName": "...", "state": "...", "city": "..." }
}

Source values

Match-object field reference

Status values

• matched — a single identity meets the confidence threshold. Cases 0, 1, 3, 3b, and 4 produce this.
• inconclusive — a top candidate exists but its score is below the 0.65 match threshold. alternates are returned for human review.
• not_hcp — Tier B found clear non-clinical role signals (Sales, Marketing, Realtor, etc.). NPI hits, if any, appear to be different individuals.
• unknown — nothing found in either tier. raw_hits from Tier B (if any) are returned for adjudication.

The 6 disposition cases

The function evaluates branches in order. The first that matches wins.

{
  "ok": true,
  "match": {
    "status":     "matched",
    "confidence": 0.95,
    "source":     "npi_direct",
    "tier":       "A",
    "npi":        "1992894257",
    "name_prefix":"DR.",
    "firstName":  "ILENE", "middleName": "LAUREN", "lastName": "FRIEDMAN",
    "credential": "M.D.",
    "gender":     "F",
    "job_title":       "Internal Medicine, M.D.",
    "job_description": "Internal Medicine",
    "primary_taxonomy": {
      "code":         "207R00000X",
      "name":         "Internal Medicine",
      "license":      "198905",
      "license_state":"NY"
    },
    "secondary_taxonomies": [],
    "practice_address": {
      "street":    "79 MIDDLEVILLE RD",
      "street_2":  null,
      "city":      "NORTHPORT",
      "state":     "NY",
      "zip":       "11768",
      "phone":     "631-261-0050",
      "fax":       "631-754-3017",
      "formatted": "79 MIDDLEVILLE RD, NORTHPORT, NY 11768"
    },
    "mailing_address":               null,
    "additional_practice_locations": [],
    "place_of_employment": {            // present only when Tier B inferred one
      "name":         "Huntington Hospital",
      "source":       "tier_b_web_inference",
      "evidence_url": "https://www.huntingtonhospital.org/..."
    },
    "job_title_inferred": null,         // populated when LinkedIn-style "Title - Org" pattern hits
    "enumerated_since":   "2006-10-12",
    "last_updated":       "2024-08-15",
    "match_signals":      ["state_match", "city_match", "zip_match", "specialty_match"],
    "match_reasoning":    "Tier A match via variant \"exact:Ilene Friedman/NY\". Signals: state_match, city_match, zip_match, specialty_match."
  },
  "alternates": [],
  "tiers_run":  ["A", "B"]
}

{
  "ok": true,
  "match": {
    "status":     "matched",
    "confidence": 0.75,
    "source":     "npi_direct" | "npi_fuzzy",
    "tier":       "A",
    /* full NPI record fields */
    "tier_b_evidence": [ /* up to 3 corroborating web hits */ ],
    "match_reasoning": "Tier A direct match (0.75); Tier B corroborates HCP via web hits (degree=MD)."
  },
  "alternates": [ ... ],
  "tiers_run":  ["A", "B"]
}

{
  "ok": true,
  "match": {
    "status":     "not_hcp",
    "confidence": 0.6,
    "source":     "tier_b_web_search",
    "tier":       "B",
    "tier_a_hits": 1,
    "flags":      ["ROLE_NON_CLINICAL"],
    "match_reasoning": "Tier B found 1 non-clinical role signal(s) in web hits. Tier A NPI hits (1) appear to be different individuals; geographic or context mismatch."
  },
  "alternates": [],
  "tiers_run":  ["A", "B"]
}

{
  "ok": true,
  "match": {
    "status":     "matched",
    "confidence": 0.78,
    "source":     "tier_b_web_search",
    "tier":       "B",
    "npi":        null,
    "firstName":  "...", "lastName": "...",
    "credential": "RN" | "PA" | "MD" | "...",
    "degree":     "RN" | "PA" | "MD" | "...",
    "tier_b_evidence": [ ... ],
    "flags":      ["NOT_IN_NPI_REGISTRY"],
    "match_reasoning": "Tier A could not place this name confidently in NPI Registry (top score 0.40). Tier B web hits show clear clinical degree/credential signal — likely an HCP not enumerated in NPI."
  },
  "alternates": [],
  "tiers_run":  ["A", "B"]
}

{
  "ok": true,
  "match": {
    "status":     "matched",
    "confidence": 0.78,
    "source":     "npi_fuzzy_spell_corrected",
    "tier":       "A",
    /* full NPI record from the corrected query */
    "spell_corrected": { "from": "Moscaritols", "to": "Moscarito" },
    "match_reasoning": "Input lastName \"Moscaritols\" appears to be a typo. Tier B web search surfaced \"Moscarito\" as a likely correction; Tier A re-run with the corrected spelling produced a confident NPI match."
  },
  "tiers_run": ["A", "B", "A-retry"]
}

{
  "match": {
    "status":     "matched",
    "confidence": 0.65,
    "source":     "npi_direct",
    "tier":       "A",
    /* full NPI record */
    "match_reasoning": "Tier A direct match at medium confidence (0.65). Tier B did not corroborate."
  }
}

{
  "match": {
    "status":     "inconclusive",
    "confidence": 0.45,
    "tier":       "A",
    "match_reasoning": "Tier A produced a candidate at score 0.45 (below the 0.65 match threshold). Tier B did not provide a clear signal."
  },
  "alternates": [ ... ],
  "raw_hits":   [ ... ]
}

{
  "match": {
    "status":      "unknown",
    "confidence":  0,
    "tiers_tried": ["A", "B"],
    "variants_tried": [ "exact:Foo Bar/NY", "variant:Foo Baz/NY", ... ],
    "match_reasoning": "No matches in Tier A (NPI Registry, 7 variants tried). Tier B returned 0 hits, none with clear HCP credential signal."
  },
  "alternates": [],
  "raw_hits":   []
}

Tier A — NPI Registry cascade

A 5-pass progressive expansion against NPPES (the public CMS API at npiregistry.cms.hhs.gov). Free, no auth.

Name normalization (pre-cascade)

• Diacritic strip — José → Jose, Müller → Muller via NFD + combining-mark removal.
• Whitespace collapse + trim — runs of spaces become single spaces; leading/trailing punctuation stripped.
• Suffix & credential stripping — trailing tokens matching the suffix/credential vocab are removed before lookup:
  • Suffixes: jr, sr, ii, iii, iv, v
  • Degrees: md, do, dds, dmd, dpm, dpt, pharmd, dnp, phd, dvm, od
  • Credentials: rn, aprn, crna, cnm, np, pa-c, pa, rph, rrt, rdn, lcsw, msw
  • Academic: mba, msc, ms, ma, ba, bsn, msn, dnsc, edd, jd
  • Fellowships: facs, facp, fasco, faan, faonl, nea-bc, ne-bc, ahn-bc, ccrn, cphq
  Dotted forms (M.D.) are normalized first by stripping periods.

Nickname expansion

A bidirectional table of ~110 canonical names with their common nicknames. The lookup walks both directions — input "Bob" expands to {Bob, Robert, Bobby, Robbie, Bert}; input "Robert" expands to the same set. Both male and female forms covered.

Last-name variants

Hyphenated last names fan out:

"Smith-Jones" → ["Smith-Jones", "Smith Jones", "Smith", "Jones"]

Each variant is tried as a separate NPPES query (NPPES wildcard-suffixes every query automatically — see "wildcard trick" below).

NPPES wildcard trick

The 5-pass cascade

Tier B — Web search + classifier

Provider-agnostic search layer (Brave / Serper / Google CSE). Used to corroborate Tier A medium-confidence matches and to identify HCPs that aren't in NPPES.

Provider selection

Driven by two env vars on the Netlify site:

WEB_SEARCH_PROVIDER = "serper" | "brave" | "google_cse"
WEB_SEARCH_API_KEY  = "..."
GOOGLE_CSE_ID       = "..."   // only for google_cse

If neither is set, Tier B returns { available: false, reason: "..." } and the function falls through to a Tier-A-only response.

Currently configured: Serper.dev (paid plan, 50k queries/month).

The 5 queries Tier B fires per attendee

1. Tightest: "<First Last>" "<City>" <ST> — name + quoted city + state. Catches local non-clinical context too (deliberately broad to detect "not_hcp").
2. Name + city + clinical-role terms: "<First Last>" "<City>" <ST> doctor physician nurse pharmacist
3. Name + employer + specialty: "<First Last>" <employer> <specialty> (only if those fields were provided)
4. LinkedIn fallback: "<First Last>" "<City>" linkedin
5. Typo tolerance: <First Last> <ST> doctor physician nurse pharmacist — unquoted, lets Google auto-spell-correct.

Queries are deduplicated and any whose body is essentially just the name are dropped. The provider returns up to 5 hits per query.

Classifier — classifyHits()

Up to the first 15 aggregated hits are inspected. For each, the title + snippet are scanned for three regex patterns:

Positive degree pattern

/\b(MD|D\.O\.|DO|DDS|DMD|DPM|DPT|PharmD|DNP|PhD|DVM|OD)\b/

Positive credential pattern

/\b(RN|APRN|CRNA|CNM|NP|PA-C|PA|RPh|RRT|RDN|NEA-BC|FAAN|FACS|FACP)\b/

Negative-role pattern

/\b(VP|Vice President|CEO|CFO|COO|Founder|Investor|Sales|Marketing|
       Realtor|Real Estate|Attorney|Lawyer|Tenant|Tenants Association|
       Activist|Politician|Councilman|Mayor)\b/i

Name verification — Levenshtein, both names required

Every positive hit must have both the input firstName and lastName fuzzy-matched to tokens in the snippet via Levenshtein distance. This was added 2026-05-18 after two false-positive incidents:

• "Kevin Weller / Jersey City NJ" — was matching a snippet about "Kevin John Weller, APRN" in New Hampshire (different state).
• "Joyce Moscaritols" (typo) — was matching "Dr. Michael Joyce, MD" because the input firstName "Joyce" appeared as someone else's last name.

Distance threshold per token: min(3, max(1, ceil(needle.length × 0.30))). So a 6-letter name allows up to 2 edits; a 10-letter name allows up to 3.

Geographic alignment

Each name-verified credential snippet is tagged:

• aligned — the input state code OR full state name appears in the snippet, OR the input city appears in the snippet
• mismatched — state codes appear in the snippet, but none match the input state
• unknown — no state info detected

State-code matching uses comma/space context ("City, ST" patterns) to avoid false positives like "MS Excel."

Decision logic

if (neg > 0 && name_matched_aligned === 0)        → isHCP: false
else if (name_matched_aligned ≥ 1)                  → isHCP: true
else if (name_matched_count ≥ 2 && no mismatch
                            && no negatives)        → isHCP: true
else                                                → isHCP: false

The classifier also returns a spell_corrected_last_name field whenever the name-verified last-name match has distance > 0 — i.e., the snippet's lastName isn't identical to the input's. This is what triggers the Case 3b retry.

LLM enrichment layer (added v0.3.0)

After Tier A + Tier B settle on a disposition, a single live LLM call enriches the result with two judgment fields: position_function and call_recommendation. Runs on every disposition — including not_hcp and unknown — because the call recommendation is most useful for non-HCPs.

What it produces

• highest_education — highest level of education / terminal degree. Deterministic from a clear NPPES credential (M.D., PharmD, DNP, Ph.D., …); otherwise inferred from web evidence (e.g. "Dean of the School of Medicine" → a doctorate). null only when there's no signal.
• position_function — a 1–2 sentence plain-language explanation of what the identified position/specialty/credential typically does (core role & responsibility), for a non-clinical reader. null when no position was identified.
• call_recommendation — { should_call, category, rationale, confidence }. Confirmed HCPs return should_call: true, category: "HCP". For non-HCPs, the model judges from the web evidence whether the person is still a valuable medical-affairs contact in the diabetes/obesity/cardiometabolic space — a professor of medicine, dean / department chair, KOL / thought leader, podcaster / online influencer, P&T or formulary committee member, professional-association member, patient-advocacy NGO/non-profit member, researcher/academic, or payer/managed-care. A current Novo Nordisk / NNI employee returns category: "Internal/Own-Company" (own-company colleague, not an outreach target). Clearly unrelated roles or namesakes return should_call: false, category: "Not Recommended".
• social_profiles — an array of the person's reliably-attributed digital profiles: [{ platform, url, handle, followers, reliable, basis }]. Only profiles corroborated to this person (by name + employer/location/specialty) are included; likely namesakes are excluded. followers is populated only when a snippet states it.
• dol — Digital Opinion Leader assessment: { is_dol, tier, topics, rationale, confidence } where tier ∈ none | emerging | established | leading. Grades digital influence in the diabetes/obesity/cardiometabolic space from the reliable profiles + evidence (audience size, posting cadence, podcast/video hosting, conference presence). A plain profile with no influence signal stays tier: "none".
• identity_ids — resolved cross-reference ids { cdm_id, ims_id, npi_id } from the OSP identity service (looked up by last name + first name + ZIP). Any field may be null. The npi_id here independently corroborates the Tier-A NPI match.
• prescribing_data — IQVIA-style prescribing for NNI cardiometabolic products, fetched by ims_id: { source, ims_id, total_trx, total_nbrx, prescribed[], products[] }. Any cardiometabolic prescribing (total_trx > 0) is treated by the recommendation gate as a direct in-scope tie — so a clinician in an adjacent specialty who actually prescribes (e.g. a neurologist on Ozempic) is recommended, while a zero-TRx result is affirmative evidence of non-relevance.

Specialty-relevance gate: a confirmed HCP is only should_call: true when their specialty is core to NNI's diabetes/obesity/cardiometabolic focus (endocrinology, primary care, cardiology, nephrology, obesity medicine) OR there is specific evidence of a cardiometabolic tie — prescribing data, or a documented sub-focus (e.g. diabetic neuropathy). HCPs in unrelated specialties return should_call: false with a potential_relevance note describing what would make them relevant. A current Novo Nordisk / NNI employee returns category: "Internal/Own-Company".

Configuration

Driven by env vars on the Netlify site:

LLM_PROVIDER   = "anthropic" | "openai"      // default: anthropic
LLM_API_KEY    = "..."                        // provider API key
LLM_MODEL      = "claude-haiku-4-5-20251001"  // default per provider
LLM_TIMEOUT_MS = "6000"                        // optional per-call timeout

Graceful degradation: if LLM_API_KEY is unset, or the call fails / times out / returns unparseable output, both fields come back null with a reason in their *_source field. The screening result is never blocked on the LLM. The call is also skipped (no spend) when there is no position and no web signal to reason about.

Identical prompts are de-duplicated by an ephemeral per-container memo (saves tokens during batch runs); this is process memory only, not persistence — the stateless guarantee holds.

Spell-correction retry (Case 3b)

The deepest sequential branch in the pipeline — tiers_run: ["A", "B", "A-retry"].

When Tier B's classifier emits a spell_corrected_last_name that differs from the input's lastName (case-insensitive), the function:

1. Builds correctedInput = { ...input, lastName: spell_corrected_last_name }
2. Calls tierA_npiFuzzy(correctedInput) — a fresh 5-pass NPPES cascade with the corrected name
3. If the retry's top candidate scores ≥ 0.65, returns the corrected match with source: "npi_fuzzy_spell_corrected" and a spell_corrected: { from, to } field
4. Otherwise falls through to Cases 1–6 with original input

Scoring & confidence

Every NPI candidate gets a score in [0, 1]. The base is 0.5 (caller already filtered by name); signals add or subtract.

Signal weights

Final score is clamped to [0, 1].

Disposition thresholds

Full pipeline

The complete sequence of branches from input to response.

Maximum external HTTP calls per screening

HTTP status codes

Stateless guarantee

No persistence anywhere. Each request is independent.

This is an explicit project decision dated 2026-05-18. No database, no call logs, no audit trail. The function code has no fs.writeFile, no Supabase client, no logging service. The only writes the function performs are the response body itself.

Try it live

Fire a real screening from this page. Uses the same API key your main app does (stored in this browser's localStorage).