{"openapi":"3.1.0","info":{"title":"CredentialMatters Public API","version":"v1","description":"Programmatic physician **license** verification (NPI + 76-country registries) and **US ABMS board-certification** verification.\n\nAuthenticate with an API key: `Authorization: Bearer hv_live_…`. Verifications are asynchronous (`POST` returns `202` + an id; poll the `GET`). See the quickstart for the full integration guide."},"servers":[{"url":"/"}],"paths":{"/v1/verifications":{"post":{"tags":["public-api-v1"],"summary":"Create a license verification (async)","operationId":"verify_license","parameters":[{"name":"wait","in":"query","required":false,"schema":{"type":"boolean","description":"Block for a bounded time (≤30 s) for a terminal result; returns 202 to poll if not ready. Single verifications only.","default":false,"title":"Wait"},"description":"Block for a bounded time (≤30 s) for a terminal result; returns 202 to poll if not ready. Single verifications only."},{"name":"max_wait","in":"query","required":false,"schema":{"type":"integer","maximum":30,"minimum":1,"description":"Max seconds to block when wait=true (hard cap 30).","default":30,"title":"Max Wait"},"description":"Max seconds to block when wait=true (hard cap 30)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1VerificationCreate"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Verification"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/verifications/{verification_id}":{"get":{"tags":["public-api-v1"],"summary":"Fetch a verification by id","operationId":"get_verification","parameters":[{"name":"verification_id","in":"path","required":true,"schema":{"type":"string","title":"Verification Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Verification"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["public-api-v1"],"summary":"Delete a verification and its evidence (data erasure)","description":"Erase a verification (GDPR/CCPA right-to-deletion).\n\nTenant-scoped hard delete of the verification record and any linked\nboard-certification rows; usage/audit rows (no result PII) are retained for\nbilling and forensics. Idempotent at the surface: a missing/foreign id is a\n``404`` so existence never leaks across tenants.","operationId":"delete_verification_endpoint_v1_verifications__verification_id__delete","parameters":[{"name":"verification_id","in":"path","required":true,"schema":{"type":"string","title":"Verification Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/verifications/{verification_id}/confirm":{"post":{"tags":["public-api-v1"],"summary":"Resolve a needs_review verification by selecting a candidate","operationId":"confirm_verification","parameters":[{"name":"verification_id","in":"path","required":true,"schema":{"type":"string","title":"Verification Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1VerificationConfirm"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Verification"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/verifications/{verification_id}/evidence/{filename}":{"get":{"tags":["public-api-v1"],"summary":"Fetch verification evidence (screenshot) — tenant-scoped","operationId":"get_verification_evidence_v1_verifications__verification_id__evidence__filename__get","parameters":[{"name":"verification_id","in":"path","required":true,"schema":{"type":"string","title":"Verification Id"}},{"name":"filename","in":"path","required":true,"schema":{"type":"string","title":"Filename"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"head":{"tags":["public-api-v1"],"summary":"Fetch verification evidence (screenshot) — tenant-scoped","operationId":"get_verification_evidence_v1_verifications__verification_id__evidence__filename__get","parameters":[{"name":"verification_id","in":"path","required":true,"schema":{"type":"string","title":"Verification Id"}},{"name":"filename","in":"path","required":true,"schema":{"type":"string","title":"Filename"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batches":{"post":{"tags":["public-api-v1"],"summary":"Submit a bulk verification batch (async; JSON or CSV)","description":"Submit a bulk verification batch. Accepts ``application/json``\n(``V1BatchCreate``), raw ``text/csv``, or ``multipart/form-data`` with a\n``file`` field (CSV or JSON). Always async — poll ``GET /v1/batches/{id}``\n(JSON or `?format=csv`) or subscribe to the ``batch.completed`` webhook.","operationId":"create_batch_endpoint_v1_batches_post","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Batch"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batches/{batch_id}":{"get":{"tags":["public-api-v1"],"summary":"Fetch a batch and its per-item progress (JSON or CSV)","operationId":"get_batch_endpoint_v1_batches__batch_id__get","parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","title":"Batch Id"}},{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(json|csv)$"},{"type":"null"}],"description":"Response format. CSV also via 'Accept: text/csv'.","title":"Format"},"description":"Response format. CSV also via 'Accept: text/csv'."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Batch"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/board-certifications":{"post":{"tags":["public-api-v1"],"summary":"Check US board certification (synchronous)","operationId":"verify_board_certification","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1BoardCertCreate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1BoardCert"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/usage":{"get":{"tags":["public-api-v1"],"summary":"This tenant's usage for the period (count-only)","operationId":"get_usage","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"description":"Trailing window in days.","default":30,"title":"Days"},"description":"Trailing window in days."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1UsageSummary"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/countries":{"get":{"tags":["public-api-v1"],"summary":"List supported countries and coverage","operationId":"list_supported_countries","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1Country"},"title":"Response List Supported Countries"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks":{"post":{"tags":["public-api-v1"],"summary":"Register a webhook endpoint (secret returned once)","operationId":"register_webhook_v1_webhooks_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1WebhookCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Webhook"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["public-api-v1"],"summary":"List registered webhook endpoints","operationId":"get_webhooks_v1_webhooks_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1Webhook"},"title":"Response Get Webhooks V1 Webhooks Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks/{webhook_id}":{"delete":{"tags":["public-api-v1"],"summary":"Delete a webhook endpoint","operationId":"remove_webhook_v1_webhooks__webhook_id__delete","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","title":"Webhook Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"V1Batch":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"reference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reference","description":"Descriptive, sortable external id (e.g. `bat_20260620_phys_us_k7m2p9qa`)."},"object":{"type":"string","title":"Object","default":"batch"},"status":{"type":"string","title":"Status","description":"queued | processing | completed | failed"},"total_items":{"type":"integer","title":"Total Items","default":0},"completed_items":{"type":"integer","title":"Completed Items","default":0},"counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Counts","description":"Item counts keyed by status (e.g. {'verified': 8, 'pending': 2})."},"items":{"items":{"$ref":"#/components/schemas/V1BatchItem"},"type":"array","title":"Items","default":[]},"metadata":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Metadata"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"}},"type":"object","required":["id","status"],"title":"V1Batch","description":"Public batch resource (``/v1/batches`` GET/POST)."},"V1BatchItem":{"properties":{"index":{"type":"integer","title":"Index"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id","description":"Your correlation id, echoed from the input row."},"status":{"type":"string","title":"Status","description":"pending | running | verified | verified_partial | needs_review | not_found | unavailable | failed"},"verification_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Verification Id","description":"Fetch the full result via GET /v1/verifications/{id}."},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name"},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Code"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["index","status"],"title":"V1BatchItem","description":"Status of one item within a batch."},"V1BoardCert":{"properties":{"object":{"type":"string","title":"Object","default":"board_certification"},"full_name":{"type":"string","title":"Full Name"},"country_code":{"type":"string","title":"Country Code","default":"US"},"result_count":{"type":"integer","title":"Result Count","default":0},"results":{"items":{"$ref":"#/components/schemas/V1BoardCertResult"},"type":"array","title":"Results","default":[]},"usage":{"anyOf":[{"$ref":"#/components/schemas/V1Usage"},{"type":"null"}]},"metadata":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Metadata"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["full_name"],"title":"V1BoardCert","description":"Public board-certification resource."},"V1BoardCertCreate":{"properties":{"full_name":{"type":"string","maxLength":300,"minLength":1,"title":"Full Name"},"country_code":{"type":"string","maxLength":3,"title":"Country Code","default":"US"},"state_or_region":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"State Or Region"},"first_name":{"anyOf":[{"type":"string","maxLength":150},{"type":"null"}],"title":"First Name"},"last_name":{"anyOf":[{"type":"string","maxLength":150},{"type":"null"}],"title":"Last Name"},"specialty":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Specialty","description":"Free-text specialty used to route to the correct ABMS board."},"npi":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Npi","description":"NPI (when known) improves board routing accuracy."},"metadata":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Metadata"}},"type":"object","required":["full_name"],"title":"V1BoardCertCreate","description":"Body for ``POST /v1/board-certifications`` (US ABMS member boards)."},"V1BoardCertResult":{"properties":{"certifying_board":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Certifying Board"},"specialty":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Specialty"},"certification_status":{"type":"string","title":"Certification Status","default":"unknown"},"first_certified":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"First Certified"},"most_recent_cert":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Most Recent Cert"},"actively_maintaining":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Actively Maintaining"},"degree":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Degree"},"reported_location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reported Location"},"certificate_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Certificate Number"},"cert_expiry_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cert Expiry Date"},"subspecialty_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subspecialty Code"},"profile_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Profile Url"},"screenshot_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Screenshot Url"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"name_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Name Confidence"}},"additionalProperties":true,"type":"object","title":"V1BoardCertResult","description":"One board-certification record for a physician."},"V1Country":{"properties":{"code":{"type":"string","title":"Code"},"name":{"type":"string","title":"Name"},"region":{"type":"string","title":"Region"},"coverage_status":{"type":"string","title":"Coverage Status","description":"live | live_partial | unavailable"},"requires_state":{"type":"boolean","title":"Requires State","default":false}},"type":"object","required":["code","name","region","coverage_status"],"title":"V1Country"},"V1Disambiguation":{"properties":{"selection_basis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selection Basis","description":"single_match | confidence_gap | user_provided_license | llm_selected | profession_gate_zero_eligible | single_low_confidence | …"},"candidate_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Candidate Count","description":"How many candidates were considered."},"trail":{"anyOf":[{"items":{"type":"object"},"type":"array"},{"type":"null"}],"title":"Trail","description":"Per-candidate kept/dropped decisions with reasons."}},"additionalProperties":true,"type":"object","title":"V1Disambiguation","description":"Why a candidate was (or wasn't) selected when refining signals were used.\n\nPresent only when portal-grade disambiguation ran (the caller supplied a\nrefining signal or there were multiple same-name candidates). Mirrors the\noperator portal's reasoning so API customers get the same auditability."},"V1Evidence":{"properties":{"verdict":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Verdict","description":"verified | needs_review | not_found | …"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"signals":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Signals","description":"Per-signal corroboration detail."}},"additionalProperties":true,"type":"object","title":"V1Evidence","description":"Independent corroboration summary for the selected candidate.\n\nSummarizes the evidence scorer's verdict (name/location/LinkedIn/phone/\neducation corroboration). Present only when evidence scoring ran."},"V1Query":{"properties":{"full_name":{"type":"string","title":"Full Name"},"country_code":{"type":"string","title":"Country Code"},"state_or_region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State Or Region"},"license_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"License Number"},"npi":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Npi"},"specialty":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Specialty"},"year_of_registration":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Year Of Registration"}},"type":"object","required":["full_name","country_code"],"title":"V1Query","description":"Echo of the inputs that produced a verification (audit/idempotency)."},"V1Usage":{"properties":{"billable_units":{"type":"integer","title":"Billable Units","default":1}},"type":"object","title":"V1Usage","description":"Per-operation **usage** surfaced to the customer on terminal states.\n\nIntentionally count-only: ``billable_units`` tells the customer how many\nbillable operations were consumed. HumanVerify's internal **cost** (LLM +\nmanaged proxy + captcha spend) is deliberately NOT exposed here — it is\npersisted server-side (``verification_cost`` / ``usage_records``) for the\noperator portal and billing, never returned on the public contract."},"V1UsageDay":{"properties":{"day":{"type":"string","title":"Day"},"operations":{"type":"integer","title":"Operations","default":0},"billable_units":{"type":"integer","title":"Billable Units","default":0}},"type":"object","required":["day"],"title":"V1UsageDay"},"V1UsageKind":{"properties":{"kind":{"type":"string","title":"Kind"},"operations":{"type":"integer","title":"Operations","default":0},"billable_units":{"type":"integer","title":"Billable Units","default":0}},"type":"object","required":["kind"],"title":"V1UsageKind"},"V1UsageSummary":{"properties":{"object":{"type":"string","title":"Object","default":"usage"},"window_days":{"type":"integer","title":"Window Days"},"since":{"type":"string","format":"date-time","title":"Since"},"generated_at":{"type":"string","format":"date-time","title":"Generated At"},"totals":{"$ref":"#/components/schemas/V1UsageTotals"},"by_kind":{"items":{"$ref":"#/components/schemas/V1UsageKind"},"type":"array","title":"By Kind","default":[]},"by_day":{"items":{"$ref":"#/components/schemas/V1UsageDay"},"type":"array","title":"By Day","default":[]}},"type":"object","required":["window_days","since","generated_at","totals"],"title":"V1UsageSummary","description":"This tenant's own usage for the period. Count-only by design —\nHumanVerify's internal cost is never exposed on `/v1`."},"V1UsageTotals":{"properties":{"operations":{"type":"integer","title":"Operations","default":0},"billable_units":{"type":"integer","title":"Billable Units","default":0}},"type":"object","title":"V1UsageTotals"},"V1Verification":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"reference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reference","description":"Descriptive, sortable external id (e.g. `vrf_20260620_phys_us_k7m2p9qa`). Stable handle for support/correlation."},"object":{"type":"string","title":"Object","default":"verification"},"status":{"type":"string","title":"Status","description":"queued | processing | verified | verified_partial | needs_review | low_confidence | not_found | unavailable | failed"},"profession_type":{"type":"string","title":"Profession Type","default":"physician"},"query":{"$ref":"#/components/schemas/V1Query"},"result_count":{"type":"integer","title":"Result Count","default":0},"results":{"items":{"$ref":"#/components/schemas/V1VerificationResult"},"type":"array","title":"Results","default":[]},"needs_review":{"type":"boolean","title":"Needs Review","description":"True when the result is ambiguous (multiple plausible candidates / weak single match) and a human decision is recommended.","default":false},"disambiguation":{"anyOf":[{"$ref":"#/components/schemas/V1Disambiguation"},{"type":"null"}],"description":"Selection reasoning when refining signals / multi-candidate disambiguation ran (Option B). Null for simple single-match lookups."},"evidence":{"anyOf":[{"$ref":"#/components/schemas/V1Evidence"},{"type":"null"}],"description":"Independent corroboration summary for the selected candidate."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"usage":{"anyOf":[{"$ref":"#/components/schemas/V1Usage"},{"type":"null"}]},"metadata":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Metadata"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"}},"type":"object","required":["id","status","query"],"title":"V1Verification","description":"Public verification resource (``/v1/verifications`` GET/POST)."},"V1VerificationConfirm":{"properties":{"npi":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Npi","description":"Select the candidate with this NPI."},"license_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"License Number","description":"Select the candidate with this license number."},"index":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Index","description":"Select the candidate at this 0-based position in `results`."}},"type":"object","title":"V1VerificationConfirm","description":"Body for ``POST /v1/verifications/{id}/confirm``.\n\nResolve a ``needs_review`` verification by selecting one of the returned\ncandidates. Provide exactly one selector; ``npi`` is preferred when present."},"V1VerificationCreate":{"properties":{"external_id":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"External Id","description":"Your correlation id (CSV `id` column). Echoed back unchanged on the matching result so you can join results to your records."},"full_name":{"type":"string","maxLength":300,"minLength":1,"title":"Full Name"},"country_code":{"type":"string","maxLength":3,"minLength":2,"title":"Country Code","description":"ISO-3166 alpha-2/3 code. Country alone routes the source."},"state_or_region":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"State Or Region","description":"Optional quality signal; never a hard filter."},"license_number":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"License Number"},"npi":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Npi","description":"US National Provider Identifier. When a valid 10-digit NPI is supplied for a US physician, the lookup resolves to that exact record (deterministic), skipping name-based disambiguation. Ignored for non-US."},"specialty":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Specialty","description":"Optional specialty hint (e.g. 'Cardiology'). Used as a soft signal to rank/disambiguate same-name candidates; never a hard filter."},"year_of_registration":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"title":"Year Of Registration"},"institution":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Institution","description":"Training/affiliated institution (e.g. medical school or hospital)."},"city":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"City"},"year_of_birth":{"anyOf":[{"type":"integer","maximum":2025.0,"minimum":1900.0},{"type":"null"}],"title":"Year Of Birth","description":"Used to estimate graduation era as a corroboration signal."},"years_of_experience":{"anyOf":[{"type":"integer","maximum":80.0,"minimum":0.0},{"type":"null"}],"title":"Years Of Experience","description":"Approximate years in practice; corroboration signal only."},"employer_name":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Employer Name"},"employer_location":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Employer Location"},"phone_number":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Phone Number","description":"Contact phone — identity corroboration signal, never a filter."},"phone_number_verified":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Phone Number Verified","description":"Whether the phone was independently verified (weights it stronger)."},"linkedin_url":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Linkedin Url","description":"LinkedIn profile/handle — a strong independent identity signal."},"is_trainee":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Trainee","description":"True if a resident/fellow/trainee."},"degree_level":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Degree Level","description":"Degrees held, e.g. ['MD','MPH']. Rules out non-physician roles."},"matched_medical_skills":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Matched Medical Skills","description":"Curated medical-skill tags (specialty signal)."},"sks_skills":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Sks Skills","description":"Skill tags (e.g. 'T2 Interventional Cardiology'); soft subspecialty signals."},"education":{"anyOf":[{"items":{"type":"object"},"type":"array"},{"type":"null"}],"title":"Education","description":"Structured education: [{school, degree, field_of_study, country, end_year}]."},"jobs":{"anyOf":[{"items":{"type":"object"},"type":"array"},{"type":"null"}],"title":"Jobs","description":"Structured work history: [{job_title, field, location, ...}]."},"accreditations":{"anyOf":[{"items":{"type":"object"},"type":"array"},{"type":"null"}],"title":"Accreditations","description":"Asserted accreditations/boards: [{name, organization}]."},"profession_type":{"type":"string","title":"Profession Type","description":"Currently 'physician' or 'accountant'.","default":"physician"},"force_reverify":{"type":"boolean","title":"Force Reverify","description":"Bypass the cache and force a fresh registry lookup. By default a recent verified result (within the platform cache window) may be reused; set true to always re-verify (costs more).","default":false},"metadata":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Metadata","description":"Opaque customer correlation data, echoed back unchanged."}},"type":"object","required":["full_name","country_code"],"title":"V1VerificationCreate","description":"Body for ``POST /v1/verifications``."},"V1VerificationResult":{"properties":{"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name"},"license_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"License Number"},"npi":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Npi"},"npi_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Npi Type"},"license_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"License Status"},"state_or_region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State Or Region"},"authority_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authority Name"},"specialty":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Specialty"},"university":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"University"},"license_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"License Year"},"confidence_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence Score"},"verification_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Verification Status"},"verification_method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Verification Method"},"profile_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Profile Url"},"screenshot_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Screenshot Url"},"registry_record":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Registry Record"}},"additionalProperties":true,"type":"object","title":"V1VerificationResult","description":"One matched record within a verification.\n\nCore fields are documented; the engine may attach additional keys\n(``registry_record``, ``taxonomies`` …) which are passed through verbatim\nso customers can rely on the documented surface while still receiving the\nfull evidence payload."},"V1Webhook":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"object":{"type":"string","title":"Object","default":"webhook"},"url":{"type":"string","title":"Url"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"event_types":{"items":{"type":"string"},"type":"array","title":"Event Types","default":[]},"enabled":{"type":"boolean","title":"Enabled","default":true},"secret":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Secret","description":"Signing secret (whsec_…). Returned only when the webhook is created — store it; it is not retrievable later."},"last_delivery_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Delivery At"},"last_status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Status"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["id","url"],"title":"V1Webhook","description":"A registered webhook endpoint. ``secret`` is returned ONLY on create."},"V1WebhookCreate":{"properties":{"url":{"type":"string","maxLength":500,"minLength":1,"title":"Url","description":"HTTPS endpoint that receives signed event callbacks."},"description":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Description"},"event_types":{"items":{"type":"string"},"type":"array","title":"Event Types","description":"Event types to subscribe to. Empty list = all events."}},"type":"object","required":["url"],"title":"V1WebhookCreate","description":"Body for ``POST /v1/webhooks``."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key as 'Authorization: Bearer hv_live_…'."}}},"security":[{"BearerAuth":[]}],"tags":[{"name":"public-api-v1","description":"Customer-facing verification API."}]}