{"openapi":"3.1.0","info":{"title":"StatuteWire API","version":"1.0.0","description":"Practitioner license verification against official state sources (live states are listed on 422 responses; other states return sample data to sandbox keys), SHA-256 evidence receipts, federal exclusion screening, and continuous monitoring. Subscription keys have a monthly request quota per plan (1,000 (Exclusions), 5,000 (Growth) or 10,000 (Enterprise) API requests per month; calendar months, UTC). Monthly roster screening does not count against it. A lookup is 1 unit, an audit pack 1, and a roster upload 1 per newly enrolled license (all or nothing). At the limit requests are refused with HTTP 402 code QUOTA_EXHAUSTED until the 1st; nothing is charged extra. Built to support credentialing reviews such as NCQA CR-3; StatuteWire does not certify NCQA compliance. Sandbox (sw_test_) keys are free and self-serve at https://statutewire.com/developers/sandbox: sample data for every state, labelled SIMULATED_FIXTURE, never a real verification, never charged.","contact":{"name":"StatuteWire Engineering"}},"servers":[{"url":"https://statutewire.com","description":"Production"},{"url":"http://localhost:3000","description":"Local Development Server"}],"security":[{"BearerAuth":[]}],"paths":{"/api/v1/sanctions":{"get":{"operationId":"verifyPractitionerSanctions","summary":"Primary-Source Verification & Sanctions Screening","description":"Returns deterministic real-time licensure standing, CMS NPI identity verification, disciplinary risk flags, and SHA-256 hashed PDF audit receipts. Identity before data: the board record is returned only when its first and last name match CMS NPPES (sandbox sample NPIs: their sample identity) after normalising case, accents, punctuation, hyphens/spaces and suffixes, ignoring middle names. A mismatch or missing data is a 422 with both names; the board record is not returned, stored, or added to the roster, and a prepaid charge is refunded.","security":[{"BearerAuth":[]}],"parameters":[{"name":"npi","in":"query","required":true,"description":"10-digit National Provider Identifier","schema":{"type":"string","pattern":"^[0-9]{10}$"}},{"name":"state","in":"query","required":true,"description":"Two-letter US state postal abbreviation, or eNLC for the nurse licensure compact (case-insensitive)","schema":{"type":"string","minLength":2,"maxLength":4}},{"name":"license_number","in":"query","required":false,"description":"Restrict the cached-record match to this license (case-insensitive) and pass it to the board lookup","schema":{"type":"string","pattern":"^[A-Za-z0-9.\\-]{1,40}$"}},{"name":"first_name","in":"query","required":false,"description":"RECOMMENDED, with last_name. When both are sent, they are compared with the identity on record (CMS NPPES; sandbox sample NPIs: the sample identity) BEFORE anything is charged or counted: a mismatch is a 422 with code IDENTITY_MISMATCH, no provider data, and no quota or prepaid charge. If the identity cannot be resolved the request fails closed (503/422), also uncharged. Omit both and behavior is unchanged: the lookup is charged, then the board record is checked against NPPES.","schema":{"type":"string","maxLength":100}},{"name":"last_name","in":"query","required":false,"description":"RECOMMENDED, with first_name (sending only one is a 400). See first_name.","schema":{"type":"string","maxLength":100}},{"name":"fresh","in":"query","required":false,"description":"true forces a primary-source sweep. Cached records older than 120 days are always re-swept.","schema":{"type":"boolean","default":false}},{"name":"profession","in":"query","required":false,"description":"Profession filter passed to the board lookup on a fresh sweep (e.g. MD, RN, NP)","schema":{"type":"string"}}],"responses":{"200":{"description":"One license record: from cache if verified within 120 days, otherwise from a fresh sweep","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SanctionsResponse"}}}},"400":{"description":"Invalid NPI; license_number missing for a live state; or license_number not in that state's format (the problem detail shows the expected format)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Invalid or missing Bearer token"},"402":{"description":"Subscription keys: monthly quota exhausted (code QUOTA_EXHAUSTED, quota_resets_at; nothing is charged extra). Prepaid keys: code INSUFFICIENT_CREDITS, with balance_checks, required_checks and top_up instructions; the request was not charged.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredProblem"}}}},"404":{"description":"The board source returned no record for this NPI (live states: no license with this license_number)"},"409":{"description":"CT only: a bare license number belongs to more than one kind of credential; use the full credential code or pass profession"},"422":{"description":"state missing or unknown; or (live keys) the state is not yet verified against live official records (the problem detail lists the live states; sandbox keys receive sample data for every state); or the identity check blocked the result: identity_verification_status MISMATCH (board name differs from the reference identity; both names shown) or INSUFFICIENT_DATA (NPI not in NPPES, an organization NPI, or a name missing or only an initial).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/IdentityBlockedProblem"}}}},"429":{"description":"Rate limit exceeded (Retry-After header)"},"502":{"description":"Board connector error"},"503":{"description":"Metering unavailable; the state source is rate-limiting (Retry-After); or CMS NPPES unreachable (identity_verification_status INSUFFICIENT_DATA, reason NPPES_UNAVAILABLE, Retry-After). Verification withheld.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/IdentityBlockedProblem"}}}}}}},"/api/v1/practitioners/{npi}/history":{"get":{"operationId":"getPractitionerAuditHistory","summary":"Retrieve a practitioner's chronological audit timeline","description":"Returns the complete immutable ledger of state board changes, past status transitions, risk evaluations, and historical verification PDF audit receipts.","security":[{"BearerAuth":[]}],"parameters":[{"name":"npi","in":"path","required":true,"description":"10-digit National Provider Identifier","schema":{"type":"string","pattern":"^[0-9]{10}$"}}],"responses":{"200":{"description":"Immutable chronological audit events trail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditHistoryResponse"}}}},"400":{"description":"Malformed 10-digit NPI"},"401":{"description":"Unauthorized"},"404":{"description":"Practitioner not found"}}}},"/api/v1/batches":{"post":{"operationId":"submitBulkRosterBatch","summary":"Bulk Roster Ingestion & Asynchronous Deduplication","description":"Enqueues bounded batches of practitioner credentials for verification with deduplication and backpressure limits. Billing, same as POST /api/v1/rosters/bulk: licenses already monitored on this account are free. Subscription keys use one quota unit per newly enrolled license, all or nothing (402 QUOTA_EXHAUSTED if fewer remain; nothing is enrolled). Prepaid keys pay 1 check per newly enrolled license from the prepaid balance and use no quota units (402 INSUFFICIENT_CREDITS if the balance cannot cover them; nothing is enrolled and nothing is debited; a charge is refunded if the upload then fails). Sandbox keys are never charged.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":5000,"items":{"type":"object","required":["npi","state","licenseNumber"],"properties":{"npi":{"type":"string","pattern":"^[0-9]{10}$"},"state":{"type":"string","minLength":2,"maxLength":2},"licenseNumber":{"type":"string"},"professionType":{"type":"string","description":"Defaults to MD"},"firstName":{"type":"string","description":"Optional; a stored name is kept when omitted"},"lastName":{"type":"string","description":"Optional; a stored name is kept when omitted"}}}}}}}}},"responses":{"200":{"description":"Batch processed synchronously (status COMPLETED) with per-item errors"},"202":{"description":"Batch accepted and still PROCESSING; poll check_status_url"},"400":{"description":"Invalid schema or batch exceeds limits"},"401":{"description":"Missing, invalid, inactive, or revoked credential"},"402":{"description":"Subscription keys: monthly quota exhausted (code QUOTA_EXHAUSTED, quota_resets_at; one unit per newly enrolled license, refused whole). Prepaid keys: code INSUFFICIENT_CREDITS (1 check per newly enrolled license; nothing enrolled, nothing debited)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredProblem"}}}},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/rosters/bulk":{"post":{"operationId":"uploadRoster","summary":"Bulk roster upload with NPPES auto-discovery","description":"Enrolls up to 5,000 entries in monitoring. Entries with state and license_number are enrolled now; entries with only an NPI (optionally a state) are looked up in CMS NPPES in the background and their self-reported licenses enrolled (discipline from the NUCC taxonomy code). Enrolled licenses are verified against the primary source on the next monitoring pass. Re-uploading the same roster is safe: enrolled licenses count as duplicates. Subscription keys use one quota unit per newly enrolled license, all or nothing (402 QUOTA_EXHAUSTED if fewer remain; nothing is enrolled); prepaid keys pay 1 check per newly enrolled license (402 INSUFFICIENT_CREDITS if the balance cannot cover them; nothing is enrolled) and must have deposited $250.00 in total (enterprise floor; 402 ENTERPRISE_FLOOR_REQUIRED below it). Sandbox keys are never charged.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","maxItems":5000,"items":{"type":"object","required":["npi"],"properties":{"npi":{"type":"string","pattern":"^[0-9]{10}$"},"state":{"type":"string","pattern":"^[A-Za-z]{2}$"},"licenseNumber":{"type":"string","description":"Requires state. Omit to discover licenses from NPPES."},"professionType":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"}}}}},"text/csv":{"schema":{"type":"string","description":"Header row with npi and optionally state, license_number, profession, first_name, last_name"}}}},"responses":{"200":{"description":"Every entry processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RosterBulkSummary"}}}},"202":{"description":"Explicit entries processed; NPI-only entries pending NPPES discovery (poll check_status_url)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RosterBulkSummary"}}}},"400":{"description":"Malformed JSON or CSV, or an empty roster","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Missing, invalid, inactive, or revoked credential"},"402":{"description":"Subscription quota exhausted (code QUOTA_EXHAUSTED), prepaid balance below the cost of the new licenses (INSUFFICIENT_CREDITS), or prepaid deposits below the $250.00 enterprise floor (ENTERPRISE_FLOOR_REQUIRED)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredProblem"}}}},"413":{"description":"More than 5,000 entries or more than 2 MB"},"415":{"description":"Content-Type is not application/json or text/csv"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/batches/{batchId}":{"get":{"operationId":"getBatchStatus","summary":"Bulk Ingestion Batch Status & Progress","security":[{"BearerAuth":[]}],"parameters":[{"name":"batchId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Batch progress: total_records, processed_records, successful_records, failed_records, duplicates_skipped, pending_discovery (NPI-only entries not yet resolved), licenses_enrolled, errors. COMPLETED when nothing is pending."},"401":{"description":"Missing, invalid, inactive, or revoked credential"},"404":{"description":"Batch not found or owned by another tenant"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/receipts/{filename}":{"get":{"operationId":"getAuditReceiptArtifact","summary":"Download Immutable SHA-256 Cryptographic Verification Receipt","security":[{"BearerAuth":[]}],"parameters":[{"name":"filename","in":"path","required":true,"description":"Receipt filename matching canonical sha256.pdf pattern","schema":{"type":"string","pattern":"^[a-f0-9]{64}\\.pdf$"}}],"responses":{"200":{"description":"Raw PDF verification document","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid receipt identifier format"},"404":{"description":"Artifact not found"},"429":{"description":"Receipt download rate limit exceeded (30 / 120 / 600 per minute by tier)"}}}},"/api/v1/audit-pack/batch":{"post":{"operationId":"exportAuditBundle","summary":"Export audit packs as one sealed PDF bundle","description":"Up to 500 licenses, given as { batch_id } (licenses recorded for a roster upload) or an array of { npi, state, license_number }. Each license must be on this account's roster, verified against its primary source, and have a stored receipt whose SHA-256 still matches; others are listed in `skipped` and not charged. Generated packs cost 5 checks each for prepaid keys (one charge) or one quota unit each for subscription keys; sandbox keys get sample bundles free. The PDF embeds every board receipt and a manifest.json whose canonical bytes are SHA-256 hashed and Ed25519-signed (see /api/v1/audit-pack/signing-key). Each pack shows its computed compliance status; the bundle does not certify NCQA compliance.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["batch_id"],"properties":{"batch_id":{"type":"string","format":"uuid"}}},{"type":"array","minItems":1,"maxItems":500,"items":{"type":"object","required":["npi","state","license_number"],"properties":{"npi":{"type":"string","pattern":"^[0-9]{10}$"},"state":{"type":"string"},"license_number":{"type":"string"}}}}]}}}},"responses":{"200":{"description":"Bundle sealed and stored; download_url expires in 15 minutes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditBundleResponse"}}}},"400":{"description":"Malformed body or invalid items (problem body lists `errors`); nothing exported","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Invalid or missing Bearer token"},"402":{"description":"Subscription quota cannot cover the packs, or prepaid balance below 5 checks per pack (INSUFFICIENT_CREDITS)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredProblem"}}}},"404":{"description":"batch_id not found on this account"},"409":{"description":"The batch predates batch license tracking; send the licenses as an array"},"413":{"description":"More than 500 licenses"},"422":{"description":"No requested license can be exported yet (problem body lists `skipped`); nothing charged"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/rosters/{rosterId}/receipts/{period}":{"get":{"operationId":"getRosterReceipt","summary":"Signed monthly exclusion-screening receipt for one roster","description":"The evidence receipt of the latest COMPLETE stored screening run of your roster in the month (YYYY-MM): every source once (list date and its basis, SHA-256, live or not live) and one line per name with the outcome per source, including sources that were NOT checked. Format statutewire-roster-receipt/2: lines for people and businesses without an NPI say \"identity: name only (no NPI)\", and each line shows its review (or UNREVIEWED) beside the unchanged screened outcome; version 1 receipts still verify. Canonical JSON signed with Ed25519; `?format=pdf` returns a PDF of the same facts with the signed JSON attached. Verify with scripts/verify_receipt.ts and the public key at /.well-known/statutewire-receipt-key.pem. Free: it summarises checks already paid for. 404 when your roster has no completed run in that month. Outside production the receipt is UNSIGNED and says so.","parameters":[{"name":"rosterId","in":"path","required":true,"schema":{"type":"string"},"description":"Your roster id (your tenant id for now)."},{"name":"period","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{4}-(0[1-9]|1[0-2])$"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","pdf"],"default":"json"}}],"responses":{"200":{"description":"Receipt JSON (signed_facts_canonical, facts_sha256, signature) or PDF","content":{"application/json":{"schema":{"type":"object"}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Malformed roster id, period or format"},"401":{"description":"Missing or invalid API key"},"404":{"description":"No completed run for this roster in that period (also another account's roster)"},"429":{"description":"Rate limit exceeded"},"503":{"description":"The run could not be read; no receipt was produced"}}}},"/api/v1/rosters/{rosterId}/members":{"post":{"operationId":"addRosterMembers","summary":"Add people or businesses without an NPI to your roster (name-only screening)","description":"Adds 1 to 500 members (all or none) that are screened monthly by NAME ONLY against OIG LEIE, SAM.gov and the live state lists: front desk, aides, contractors, vendor businesses. Body: { members: [{ kind: PERSON, first_name, middle_name?, last_name, state?, external_ref? } | { kind: ENTITY, entity_name, state?, external_ref? }] }. A name hit is a POSSIBLE_MATCH that needs review, never a confirmed exclusion; no hit on every live source is NO_FINDINGS with the source list. No date of birth, SSN, address or other PHI: a field or value that looks like one is a 422 and nothing is stored. No NPI field (practitioners with an NPI use POST /api/v1/rosters/bulk). A duplicate (same normalised name, state and external_ref as an active member) is a 409. Free: rate limited, not metered. Owner only.","parameters":[{"name":"rosterId","in":"path","required":true,"schema":{"type":"string"},"description":"Your roster id (your tenant id for now)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["members"],"properties":{"members":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"object"}}}}}}},"responses":{"201":{"description":"Members added"},"400":{"description":"Malformed JSON, roster id or fields"},"401":{"description":"Missing or invalid API key"},"404":{"description":"Not your roster"},"409":{"description":"A member is already on the roster (code DUPLICATE_MEMBER); nothing was added"},"413":{"description":"More than 500 members"},"422":{"description":"A field or value looks like PHI (SSN, date of birth, address), or a row is invalid (row_errors); nothing was stored"},"429":{"description":"Rate limit exceeded"},"503":{"description":"The members could not be saved"}}},"get":{"operationId":"listRosterMembers","summary":"List the members of your roster that have no NPI","parameters":[{"name":"rosterId","in":"path","required":true,"schema":{"type":"string"}},{"name":"include_removed","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":500}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Members and has_more"},"400":{"description":"Bad parameter"},"401":{"description":"Missing or invalid API key"},"404":{"description":"Not your roster"},"429":{"description":"Rate limit exceeded"},"503":{"description":"The members could not be read"}}}},"/api/v1/rosters/{rosterId}/members/{memberId}":{"delete":{"operationId":"removeRosterMember","summary":"Remove a member from future screening","description":"Sets removed_at; the member and past runs are kept (a member is never deleted). Removing twice is harmless.","parameters":[{"name":"rosterId","in":"path","required":true,"schema":{"type":"string"}},{"name":"memberId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Removed (already_removed tells whether it was removed before)"},"400":{"description":"Malformed id"},"401":{"description":"Missing or invalid API key"},"404":{"description":"No such member on your roster"},"429":{"description":"Rate limit exceeded"},"503":{"description":"The member could not be removed"}}}},"/api/v1/rosters/{rosterId}/practitioners":{"get":{"operationId":"listRosterPractitioners","summary":"List the practitioners on your roster that were added by NPI (active ones only)","description":"Free; rate limited, not metered. Removed practitioners are not listed. Query: limit (1 to 1000, default 500), offset.","parameters":[{"name":"rosterId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Active practitioners with npi, first_name, last_name, state, added_at"},"400":{"description":"Malformed limit or offset"},"401":{"description":"Missing or invalid API key"},"404":{"description":"Not your roster"},"429":{"description":"Rate limit exceeded"},"503":{"description":"The practitioners could not be read"}}}},"/api/v1/rosters/{rosterId}/practitioners/{npi}":{"delete":{"operationId":"removeRosterPractitioner","summary":"Remove a practitioner added by NPI from future screening","description":"Sets removed_at; the row is kept and past receipts, history and audit packs stay readable. The next monthly run skips the NPI and the next active count drops it. Removing twice is harmless (already_removed: true). Other accounts' rosters are never touched.","parameters":[{"name":"rosterId","in":"path","required":true,"schema":{"type":"string"}},{"name":"npi","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{10}$"}}],"responses":{"200":{"description":"Removed (already_removed tells whether it was removed before)"},"400":{"description":"Malformed NPI"},"401":{"description":"Missing or invalid API key"},"404":{"description":"No such practitioner on your roster"},"429":{"description":"Rate limit exceeded"},"503":{"description":"The practitioner could not be removed"}}}},"/api/v1/rosters/{rosterId}/runs/{runId}/reviews":{"post":{"operationId":"reviewPossibleMatch","summary":"Record a review of a possible match on a stored screening run","description":"Body: { line_key (npi:<NPI> or member:<id>, as on the receipt), source (oig_leie, sam_gov, ca_medi_cal_si, ny_omig, pa_medicheck, tx_hhsc_oig, fl_ahca), decision (NOT_SAME_PERSON or CONFIRMED_MATCH), reason (10 to 500 characters), reviewer_name, reviewer_email }. Allowed only for a line whose screened outcome is POSSIBLE_MATCH and a source that reported one; a review of an EXCLUSION_FOUND, NO_FINDINGS or COULD_NOT_CHECK line is a 409. Reviews are append-only: a later review supersedes an earlier one only by being newer. A review never changes the screened outcome: the receipt shows it beside the outcome, and a possible match is never turned into a clear result. No date of birth, SSN or other PHI in any field (422). Owner only; sandbox keys have no runs.","parameters":[{"name":"rosterId","in":"path","required":true,"schema":{"type":"string"}},{"name":"runId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["line_key","source","decision","reason","reviewer_name","reviewer_email"]}}}},"responses":{"201":{"description":"Review recorded; screened_outcome is unchanged"},"400":{"description":"Malformed field"},"401":{"description":"Missing or invalid API key"},"404":{"description":"No such run or line (also another account's run, and sandbox keys)"},"409":{"description":"The line is not a POSSIBLE_MATCH (code REVIEW_NOT_ALLOWED), the source reported no possible match, or the run is not COMPLETE"},"422":{"description":"A field or value looks like PHI; nothing was stored"},"429":{"description":"Rate limit exceeded"},"503":{"description":"The review could not be saved"}}}},"/.well-known/statutewire-receipt-key.pem":{"get":{"operationId":"getReceiptPublicKey","summary":"Public key (PEM) that verifies StatuteWire receipts","responses":{"200":{"description":"Ed25519 public key, PEM only","content":{"text/plain":{"schema":{"type":"string"}}}},"503":{"description":"No signing key configured"}}}},"/api/v1/audit-pack/signing-key":{"get":{"operationId":"getAuditSigningKey","summary":"Public key for verifying audit bundle signatures","responses":{"200":{"description":"Ed25519 public key (PEM) and key id","content":{"application/json":{"schema":{"type":"object","required":["algorithm","key_id","public_key_pem"],"properties":{"algorithm":{"type":"string","const":"Ed25519"},"key_id":{"type":"string"},"public_key_pem":{"type":"string"},"signs":{"type":"string"}}}}}},"429":{"description":"Rate limit exceeded"},"503":{"description":"No signing key configured: bundles are UNSIGNED"}}}},"/api/v1/audit-pack":{"get":{"operationId":"exportAuditPack","summary":"Export a per-license audit pack","description":"Certifies one stored license record: standing, risk flags, SHA-256 evidence hash and receipt link, and the re-verification due date (120 days after the record was last verified).","security":[{"BearerAuth":[]}],"parameters":[{"name":"npi","in":"query","required":true,"schema":{"type":"string","pattern":"^[0-9]{10}$"}},{"name":"state","in":"query","required":false,"description":"Certify the record for this state (two-letter code or eNLC, case-insensitive). Recommended for multi-state practitioners.","schema":{"type":"string","minLength":2,"maxLength":4}},{"name":"license_number","in":"query","required":false,"description":"Certify this license (case-insensitive). Required (with state) when the NPI has more than one license record.","schema":{"type":"string","pattern":"^[A-Za-z0-9.\\-]{1,40}$"}}],"responses":{"200":{"description":"Audit pack for one license record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditPackResponse"}}}},"400":{"description":"Invalid NPI or license_number","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Invalid or missing Bearer token"},"402":{"description":"Subscription keys: monthly quota exhausted (code QUOTA_EXHAUSTED, quota_resets_at; nothing is charged extra). Prepaid keys: code INSUFFICIENT_CREDITS, with balance_checks, required_checks and top_up instructions; the request was not charged.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredProblem"}}}},"404":{"description":"NPI not on this account, or no record matches npi/state/license_number"},"409":{"description":"The request matches more than one license record. Retry with state and license_number from `candidates`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AmbiguousLicenseProblem"}}}},"422":{"description":"Unsupported state, or risk assessment incomplete (pack withheld)"},"429":{"description":"Rate limit exceeded (Retry-After header)"},"503":{"description":"Metering unavailable; pack withheld"}}}},"/api/v1/sandbox/verify":{"get":{"operationId":"sandboxSampleVerification","summary":"Synthetic sample payload for quick tool tests (no API key)","description":"Returns a fixed synthetic practitioner (0000000001 active/clean, 0000000002 on probation) without an API key. Not a verification: no primary source is queried, there is no receipt, and primarySourceVerified is false. Its shape differs from /api/v1/sanctions; for the real response format use a sandbox API key with /api/v1/sanctions. Rate limited to 60 requests per minute per IP.","security":[],"parameters":[{"name":"npi","in":"query","required":false,"schema":{"type":"string","enum":["0000000001","0000000002"],"default":"0000000001"}}],"responses":{"200":{"description":"Synthetic sample payload (simulated: true, primarySourceVerified: false)"},"404":{"description":"Not one of the sample NPIs"},"429":{"description":"Rate limit exceeded (Retry-After header)"}}}},"/api/v1/webhooks/subscriptions":{"post":{"operationId":"createWebhookSubscription","summary":"Register HMAC-SHA256 Signed Webhook Endpoint","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["targetUrl"],"properties":{"targetUrl":{"type":"string","format":"uri"},"eventTypes":{"$ref":"#/components/schemas/WebhookEventTypes","description":"Events to receive. Defaults to practitioner.status_changed and practitioner.probation_instituted. practitioner.federal_exclusion is opt-in: include it here, or add it later with PATCH."}}}}}},"responses":{"201":{"description":"Webhook subscription registered (with its event_types); secret_key is returned only here"},"400":{"description":"Missing or unsafe targetUrl, or unknown eventTypes"},"401":{"description":"Missing, invalid, inactive, or revoked credential"},"409":{"description":"Active subscription limit for the tier reached (5 / 25 / 100)"},"429":{"description":"Creation rate limit exceeded (5 / 20 / 60 per hour by tier)"}}},"get":{"operationId":"listWebhookSubscriptions","summary":"List Active Webhook Subscriptions for the Caller","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Active subscriptions (secrets omitted)"},"401":{"description":"Missing, invalid, inactive, or revoked credential"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/webhooks/subscriptions/{subscriptionId}":{"patch":{"operationId":"updateWebhookSubscriptionEventTypes","summary":"Change Which Events a Subscription Receives (e.g. opt in to practitioner.federal_exclusion)","security":[{"BearerAuth":[]}],"parameters":[{"name":"subscriptionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["eventTypes"],"properties":{"eventTypes":{"$ref":"#/components/schemas/WebhookEventTypes","description":"The full new list"}}}}}},"responses":{"200":{"description":"Updated subscription with its event_types (target URL and secret unchanged)"},"400":{"description":"Missing or unknown eventTypes, or malformed JSON"},"401":{"description":"Missing, invalid, inactive, or revoked credential"},"404":{"description":"No active subscription with this ID for the caller"},"429":{"description":"Rate limit exceeded"}}},"delete":{"operationId":"deleteWebhookSubscription","summary":"Deactivate a Webhook Subscription and Cancel Pending Deliveries","security":[{"BearerAuth":[]}],"parameters":[{"name":"subscriptionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Subscription deactivated"},"401":{"description":"Missing, invalid, inactive, or revoked credential"},"404":{"description":"Not found, already deleted, or owned by another tenant"},"429":{"description":"Rate limit exceeded"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"StatuteWire API Key"}},"schemas":{"AuditBundleResponse":{"type":"object","required":["bundle_id","status","environment","sample_data","download_url","url_expires_at","pdf_sha256","manifest_sha256","signature","packs_requested","packs_generated","charged_checks","packs","skipped"],"properties":{"bundle_id":{"type":"string","format":"uuid"},"status":{"type":"string","const":"SEALED"},"environment":{"type":"string","enum":["live","sandbox"]},"sample_data":{"type":"boolean"},"download_url":{"type":"string","format":"uri","description":"Signed URL, valid 15 minutes"},"url_expires_at":{"type":"string","format":"date-time"},"pdf_sha256":{"type":"string"},"manifest_sha256":{"type":"string"},"signature":{"type":["object","null"],"description":"null when no signing key is configured (UNSIGNED)","properties":{"algorithm":{"type":"string","const":"Ed25519"},"key_id":{"type":"string"},"value":{"type":"string","description":"base64"}}},"packs_requested":{"type":"integer"},"packs_generated":{"type":"integer"},"charged_checks":{"type":"integer","description":"Prepaid checks charged (5 per generated pack); 0 for sandbox and subscription keys"},"packs":{"type":"array","items":{"type":"object","properties":{"npi":{"type":"string"},"state":{"type":"string"},"license_number":{"type":"string"},"compliance_status":{"type":"string"},"receipt_sha256":{"type":"string"}}}},"skipped":{"type":"array","items":{"type":"object","properties":{"npi":{"type":"string"},"state":{"type":"string"},"license_number":{"type":"string"},"reason":{"type":"string","enum":["NOT_ON_ROSTER","NOT_FOUND","NOT_VERIFIED","EVIDENCE_MISSING","EVIDENCE_HASH_MISMATCH","RISK_INCOMPLETE"]},"detail":{"type":"string"}}}}}},"RosterBulkSummary":{"type":"object","required":["batch_id","status","total_received","valid_enrolled","duplicates_skipped","failed_invalid","pending_discovery","licenses_enrolled","errors","check_status_url"],"description":"total_received = valid_enrolled + duplicates_skipped + failed_invalid + pending_discovery","properties":{"batch_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["COMPLETED","PROCESSING"]},"total_received":{"type":"integer"},"valid_enrolled":{"type":"integer"},"duplicates_skipped":{"type":"integer"},"failed_invalid":{"type":"integer"},"pending_discovery":{"type":"integer"},"licenses_enrolled":{"type":"integer","description":"Licenses enrolled by this request (prepaid keys are charged per license)"},"errors":{"type":"array","items":{"type":"object","required":["index","npi","license_number","reason"],"properties":{"index":{"type":"integer"},"npi":{"type":["string","null"]},"license_number":{"type":["string","null"]},"reason":{"type":"string"}}}},"check_status_url":{"type":"string"}}},"PaymentRequiredProblem":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","properties":{"quota_resets_at":{"type":"string","format":"date-time","description":"Subscription keys: when the monthly quota resets"},"quota_units_required":{"type":"integer","minimum":2,"description":"QUOTA_EXHAUSTED on a multi-unit request: units it needed (all or nothing)"},"code":{"type":"string","enum":["QUOTA_EXHAUSTED","INSUFFICIENT_CREDITS","ENTERPRISE_FLOOR_REQUIRED"],"description":"QUOTA_EXHAUSTED: subscription key, monthly quota used up (quota_resets_at); requests are refused until then and nothing is charged extra. Prepaid keys: INSUFFICIENT_CREDITS: the balance (in checks) is below this request's cost. ENTERPRISE_FLOOR_REQUIRED: bulk roster uploads need $250.00 in total deposits"},"deposited_cents":{"type":"integer","minimum":0,"description":"ENTERPRISE_FLOOR_REQUIRED: total deposited so far"},"required_cents":{"type":"integer","minimum":1,"description":"ENTERPRISE_FLOOR_REQUIRED only: the deposit floor in USD cents"},"required_checks":{"type":"integer","minimum":1,"description":"INSUFFICIENT_CREDITS only: checks this request costs"},"balance_checks":{"type":"integer","minimum":0,"description":"INSUFFICIENT_CREDITS only: checks remaining"},"top_up":{"type":"string","description":"How to buy a credit pack"}}}]},"ProblemDetails":{"type":"object","description":"RFC 9457 (formerly 7807) problem response","required":["type","title","status","detail","instance"],"properties":{"type":{"type":"string","const":"about:blank","description":"No problem type beyond the HTTP status; see `code` where present"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"IdentityBlockedProblem":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","description":"Present when the identity check blocked the result; absent on other 422/503 problems.","properties":{"identity_verification_status":{"type":"string","enum":["MISMATCH","INSUFFICIENT_DATA"]},"reason":{"type":"string","enum":["NPI_NOT_FOUND","NPI_IS_ORGANIZATION","NPPES_UNAVAILABLE"],"description":"Why there is no reference identity to compare"},"mismatched_fields":{"type":"array","items":{"type":"string","enum":["first_name","last_name"]}},"identity":{"type":"object","properties":{"reference":{"type":"object","properties":{"source":{"type":"string","enum":["CMS_NPPES","SAMPLE_IDENTITY"]},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]}}},"board":{"type":"object","properties":{"source":{"type":"string","description":"Board name"},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]}}}}}}}]},"AmbiguousLicenseProblem":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["candidates"],"properties":{"candidates":{"type":"array","items":{"type":"object","required":["state","license_number"],"properties":{"state":{"type":"string"},"license_number":{"type":"string"},"profession":{"type":["string","null"]},"licensure_status":{"type":["string","null"]},"last_monitored_at":{"type":["string","null"],"format":"date-time"}}}}}}]},"SanctionsResponse":{"type":"object","required":["schema_version","npi","first_name","last_name","profession","state","license_number","licensure_status","identity_verification_status","board_jurisdiction","risk_summary","raw_artifact_sha256","raw_artifact_url","last_monitored_at","data_source","cache_hit","federal_exclusions","medicaid_exclusions","verification_source","environment","discipline","compact_eligible","prescriptive_authority"],"properties":{"schema_version":{"type":"string","const":"2026-v1"},"npi":{"type":"string","pattern":"^[0-9]{10}$"},"first_name":{"type":"string"},"last_name":{"type":"string"},"profession":{"type":"string"},"state":{"type":"string","description":"Registry key: two-letter state or eNLC"},"license_number":{"type":"string"},"licensure_status":{"type":"string"},"identity_verification_status":{"type":"string","enum":["MATCH"],"description":"First + last name check against CMS NPPES (lib/identity/nameMatch.ts). A 200 is always MATCH, fresh or cached; MISMATCH and INSUFFICIENT_DATA are 422/503 problems (IdentityBlockedProblem). Replaces the earlier VERIFIED / MISMATCH_SUSPECT / NPI_NOT_FOUND / UNVERIFIED_EXTERNAL_OUTAGE values."},"board_jurisdiction":{"type":"string"},"discipline":{"$ref":"#/components/schemas/ClinicalDiscipline"},"compact_eligible":{"type":["boolean","null"],"description":"true only when the source reported a multistate (compact) privilege on this license; null when not on record for a stored result."},"prescriptive_authority":{"type":["boolean","null"],"description":"Same value as risk_summary.prescriptive_authority_active; null when that is unknown."},"risk_summary":{"type":"object","required":["clean_record","current_probation","has_public_orders","prescriptive_authority_active","disciplinary_count"],"description":"Each flag is a boolean, or \"UNKNOWN - DO NOT RELY\" when the source did not report it.","properties":{"clean_record":{"$ref":"#/components/schemas/RiskFlag"},"current_probation":{"$ref":"#/components/schemas/RiskFlag"},"has_public_orders":{"$ref":"#/components/schemas/RiskFlag"},"prescriptive_authority_active":{"$ref":"#/components/schemas/RiskFlag"},"disciplinary_count":{"type":"integer"}}},"raw_artifact_sha256":{"type":"string","description":"SHA-256 of the receipt PDF, or \"UNAVAILABLE\" when no evidence is stored"},"raw_artifact_url":{"type":["string","null"],"format":"uri","description":"Receipt PDF (authenticated download); null when no evidence is stored"},"last_monitored_at":{"type":"string","format":"date-time"},"data_source":{"type":"string","enum":["CACHE","SIMULATED_FIXTURE","LIVE_SOURCE"],"description":"CACHE: stored result verified within 120 days. LIVE_SOURCE: fresh lookup against the state's official records (official open data where enabled: WA Department of Health, e.g. MD.MD.60492810; CO DORA, e.g. DR.0059812; CT eLicense, e.g. 1.059841; DE Division of Professional Regulation, e.g. C1-0012345; license_number required). SIMULATED_FIXTURE: fresh sweep of a state still on sample data."},"cache_hit":{"type":"boolean"},"verification_source":{"type":"string","enum":["LIVE_SOURCE","SIMULATED_FIXTURE"],"description":"Where this license record was verified, including for cache hits. Live API keys only ever receive LIVE_SOURCE; sandbox keys only SIMULATED_FIXTURE."},"environment":{"type":"string","enum":["live","sandbox"],"description":"The calling API key's environment"},"federal_exclusions":{"type":"object","required":["oig_leie","sam_gov"],"description":"Live federal exclusion screening, run on every response (cache hits included).","properties":{"oig_leie":{"$ref":"#/components/schemas/OigScreenResult"},"sam_gov":{"$ref":"#/components/schemas/SamScreenResult"}}},"medicaid_exclusions":{"type":"object","description":"State Medicaid exclusion lists, run on every response (cache hits included). California Medi-Cal Suspended and Ineligible list NY OMIG Medicaid Exclusion List, PA Medicheck List, TX HHSC OIG Exclusions List and FL AHCA Medicaid Sanctioned Providers List so far. NOT_CHECKED means the source is switched off; COULD_NOT_CHECK means it failed or is stale. Neither is a clear result.","properties":{"ca_medi_cal_si":{"$ref":"#/components/schemas/CaSiScreenResult"},"ny_omig":{"$ref":"#/components/schemas/NyOmigScreenResult"},"pa_medicheck":{"$ref":"#/components/schemas/PaMedicheckScreenResult"},"tx_hhsc_oig":{"$ref":"#/components/schemas/TxHhscOigScreenResult"},"fl_ahca":{"$ref":"#/components/schemas/FlAhcaScreenResult"},"states":{"type":"object","description":"States on the shared state-source engine, keyed by source key (for example az_ahcccs). Present only while at least one such state is switched on, and only the states that are on: a state that is off has no entry, which means not covered, never clear.","additionalProperties":{"$ref":"#/components/schemas/EngineStateScreenResult"}}}}}},"EngineStateScreenResult":{"type":"object","description":"Screening against one state's Medicaid exclusion list on the shared engine. EXCLUSION_FOUND: a current finding carries this NPI (a state whose list is ambiguous about the exclusion returns POSSIBLE_MATCH instead). POSSIBLE_MATCH: a current finding with no valid NPI on file reads as the same name (needs review, never clear). History entries (not an exclusion, or ended) are listed in history and never change the status. COULD_NOT_CHECK: no list, a failed lookup or a list not confirmed current for 14 days. NOT_CHECKED: the state is off. Neither is a clear result.","required":["status","source_key","source","source_mode","list_date","list_date_basis","list_checked_at","list_imported_at","list_sha256","checked_at","matches","history"],"properties":{"status":{"type":"string","enum":["EXCLUSION_FOUND","POSSIBLE_MATCH","CLEAR","COULD_NOT_CHECK","NOT_CHECKED"]},"source_key":{"type":"string"},"source":{"type":"string"},"source_mode":{"type":"string","enum":["LIVE","NOT_ENABLED"]},"list_date":{"type":["string","null"]},"list_date_basis":{"type":["string","null"],"enum":["SOURCE_LAST_MODIFIED","RETRIEVED",null]},"list_checked_at":{"type":["string","null"]},"list_imported_at":{"type":["string","null"]},"list_sha256":{"type":["string","null"],"description":"SHA-256 of the exact list file screened"},"source_details":{"$ref":"#/components/schemas/SourceDetails"},"checked_at":{"type":"string"},"matches":{"type":"array","items":{"type":"object","properties":{"match_type":{"type":"string","enum":["NPI","NAME"]},"name":{"type":"string"},"npi":{"type":["string","null"]},"license_number":{"type":["string","null"]},"provider_type":{"type":["string","null"]},"action_text":{"type":["string","null"]},"start_date":{"type":["string","null"]},"end_date":{"type":["string","null"]},"end_permanent":{"type":"boolean"},"source_row":{"type":"integer"}}}},"history":{"type":"array","description":"entries that match but are history only (at most 10)","items":{"type":"object","properties":{"name":{"type":"string"},"reason":{"type":"string"},"date":{"type":["string","null"]},"match_type":{"type":"string","enum":["NPI","NAME"]},"source_row":{"type":"integer"}}}},"note":{"type":"string"}}},"SourceDetails":{"type":"object","description":"Where the screened list came from (roadmap X6). A null field is UNKNOWN, never blank-as-clean. Present on results produced from X6 on; absent when no list was consulted.","required":["source_name","source_url","file_name","file_date","retrieved_at","sha256"],"properties":{"source_name":{"type":"string","description":"The source's registered name"},"source_url":{"type":["string","null"],"description":"The official URL the list file was downloaded from"},"file_name":{"type":["string","null"],"description":"The file's own name (OIG UPDATED.csv, the SAM extract name); null when the source publishes no named file"},"file_date":{"type":["string","null"],"description":"The publisher's date for the file (Last-Modified or extract date); null when none is published"},"retrieved_at":{"type":["string","null"],"description":"When StatuteWire first retrieved this exact file"},"sha256":{"type":["string","null"],"description":"SHA-256 of the exact file screened"}}},"CaSiScreenResult":{"type":"object","description":"Screening against the California Medi-Cal Suspended and Ineligible list (DHCS, data.chhs.ca.gov). The file has no NPI column: an NPI match uses valid NPIs found in its Provider Number field and is EXCLUSION_FOUND; a same-name entry with no NPI is POSSIBLE_MATCH (needs review, never clear).","required":["status","source","source_mode","list_published","list_checked_at","list_imported_at","list_sha256","checked_at","matches"],"properties":{"status":{"type":"string","enum":["EXCLUSION_FOUND","POSSIBLE_MATCH","CLEAR","COULD_NOT_CHECK","NOT_CHECKED"]},"source":{"type":"string"},"source_mode":{"type":"string","enum":["LIVE","NOT_ENABLED"]},"list_published":{"type":["string","null"],"description":"last_modified of the published CKAN resource"},"list_checked_at":{"type":["string","null"],"description":"when the portal was last confirmed to still publish this file"},"list_imported_at":{"type":["string","null"]},"list_sha256":{"type":["string","null"],"description":"SHA-256 of the exact list file screened"},"source_details":{"$ref":"#/components/schemas/SourceDetails"},"checked_at":{"type":"string"},"matches":{"type":"array","items":{"type":"object","properties":{"match_type":{"type":"string","enum":["NPI","NAME"]},"name":{"type":"string"},"npi":{"type":["string","null"]},"provider_type":{"type":["string","null"]},"license_number":{"type":["string","null"]},"suspension_date":{"type":["string","null"]},"active_period":{"type":["string","null"]},"source_row":{"type":"integer"}}}},"note":{"type":"string"}}},"PaMedicheckScreenResult":{"type":"object","description":"Screening against the Pennsylvania Medicheck List of precluded providers (PA DHS). The list keeps ENDED preclusions: a preclusion is current when its end date is open, today or later (America/New_York) or unreadable. An NPI match to a current preclusion is EXCLUSION_FOUND; a same-name current entry with no NPI is POSSIBLE_MATCH (needs review, never clear). Matches to ended preclusions are listed in past_preclusions and do not change a CLEAR. PA Medicaid only.","required":["status","source","source_mode","list_date","list_date_basis","list_checked_at","list_imported_at","list_sha256","checked_at","matches","past_preclusions"],"properties":{"status":{"type":"string","enum":["EXCLUSION_FOUND","POSSIBLE_MATCH","CLEAR","COULD_NOT_CHECK","NOT_CHECKED"]},"source":{"type":"string"},"source_mode":{"type":"string","enum":["LIVE","NOT_ENABLED"]},"list_date":{"type":["string","null"],"description":"The server's Last-Modified when it sends one; otherwise the date this exact file was first retrieved"},"list_date_basis":{"type":["string","null"],"enum":["SOURCE_LAST_MODIFIED","RETRIEVED",null]},"list_checked_at":{"type":["string","null"],"description":"when the publisher was last confirmed to still serve this file"},"list_imported_at":{"type":["string","null"]},"list_sha256":{"type":["string","null"],"description":"SHA-256 of the exact list file screened"},"source_details":{"$ref":"#/components/schemas/SourceDetails"},"checked_at":{"type":"string"},"matches":{"type":"array","description":"current preclusions only","items":{"type":"object","properties":{"match_type":{"type":"string","enum":["NPI","NAME"]},"name":{"type":"string"},"npi":{"type":["string","null"]},"license_number":{"type":["string","null"]},"preclusion_status":{"type":["string","null"],"description":"the published Status text; informational, currency comes from end_date"},"begin_date":{"type":["string","null"]},"end_date":{"type":["string","null"],"description":"null = open-ended (or unreadable, see end_date_unparseable)"},"end_date_unparseable":{"type":"boolean","description":"the list has an end date that could not be read; treated as current"},"source_row":{"type":"integer"}}}},"past_preclusions":{"type":"array","description":"ended preclusions: history, never a current exclusion","items":{"type":"object","properties":{"match_type":{"type":"string","enum":["NPI","NAME"]},"name":{"type":"string"},"npi":{"type":["string","null"]},"license_number":{"type":["string","null"]},"preclusion_status":{"type":["string","null"],"description":"the published Status text; informational, currency comes from end_date"},"begin_date":{"type":["string","null"]},"end_date":{"type":["string","null"],"description":"null = open-ended (or unreadable, see end_date_unparseable)"},"end_date_unparseable":{"type":"boolean","description":"the list has an end date that could not be read; treated as current"},"source_row":{"type":"integer"}}}},"note":{"type":"string"}}},"TxHhscOigScreenResult":{"type":"object","description":"Screening against the Texas HHSC OIG Exclusions List (oig.hhsc.state.tx.us). The list holds every provider ever excluded; a provider with a valid reinstatement date on or before today (America/Chicago) is REINSTATED. A blank, future or unreadable reinstatement date is treated as CURRENT. An NPI match to a current exclusion is EXCLUSION_FOUND; a same-name current entry with no NPI is POSSIBLE_MATCH (needs review, never clear). Reinstated matches are listed in reinstated_exclusions and do not change a CLEAR. TX Medicaid only.","required":["status","source","source_mode","list_date","list_date_basis","list_checked_at","list_imported_at","list_sha256","checked_at","matches","reinstated_exclusions"],"properties":{"status":{"type":"string","enum":["EXCLUSION_FOUND","POSSIBLE_MATCH","CLEAR","COULD_NOT_CHECK","NOT_CHECKED"]},"source":{"type":"string"},"source_mode":{"type":"string","enum":["LIVE","NOT_ENABLED"]},"list_date":{"type":["string","null"],"description":"The date this exact file was first retrieved (the publisher sends no list date)"},"list_date_basis":{"type":["string","null"],"enum":["SOURCE_LAST_MODIFIED","RETRIEVED",null]},"list_checked_at":{"type":["string","null"],"description":"when the publisher was last confirmed to still serve this file"},"list_imported_at":{"type":["string","null"]},"list_sha256":{"type":["string","null"],"description":"SHA-256 of the exact list file screened"},"source_details":{"$ref":"#/components/schemas/SourceDetails"},"checked_at":{"type":"string"},"matches":{"type":"array","description":"current exclusions only","items":{"$ref":"#/components/schemas/TxHhscOigMatch"}},"reinstated_exclusions":{"type":"array","description":"reinstated entries: history, never a current exclusion","items":{"$ref":"#/components/schemas/TxHhscOigMatch"}},"note":{"type":"string"}}},"TxHhscOigMatch":{"type":"object","properties":{"match_type":{"type":"string","enum":["NPI","NAME"]},"name":{"type":"string"},"npi":{"type":["string","null"]},"license_number":{"type":["string","null"],"description":"for the reviewer to compare; never used to suppress a match"},"occupation":{"type":["string","null"]},"reason":{"type":["string","null"],"description":"the published WebComments text; informational"},"start_date":{"type":["string","null"]},"reinstated_date":{"type":["string","null"],"description":"null = not reinstated (or unreadable, see reinstated_date_unparseable)"},"reinstated_date_unparseable":{"type":"boolean","description":"the list has a reinstatement date that could not be read; treated as current"},"source_row":{"type":"integer"}}},"FlAhcaScreenResult":{"type":"object","description":"Screening against the Florida AHCA Medicaid Sanctioned Providers List (apps.ahca.myflorida.com, final orders). The list is made of sanction ORDERS, most of them fines. Terminations, suspensions and 'NONE' (and a blank or unrecognised type, cautiously) are findings; fines, corrective action plans and rescinded sanctions are NEVER a finding and are listed in non_exclusion_sanctions as history. The list has no end date and a Florida Medicaid termination is not necessarily a formal exclusion, so EVERY finding, even on an NPI match, is POSSIBLE_MATCH (this source never returns EXCLUSION_FOUND); the note says 'Florida Medicaid <type> on record (<sanction date>); the list has no end date. Confirm current status.' FL Medicaid only.","required":["status","source","source_mode","list_date","list_date_basis","list_checked_at","list_imported_at","list_sha256","checked_at","matches","non_exclusion_sanctions"],"properties":{"status":{"type":"string","enum":["POSSIBLE_MATCH","CLEAR","COULD_NOT_CHECK","NOT_CHECKED"]},"source":{"type":"string"},"source_mode":{"type":"string","enum":["LIVE","NOT_ENABLED"]},"list_date":{"type":["string","null"],"description":"The date this exact file was first retrieved (the publisher sends no list date)"},"list_date_basis":{"type":["string","null"],"enum":["SOURCE_LAST_MODIFIED","RETRIEVED",null]},"list_checked_at":{"type":["string","null"],"description":"when the publisher was last confirmed to still serve this file"},"list_imported_at":{"type":["string","null"]},"list_sha256":{"type":["string","null"],"description":"SHA-256 of the exact list file screened"},"source_details":{"$ref":"#/components/schemas/SourceDetails"},"checked_at":{"type":"string"},"matches":{"type":"array","description":"terminations, suspensions, NONE and unknown sanction types only","items":{"$ref":"#/components/schemas/FlAhcaMatch"}},"non_exclusion_sanctions":{"type":"array","description":"fines, corrective action plans and rescinded sanctions: history, never a finding (at most 10 are returned)","items":{"$ref":"#/components/schemas/FlAhcaMatch"}},"note":{"type":"string"}}},"FlAhcaMatch":{"type":"object","properties":{"match_type":{"type":"string","enum":["NPI","NAME"]},"name":{"type":"string"},"npi":{"type":["string","null"]},"license_number":{"type":["string","null"],"description":"for the reviewer to compare; never used to suppress a match"},"medicaid_provider_number":{"type":["string","null"]},"provider_type":{"type":["string","null"]},"sanction_type":{"type":["string","null"],"description":"as published: TERMINATION, SUSPENSION, FINE, ..."},"sanction_class":{"type":"string","enum":["EXCLUSION","NON_EXCLUSION","UNKNOWN"],"description":"UNKNOWN (blank or unrecognised type) is counted as a finding, cautiously"},"violation_code":{"type":["string","null"]},"sanction_date":{"type":["string","null"]},"date_rendered":{"type":["string","null"]},"ahca_case_number":{"type":["string","null"]},"source_row":{"type":"integer"}}},"NyOmigScreenResult":{"type":"object","description":"Screening against the NY OMIG Medicaid Exclusion List (apps.omig.ny.gov, tab-delimited export). The name is one free-text field and the list has no date of birth: an NPI match is EXCLUSION_FOUND; a same-name entry with no NPI is POSSIBLE_MATCH (needs review, never clear). NY Medicaid only.","required":["status","source","source_mode","list_date","list_date_basis","list_checked_at","list_imported_at","list_sha256","checked_at","matches"],"properties":{"status":{"type":"string","enum":["EXCLUSION_FOUND","POSSIBLE_MATCH","CLEAR","COULD_NOT_CHECK","NOT_CHECKED"]},"source":{"type":"string"},"source_mode":{"type":"string","enum":["LIVE","NOT_ENABLED"]},"list_date":{"type":["string","null"],"description":"The server's Last-Modified when it sends one; otherwise the date this exact file was first retrieved"},"list_date_basis":{"type":["string","null"],"enum":["SOURCE_LAST_MODIFIED","RETRIEVED",null]},"list_checked_at":{"type":["string","null"],"description":"when the publisher was last confirmed to still serve this file"},"list_imported_at":{"type":["string","null"]},"list_sha256":{"type":["string","null"],"description":"SHA-256 of the exact list file screened"},"source_details":{"$ref":"#/components/schemas/SourceDetails"},"checked_at":{"type":"string"},"matches":{"type":"array","items":{"type":"object","properties":{"match_type":{"type":"string","enum":["NPI","NAME"]},"name":{"type":"string"},"npi":{"type":["string","null"]},"provider_type":{"type":["string","null"]},"license_number":{"type":["string","null"]},"exclusion_date":{"type":["string","null"]},"source_row":{"type":"integer"}}}},"note":{"type":"string"}}},"SamScreenResult":{"type":"object","description":"Screening against SAM.gov exclusions (federal debarments and suspensions), imported from SAM's daily public extract. Only exclusions in force are matched (no termination date, or one in the future). EXCLUDED: an exclusion carries this NPI. POSSIBLE_MATCH: an excluded individual without an NPI on file has the same first and last name (and license state, for US states); review before acting. CLEAR: no match. UNAVAILABLE: no list imported yet or the lookup failed; never treat as CLEAR.","required":["status","source","source_mode","list_extract_date","list_imported_at","list_sha256","checked_at","matches"],"properties":{"status":{"type":"string","enum":["EXCLUDED","POSSIBLE_MATCH","CLEAR","UNAVAILABLE"]},"source":{"type":"string","const":"SAM.gov Exclusions"},"source_mode":{"type":"string","const":"LIVE"},"list_extract_date":{"type":["string","null"],"format":"date","description":"Date of the SAM daily extract the list came from"},"list_imported_at":{"type":["string","null"],"format":"date-time"},"list_sha256":{"type":["string","null"],"description":"SHA-256 of the exact extract ZIP"},"source_details":{"$ref":"#/components/schemas/SourceDetails"},"checked_at":{"type":"string","format":"date-time"},"note":{"type":"string"},"matches":{"type":"array","items":{"type":"object","required":["match_type","name","npi","state","classification","sam_number","uei","exclusion_type","exclusion_program","excluding_agency","exclusion_date","termination_date","source_row"],"properties":{"match_type":{"type":"string","enum":["NPI","NAME"]},"name":{"type":"string"},"npi":{"type":["string","null"]},"state":{"type":["string","null"]},"classification":{"type":["string","null"],"description":"Individual, Firm, Vessel, or Special Entity Designation"},"sam_number":{"type":["string","null"]},"uei":{"type":["string","null"],"description":"Unique Entity ID"},"exclusion_type":{"type":["string","null"]},"exclusion_program":{"type":["string","null"],"description":"Reciprocal, NonProcurement, or Procurement"},"excluding_agency":{"type":["string","null"]},"exclusion_date":{"type":["string","null"],"format":"date"},"termination_date":{"type":["string","null"],"format":"date","description":"null = indefinite"},"source_row":{"type":"integer"}}}}}},"WebhookEventTypes":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["practitioner.status_changed","practitioner.probation_instituted","practitioner.federal_exclusion","practitioner.npi_deactivated"]},"description":"practitioner.federal_exclusion (opt-in): sent when a monitored NPI appears on a federal exclusion list (OIG LEIE or SAM.gov; newStatus EXCLUDED) or is removed from it (newStatus CLEAR). Same envelope as other events, plus an `exclusion` object naming the source and carrying the list's SHA-256, date, source row, exclusion type and dates. Only NPI matches are sent; name-only matches are not. Also sent once per tenant for an NPI on the tenant's active roster that is newly on the OIG or SAM list compared with the previous import (flat payload: npi, source, list_date, file_sha256, match_type \"NPI\", note \"possible match — confirm with the source\"; no names). An NPI the monitoring path already announced for the same list is not sent twice. practitioner.npi_deactivated (opt-in): sent once per tenant, NPI and deactivation date when an NPI on the tenant's active roster is on the CMS NPPES deactivation list. It is an NPPES status, not a sanction or an exclusion. Payload: npi, deactivation_date (null = the file gave none), source, list_sha256, list_imported_at."},"OigScreenResult":{"type":"object","description":"Screening against the HHS-OIG List of Excluded Individuals/Entities (LEIE), imported from the published full list. EXCLUDED: a listed row carries this NPI. POSSIBLE_MATCH: a listed individual without an NPI on file has the same first and last name (and license state, for US states); confirm with date of birth before acting. CLEAR: no matching row. UNAVAILABLE: no list imported yet or the lookup failed; never treat as CLEAR.","required":["status","source","source_mode","list_published","list_imported_at","list_sha256","checked_at","matches"],"properties":{"status":{"type":"string","enum":["EXCLUDED","POSSIBLE_MATCH","CLEAR","UNAVAILABLE"]},"source":{"type":"string","const":"HHS-OIG LEIE"},"source_mode":{"type":"string","const":"LIVE"},"list_published":{"type":["string","null"],"description":"Last-Modified of the OIG file the list was imported from"},"list_imported_at":{"type":["string","null"],"format":"date-time"},"list_sha256":{"type":["string","null"],"description":"SHA-256 of the exact OIG file the list was imported from"},"source_details":{"$ref":"#/components/schemas/SourceDetails"},"checked_at":{"type":"string","format":"date-time"},"note":{"type":"string"},"matches":{"type":"array","items":{"type":"object","required":["match_type","name","npi","state","general","specialty","exclusion_type","exclusion_date","reinstated","reinstatement_date","waiver","source_row"],"properties":{"match_type":{"type":"string","enum":["NPI","NAME"]},"name":{"type":"string"},"npi":{"type":["string","null"]},"state":{"type":["string","null"]},"general":{"type":["string","null"]},"specialty":{"type":["string","null"]},"exclusion_type":{"type":["string","null"],"description":"Statutory authority, e.g. 1128a1"},"exclusion_date":{"type":["string","null"],"format":"date"},"reinstated":{"type":"boolean"},"reinstatement_date":{"type":["string","null"],"format":"date"},"waiver":{"type":["object","null"],"properties":{"date":{"type":"string","format":"date"},"state":{"type":["string","null"]}}},"source_row":{"type":"integer","description":"Data row number in the source file"}}}}}},"ClinicalDiscipline":{"type":["string","null"],"enum":["PHYSICIAN_MD","PHYSICIAN_DO","DENTIST","NURSE_RN","NURSE_APRN","PHYSICIAN_ASSISTANT","PHARMACIST",null],"description":"Canonical clinical discipline. null: not one of these (e.g. LPN/LVN, non-clinical licenses), the license label is ambiguous (MD or DO), or not on record for a stored result."},"RiskFlag":{"oneOf":[{"type":"boolean"},{"type":"string","const":"UNKNOWN - DO NOT RELY"}]},"AuditPackResponse":{"type":"object","required":["standard","certified_by","environment","verification_source","compliance","generated_at","practitioner","risk_summary","evidentiary_proof","federal_exclusions","retention_schedule"],"properties":{"standard":{"type":"string","description":"What the pack is. Never claims NCQA or Joint Commission certification; sandbox packs say they are not a primary-source verification"},"certified_by":{"type":"string","description":"Always \"Not certified ...\": StatuteWire does not certify; see compliance for the computed status"},"environment":{"type":"string","enum":["live","sandbox"],"description":"The calling API key's environment"},"verification_source":{"type":"string","enum":["LIVE_SOURCE","SIMULATED_FIXTURE"],"description":"Live keys only receive packs for records verified against live official sources; sandbox keys only sample records."},"compliance":{"type":"object","required":["status","reasons"],"description":"Computed from the record, never asserted. SAMPLE_DATA: sample record, verifies nothing. ACTION_REQUIRED: federal exclusion by NPI, license not active, or re-verification overdue. REVIEW_REQUIRED: possible exclusion match, screening unavailable, evidence unavailable, license restricted, or public orders on record. VERIFIED_CURRENT: live primary source, within the cycle, no flags.","properties":{"status":{"type":"string","enum":["SAMPLE_DATA","ACTION_REQUIRED","REVIEW_REQUIRED","VERIFIED_CURRENT"]},"reasons":{"type":"array","items":{"type":"string","enum":["SAMPLE_DATA","EXCLUDED_OIG","EXCLUDED_SAM","LICENSE_NOT_ACTIVE","REVERIFICATION_OVERDUE","LICENSE_RESTRICTED","PUBLIC_ORDERS_ON_RECORD","POSSIBLE_EXCLUSION_MATCH","EXCLUSION_SCREENING_UNAVAILABLE","EVIDENCE_UNAVAILABLE"]}}}},"federal_exclusions":{"type":"object","required":["oig_leie","sam_gov"],"description":"Live federal exclusion screening at the time the pack was generated.","properties":{"oig_leie":{"$ref":"#/components/schemas/OigScreenResult"},"sam_gov":{"$ref":"#/components/schemas/SamScreenResult"}}},"generated_at":{"type":"string","format":"date-time"},"practitioner":{"type":"object","required":["npi","full_name","profession","state","license_number","licensure_status","board_jurisdiction","discipline","compact_eligible","prescriptive_authority"],"properties":{"npi":{"type":"string"},"full_name":{"type":"string"},"profession":{"type":"string"},"state":{"type":"string"},"license_number":{"type":"string"},"licensure_status":{"type":"string"},"board_jurisdiction":{"type":"string"},"discipline":{"$ref":"#/components/schemas/ClinicalDiscipline"},"compact_eligible":{"type":["boolean","null"],"description":"true only when the source reported a multistate (compact) privilege on this license; null when not on record for a stored result."},"prescriptive_authority":{"type":["boolean","null"],"description":"Same value as risk_summary.prescriptive_authority_active; null when that is unknown."}}},"risk_summary":{"type":"object","description":"clean_record and current_probation are always known (otherwise the pack is withheld with 422); the other flags are null when the source did not report them.","required":["clean_record","current_probation","has_public_orders","prescriptive_authority_active","disciplinary_count"],"properties":{"clean_record":{"type":"boolean"},"current_probation":{"type":"boolean"},"has_public_orders":{"type":["boolean","null"]},"prescriptive_authority_active":{"type":["boolean","null"]},"disciplinary_count":{"type":"integer"}}},"evidentiary_proof":{"type":"object","required":["sha256_audit_hash","audit_receipt_url","verification_status"],"properties":{"sha256_audit_hash":{"type":"string","description":"SHA-256 of the receipt PDF, or \"UNAVAILABLE\""},"audit_receipt_url":{"type":["string","null"],"format":"uri"},"verification_status":{"type":"string","enum":["CRYPTOGRAPHICALLY_VERIFIED","SAMPLE_EVIDENCE","EVIDENCE_UNAVAILABLE"],"description":"SAMPLE_EVIDENCE: the hash matches a stored receipt, but the receipt is sample data"}}},"retention_schedule":{"type":"object","required":["credentialing_cycle_days","last_verified_at","next_reverification_due","reverification_overdue"],"properties":{"credentialing_cycle_days":{"type":"integer","const":120},"last_verified_at":{"type":["string","null"],"format":"date-time","description":"last_monitored_at, or created_at if never verified"},"next_reverification_due":{"type":["string","null"],"format":"date-time","description":"last_verified_at + 120 days"},"reverification_overdue":{"type":["boolean","null"]}}}}},"AuditHistoryResponse":{"type":"object","required":["status","meta","events"],"properties":{"status":{"type":"string"},"meta":{"type":"object","required":["npi","total_events","compliance_standard","timestamp"],"properties":{"npi":{"type":"string"},"total_events":{"type":"integer"},"compliance_standard":{"type":"string","const":"STATUTEWIRE_AUDIT_LEDGER_V1","description":"Names the ledger format; not a compliance certification"},"timestamp":{"type":"string","format":"date-time"}}},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event_type":{"type":"string"},"previous_status":{"type":"string","nullable":true},"new_status":{"type":"string"},"board":{"type":"string"},"source_portal":{"type":"string"},"audit_receipt_url":{"type":"string","format":"uri"},"raw_payload_sha256":{"type":"string"},"risk_assessment":{"type":"object"},"captured_at":{"type":"string","format":"date-time"}}}}}}}}}