{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Veraxus Eligibility API","version":"1.18.0","summary":"Practice-scoped eligibility verification for customer software and agents.","description":"Run payer eligibility as JSON or X12 270/271. Live checks are billed; rejected input, payer outages, and Veraxus failures are not. Eligibility itself never posts the password: Connect is the only password door. On a confirmed dead keep, eligibility may trigger the canonical scheduled Connect path only when the guarded automatic email-code conditions pass; reconnecting is poll-only and never asks the caller for a password or code. Batch submissions are durable, idempotent, and capacity-isolated per practice. Eligibility and batch scope use practice_id; organization_id is a deprecated alias there. Portal-login, credential, and MFA routes use organization_id as the practice field (not an alias of practice_id). MCP agents connect to /mcp.\n\n## Changelog\n\n### 1.18.0\nA dependent batch row (relationship spouse, child or other, with patient_date_of_birth) may leave out date_of_birth, as a single check already could. Each payer keeps its own rule: cigna, metlife and delta_dental_ins need the subscriber’s first_name and last_name but not the subscriber’s birth date; aetna, ddmo, dnoa, pehp and guardian need only the patient_* fields; every other payer still requires date_of_birth and refuses the row with invalid_request. A subscriber row still needs date_of_birth. Aetna now checks patient_date_of_birth, not date_of_birth, for a dependent.\n\n### 1.17.2\nThe Oryx operation submitClaimToClearinghouse sends one approved claim through the practice’s clearinghouse (Vyne when Oryx’s clearinghouse code is NEA), as the office’s Submit does, under POST /pms/oryx/execute/{operation} with the usual write gate: an Idempotency-Key and an approval or vendor attestation. It reads first and sends nothing unless the claim is in the patient’s unsent queue as readyForSubmission, is an electronic claim, is not already in the sent claims, and its lines still hash to expectedLineFingerprint (and its total to expectedTotal). listUnsentClaims and listSentClaims rows now carry line_fingerprint for that check. A refusal is 409 pms_write_refused with error.reason not_ready, not_electronic, changed, already_sent, filter_unconfirmed or send_unresolved; nothing was sent. Veraxus sends a claim once whatever the idempotency key: once submitClaimToClearinghouse or submitClaims has sent it, or while a send of it is unresolved, another send of that claim is refused. Oryx answering success false, or validationError or manualClaim for the claim, is 422 pms_vendor_rejected. The clearinghouse claim number appears in POST /pms/{vendor}/claims/status after Oryx’s queue sends the claim. POST /pms/{vendor}/claims/submit sends 1 to 25 approved claims in one native POST with the same guards per claim, read from the practice’s unsent queue once (operation submitClaimsToClearinghouse): on_guard_failure abort (default) sends nothing when any claim fails, skip sends the passing claims, and each claim answers submitted, submitted_unconfirmed, vendor_rejected, not_ready, not_electronic, changed, already_sent, send_unresolved, not_sent_aborted or unknown_outcome, with sent_count, refused_count and the readback.\n\n### 1.17.1\nPOST /pms/{vendor}/claims/status takes claims: [{claim_id, patient_id, service_date}] (claim_ids still reads the status text alone), and GET /pms/{vendor}/claims/{claim_id}/status takes patient_id and service_date query parameters. Each claim now carries oryx_status_text from Oryx’s status check for the claim id, and every other field comes from the claim’s own row in Oryx’s sent claims: payer, patient_policy_id, service_date_from and service_date_to are new, and claim_date, validation_error_count and response_note are removed. The 1.17.0 read took those from Oryx’s transaction lookup, which is keyed by an eTrans id rather than the claim id, so real claims came back found false. Without patient_id a claim reads the status text only, with sent null and a note. With service_date the search covers 30 days either side; without it, the 365 days ending today.\n\n### 1.17.0\nPOST /pms/{vendor}/claims/status and GET /pms/{vendor}/claims/{claim_id}/status read what the practice’s clearinghouse reported into the PMS for 1 to 10 claims: the PMS’s own status, sent date, clearinghouse claim number, payer reference number, clearinghouse status message, status history and ERA flag. For Oryx the clearinghouse is Vyne when Oryx’s clearinghouse code is NEA (clearinghouse.vendor vyne). Oryx has no live status inquiry, so this is the latest answer Oryx holds, read now; it never signs in. The same read is the Oryx operation getClaimClearinghouseStatus under POST /pms/oryx/execute/{operation} and the MCP pms_read tool. Errors are the /pms read errors (409 not_connected, 502 pms_read_failed, 503 pms_unavailable).\n\n### 1.16.0\nCurve (curve) is open to every practice. PUT /credentials, POST /portal/connect and POST /portal/mfa with payer_id curve, GET /pms/connections and Curve reads under POST /pms/curve/execute/{operation} no longer need curve on the company's payer list: they run only on the practice's own saved Curve login. Oryx is unchanged. A PMS write now needs the practice's write admission whatever the payer list says. GET /credentials lists the practice's cloud PMS login with portal_url. The MCP store_credentials tool accepts portal_url. To have Veraxus enter Curve's emailed sign-in code itself, set the Curve user's email to the practice's code_email_address (GET /organizations) once Veraxus marks it receiving; otherwise send the code with POST /portal/mfa. GET /pms/connections reports needs_code while a code is waiting.\n\n### 1.15.1\nCloud PMS now publishes typed Oryx claim-draft and attachment inputs in the operation registry and OpenAPI. getClaimDraftData, createClaim, updateClaim and updateClaimNarrative complete the draft handoff; uploadPatientDocument, attachment linkage, validation, submission and read-back use the existing scoped and idempotent PMS executor. Claim POSTs use numeric ID lists and attachment saves use the SPA packet, not read envelopes. These write shapes remain spa-client-uncaptured until live proof.\n\n### 1.15.0\nCurve Dental (curve) joins the cloud PMS vendors beside Oryx. GET /pms/vendors lists it with second_factor email_optional, and the {vendor} path parameter accepts curve. GET /pms/curve/operations lists Curve's own operations and POST /pms/curve/execute/{operation} runs them on the practice's saved Curve login; an Oryx operation name is never run on a Curve login. GET /pms/connections reads each licensed vendor's own status. PUT /credentials validates portal_url per vendor: payer_id curve takes the practice's Curve address (https://yourpractice.curvehero.com) and refuses any other vendor's address, and oryx refuses a Curve address. When a Curve user's sign-in asks for a second factor, Curve emails the code to that user; Connect parks it and POST /portal/mfa with payer_id curve completes it. /pms read and write errors name the vendor.\n\n### 1.14.0\nGET /eligibility/{id}/benefit-form renders the existing stored customer-safe Benefits Statement as a private PDF attachment through the same Veraxus generator. Requires eligibility scope and the check tenant/practice; no payer recheck or charge. Default Veraxus branding remains, with fixed Pulp branding restricted to tn_verora. Pending and unavailable checks do not return a PDF. GET /eligibility/{id} adds nullable request_identity from the unique valid original same-scope single-check idempotency receipt; missing or ambiguous proof remains null.\n\n### 1.13.2\nPOST /portal-logins/intake sets a cloud practice system aside. A row that names one (Oryx today), under logins or requested_portals, is parked with the new reason not_a_payer_portal; its login is not saved and no connector is requested. Practice systems are connected through /pms and are never payers.\n\n### 1.13.1\nPOST /portal-logins/intake follows the Portals page rules. A saved login whose portal is signed in right now is proven: a different password for it is parked with the new reason serving_login_differs instead of being applied. A login can be saved for any available payer, whether or not the company’s payer list includes it. A login is saved wherever the staff Portals page shows its payer: as the sign-in login for any payer a practice can sign in to (including one whose checks are still coming soon), on the payer’s own card when it cannot sign in yet, and on a card named as typed only for a portal outside the catalog. A requested portal whose name is one catalog payer follows the same rule instead of being parked.\n\n### 1.13.0\nPOST /portal-logins/intake saves every portal login from one practice submission in a single call, and GET /portal-logins/intake reads the stored result. Each login is saved for sign-in and on the Portal vault record with the email on the payer account. It stores logins only: no sign-in, no code request, and automatic sign-in stays off. The same submission_id and revision sent again returns the stored result; a higher revision applies a corrected password; a login saved under a different username is parked, never replaced. A portal Veraxus cannot sign in to yet can carry its login too: it is kept on a staff-only Portal Vault card for when that connector is built. New error codes: organization_identity_mismatch, intake_revision_conflict, intake_not_found.\n\n### 1.12.0\nEverything the Veraxus Benefits Statement shows now reaches the API. statement (single checks and batch rows) is the statement exactly as the dashboard PDF draws it: sections of kind kv, notes, table, groups or paragraph, with the printed text. Dental history rows (benefit.dental.history, parsed.history, and toothChart procedures) carry the payer's adjudicated claim-line facts when the payer publishes them: line, units, status, claimNumber, servicingProvider, paymentDate, modifier, billedAmount, allowedAmount, disallowedAmount, paidAmount, coinsuranceAmount, copayAmount, deductibleAmount, cobAmount and patientResponsibility in US dollars (e.g. 33.67), and patientPercent, the coinsurance share actually applied, in percent from 0 to 100 (20 means 20%). Claims (benefit.dental.claims) carry claimId, claimNumber, patientName, renderingProvider, payee, medicalGroup and patientAccountNo alongside the amounts; batch rows publish them too. All are optional and nullable. Arbitrary mapper fields are still never output. Today pehp fills the line facts; checks stored earlier gain the new fields on read.\n\n### 1.11.1\nA portal check that failed only because the requested date_of_service is outside what the payer portal's answer covers (the portal answers one current benefit snapshot) now returns error_code date_of_service_unsupported, not incomplete. Its error names the request's date and, when known, the day Veraxus read the portal's current benefits on the snapshot calendar: the portal's own calendar when Veraxus recorded one (for example America/Denver), otherwise UTC. The copy names that calendar in parentheses. A past date of service cannot be answered, for example: This payer's portal answers current benefits only and cannot answer a past date of service. Veraxus read this portal's current benefits on 2030-05-02 (UTC); date_of_service 2030-04-30 is before that day. retry.hint offers that day, or the current day on the snapshot calendar once that is later, only for an appointment on or after it, and retry.ok is false. A later date Veraxus does not serve yet (for ddmo, Veraxus serves a later date_of_service only when it is at most 60 days after the read day and in the same calendar year) names the first day the same request is answered: retry.hint says Run this check again on or after that day, followed by its calendar, for example (America/Denver). retry.ok is true, and retryable is true with retry_after set to the seconds until midnight of that day on the snapshot calendar, never before the next snapshot day starts. A date_of_service 365 or more days after the read day (for example an appointment typed with next year's year) is offered no retry: retry.ok is false and retry.hint says to check the date of service. When Veraxus recorded no portal calendar and the read day is UTC, that limit is 364 days, because a caller's local day can be one day behind the UTC day. Without a known read day the error names only the requested date, and retry.ok is false. why stays incomplete, failure_stage stays mapper, portal_login starts no sign-in or code, and the check is unbilled with billing.reason invalid_request, not payer_unavailable. A posted 270 gets a 271 with AAA 62 (date of service not within the allowable inquiry period), not AAA 72: AAA*Y**62*R (valid request, resubmission allowed) for that later date, and AAA*N**62*C otherwise. The single response, GET /eligibility/{id}, the GET /eligibility list, the idempotency receipt and batch rows all carry the same why and error_code. retry.ok, retryable, retry_after and retry.hint reflect the time of the read: GET and batch rows recompute them, so retry_after counts down, and once the current day on the snapshot calendar is after the date_of_service they give the past-date answer (retry.ok false, no retry_after, and a hint that the date has passed). A keyed idempotent replay repeats the first response unchanged. getting_started's day book now publishes retry_ok null for why incomplete, not false: read retry.ok on the check. The code applies to checks run after the 1.11.1 release: a check stored before 1.11.1 keeps its recorded answer and its recorded billing reason on every surface. Today this applies to ddmo. A check that failed for its date and for another reason too keeps error_code incomplete.\n\n### 1.11.0\nGET /inbox/authenticator-codes returns, for each saved login of a practice that holds an authenticator key, the 6-digit code the office's authenticator app shows now, the next code, and when the current one stops working (server_time, period_seconds 30, valid_from, valid_until). The key is never returned. A shared login is one row; codes is empty when no login has a key. Requires the inbox scope. Veraxus audits at most one read per credential, actor_user_id and practice per 15 minutes.\n\n### 1.10.1\nAn X12 270 whose 2000D/2100D dependent loop has no member ID of its own now names that dependent as the patient: the 2100C subscriber stays the member, relationship comes from INS02 (01 spouse, 19 child, anything else or no INS other), and the patient's name and birth date come from the loop's NM1*03 and DMG. A portal payer that cannot select a dependent returns error_code dependent_not_supported for it, the dependent-capable payers receive that dependent, and the returned 271 answers under the dependent's own 2000D/2100D loop instead of naming the subscriber. On a portal payer, a dependent loop without the dependent's name or birth date returns 400 invalid_request. availity is unchanged, and network (270/271) payers still send the posted 270 as is. A request-level refusal (dependent_not_supported, member_request_invalid) stays unbilled and now reads billing.reason invalid_request on single checks and batch rows, not payer_unavailable or system_failure.\n\n### 1.10.0\nOnly metlife, ddmo, dnoa and delta_dental_ins select a dependent (relationship other than self) from the patient_* fields. Every other portal payer returns error_code dependent_not_supported before any portal request for a JSON single check or a batch row that names a dependent (relationship not self, with network fill off), so that request never returns credentials_required, not_connected or reconnect; it is not billed. An X12 270 whose dependent loop has no member ID is not yet covered. When the network (270/271) fill is on and can carry the dependent, that leg answers instead. availity is unchanged by this release. Network (270/271) payers are unchanged. A connector's refusal of the request's own fields (member_request_invalid) now returns error_code invalid_request with that refusal's text, not incomplete. Both are answers about the request, whatever the login listing says: why incomplete, retry.ok false, failure_stage preflight, and portal_login keeps its listed status but starts no sign-in, code or retry (start_with wait, or null when the login is ready; complete_with null). When a portal check fails on its own answer rather than the login, a sign-in-needed listing no longer sets why reconnect: portal_login.status is status_unknown with start_with wait, never connect_portal_login. A check the network filled keeps the listing's reconnect.\n\n### 1.9.1\nGET /inbox/{id} code may be a token of 4 to 12 capital letters and digits as well as 4 to 8 digits (pattern ^[A-Z0-9]{4,12}$); some payers send such codes. GET /inbox masks those tokens in subject and preview.\n\n### 1.9.0\nGET /inbox lists payer mail held for a practice's code address that Veraxus did not use as a sign-in code, and GET /inbox/{id} returns one message with its one-time code and links. Both require the new inbox scope, which a key has only when minted with it. Mail is kept 72 hours, at most 50 messages per practice. A code Veraxus entered into a portal is never listed.\n\n### 1.8.0\nGET /organizations rows, the POST /organizations response, and POST /organizations/import rows include code_email_address (string or null) and code_email_receiving (boolean). The address is null unless the account is enrolled. Do not set it on a payer account until Veraxus marks it receiving. Eligibility responses may publish reconnecting while a guarded scheduled Connect automatically completes an email-code sign-in; callers poll and do not submit a password or code.\n\n### 1.7.0\nOrganization-scoped licensed non-UCCI payers on the closed Connect allowlist can use the signed composite POST /portal/onboard operation. It stores credentials and invokes the canonical Connect engine in one operation; callers never follow it with POST /portal/connect. United Concordia remains limited to its separately released exact tn_verora/org_4ab6ddda scope, and revocation remains separately gated.\n\n### 1.6.0\nDelegated United Concordia can end operation_status failed with operation_error_code credentials_invalid (retryable:false) when the portal rejects the saved login. GET /portal-logins with organization_id, payer_id, and operation_id then includes operation_error_reason: invalid_credentials, account_locked, or password_expired. A sign-in that did not complete and was not rejected stays sign_in_failed. current_session_status expired on a ready delegated operation means the portal session ended; send a fresh POST /portal/onboard with a new operation_id and do not revoke.\n\n### 1.5.0\nDelegated United Concordia sign-in that did not complete is terminal: operation_status failed, operation_error_code sign_in_failed (retryable:false, human action required). A new POST /portal/onboard with a new operation_id is accepted after that terminal; replaying the old id returns the same receipt. united_concordia delegated challenges require expires_at. POST /portal/onboard and /portal/revoke 403 delegated consent failures include error.reason. Connect/MFA idempotency receipt replay keeps machine-readable error.code.\n\n### 1.4.0\nPUT /credentials 200 adds credential_revision (monotonic integer, +1 per credential-material write including identical retries) and credential_updated_at (ISO timestamp of that vault row write). GET /credentials rows add credential_revision and last_client_reference. Shared-login aliases report the canonical stored row.\n\n### 1.3.0\nShared 4xx/5xx Error responses (500, 502, 503, and portal_outage) on every operation. GET /organizations documents q, limit, and cursor. OpenAPI 3.1 webhooks object lists every event type. Request and 2xx response examples on every operation, taken from sandbox fixtures. GET /v1/reference serves a pinned Redoc HTML reference; HTML Accept on GET /v1/openapi.json is the same 200 HTML representation (no Location). Redocly lint is gated at 0 errors and 0 warnings. Portal-login reads document organization_id. POST /portal/connect documents 423 locked. Store and Connect receipts echo client_reference. Eligibility description states the check itself never posts the password.\n\n### 1.2.0\nContract v1.1 eligibility, portal login, claims, and webhook surfaces.","contact":{"name":"Veraxus Support","url":"https://veraxus.ai/docs"},"license":{"name":"Proprietary","identifier":"LicenseRef-Veraxus-Proprietary"}},"externalDocs":{"description":"Veraxus integration guide","url":"https://veraxus.ai/docs"},"servers":[{"url":"https://api.veraxus.ai/v1","description":"Customer REST API"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Eligibility","description":"Single and durable batch eligibility checks."},{"name":"Practices","description":"Practice roster and practice-scoped resources."},{"name":"Portal logins","description":"Vaulted payer login lifecycle."},{"name":"Network","description":"Leased-network participation read from the office's own portal login."},{"name":"Inbox","description":"Payer mail held for a practice's code address."},{"name":"Account","description":"Key identity, payer catalog, and usage."},{"name":"Claims","description":"Claim and predetermination drafts, vendor-attestation confirm, and payer contracts. Requires the claims scope. Dark unless CLAIMS_SUBMISSION is live or sandbox."},{"name":"Webhooks","description":"Outbound eligibility and claim events. Company defaults cover all practices; active practice subscriptions override matching defaults. Requires a company-wide credential and vault scope; OAuth grant owners must be company admins. Payloads contain result references, never PHI."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"pk_live_ | vat_live_","description":"Veraxus API key or OAuth access token. Send Authorization: Bearer <token>. Scopes: eligibility, vault, portal_login_mutation, claims. Claims routes require the claims scope (opt-in on key creation)."}},"schemas":{"OryxClaimDraftDataInput":{"type":"object","additionalProperties":false,"properties":{"patientId":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$","description":"Native patient ID whose add-claim billing context should be read."},"patientPolicyId":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$","description":"Optional patient-policy record ID, distinct from the policy or plan ID."},"forMigratedBalance":{"type":"boolean","description":"Explicitly select the SPA's migrated-balance billing-context variant."}},"required":["patientId"]},"OryxCreateClaimInput":{"type":"object","additionalProperties":false,"properties":{"claim":{"type":"object","additionalProperties":true,"description":"Full native billing form from getClaimDraftData.raw. Select the intended invoice items, retain native fields, attach the native patient, and set policyId from the selected policy.policy.id. This is not a Veraxus /claims draft or X12 body.","required":["patient","policyId","items","closedItems"],"properties":{"patient":{"type":"object","additionalProperties":true,"description":"Native patient record from the billing context, retaining its original fields.","required":["id"],"properties":{"id":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Positive native Oryx record ID, represented as a safe JSON integer."}}},"policyId":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Positive native Oryx record ID, represented as a safe JSON integer."},"policy":{"type":"object","additionalProperties":true,"description":"Selected native patient-policy object; policyId is its policy.policy.id."},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"required":["items"],"properties":{"items":{"type":"array","description":"Approved selected native invoice items in this group; retain their billing fields.","items":{"type":"object","additionalProperties":true,"required":["checked"],"properties":{"checked":{"const":true,"description":"Each included invoice item must be explicitly selected for this approved draft."}}}}}},"description":"Open native invoice groups, containing only the approved selected items."},"closedItems":{"type":"array","items":{"type":"object","additionalProperties":true,"required":["items"],"properties":{"items":{"type":"array","description":"Approved selected native invoice items in this group; retain their billing fields.","items":{"type":"object","additionalProperties":true,"required":["checked"],"properties":{"checked":{"const":true,"description":"Each included invoice item must be explicitly selected for this approved draft."}}}}}},"description":"Closed native invoice groups, containing only the approved selected items."},"remarks":{"type":"string","description":"Verora's approved claim narrative."},"transactionNote":{"type":"string","description":"Approved transaction note copied into the native draft."},"selectedDefaultTreatingProvider":{"type":["integer","null"],"minimum":1,"maximum":9007199254740991,"description":"Native treating-provider selection from the billing form, or null when unselected."},"selectedDefaultBillingProvider":{"type":["integer","null"],"minimum":1,"maximum":9007199254740991,"description":"Native billing-provider selection from the billing form, or null when unselected."},"claimPerProvider":{"type":"boolean","description":"Retain the billing form's native per-provider claim grouping selection."}},"anyOf":[{"properties":{"items":{"contains":{"properties":{"items":{"minItems":1}}}}}},{"properties":{"closedItems":{"contains":{"properties":{"items":{"minItems":1}}}}}}]},"manualClaim":{"type":"boolean","default":false,"description":"Explicitly choose the SPA's manualClaim query. Never automatically split custom codes into a second POST."}},"required":["claim"]},"OryxUpdateClaimInput":{"type":"object","additionalProperties":false,"properties":{"claim":{"type":"object","additionalProperties":true,"required":["props"],"description":"Full editor body from getClaim.raw, with native props.claimId and Oryx date objects retained. Change only approved fields; this does not submit the claim.","properties":{"props":{"type":"object","additionalProperties":true,"description":"Native editor properties identifying the existing claim; retain unrelated fields.","required":["claimId"],"properties":{"claimId":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Positive native Oryx record ID, represented as a safe JSON integer."}}},"selectedDefaultTreatingProvider":{"type":["integer","null"],"minimum":1,"maximum":9007199254740991,"description":"Retained native treating-provider selection, or null."},"selectedDefaultBillingProvider":{"type":["integer","null"],"minimum":1,"maximum":9007199254740991,"description":"Retained native billing-provider selection, or null."}}}},"required":["claim"]},"OryxClaimNarrativeInput":{"type":"object","additionalProperties":false,"properties":{"claimId":{"type":"string","pattern":"^[0-9]{1,16}$","description":"Native Oryx claim ID as a decimal string; never a Verora draft ID."},"narrative":{"type":"string","description":"Approved narrative; empty string explicitly clears it."}},"required":["claimId","narrative"]},"OryxValidateClaimsInput":{"type":"object","additionalProperties":false,"properties":{"claimsList":{"type":"object","additionalProperties":false,"properties":{"claims":{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Positive native Oryx record ID, represented as a safe JSON integer."},"uniqueItems":true,"maxItems":100,"minItems":1,"description":"Native Oryx IDs, never unsent-queue row objects. Consumer bound: 1–100 distinct claims."}},"required":["claims"],"description":"Native claim-ID list to validate without submitting the claims."}},"required":["claimsList"]},"OryxSubmitClaimsInput":{"type":"object","additionalProperties":false,"properties":{"claimsList":{"type":"object","additionalProperties":false,"properties":{"claims":{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Positive native Oryx record ID, represented as a safe JSON integer."},"uniqueItems":true,"maxItems":100,"minItems":1,"description":"1–100 distinct native Oryx claim IDs approved for this send; never queue rows."}},"required":["claims"],"description":"Native claim-ID list approved for submission through the practice's clearinghouse."}},"required":["claimsList"]},"OryxSubmitClaimToClearinghouseInput":{"type":"object","additionalProperties":false,"properties":{"claimId":{"type":"string","pattern":"^[0-9]{1,16}$","description":"Native Oryx claim ID as a decimal string; never a Verora draft ID."},"patientId":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$","description":"Native patient ID that owns the claim (the unsent row's patient_id)."},"expectedLineFingerprint":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"The line_fingerprint listUnsentClaims returned for this claim when the send was approved. Oryx's current lines must still hash to it."},"expectedTotal":{"type":"number","minimum":0,"description":"Optional approved claim total; the unsent row's total_submitted must match it to the cent."},"serviceDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Optional YYYY-MM-DD service date (service_date_from); narrows the unsent and sent reads to ±30 days. Without it the last 365 days are read."}},"required":["claimId","patientId","expectedLineFingerprint"]},"OryxSubmitClaimsToClearinghouseInput":{"type":"object","additionalProperties":false,"properties":{"claims":{"type":"array","minItems":1,"maxItems":25,"description":"1–25 distinct approved claims. Each must still be readyForSubmission in Oryx's unsent queue with the approved lines.","items":{"type":"object","additionalProperties":false,"properties":{"claimId":{"type":"string","pattern":"^[0-9]{1,16}$","description":"Native Oryx claim ID as a decimal string; never a Verora draft ID."},"patientId":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$","description":"Optional native patient ID; when given, the unsent row must belong to this patient."},"expectedLineFingerprint":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"line_fingerprint from listUnsentClaims at approval time."},"expectedTotal":{"type":"number","minimum":0,"description":"Optional approved total; total_submitted must match to the cent."}},"required":["claimId","expectedLineFingerprint"]}},"onGuardFailure":{"type":"string","enum":["abort","skip"],"default":"abort","description":"abort (default): send nothing when any claim fails a guard. skip: send only the claims that pass."}},"required":["claims"]},"OryxResubmitClaimInput":{"type":"object","additionalProperties":false,"properties":{"claimId":{"type":"string","pattern":"^[0-9]{1,16}$","description":"Native Oryx claim ID as a decimal string; never a Verora draft ID."}},"required":["claimId"]},"OryxSaveClaimAttachmentInput":{"type":"object","additionalProperties":false,"properties":{"attachment":{"type":"object","additionalProperties":false,"description":"The SPA's attachment save body, not listClaimDocuments.raw.obj. Preserve every intended existing item when replacing the saved packet. File upload IDs become patientImages[].imageId; DICOM IDs belong in dicomInstances. Narrative is updated separately with updateClaimNarrative.","required":["claimId","patientImages","dicomInstances","patientImageSeriesIds","dicomSeriesIds","payorReferenceNumber","includePearlAnnotations"],"properties":{"claimId":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Positive native Oryx record ID, represented as a safe JSON integer."},"patientImages":{"type":"array","items":{"type":"object","additionalProperties":true,"required":["imageId","documentCodeId"],"properties":{"imageId":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Positive native Oryx record ID, represented as a safe JSON integer."},"documentCodeId":{"type":["integer","null"],"minimum":0,"maximum":9007199254740991,"description":"Native Oryx document-code enum, or null; never an invented document label."}}},"maxItems":100,"description":"Patient image/document IDs, including uploaded file IDs, with their native document codes."},"dicomInstances":{"type":"array","items":{"type":"object","additionalProperties":true,"required":["imageId","documentCodeId"],"properties":{"imageId":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Positive native Oryx record ID, represented as a safe JSON integer."},"documentCodeId":{"type":["integer","null"],"minimum":0,"maximum":9007199254740991,"description":"Native Oryx document-code enum, or null; never an invented document label."}}},"maxItems":100,"description":"DICOM instance IDs and their native document codes; separate from patient documents."},"patientImageSeriesIds":{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Positive native Oryx record ID, represented as a safe JSON integer."},"uniqueItems":true,"maxItems":100,"description":"Native patient-image series IDs included in the saved packet."},"dicomSeriesIds":{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Positive native Oryx record ID, represented as a safe JSON integer."},"uniqueItems":true,"maxItems":100,"description":"Native DICOM series IDs included in the saved packet."},"payorReferenceNumber":{"type":"string","description":"Native payor reference number using Oryx's exact field spelling; may be empty."},"includePearlAnnotations":{"type":"boolean","description":"Approved selection controlling inclusion of Pearl annotations in the attachment packet."}}}},"required":["attachment"]},"OryxSaveAndSubmitClaimAttachmentInput":{"type":"object","additionalProperties":false,"properties":{"attachment":{"type":"object","additionalProperties":false,"description":"The SPA's attachment save body, not listClaimDocuments.raw.obj. Preserve every intended existing item when replacing the saved packet. File upload IDs become patientImages[].imageId; DICOM IDs belong in dicomInstances. Narrative is updated separately with updateClaimNarrative.","required":["claimId","patientImages","dicomInstances","patientImageSeriesIds","dicomSeriesIds","payorReferenceNumber","includePearlAnnotations"],"properties":{"claimId":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Positive native Oryx record ID, represented as a safe JSON integer."},"patientImages":{"type":"array","items":{"type":"object","additionalProperties":true,"required":["imageId","documentCodeId"],"properties":{"imageId":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Positive native Oryx record ID, represented as a safe JSON integer."},"documentCodeId":{"type":["integer","null"],"minimum":0,"maximum":9007199254740991,"description":"Native Oryx document-code enum, or null; never an invented document label."}}},"maxItems":100,"description":"Patient image/document IDs, including uploaded file IDs, with their native document codes."},"dicomInstances":{"type":"array","items":{"type":"object","additionalProperties":true,"required":["imageId","documentCodeId"],"properties":{"imageId":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Positive native Oryx record ID, represented as a safe JSON integer."},"documentCodeId":{"type":["integer","null"],"minimum":0,"maximum":9007199254740991,"description":"Native Oryx document-code enum, or null; never an invented document label."}}},"maxItems":100,"description":"DICOM instance IDs and their native document codes; separate from patient documents."},"patientImageSeriesIds":{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Positive native Oryx record ID, represented as a safe JSON integer."},"uniqueItems":true,"maxItems":100,"description":"Native patient-image series IDs included in the saved packet."},"dicomSeriesIds":{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Positive native Oryx record ID, represented as a safe JSON integer."},"uniqueItems":true,"maxItems":100,"description":"Native DICOM series IDs included in the saved packet."},"payorReferenceNumber":{"type":"string","description":"Native payor reference number using Oryx's exact field spelling; may be empty."},"includePearlAnnotations":{"type":"boolean","description":"Approved selection controlling inclusion of Pearl annotations in the attachment packet."}}}},"required":["attachment"]},"OryxSubmitClaimAttachmentInput":{"type":"object","additionalProperties":false,"properties":{"claimId":{"type":"string","pattern":"^[0-9]{1,16}$","description":"Native Oryx claim ID as a decimal string; never a Verora draft ID."},"claimFormat":{"type":"string","enum":["american","canadian"],"description":"Explicit native US or Canadian attachment-delivery endpoint variant."}},"required":["claimId","claimFormat"]},"OryxSubmitClaimAttachmentBatchInput":{"type":"object","additionalProperties":false,"properties":{"claimIds":{"type":"array","minItems":1,"maxItems":100,"uniqueItems":true,"description":"1–100 native claim IDs whose saved packets are approved for delivery; numeric IDs must remain distinct after normalization.","items":{"anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Positive native Oryx record ID, represented as a safe JSON integer."},{"type":"string","pattern":"^[0-9]{1,16}$","description":"Native Oryx claim ID as a decimal string; never a Verora draft ID."}]}}},"required":["claimIds"]},"OryxUploadPatientDocumentInput":{"type":"object","additionalProperties":false,"properties":{"patientId":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$","description":"Native patient ID that owns the uploaded document."},"fileName":{"type":"string","minLength":1,"description":"Original upload filename, including its file extension."},"contentType":{"type":"string","pattern":"^[\\w.+-]+/[\\w.+-]+$","description":"MIME media type of the uploaded bytes, such as application/pdf or image/jpeg."},"contentBase64":{"type":"string","minLength":4,"maxLength":34952536,"pattern":"^[A-Za-z0-9+/]+={0,2}$","contentEncoding":"base64","description":"Standard padded base64 of the file bytes, length divisible by four. The native upload limit is 25 MiB; each HTTP deployment's smaller request-body limit still applies to the encoded JSON envelope."},"name":{"type":"string","minLength":1,"description":"Display name stored with the native patient document."},"template":{"type":"string","default":"patient","description":"Native document template; use patient for this claim-attachment workflow."},"folder":{"type":"string","description":"Use Claim Attachment for claim documents."}},"required":["patientId","fileName","contentType","contentBase64","name"]},"Error":{"type":"object","additionalProperties":false,"description":"Every non-2xx response. Branch on error.code (stable machine string); error.message is safe to show a person.","properties":{"error":{"type":"object","additionalProperties":false,"description":"code is the stable machine string to branch on; message explains it in plain words.","properties":{"code":{"type":"string","enum":["attachment_contract_incomplete","attachment_locked","attachment_not_found","attachment_too_large","attestation_required","attempt_in_progress","attachment_type_not_allowed","baa_required","batch_dispatch_unavailable","batch_not_found","challenge_unavailable","check_failed","claims_disabled","claims_gate_closed","code_rejected","company_admin_required","company_key_required","conflict","connect_budget_exhausted","credentials_invalid","credentials_required","customer_suspended","duplicate_client_reference","exact_mfa_required","forbidden","hitl_required","idempotency_conflict","idempotency_key_conflict","idempotency_key_required","idempotency_mismatch","inbox_unavailable","insufficient_scope","intake_not_found","intake_revision_conflict","internal","invalid_api_key","invalid_client_reference","invalid_json","invalid_json_ingress","invalid_origin","invalid_payer_name","invalid_portal_url","invalid_request","invalid_service_type","invalid_source_form_input","invalid_x12","lane_paused","locked","lookup_unresolved","message_not_found","method_not_allowed","missing_api_key","not_found","org_forbidden","organization_identity_mismatch","organization_not_found","organization_required","payer_not_licensed","payer_unavailable","portal_login_identity_change_not_supported","portal_login_operation_not_found","portal_mfa_attempt_forbidden","portal_mfa_attempt_invalid","portal_mfa_attempt_required","portal_mfa_idempotency_mismatch","portal_mfa_required","portal_outage","portal_revoke_required","practice_forbidden","source_form_scope_forbidden","practice_required","quarantined","reauthentication_required","request_too_large","scope_conflict","scope_required","sign_in_failed","staging_contract_incomplete","submission_unknown","tenant_key_required","too_many_requests","unknown_payer","unsupported_connect_payer","unsupported_media_type","unsupported_mfa_payer","vault_error","vault_unreadable","wrong_payer_id_kind","x12_delimiters","x12_missing_required","x12_multiple_claims","x12_payer_unmapped","x12_too_large","x12_usage_indicator_mismatch"],"description":"Stable machine string to branch on. HTTP status and retryable for each code:\n\n| code | HTTP | retryable |\n| --- | --- | --- |\n| attachment_contract_incomplete | 409 | false |\n| attachment_locked | 409 | false |\n| attachment_not_found | 404 | false |\n| attachment_too_large | 413 | false |\n| attestation_required | 400 | false |\n| attempt_in_progress | 409 | true |\n| attachment_type_not_allowed | 400 | false |\n| baa_required | 403 | false |\n| batch_dispatch_unavailable | 503 | true |\n| batch_not_found | 404 | false |\n| challenge_unavailable | 409 | false |\n| check_failed | 400 | false |\n| claims_disabled | 404 | false |\n| claims_gate_closed | 409 | false |\n| code_rejected | 400 | false |\n| company_admin_required | 403 | false |\n| company_key_required | 403 | false |\n| conflict | 409 | false |\n| connect_budget_exhausted | 429 | true |\n| credentials_invalid | 400 | false |\n| credentials_required | 400 | false |\n| customer_suspended | 403 | false |\n| duplicate_client_reference | 400 | false |\n| exact_mfa_required | 400 | false |\n| forbidden | 403 | false |\n| hitl_required | 403 | false |\n| idempotency_conflict | 409 | false |\n| idempotency_key_conflict | 409 | false |\n| idempotency_key_required | 400 | false |\n| idempotency_mismatch | 409 | false |\n| inbox_unavailable | 503 | true |\n| insufficient_scope | 403 | false |\n| intake_not_found | 404 | false |\n| intake_revision_conflict | 409 | false |\n| internal | 500 | false |\n| invalid_api_key | 401 | false |\n| invalid_client_reference | 400 | false |\n| invalid_json | 400 | false |\n| invalid_json_ingress | 400 | false |\n| invalid_origin | 403 | false |\n| invalid_payer_name | 400 | false |\n| invalid_portal_url | 400 | false |\n| invalid_request | 400 | false |\n| invalid_service_type | 400 | false |\n| invalid_source_form_input | 400 | false |\n| invalid_x12 | 400 | false |\n| lane_paused | 409 | false |\n| locked | 423 | false |\n| lookup_unresolved | 409 | false |\n| message_not_found | 404 | false |\n| method_not_allowed | 405 | false |\n| missing_api_key | 401 | false |\n| not_found | 404 | false |\n| org_forbidden | 403 | false |\n| organization_identity_mismatch | 409 | false |\n| organization_not_found | 404 | false |\n| organization_required | 400 | false |\n| payer_not_licensed | 400 | false |\n| payer_unavailable | 503 | true |\n| portal_login_identity_change_not_supported | 409 | false |\n| portal_login_operation_not_found | 404 | false |\n| portal_mfa_attempt_forbidden | 400 | false |\n| portal_mfa_attempt_invalid | 400 | false |\n| portal_mfa_attempt_required | 400 | false |\n| portal_mfa_idempotency_mismatch | 400 | false |\n| portal_mfa_required | 400 | false |\n| portal_outage | 503 | true |\n| portal_revoke_required | 409 | false |\n| practice_forbidden | 403 | false |\n| source_form_scope_forbidden | 403 | false |\n| practice_required | 400 | false |\n| quarantined | 503 | true |\n| reauthentication_required | 400 | false |\n| request_too_large | 413 | false |\n| scope_conflict | 400 | false |\n| scope_required | 403 | false |\n| sign_in_failed | 400 | false |\n| staging_contract_incomplete | 409 | false |\n| submission_unknown | 503 | true |\n| tenant_key_required | 403 | false |\n| too_many_requests | 429 | true |\n| unknown_payer | 400 | false |\n| unsupported_connect_payer | 400 | false |\n| unsupported_media_type | 415 | false |\n| unsupported_mfa_payer | 400 | false |\n| vault_error | 503 | true |\n| vault_unreadable | 503 | true |\n| wrong_payer_id_kind | 400 | false |\n| x12_delimiters | 400 | false |\n| x12_missing_required | 400 | false |\n| x12_multiple_claims | 400 | false |\n| x12_payer_unmapped | 400 | false |\n| x12_too_large | 413 | false |\n| x12_usage_indicator_mismatch | 400 | false |"},"message":{"type":"string","description":"Plain-words explanation, safe to show a person."},"retryable":{"type":"boolean","description":"True when the agent should retry after retry_after seconds (portal_outage siblings)."},"retry_after":{"type":["integer","null"],"description":"Seconds to wait before retry. Null when retryable is false."},"required_scope":{"type":"string","description":"Present on 403 insufficient_scope: the scope this credential must include (eligibility, vault, portal_login_mutation, or claims)."},"required":{"type":"string","deprecated":true,"description":"Deprecated alias for required_scope on eligibility 403s."},"legacy_code":{"type":"string","description":"Deprecated alias for code when a previous release used a different machine string (e.g. scope_required)."},"reason":{"type":"string","enum":["unknown_kid","bad_signature","header_invalid","claims_invalid","iss_aud_mismatch","action_mismatch","request_mismatch","expired","not_yet_valid","sandbox_fixture"],"description":"Present on POST /portal/onboard and POST /portal/revoke 403 delegated_consent_invalid / delegated_consent_expired: why verification failed. Does not change error.code."},"field":{"type":"string","description":"Present on 400 invalid_request when a single input field failed calendar-date or relationship validation (e.g. date_of_birth, date_of_service, relationship)."},"next_allowed_at":{"type":"string","format":"date-time","description":"Present on 429 connect_budget_exhausted: the next time a fresh Connect may run."}},"required":["code","message","retryable","retry_after"]}},"required":["error"]},"EligibilityResult":{"type":"object","additionalProperties":false,"properties":{"verification_admission":{"type":"object","additionalProperties":false,"description":"Permission to attempt the exact practice/book/request. It does not attest a patient match or completed benefits. Submission rechecks it before dispatch.","properties":{"version":{"type":"string","const":"1","description":"Admission contract version."},"practice_id":{"type":"string","description":"Exact practice this decision applies to."},"payer_id":{"type":"string","description":"Exact canonical payer book; sibling books retain separate admission."},"mailbox_id":{"type":"string","description":"Shared-login action group; does not merge payer sessions."},"disposition":{"type":"string","enum":["proceed","wait","action_required","input_required","unsupported"],"description":"Permission to attempt, wait for evidence, complete setup, correct input, or use another supported source."},"reason":{"type":"string","description":"Machine-readable reason for the decision."},"message":{"type":"string","description":"Customer explanation of the decision."},"action":{"type":"object","additionalProperties":false,"description":"Next action and the party responsible for completing it.","properties":{"owner":{"type":"string","enum":["none","practice","customer","veraxus"],"description":"Party responsible for the action; none means no action is required."},"kind":{"type":"string","enum":["none","refresh_status","store_credentials","connect","enter_code","approve_push","correct_input"],"description":"Typed next action; an eligibility request never asks for credentials or a human code."},"href":{"type":["string","null"],"description":"Allowed console path for a practice action, or null."},"field":{"type":["string","null"],"description":"Request field to correct, or null; never contains a patient value."}},"required":["owner","kind","href","field"]},"checked_at":{"type":["string","null"],"format":"date-time","description":"Authenticated evidence timestamp, or null when none is available."},"assessed_at":{"type":"string","format":"date-time","description":"Time this admission decision was assessed."},"valid_until":{"type":"string","format":"date-time","description":"Decision freshness deadline; dispatch still rechecks admission."}},"required":["version","practice_id","payer_id","mailbox_id","disposition","reason","message","action","checked_at","assessed_at","valid_until"]},"current_dental_insurance":{"type":"object","additionalProperties":false,"properties":{"requested_service_date":{"type":"string","format":"date"},"procedure_code":{"type":"string","pattern":"^D[0-9]{4}$"},"current_coverage_proven":{"const":true},"coverage_name":{"type":"string","maxLength":8192},"effective_date":{"type":"string","format":"date","description":"First day of the eligibility span the portal returned for the dates asked about. Not asserted to be the coverage start date."},"end_date":{"type":"string","format":"date","description":"Last day of the eligibility span the portal returned for the dates asked about. Not asserted to be the coverage end date."},"decision_date":{"type":["string","null"],"format":"date","description":"The portal's Date of Decision for this coverage row, from the eligibility summary. Null when the portal shows none. Not asserted to be the coverage start date."},"redetermination_date":{"type":["string","null"],"format":"date","description":"The portal's Redetermination Date for the member, from the eligibility summary. Null when the portal shows none. Not asserted to be the coverage start date."},"program":{"enum":["medicaid","check_up",null]},"delivery_model":{"enum":["fee_for_service","managed_care",null]},"dental_administrator":{"enum":["LIBERTY Dental",null]}},"required":["requested_service_date","procedure_code","current_coverage_proven","coverage_name","effective_date","end_date","decision_date","redetermination_date","program","delivery_model","dental_administrator"],"description":"Nevada selected Dental enrollment for the original requested service date and CDT, only when its canonical current benefit proof is admitted. Program, delivery model and dental administrator stay null when not proved; medical managed-care labels never assign the dental administrator. Stored checks retain the original requested-day result. effective_date and end_date are the eligibility span the portal returned for the dates asked about, and are not asserted to be the coverage start or end. decision_date is the portal's Date of Decision for that coverage row, and redetermination_date is the portal's Redetermination Date for the member; each is null when the portal shows none. None of these dates is asserted to be the coverage start date."},"published_provider_fee_schedules":{"type":"array","maxItems":4096,"items":{"type":"object","additionalProperties":false,"properties":{"family_entry_index":{"type":"integer","minimum":0,"maximum":4096},"source_family":{"const":"publishedFees"},"requested_code":{"anyOf":[{"type":"string","pattern":"^D[0-9]{4}$"},{"type":"null"}]},"requested_service_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"amount_meaning":{"const":"provider_reimbursement"},"provider_scope_only":{"const":true},"patient_applicability_proven":{"const":false},"patient_cost_share_proven":{"const":false},"schedule_source":{"const":"nevada_published_fee_schedule"},"source_url":{"enum":["https://www.nevadamedicaid.nv.gov/siteassets/content/resources/rates/pt-22-fee-schedule--072026.xlsx","https://www.nevadamedicaid.nv.gov/siteassets/content/resources/rates/pt-22-id-waiver-fee-schedule-072026.xlsx"]},"schedule_scope":{"enum":["fee_for_service_dentist","fee_for_service_id_waiver"]},"as_of":{"const":"2026-07"},"fetched_at":{"type":"string","format":"date-time"},"public_file_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"sheet":{"const":"Sheet1"},"columns":{"type":"array","minItems":6,"maxItems":6,"items":{"type":"string","maxLength":8192}},"row_count":{"type":"integer","minimum":0,"maximum":4096},"unique_codes":{"type":"integer","minimum":0,"maximum":4096},"zero_listed_rates":{"type":"integer","minimum":0,"maximum":4096},"zero_rate_policy":{"const":"62_percent_usual_and_customary_unless_medicaid_policy_states_otherwise"},"member_applicability":{"const":"unproven"},"rows":{"type":"array","maxItems":4096,"items":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","maxLength":8192},"procedure_code":{"type":"string","maxLength":8192},"description":{"type":"string","maxLength":8192},"provider_allowed_amount":{"type":["number","null"],"minimum":0},"remaining":{"type":"null"},"patient_copay":{"type":"null"},"covered":{"type":"null"},"prior_auth":{"type":"null"},"modifier":{"type":["string","null"],"maxLength":8192},"rate_type":{"enum":["DEF","DNT","DNI"]},"listed_rate":{"type":"number","minimum":0},"usual_and_customary_pct":{"enum":[62,null]},"rate_begin_date":{"type":"string","format":"date"},"schedule_scope":{"enum":["fee_for_service_dentist","fee_for_service_id_waiver"]}},"required":["code","procedure_code","description","provider_allowed_amount","remaining","patient_copay","covered","prior_auth","modifier","rate_type","listed_rate","usual_and_customary_pct","rate_begin_date","schedule_scope"]}}},"required":["family_entry_index","source_family","requested_code","requested_service_date","amount_meaning","provider_scope_only","patient_applicability_proven","patient_cost_share_proven","schedule_source","source_url","schedule_scope","as_of","fetched_at","public_file_sha256","sheet","columns","row_count","unique_codes","zero_listed_rates","zero_rate_policy","member_applicability","rows"]},"description":"Full official Nevada published provider reimbursement schedules, separately scoped to general dentist and ID waiver. All source rows and zero-rate/U&C policy are retained. These public rates do not establish patient applicability, coverage or cost share; requested date/code are original command context only."},"provider_fee_schedules":{"type":"array","maxItems":4096,"items":{"type":"object","additionalProperties":false,"properties":{"family_entry_index":{"type":"integer","minimum":0,"maximum":4096},"source_family":{"const":"authenticatedFees"},"requested_code":{"type":"string","pattern":"^D[0-9]{4}$"},"requested_service_date":{"type":"string","format":"date"},"service_category":{"enum":["Dental - Adult","Dental - Child"]},"scope_origin":{"const":"command_scope_only"},"amount_meaning":{"const":"provider_reimbursement"},"provider_scope_only":{"const":true},"patient_applicability_proven":{"const":false},"patient_cost_share_proven":{"const":false},"columns":{"type":"array","minItems":7,"maxItems":7,"items":{"type":"string","maxLength":8192}},"row_count":{"type":"integer","minimum":0,"maximum":4096},"rows":{"type":"array","maxItems":4096,"items":{"type":"object","additionalProperties":false,"properties":{"procedure_code":{"type":"string","maxLength":8192},"description":{"type":"string","maxLength":8192},"procedure_literal":{"type":"string","maxLength":8192},"provider_type":{"type":"string","maxLength":8192},"provider_specialty":{"type":"string","maxLength":8192},"modifier":{"type":"string","maxLength":8192},"fee_amount_literal":{"type":"string","maxLength":8192},"age_restrictions_literal":{"type":"string","maxLength":8192},"effective_date_literal":{"type":"string","maxLength":8192},"provider_allowed_amount":{"type":"number","minimum":0},"age_restriction_from":{"type":"integer","minimum":0,"maximum":4096},"age_restriction_through":{"type":"integer","minimum":0,"maximum":4096},"effective_from":{"type":"string","format":"date"},"effective_through":{"type":"string","format":"date"}},"required":["procedure_code","description","procedure_literal","provider_type","provider_specialty","modifier","fee_amount_literal","age_restrictions_literal","effective_date_literal"]}}},"required":["family_entry_index","source_family","requested_code","requested_service_date","service_category","scope_origin","amount_meaning","provider_scope_only","patient_applicability_proven","patient_cost_share_proven","columns","row_count","rows"]},"description":"Nevada provider reimbursement rows for the requested code, with full provider type/specialty/modifier, age restrictions and fee effective periods. Adult/Child search categories do not establish patient applicability, coverage, plan assignment or cost share. The requested service date is command context; these rates are not patient copays."},"insurance_types":{"type":"object","additionalProperties":false,"properties":{"requested_service_date":{"type":["string","null"],"format":"date"},"current_coverage_proven":{"const":false},"dental_administrator":{"type":"null"},"redetermination_date":{"type":["string","null"],"format":"date","description":"The portal's Redetermination Date for the member, from the eligibility summary. Published only on a check with current coverage proof; null otherwise and when the portal shows none. Not asserted to be the coverage start date."},"enrollments":{"type":"array","maxItems":4096,"items":{"type":"object","additionalProperties":false,"properties":{"family_entry_index":{"type":"integer","minimum":0,"maximum":4096},"source_family":{"enum":["summary","coverage","member"]},"row_index":{"type":"integer","minimum":0,"maximum":4096},"coverage_name":{"type":["string","null"],"maxLength":8192},"effective_date":{"type":["string","null"],"format":"date","description":"First day of the span the portal returned on this row. On an eligibility summary row that is the eligibility span for the dates asked about. Not asserted to be the coverage start date."},"end_date":{"type":["string","null"],"format":"date","description":"Last day of the span the portal returned on this row. On an eligibility summary row that is the eligibility span for the dates asked about. Not asserted to be the coverage end date."},"decision_date":{"type":["string","null"],"format":"date","description":"The portal's Date of Decision for this coverage row, on eligibility summary rows. Published only on a check with current coverage proof; null otherwise, on rows from other pages, and when the portal shows none. Not asserted to be the coverage start date."},"program":{"enum":["medicaid",null]},"delivery_model":{"enum":["fee_for_service",null]},"benefit_scope":{"const":"unproven"}},"required":["family_entry_index","source_family","row_index","coverage_name","effective_date","end_date","decision_date","program","delivery_model","benefit_scope"]}},"managed_care_labels":{"type":"array","maxItems":4096,"items":{"type":"object","additionalProperties":false,"properties":{"family_entry_index":{"type":"integer","minimum":0,"maximum":4096},"row_index":{"type":"integer","minimum":0,"maximum":4096},"type":{"type":["string","null"],"maxLength":8192},"benefit_plan":{"type":["string","null"],"maxLength":8192}},"required":["family_entry_index","row_index","type","benefit_plan"]}},"managed_care_organizations":{"type":"array","maxItems":4096,"items":{"type":"object","additionalProperties":false,"properties":{"family_entry_index":{"type":"integer","minimum":0,"maximum":4096},"row_index":{"type":"integer","minimum":0,"maximum":4096},"organization":{"type":["string","null"],"maxLength":8192}},"required":["family_entry_index","row_index","organization"]}}},"required":["requested_service_date","current_coverage_proven","dental_administrator","redetermination_date","enrollments","managed_care_labels","managed_care_organizations"],"description":"Nevada's returned dated enrollment records, when available. Separate from benefit usability: current_coverage_proven remains false. Managed-care labels and organizations are separate source repeaters and do not establish dental assignment. Unknown program or delivery model stays null. On each row, effective_date and end_date are the span the portal returned for that row; on an eligibility summary row that is the eligibility span for the dates asked about. They are not asserted to be the coverage start or end. decision_date is the portal's Date of Decision for an eligibility summary row, and redetermination_date is the portal's Redetermination Date for the member; both are published only on a check with current coverage proof and are null otherwise or when the portal shows none. None of these dates is asserted to be the coverage start date."},"id":{"type":"string","description":"Check id (chk_…). Poll GET /eligibility/{id} / get_eligibility with it."},"request_identity":{"type":["object","null"],"additionalProperties":false,"description":"On GET-by-id only: proof from the unique valid complete unexpired single-check idempotency receipt for this exact tenant, practice and check. Null when absent, invalid or ambiguous; do not infer patient identity from the masked member reference. Client recipe is the existing eligibilityIdempotencyPayload(single, original request) then UTF-8 SHA256 of recursively key-sorted JSON: kind='single'; payer_id/payerId, member_id/memberId, date_of_service/dateOfService, service_type/serviceType, date_of_birth/dateOfBirth, first_name/firstName, last_name/lastName, relationship, patient_first_name/patientFirstName, patient_last_name/patientLastName, patient_date_of_birth/patientDateOfBirth, zip_code/zipCode, address, subscriber_last_name/subscriberLastName; client_reference_id/clientReferenceId/client_reference/clientReference; raw270; practice_id/practiceId/organization_id/organizationId. First non-nullish alias wins, otherwise null; values unchanged. sandbox is true only for boolean true, string 'true', or wire='harness'; force_refresh is Boolean(force_refresh ?? forceRefresh). availity_payer_id is omitted unless either availity alias is defined, otherwise String(selected alias).trim(). procedure_code is omitted unless supplied, otherwise all defined procedure aliases must be valid strings, trimmed/uppercased CDT D plus four digits and agree; existing requested-CDT scope restrictions still apply. For X12 the original validated door.raw270 overrides raw270. Recursively sort object keys with JavaScript string sort, omit undefined object properties, keep array order and JSON.stringify primitive values; SHA256 lowercase hex. Never fill omitted dates/names from derived result fields. This proves the original request, not inferred current policy applicability; retain and compare the original request and owning practice binding.","properties":{"kind":{"type":"string","enum":["eligibility_idempotency_v1"]},"payload_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","example":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}},"required":["kind","payload_sha256"]},"practice_id":{"type":"string","description":"Practice this check ran for. The canonical scope field."},"organization_id":{"type":"string","deprecated":true,"description":"Deprecated alias for practice_id; same value."},"payer_id":{"type":"string","description":"Catalog payer id the check ran against (the id/eligibility_payer_id from GET /payers)."},"member_id":{"type":"string","description":"Masked member reference returned only by the single-check resource."},"status":{"type":"string","enum":["pending","ok","inactive","failed"],"description":"pending: still running, poll by id. ok: served. inactive: served and coverage is terminated. failed: the check did not serve — read why for the reason and retry for what to do."},"usable":{"type":"boolean","description":"True only when why is live: benefit holds reported facts. Coverage is established only when active is explicitly true or false; null is unknown. When false, benefit is null — act on why instead."},"why":{"type":"string","enum":["live","needs_code","reconnect","payer_down","member_not_found","server_error","incomplete","invalid_request","cancelled"],"description":"The one field to branch on. live: usable benefits in benefit. needs_code: a one-time code is owed — submit it with complete_portal_mfa (Aetna is the exception: list_portal_mfa_challenges then complete_aetna_portal_mfa with the challenge id and generation), then re-run; do not reconnect. reconnect: recover the portal login with connect_portal_login using the saved credentials; no code is pending. A human code is required only if recovery returns needs_code. payer_down: payer side is down — retry later, not billed. member_not_found: the identity fields did not match a member — fix them and re-run (billed). server_error: our side, still pending, or a guarded automatic reconnect is in progress — retry or poll later, not billed, and do not start another Connect. incomplete: verification could not be completed — not billed; read error_code and failure_stage. invalid_request: the input was rejected before any payer call. cancelled: you cancelled this batch check before any payer call — not billed, and never a payer or login verdict."},"served_by":{"type":["string","null"],"enum":["payer_portal","eligibility_network",null],"description":"Which leg answered this check: payer_portal is a live payer-portal harvest, eligibility_network is a relayed X12 270/271. Null while status is pending and on failed checks — no leg served data, so there is nothing to attribute. Sandbox checks report payer_portal. Read this field to attribute a result; raw271 does not indicate the leg (see raw271)."},"auth_status":{"type":"string","enum":["ok","reauthentication_required","eligibility_network"],"description":"Health of the serving login: ok, reauthentication_required (the saved portal session needs recovery; this does not establish that MFA is required), or eligibility_network only when the network leg actually filled this row. Login health, not provenance — read served_by to attribute a result."},"session":{"type":"object","additionalProperties":false,"description":"State of this payer's saved portal login session. reconnecting means the guarded automatic email-code sign-in is in progress and the check should be polled. mfa_required true means a one-time code is owed now (see portal_login.complete_with); status expired means the session needs recovery through connect_portal_login; it does not mean a code is owed.","properties":{"status":{"type":"string","description":"Session state: e.g. code_required, expired, not_applicable."},"mfa_expired":{"type":"boolean","description":"Legacy session-expiry flag. Recover through connect_portal_login; only mfa_required true establishes that a code is owed."},"mfa_required":{"type":"boolean","description":"True when a one-time code is owed right now."},"mfa_required_at":{"type":["string","null"],"description":"UTC time the code became owed; null when none is owed."}},"required":["status","mfa_expired","mfa_required","mfa_required_at"]},"portal_login":{"type":"object","additionalProperties":false,"description":"The saved portal login behind this payer. status matches GET /v1/portal-logins. legacy_status keeps the previous vocabulary (ready, needs_human, portal_down, not_connected, none) for one release.","properties":{"status":{"type":"string","enum":["ready","reconnecting","needs_code","confirmation_pending","expired","not_connected","credentials_invalid","locked","portal_outage","quarantined","status_unknown","vault_error","none"],"description":"Same enum as GET /v1/portal-logins, plus none when this payer uses no portal login. reconnecting is poll-only and never asks the caller for a password or code."},"legacy_status":{"type":"string","enum":["ready","needs_human","portal_down","not_connected","none"],"description":"Previous portal_login.status vocabulary. Present for one release."},"message":{"type":["string","null"],"description":"Plain-words instruction safe to show the office."},"start_with":{"type":["string","null"],"enum":["connect_portal_login","complete_portal_mfa","complete_aetna_portal_mfa","observe_metlife_portal_mfa","wait","poll",null],"description":"MFA-first next verb: poll while reconnecting, complete_* when needs_code, wait on outage/quarantine, connect_portal_login when not_connected or expired."},"complete_with":{"type":["string","null"],"enum":["complete_portal_mfa","complete_aetna_portal_mfa",null],"description":"When set, a code is parked: call this verb with the code. Never call connect again first."}},"required":["status","legacy_status","message","start_with","complete_with"]},"benefit":{"type":["object","null"],"additionalProperties":true,"description":"The benefits JSON when usable: active (boolean, or null for explicitly unknown coverage with a waived check), planName, deductible (individual/family/remaining), annualMax, coinsurancePct, and dental (plan, accumulators, categories, procedures, history, family, claims when the payer publishes them). Accumulators include additive kind (deductible|maximum|ortho_lifetime|other) next to unchanged type. Categories include waitingPeriod, limitations, additive coinsuranceBasis (plan_pays|patient_pays|unknown), and planPaysPctInNetwork next to unchanged coinsuranceInNetwork. Procedure rows (dental.procedures[]) may carry optional canonical shares: planPaysPct and patientPaysPct (in-network plane), outOfNetworkPlanPct and outOfNetworkPatientPct (out-of-network plane), and boolean deductibleApplies. For payers that publish the per-tier carrier networkedBenefits[] (ddmo), Veraxus fills a plane only when every tier of that plane agrees and plan + patient = 100; otherwise the plane is absent and networkedBenefits[] (networkTier, network in|out, reportedBenefitPct, reportedBenefitFraction, patientPaysPct, raw deductibleApplies, meaning) holds each tier's labeled share. Other payers publish their mapper's own labeled value in these keys. Null unless why is live. Missing money is reported missing, never invented."},"statement":{"type":["object","null"],"additionalProperties":false,"description":"The Veraxus Benefits Statement for this check, exactly as the dashboard PDF draws it, when usable: the same sections in the same order. Each section has a kind: kv (title + cells of [label, value]), notes (title + rows of {name, text}), table (table: title, note, columns of {key, label, weight}, rows keyed by column key), groups (title + groups of {name, table}), or paragraph (title + text). Every value is the text the statement prints. Use the typed benefit fields to compute; use statement to show what Veraxus shows.","properties":{"sections":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["kv","notes","table","groups","paragraph"]},"title":{"type":["string","null"]},"note":{"type":["string","null"]},"text":{"type":["string","null"]},"cells":{"type":"array","items":{"type":"array","items":{"type":"string"}}},"rows":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"text":{"type":"string"}}}},"table":{"type":"object","additionalProperties":false,"properties":{"title":{"type":["string","null"]},"note":{"type":["string","null"]},"columns":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"key":{"type":"string"},"label":{"type":"string"},"weight":{"type":"number"}}}},"rows":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Column key to the text the statement prints in that cell."}}}},"groups":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"table":{"type":"object","additionalProperties":false,"properties":{"title":{"type":["string","null"]},"note":{"type":["string","null"]},"columns":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"key":{"type":"string"},"label":{"type":"string"},"weight":{"type":"number"}}}},"rows":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Column key to the text the statement prints in that cell."}}}}}}}},"required":["kind"]}}}},"parsed":{"type":["object","null"],"additionalProperties":true,"description":"Flat parse of the served payload (plan, categories, accumulators, procedures, family, claims). procedures[] rows carry the same optional canonical shares as benefit.dental.procedures[] (planPaysPct, patientPaysPct, outOfNetworkPlanPct, outOfNetworkPatientPct, deductibleApplies, networkedBenefits). Batch receipt rows carry only the flat keys; their per-tier detail is on GET /eligibility/{id}. Populated alongside benefit when available; null otherwise."},"error":{"type":["string","null"],"description":"Human-readable reason when the check did not serve; null on success. Pair with error_code."},"error_code":{"type":["string","null"],"description":"Machine code for error (e.g. retry when the lane is paused and the keep is warm, reconnect when the office must Connect, credentials_required when no login is saved, internal for a host fault, mfa_expired, member_not_found, payer_down when the saved login is quarantined or the payer portal is out, payer_unavailable, incomplete, date_of_service_unsupported when the payer portal answers current benefits only and the requested date_of_service is outside that answer (not billed; a past date of service cannot be answered and retry.ok is false; a later date names in retry.hint the day the same check is answered, on the portal's calendar or else UTC, with retry.ok true and retry_after; a date 365 or more days out (364 when the read day is UTC), or one that has passed by the time of the read, is retry.ok false), pending). server_error is only a host exception. Null on success."},"retryable":{"type":"boolean","description":"True when this failed check is safe to retry unchanged after retry_after seconds (paused lane + warm keep, or error_code date_of_service_unsupported for a later date the portal answers from a named day, as of the time of the read). Omitted when not retryable."},"retry_after":{"type":["integer","null"],"description":"Seconds to wait before retrying a retryable failed check. Null/omitted when not retryable. For error_code date_of_service_unsupported it counts from the time of the read to midnight of the named day on the snapshot calendar: GET and batch rows recompute it, and a keyed idempotent replay repeats the first value."},"retry":{"type":"object","additionalProperties":false,"description":"What to do next. ok true: safe to retry later as-is. ok false: retrying unchanged will not help — follow hint (submit a code, reconnect, or fix input). poll names the verb to poll a pending check.","properties":{"ok":{"type":"boolean","description":"True: safe to retry later unchanged. False: follow hint first."},"hint":{"type":["string","null"],"description":"What to do before retrying, in plain words."},"poll":{"type":"string","description":"Compatibility verb to poll a pending check (get_eligibility). Prefer poll_tool and poll_path."},"poll_tool":{"type":"string","description":"MCP tool to poll a pending check (get_eligibility)."},"poll_path":{"type":"string","description":"REST path to poll this check, filled as /v1/eligibility/{id}."}},"required":["ok"]},"billing":{"type":"object","additionalProperties":false,"description":"What this check cost. Branch on waived, not on reason: waived true means not billed (reason says why — sandbox, payer_unavailable, pending, idempotent_replay, invalid_request); waived false means billed and reason names the rate (live_check, or cache for a cached serve). A member miss is billed; a dead login, payer outage, or Veraxus failure is not.","properties":{"unit":{"type":"string","const":"eligibility_check","description":"Billing unit; always eligibility_check."},"cents":{"type":"integer","minimum":0,"description":"Amount billed for this check, in US cents; 0 when waived."},"currency":{"type":"string","const":"USD","description":"Always USD."},"waived":{"type":"boolean","description":"True when not billed (sandbox, payer outage, pending, or a Veraxus failure)."},"reason":{"type":["string","null"],"description":"When waived: why (sandbox, payer_unavailable, pending, idempotent_replay, invalid_request). When billed: the rate that applied (live_check, cache). Branch on waived, not on this field."}},"required":["unit","cents","currency","waived"]},"idempotent":{"type":"boolean","description":"True when this response was served from the short same-request deduplication window (an identical concurrent submission), not re-billed (billing.reason idempotent_replay). An Idempotency-Key replay instead returns the original envelope unchanged, so this field then reflects the original run."},"step":{"type":"string","description":"Present only on server_error: the coarse stage that failed (e.g. portal). Diagnostic, not actionable."},"raw271":{"type":"string","description":"X12 271 rendering of this result — a response format, not a provenance signal; read served_by to attribute a result. On the POST response it appears only when a 270 was posted, SYNTHESIZED from whatever leg served the check, including a payer_portal harvest; the JSON door omits it even when the eligibility network served the check. A stored check (GET) retains only a relayed network 271, regardless of the door originally posted to."},"warnings":{"type":"array","description":"Non-fatal input notes on a single-check response. relationship_normalized means an unknown relationship token was treated as other. Omitted when there are no warnings. Batch admission still rejects unknown relationship values.","items":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Stable machine string (relationship_normalized)."},"field":{"type":"string","description":"Input field the note applies to."},"message":{"type":"string","description":"Plain-words explanation, safe to show a person."}},"required":["code","field","message"]}},"enrichment":{"type":"string","enum":["pending","complete","failed"],"description":"Present when a background enrichment pass runs after the first answer. pending: poll get_eligibility for the richer payload; complete/failed: final."},"duration_ms":{"type":["integer","null"],"description":"Milliseconds the answering route took (portal replay or network). When no route answered, total time for the check. Null while pending or when an older row was never stamped. Published as duration_ms because latency_ms is a lab key stripped envelope-wide on MCP. Never PHI."},"failure_stage":{"type":["string","null"],"enum":["preflight","restore","probe","search","benefits","mapper","network","unknown",null],"description":"Coarse stage that failed: preflight, restore, probe, search, benefits, mapper, network, or unknown. Null on pending and on served checks. Derived from failCategory, hop, and errorClass. Never PHI."}},"required":["status","usable","why","error","error_code","retry","billing"]},"EligibilityBatchRequest":{"type":"object","additionalProperties":false,"properties":{"practice_id":{"type":"string","minLength":1,"maxLength":128,"description":"Practice returned by list_organizations. Required for a company-wide key; omitted for a practice-bound key."},"organization_id":{"type":"string","minLength":1,"maxLength":128,"deprecated":true,"description":"Deprecated alias for practice_id. If both are sent, they must match exactly."},"idempotency_key":{"type":"string","minLength":1,"maxLength":256,"description":"MCP retry key. REST callers use the Idempotency-Key header; if this JSON alias is also sent, the values must match."},"checks":{"type":"array","minItems":1,"maxItems":50,"description":"The day's book: 1–50 rows for this one practice, each with a client_reference_id and the same identity/date/service fields as a single check.","items":{"type":"object","additionalProperties":false,"properties":{"availity_payer_id":{"type":"string","enum":["00430D","65065","80314D","84103","ANTHEMXXDENTAL","WLPDEN"],"description":"Required with payer_id=availity. Select an insurer from list_payers request_capabilities.availity_payers. For Humana Dental, use 65065, or send payer_id=humana. The listed insurer IDs also work as eligibility payer_id aliases. Uses this practice's Availity login."},"client_reference_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._~:-]{0,127}$","description":"Opaque appointment or schedule-row ID. Do not put a patient name, member ID, or other PHI here. Echoed unchanged in batch status."},"payer_id":{"type":"string","minLength":1,"maxLength":128,"description":"Exact id/eligibility_payer_id from list_payers. Never use vault_payer_id or mailbox_id."},"member_id":{"type":"string","minLength":1,"maxLength":256,"description":"Member/subscriber ID exactly as printed on the card."},"date_of_birth":{"type":"string","format":"date","description":"Subscriber date of birth, YYYY-MM-DD. A dependent row (relationship spouse, child or other with patient_date_of_birth) may leave it out; the payer's own rules then decide."},"first_name":{"type":"string","minLength":1,"maxLength":128,"description":"Subscriber first name as the payer has it."},"last_name":{"type":"string","minLength":1,"maxLength":128,"description":"Subscriber last name as the payer has it."},"relationship":{"type":"string","enum":["self","spouse","child","other"],"description":"Patient's relationship to the subscriber. Defaults to self; send with the patient_* fields for a dependent."},"patient_first_name":{"type":"string","minLength":1,"maxLength":128,"description":"Dependent patient's first name when the patient is not the subscriber."},"patient_last_name":{"type":"string","minLength":1,"maxLength":128,"description":"Dependent patient's last name when the patient is not the subscriber."},"patient_date_of_birth":{"type":"string","format":"date","description":"Dependent patient's date of birth, YYYY-MM-DD."},"date_of_service":{"type":"string","format":"date","description":"Scheduled date of service (YYYY-MM-DD). Required on canonical batches."},"service_type":{"type":"string","enum":["office_visit","specialist","imaging","physical_therapy","outpatient_surgery","dme","dental_prophy","dental_crown"],"default":"dental_prophy","description":"Benefit category to verify. Defaults to dental_prophy when omitted."},"zip_code":{"type":"string","minLength":1,"maxLength":16,"description":"Subscriber ZIP when the payer's search needs it; usually optional."},"address":{"type":"string","minLength":1,"maxLength":256,"description":"Member street address when the payer's search needs it; usually optional."},"subscriber_last_name":{"type":"string","minLength":1,"maxLength":128,"description":"Cardholder or subscriber last name when the payer's search needs it; usually optional. Distinct from last_name."},"force_refresh":{"type":"boolean","default":false,"description":"Skip any cached answer and go to the payer now. Costs a live check."}},"required":["client_reference_id","payer_id","member_id","first_name","last_name","date_of_service"],"if":{"properties":{"relationship":{"type":"string","enum":["spouse","child","other"]},"patient_date_of_birth":{"type":"string","format":"date"}},"required":["relationship","patient_date_of_birth"]},"then":{},"else":{"properties":{"date_of_birth":{"type":"string","format":"date"}},"required":["date_of_birth"]}}}},"required":["checks"]},"VerificationPreviewRequest":{"anyOf":[{"type":"object","additionalProperties":false,"properties":{"practice_id":{"type":"string","minLength":1,"maxLength":128,"description":"Practice returned by list_organizations. Required for a company-wide key; omitted for a practice-bound key."},"organization_id":{"type":"string","minLength":1,"maxLength":128,"deprecated":true,"description":"Deprecated alias for practice_id. If both are sent, they must match exactly."},"idempotency_key":{"type":"string","minLength":1,"maxLength":256,"description":"MCP retry key. REST callers use the Idempotency-Key header; if this JSON alias is also sent, the values must match."},"checks":{"type":"array","minItems":1,"maxItems":50,"description":"The day's book: 1–50 rows for this one practice, each with a client_reference_id and the same identity/date/service fields as a single check.","items":{"type":"object","additionalProperties":false,"properties":{"availity_payer_id":{"type":"string","enum":["00430D","65065","80314D","84103","ANTHEMXXDENTAL","WLPDEN"],"description":"Required with payer_id=availity. Select an insurer from list_payers request_capabilities.availity_payers. For Humana Dental, use 65065, or send payer_id=humana. The listed insurer IDs also work as eligibility payer_id aliases. Uses this practice's Availity login."},"client_reference_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._~:-]{0,127}$","description":"Opaque appointment or schedule-row ID. Do not put a patient name, member ID, or other PHI here. Echoed unchanged in batch status."},"payer_id":{"type":"string","minLength":1,"maxLength":128,"description":"Exact id/eligibility_payer_id from list_payers. Never use vault_payer_id or mailbox_id."},"member_id":{"type":"string","minLength":1,"maxLength":256,"description":"Member/subscriber ID exactly as printed on the card."},"date_of_birth":{"type":"string","format":"date","description":"Subscriber date of birth, YYYY-MM-DD. A dependent row (relationship spouse, child or other with patient_date_of_birth) may leave it out; the payer's own rules then decide."},"first_name":{"type":"string","minLength":1,"maxLength":128,"description":"Subscriber first name as the payer has it."},"last_name":{"type":"string","minLength":1,"maxLength":128,"description":"Subscriber last name as the payer has it."},"relationship":{"type":"string","enum":["self","spouse","child","other"],"description":"Patient's relationship to the subscriber. Defaults to self; send with the patient_* fields for a dependent."},"patient_first_name":{"type":"string","minLength":1,"maxLength":128,"description":"Dependent patient's first name when the patient is not the subscriber."},"patient_last_name":{"type":"string","minLength":1,"maxLength":128,"description":"Dependent patient's last name when the patient is not the subscriber."},"patient_date_of_birth":{"type":"string","format":"date","description":"Dependent patient's date of birth, YYYY-MM-DD."},"date_of_service":{"type":"string","format":"date","description":"Scheduled date of service (YYYY-MM-DD). Required on canonical batches."},"service_type":{"type":"string","enum":["office_visit","specialist","imaging","physical_therapy","outpatient_surgery","dme","dental_prophy","dental_crown"],"default":"dental_prophy","description":"Benefit category to verify. Defaults to dental_prophy when omitted."},"zip_code":{"type":"string","minLength":1,"maxLength":16,"description":"Subscriber ZIP when the payer's search needs it; usually optional."},"address":{"type":"string","minLength":1,"maxLength":256,"description":"Member street address when the payer's search needs it; usually optional."},"subscriber_last_name":{"type":"string","minLength":1,"maxLength":128,"description":"Cardholder or subscriber last name when the payer's search needs it; usually optional. Distinct from last_name."},"force_refresh":{"type":"boolean","default":false,"description":"Skip any cached answer and go to the payer now. Costs a live check."}},"required":["client_reference_id","payer_id","date_of_service"]}}},"required":["checks"]},{"type":"object","additionalProperties":false,"properties":{"availity_payer_id":{"type":"string","enum":["00430D","65065","80314D","84103","ANTHEMXXDENTAL","WLPDEN"],"description":"Required with payer_id=availity. Select an insurer from list_payers request_capabilities.availity_payers. For Humana Dental, use 65065, or send payer_id=humana. The listed insurer IDs also work as eligibility payer_id aliases. Uses this practice's Availity login."},"client_reference_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._~:-]{0,127}$","description":"Opaque appointment or schedule-row ID. Do not put a patient name, member ID, or other PHI here. Echoed unchanged in batch status."},"payer_id":{"type":"string","minLength":1,"maxLength":128,"description":"Exact id/eligibility_payer_id from list_payers. Never use vault_payer_id or mailbox_id."},"member_id":{"type":"string","minLength":1,"maxLength":256,"description":"Member/subscriber ID exactly as printed on the card."},"date_of_birth":{"type":"string","format":"date","description":"Subscriber date of birth, YYYY-MM-DD. A dependent row (relationship spouse, child or other with patient_date_of_birth) may leave it out; the payer's own rules then decide."},"first_name":{"type":"string","minLength":1,"maxLength":128,"description":"Subscriber first name as the payer has it."},"last_name":{"type":"string","minLength":1,"maxLength":128,"description":"Subscriber last name as the payer has it."},"relationship":{"type":"string","enum":["self","spouse","child","other"],"description":"Patient's relationship to the subscriber. Defaults to self; send with the patient_* fields for a dependent."},"patient_first_name":{"type":"string","minLength":1,"maxLength":128,"description":"Dependent patient's first name when the patient is not the subscriber."},"patient_last_name":{"type":"string","minLength":1,"maxLength":128,"description":"Dependent patient's last name when the patient is not the subscriber."},"patient_date_of_birth":{"type":"string","format":"date","description":"Dependent patient's date of birth, YYYY-MM-DD."},"date_of_service":{"type":"string","format":"date","description":"Scheduled date of service (YYYY-MM-DD). Required on canonical batches."},"service_type":{"type":"string","enum":["office_visit","specialist","imaging","physical_therapy","outpatient_surgery","dme","dental_prophy","dental_crown"],"default":"dental_prophy","description":"Benefit category to verify. Defaults to dental_prophy when omitted."},"zip_code":{"type":"string","minLength":1,"maxLength":16,"description":"Subscriber ZIP when the payer's search needs it; usually optional."},"address":{"type":"string","minLength":1,"maxLength":256,"description":"Member street address when the payer's search needs it; usually optional."},"subscriber_last_name":{"type":"string","minLength":1,"maxLength":128,"description":"Cardholder or subscriber last name when the payer's search needs it; usually optional. Distinct from last_name."},"force_refresh":{"type":"boolean","default":false,"description":"Skip any cached answer and go to the payer now. Costs a live check."},"practice_id":{"type":"string","minLength":1,"maxLength":128,"description":"Practice returned by list_organizations. Required for a company-wide key; omitted for a practice-bound key."},"organization_id":{"type":"string","minLength":1,"maxLength":128,"deprecated":true,"description":"Deprecated alias for practice_id. If both are sent, they must match exactly."},"procedure_code":{"type":"string","maxLength":64,"pattern":"^\\s*[dD][0-9]{4}\\s*$","description":"Optional requested CDT for a single live nevada_medicaid check only. Trimmed and uppercased to D plus four digits; omitted keeps the worker's D0120 default. Not supported for other payers, sandbox, network, or batch checks."}},"required":["payer_id"]}]},"VerificationPreviewResponse":{"type":"object","additionalProperties":false,"description":"Free practice-specific admission review; no member lookup, Connect, MFA, or billing occurs.","properties":{"version":{"type":"string","const":"1","description":"Preview contract version."},"practice_id":{"type":"string","description":"Practice selected for every row in this preview."},"assessed_at":{"type":"string","format":"date-time","description":"Time this day book was assessed."},"summary":{"type":"object","additionalProperties":false,"description":"Number of appointment rows in each admission disposition.","properties":{"proceed":{"type":"integer","minimum":0,"description":"Number of rows with disposition proceed."},"wait":{"type":"integer","minimum":0,"description":"Number of rows with disposition wait."},"action_required":{"type":"integer","minimum":0,"description":"Number of rows with disposition action_required."},"input_required":{"type":"integer","minimum":0,"description":"Number of rows with disposition input_required."},"unsupported":{"type":"integer","minimum":0,"description":"Number of rows with disposition unsupported."}},"required":["proceed","wait","action_required","input_required","unsupported"]},"actions":{"type":"array","maxItems":50,"description":"Grouped connection or input tasks, with the appointment rows affected by each task.","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Identifier of this grouped task."},"mailbox_id":{"type":"string","description":"Login group whose task affects these rows."},"payer_ids":{"type":"array","items":{"type":"string"},"description":"Exact payer books affected by the task."},"reason":{"type":"string","description":"Machine-readable task reason."},"message":{"type":"string","description":"Customer explanation of the task."},"action":{"type":"object","additionalProperties":false,"description":"Next action and the party responsible for completing it.","properties":{"owner":{"type":"string","enum":["none","practice","customer","veraxus"],"description":"Party responsible for the action; none means no action is required."},"kind":{"type":"string","enum":["none","refresh_status","store_credentials","connect","enter_code","approve_push","correct_input"],"description":"Typed next action; an eligibility request never asks for credentials or a human code."},"href":{"type":["string","null"],"description":"Allowed console path for a practice action, or null."},"field":{"type":["string","null"],"description":"Request field to correct, or null; never contains a patient value."}},"required":["owner","kind","href","field"]},"affected_count":{"type":"integer","minimum":1,"description":"Number of appointment rows affected by this task."},"client_reference_ids":{"type":"array","items":{"type":["string","null"]},"description":"Customer appointment references for affected rows."},"indexes":{"type":"array","items":{"type":"integer","minimum":0,"maximum":49},"description":"Zero-based positions of affected rows in the submitted day book."}},"required":["id","mailbox_id","payer_ids","reason","message","action","affected_count","client_reference_ids","indexes"]}},"results":{"type":"array","maxItems":50,"description":"Admission decision for each original appointment row.","items":{"type":"object","additionalProperties":false,"properties":{"index":{"type":"integer","minimum":0,"maximum":49,"description":"Zero-based position in the original request."},"client_reference_id":{"type":["string","null"],"description":"Customer appointment reference, or null."},"payer_id":{"type":"string","description":"Exact canonical payer book for this row."},"verification_admission":{"type":"object","additionalProperties":false,"description":"Permission to attempt the exact practice/book/request. It does not attest a patient match or completed benefits. Submission rechecks it before dispatch.","properties":{"version":{"type":"string","const":"1","description":"Admission contract version."},"practice_id":{"type":"string","description":"Exact practice this decision applies to."},"payer_id":{"type":"string","description":"Exact canonical payer book; sibling books retain separate admission."},"mailbox_id":{"type":"string","description":"Shared-login action group; does not merge payer sessions."},"disposition":{"type":"string","enum":["proceed","wait","action_required","input_required","unsupported"],"description":"Permission to attempt, wait for evidence, complete setup, correct input, or use another supported source."},"reason":{"type":"string","description":"Machine-readable reason for the decision."},"message":{"type":"string","description":"Customer explanation of the decision."},"action":{"type":"object","additionalProperties":false,"description":"Next action and the party responsible for completing it.","properties":{"owner":{"type":"string","enum":["none","practice","customer","veraxus"],"description":"Party responsible for the action; none means no action is required."},"kind":{"type":"string","enum":["none","refresh_status","store_credentials","connect","enter_code","approve_push","correct_input"],"description":"Typed next action; an eligibility request never asks for credentials or a human code."},"href":{"type":["string","null"],"description":"Allowed console path for a practice action, or null."},"field":{"type":["string","null"],"description":"Request field to correct, or null; never contains a patient value."}},"required":["owner","kind","href","field"]},"checked_at":{"type":["string","null"],"format":"date-time","description":"Authenticated evidence timestamp, or null when none is available."},"assessed_at":{"type":"string","format":"date-time","description":"Time this admission decision was assessed."},"valid_until":{"type":"string","format":"date-time","description":"Decision freshness deadline; dispatch still rechecks admission."}},"required":["version","practice_id","payer_id","mailbox_id","disposition","reason","message","action","checked_at","assessed_at","valid_until"]}},"required":["index","client_reference_id","payer_id","verification_admission"]}}},"required":["version","practice_id","assessed_at","summary","actions","results"]},"EligibilityBatchLegacyRequest":{"type":"object","additionalProperties":false,"properties":{"practice_id":{"type":"string","minLength":1,"maxLength":128,"description":"Practice returned by list_organizations. Required for a company-wide key; omitted for a practice-bound key."},"organization_id":{"type":"string","minLength":1,"maxLength":128,"deprecated":true,"description":"Deprecated alias for practice_id. If both are sent, they must match exactly."},"idempotency_key":{"type":"string","minLength":1,"maxLength":256,"description":"MCP retry key. REST callers use the Idempotency-Key header; if this JSON alias is also sent, the values must match."},"checks":{"type":"array","minItems":1,"maxItems":50,"description":"The day's book: 1–50 rows for this one practice, each with a client_reference_id and the same identity/date/service fields as a single check.","items":{"type":"object","additionalProperties":false,"properties":{"availity_payer_id":{"type":"string","enum":["00430D","65065","80314D","84103","ANTHEMXXDENTAL","WLPDEN"],"description":"Required with payer_id=availity. Select an insurer from list_payers request_capabilities.availity_payers. For Humana Dental, use 65065, or send payer_id=humana. The listed insurer IDs also work as eligibility payer_id aliases. Uses this practice's Availity login."},"client_reference_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._~:-]{0,127}$","description":"Opaque appointment or schedule-row ID. Do not put a patient name, member ID, or other PHI here. Echoed unchanged in batch status."},"payer_id":{"type":"string","minLength":1,"maxLength":128,"description":"Exact id/eligibility_payer_id from list_payers. Never use vault_payer_id or mailbox_id."},"member_id":{"type":"string","minLength":1,"maxLength":256,"description":"Member/subscriber ID exactly as printed on the card."},"date_of_birth":{"type":"string","format":"date","description":"Subscriber date of birth, YYYY-MM-DD. A dependent row (relationship spouse, child or other with patient_date_of_birth) may leave it out; the payer's own rules then decide."},"first_name":{"type":"string","minLength":1,"maxLength":128,"description":"Subscriber first name as the payer has it."},"last_name":{"type":"string","minLength":1,"maxLength":128,"description":"Subscriber last name as the payer has it."},"relationship":{"type":"string","enum":["self","spouse","child","other"],"description":"Patient's relationship to the subscriber. Defaults to self; send with the patient_* fields for a dependent."},"patient_first_name":{"type":"string","minLength":1,"maxLength":128,"description":"Dependent patient's first name when the patient is not the subscriber."},"patient_last_name":{"type":"string","minLength":1,"maxLength":128,"description":"Dependent patient's last name when the patient is not the subscriber."},"patient_date_of_birth":{"type":"string","format":"date","description":"Dependent patient's date of birth, YYYY-MM-DD."},"date_of_service":{"type":"string","format":"date","description":"Scheduled date of service (YYYY-MM-DD). Required on canonical batches."},"service_type":{"type":"string","enum":["office_visit","specialist","imaging","physical_therapy","outpatient_surgery","dme","dental_prophy","dental_crown"],"default":"dental_prophy","description":"Benefit category to verify. Defaults to dental_prophy when omitted."},"zip_code":{"type":"string","minLength":1,"maxLength":16,"description":"Subscriber ZIP when the payer's search needs it; usually optional."},"address":{"type":"string","minLength":1,"maxLength":256,"description":"Member street address when the payer's search needs it; usually optional."},"subscriber_last_name":{"type":"string","minLength":1,"maxLength":128,"description":"Cardholder or subscriber last name when the payer's search needs it; usually optional. Distinct from last_name."},"force_refresh":{"type":"boolean","default":false,"description":"Skip any cached answer and go to the payer now. Costs a live check."}},"required":["payer_id","member_id","first_name","last_name"],"if":{"properties":{"relationship":{"type":"string","enum":["spouse","child","other"]},"patient_date_of_birth":{"type":"string","format":"date"}},"required":["relationship","patient_date_of_birth"]},"then":{},"else":{"properties":{"date_of_birth":{"type":"string","format":"date"}},"required":["date_of_birth"]}}}},"required":["checks"]},"EligibilityBatchResponse":{"type":"object","additionalProperties":false,"properties":{"actions":{"type":"array","maxItems":50,"description":"Grouped connection or input tasks, with the appointment rows affected by each task.","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Identifier of this grouped task."},"mailbox_id":{"type":"string","description":"Login group whose task affects these rows."},"payer_ids":{"type":"array","items":{"type":"string"},"description":"Exact payer books affected by the task."},"reason":{"type":"string","description":"Machine-readable task reason."},"message":{"type":"string","description":"Customer explanation of the task."},"action":{"type":"object","additionalProperties":false,"description":"Next action and the party responsible for completing it.","properties":{"owner":{"type":"string","enum":["none","practice","customer","veraxus"],"description":"Party responsible for the action; none means no action is required."},"kind":{"type":"string","enum":["none","refresh_status","store_credentials","connect","enter_code","approve_push","correct_input"],"description":"Typed next action; an eligibility request never asks for credentials or a human code."},"href":{"type":["string","null"],"description":"Allowed console path for a practice action, or null."},"field":{"type":["string","null"],"description":"Request field to correct, or null; never contains a patient value."}},"required":["owner","kind","href","field"]},"affected_count":{"type":"integer","minimum":1,"description":"Number of appointment rows affected by this task."},"client_reference_ids":{"type":"array","items":{"type":["string","null"]},"description":"Customer appointment references for affected rows."},"indexes":{"type":"array","items":{"type":"integer","minimum":0,"maximum":49},"description":"Zero-based positions of affected rows in the submitted day book."}},"required":["id","mailbox_id","payer_ids","reason","message","action","affected_count","client_reference_ids","indexes"]}},"workflow_summary":{"type":"object","additionalProperties":false,"description":"Number of appointment rows in each admission disposition.","properties":{"proceed":{"type":"integer","minimum":0,"description":"Number of rows with disposition proceed."},"wait":{"type":"integer","minimum":0,"description":"Number of rows with disposition wait."},"action_required":{"type":"integer","minimum":0,"description":"Number of rows with disposition action_required."},"input_required":{"type":"integer","minimum":0,"description":"Number of rows with disposition input_required."},"unsupported":{"type":"integer","minimum":0,"description":"Number of rows with disposition unsupported."}},"required":["proceed","wait","action_required","input_required","unsupported"]},"workflow_state":{"type":"string","enum":["running","waiting","complete"],"description":"Where the whole batch stands. running: at least one row is queued or with the payer. waiting: nothing is running and every unfinished row is held on a login or a status read; actions names the login, the reason and who owns the fix. complete: no row is pending. status and summary keep their meaning."},"workflow_counts":{"type":"object","additionalProperties":false,"description":"Number of rows in each row-level workflow_state.","properties":{"queued":{"type":"integer","minimum":0,"description":"Rows with workflow_state queued."},"running":{"type":"integer","minimum":0,"description":"Rows with workflow_state running."},"waiting":{"type":"integer","minimum":0,"description":"Rows with workflow_state waiting."},"waiting_for_action":{"type":"integer","minimum":0,"description":"Rows with workflow_state waiting_for_action."},"completed":{"type":"integer","minimum":0,"description":"Rows with workflow_state completed."},"failed":{"type":"integer","minimum":0,"description":"Rows with workflow_state failed."},"cancelled":{"type":"integer","minimum":0,"description":"Rows with workflow_state cancelled."},"rejected":{"type":"integer","minimum":0,"description":"Rows with workflow_state rejected."}},"required":["queued","running","waiting","waiting_for_action","completed","failed","cancelled","rejected"]},"batch_id":{"type":"string","description":"Durable batch id. Poll GET /eligibility/batches/{batch_id} / get_eligibility_batch with it."},"practice_id":{"type":"string","description":"Practice the whole batch ran for. One batch is always one practice."},"organization_id":{"type":"string","deprecated":true,"description":"Deprecated alias for practice_id; same value."},"created_at":{"type":"string","format":"date-time","description":"UTC creation time of this durable receipt."},"expires_at":{"type":"string","format":"date-time","description":"UTC time after which the receipt and its idempotency key may be reused."},"status":{"type":"string","enum":["pending","complete"],"description":"pending: rows are still dispatching — poll with Retry-After. complete: every row is terminal."},"submitted_count":{"type":"integer","minimum":0,"maximum":50,"description":"Rows received in the submission."},"accepted_count":{"type":"integer","minimum":0,"maximum":50,"description":"Rows admitted for dispatch."},"rejected_count":{"type":"integer","minimum":0,"maximum":50,"description":"Rows rejected at intake (invalid input); they appear in results with status failed and served_by null."},"active_limit_per_practice":{"type":"integer","const":50,"description":"Cap on nonterminal bulk checks per practice; other practices under the same customer have their own independent cap."},"summary":{"type":"object","additionalProperties":false,"description":"Row counts by outcome. usable counts rows with why live; the batch is done when pending is 0.","properties":{"pending":{"type":"integer","minimum":0,"description":"Rows still running."},"usable":{"type":"integer","minimum":0,"description":"Rows served with reported benefit facts (why live); active may be null when coverage is unknown."},"failed":{"type":"integer","minimum":0,"description":"Rows that terminated without usable benefits."},"rejected":{"type":"integer","minimum":0,"description":"Rows rejected at intake."}},"required":["pending","usable","failed","rejected"]},"results":{"type":"array","maxItems":50,"description":"One row per submitted check, in submission order, each echoing your client_reference_id. Same shape as a single check plus index/client_reference_id/check_id.","items":{"type":"object","additionalProperties":false,"properties":{"verification_admission":{"type":"object","additionalProperties":false,"description":"Permission to attempt the exact practice/book/request. It does not attest a patient match or completed benefits. Submission rechecks it before dispatch.","properties":{"version":{"type":"string","const":"1","description":"Admission contract version."},"practice_id":{"type":"string","description":"Exact practice this decision applies to."},"payer_id":{"type":"string","description":"Exact canonical payer book; sibling books retain separate admission."},"mailbox_id":{"type":"string","description":"Shared-login action group; does not merge payer sessions."},"disposition":{"type":"string","enum":["proceed","wait","action_required","input_required","unsupported"],"description":"Permission to attempt, wait for evidence, complete setup, correct input, or use another supported source."},"reason":{"type":"string","description":"Machine-readable reason for the decision."},"message":{"type":"string","description":"Customer explanation of the decision."},"action":{"type":"object","additionalProperties":false,"description":"Next action and the party responsible for completing it.","properties":{"owner":{"type":"string","enum":["none","practice","customer","veraxus"],"description":"Party responsible for the action; none means no action is required."},"kind":{"type":"string","enum":["none","refresh_status","store_credentials","connect","enter_code","approve_push","correct_input"],"description":"Typed next action; an eligibility request never asks for credentials or a human code."},"href":{"type":["string","null"],"description":"Allowed console path for a practice action, or null."},"field":{"type":["string","null"],"description":"Request field to correct, or null; never contains a patient value."}},"required":["owner","kind","href","field"]},"checked_at":{"type":["string","null"],"format":"date-time","description":"Authenticated evidence timestamp, or null when none is available."},"assessed_at":{"type":"string","format":"date-time","description":"Time this admission decision was assessed."},"valid_until":{"type":"string","format":"date-time","description":"Decision freshness deadline; dispatch still rechecks admission."}},"required":["version","practice_id","payer_id","mailbox_id","disposition","reason","message","action","checked_at","assessed_at","valid_until"]},"current_dental_insurance":{"type":"object","additionalProperties":false,"properties":{"requested_service_date":{"type":"string","format":"date"},"procedure_code":{"type":"string","pattern":"^D[0-9]{4}$"},"current_coverage_proven":{"const":true},"coverage_name":{"type":"string","maxLength":8192},"effective_date":{"type":"string","format":"date","description":"First day of the eligibility span the portal returned for the dates asked about. Not asserted to be the coverage start date."},"end_date":{"type":"string","format":"date","description":"Last day of the eligibility span the portal returned for the dates asked about. Not asserted to be the coverage end date."},"decision_date":{"type":["string","null"],"format":"date","description":"The portal's Date of Decision for this coverage row, from the eligibility summary. Null when the portal shows none. Not asserted to be the coverage start date."},"redetermination_date":{"type":["string","null"],"format":"date","description":"The portal's Redetermination Date for the member, from the eligibility summary. Null when the portal shows none. Not asserted to be the coverage start date."},"program":{"enum":["medicaid","check_up",null]},"delivery_model":{"enum":["fee_for_service","managed_care",null]},"dental_administrator":{"enum":["LIBERTY Dental",null]}},"required":["requested_service_date","procedure_code","current_coverage_proven","coverage_name","effective_date","end_date","decision_date","redetermination_date","program","delivery_model","dental_administrator"],"description":"Nevada selected Dental enrollment for the original requested service date and CDT, only when its canonical current benefit proof is admitted. Program, delivery model and dental administrator stay null when not proved; medical managed-care labels never assign the dental administrator. Stored checks retain the original requested-day result. effective_date and end_date are the eligibility span the portal returned for the dates asked about, and are not asserted to be the coverage start or end. decision_date is the portal's Date of Decision for that coverage row, and redetermination_date is the portal's Redetermination Date for the member; each is null when the portal shows none. None of these dates is asserted to be the coverage start date."},"published_provider_fee_schedules":{"type":"array","maxItems":4096,"items":{"type":"object","additionalProperties":false,"properties":{"family_entry_index":{"type":"integer","minimum":0,"maximum":4096},"source_family":{"const":"publishedFees"},"requested_code":{"anyOf":[{"type":"string","pattern":"^D[0-9]{4}$"},{"type":"null"}]},"requested_service_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"amount_meaning":{"const":"provider_reimbursement"},"provider_scope_only":{"const":true},"patient_applicability_proven":{"const":false},"patient_cost_share_proven":{"const":false},"schedule_source":{"const":"nevada_published_fee_schedule"},"source_url":{"enum":["https://www.nevadamedicaid.nv.gov/siteassets/content/resources/rates/pt-22-fee-schedule--072026.xlsx","https://www.nevadamedicaid.nv.gov/siteassets/content/resources/rates/pt-22-id-waiver-fee-schedule-072026.xlsx"]},"schedule_scope":{"enum":["fee_for_service_dentist","fee_for_service_id_waiver"]},"as_of":{"const":"2026-07"},"fetched_at":{"type":"string","format":"date-time"},"public_file_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"sheet":{"const":"Sheet1"},"columns":{"type":"array","minItems":6,"maxItems":6,"items":{"type":"string","maxLength":8192}},"row_count":{"type":"integer","minimum":0,"maximum":4096},"unique_codes":{"type":"integer","minimum":0,"maximum":4096},"zero_listed_rates":{"type":"integer","minimum":0,"maximum":4096},"zero_rate_policy":{"const":"62_percent_usual_and_customary_unless_medicaid_policy_states_otherwise"},"member_applicability":{"const":"unproven"},"rows":{"type":"array","maxItems":4096,"items":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","maxLength":8192},"procedure_code":{"type":"string","maxLength":8192},"description":{"type":"string","maxLength":8192},"provider_allowed_amount":{"type":["number","null"],"minimum":0},"remaining":{"type":"null"},"patient_copay":{"type":"null"},"covered":{"type":"null"},"prior_auth":{"type":"null"},"modifier":{"type":["string","null"],"maxLength":8192},"rate_type":{"enum":["DEF","DNT","DNI"]},"listed_rate":{"type":"number","minimum":0},"usual_and_customary_pct":{"enum":[62,null]},"rate_begin_date":{"type":"string","format":"date"},"schedule_scope":{"enum":["fee_for_service_dentist","fee_for_service_id_waiver"]}},"required":["code","procedure_code","description","provider_allowed_amount","remaining","patient_copay","covered","prior_auth","modifier","rate_type","listed_rate","usual_and_customary_pct","rate_begin_date","schedule_scope"]}}},"required":["family_entry_index","source_family","requested_code","requested_service_date","amount_meaning","provider_scope_only","patient_applicability_proven","patient_cost_share_proven","schedule_source","source_url","schedule_scope","as_of","fetched_at","public_file_sha256","sheet","columns","row_count","unique_codes","zero_listed_rates","zero_rate_policy","member_applicability","rows"]},"description":"Full official Nevada published provider reimbursement schedules, separately scoped to general dentist and ID waiver. All source rows and zero-rate/U&C policy are retained. These public rates do not establish patient applicability, coverage or cost share; requested date/code are original command context only."},"provider_fee_schedules":{"type":"array","maxItems":4096,"items":{"type":"object","additionalProperties":false,"properties":{"family_entry_index":{"type":"integer","minimum":0,"maximum":4096},"source_family":{"const":"authenticatedFees"},"requested_code":{"type":"string","pattern":"^D[0-9]{4}$"},"requested_service_date":{"type":"string","format":"date"},"service_category":{"enum":["Dental - Adult","Dental - Child"]},"scope_origin":{"const":"command_scope_only"},"amount_meaning":{"const":"provider_reimbursement"},"provider_scope_only":{"const":true},"patient_applicability_proven":{"const":false},"patient_cost_share_proven":{"const":false},"columns":{"type":"array","minItems":7,"maxItems":7,"items":{"type":"string","maxLength":8192}},"row_count":{"type":"integer","minimum":0,"maximum":4096},"rows":{"type":"array","maxItems":4096,"items":{"type":"object","additionalProperties":false,"properties":{"procedure_code":{"type":"string","maxLength":8192},"description":{"type":"string","maxLength":8192},"procedure_literal":{"type":"string","maxLength":8192},"provider_type":{"type":"string","maxLength":8192},"provider_specialty":{"type":"string","maxLength":8192},"modifier":{"type":"string","maxLength":8192},"fee_amount_literal":{"type":"string","maxLength":8192},"age_restrictions_literal":{"type":"string","maxLength":8192},"effective_date_literal":{"type":"string","maxLength":8192},"provider_allowed_amount":{"type":"number","minimum":0},"age_restriction_from":{"type":"integer","minimum":0,"maximum":4096},"age_restriction_through":{"type":"integer","minimum":0,"maximum":4096},"effective_from":{"type":"string","format":"date"},"effective_through":{"type":"string","format":"date"}},"required":["procedure_code","description","procedure_literal","provider_type","provider_specialty","modifier","fee_amount_literal","age_restrictions_literal","effective_date_literal"]}}},"required":["family_entry_index","source_family","requested_code","requested_service_date","service_category","scope_origin","amount_meaning","provider_scope_only","patient_applicability_proven","patient_cost_share_proven","columns","row_count","rows"]},"description":"Nevada provider reimbursement rows for the requested code, with full provider type/specialty/modifier, age restrictions and fee effective periods. Adult/Child search categories do not establish patient applicability, coverage, plan assignment or cost share. The requested service date is command context; these rates are not patient copays."},"insurance_types":{"type":"object","additionalProperties":false,"properties":{"requested_service_date":{"type":["string","null"],"format":"date"},"current_coverage_proven":{"const":false},"dental_administrator":{"type":"null"},"redetermination_date":{"type":["string","null"],"format":"date","description":"The portal's Redetermination Date for the member, from the eligibility summary. Published only on a check with current coverage proof; null otherwise and when the portal shows none. Not asserted to be the coverage start date."},"enrollments":{"type":"array","maxItems":4096,"items":{"type":"object","additionalProperties":false,"properties":{"family_entry_index":{"type":"integer","minimum":0,"maximum":4096},"source_family":{"enum":["summary","coverage","member"]},"row_index":{"type":"integer","minimum":0,"maximum":4096},"coverage_name":{"type":["string","null"],"maxLength":8192},"effective_date":{"type":["string","null"],"format":"date","description":"First day of the span the portal returned on this row. On an eligibility summary row that is the eligibility span for the dates asked about. Not asserted to be the coverage start date."},"end_date":{"type":["string","null"],"format":"date","description":"Last day of the span the portal returned on this row. On an eligibility summary row that is the eligibility span for the dates asked about. Not asserted to be the coverage end date."},"decision_date":{"type":["string","null"],"format":"date","description":"The portal's Date of Decision for this coverage row, on eligibility summary rows. Published only on a check with current coverage proof; null otherwise, on rows from other pages, and when the portal shows none. Not asserted to be the coverage start date."},"program":{"enum":["medicaid",null]},"delivery_model":{"enum":["fee_for_service",null]},"benefit_scope":{"const":"unproven"}},"required":["family_entry_index","source_family","row_index","coverage_name","effective_date","end_date","decision_date","program","delivery_model","benefit_scope"]}},"managed_care_labels":{"type":"array","maxItems":4096,"items":{"type":"object","additionalProperties":false,"properties":{"family_entry_index":{"type":"integer","minimum":0,"maximum":4096},"row_index":{"type":"integer","minimum":0,"maximum":4096},"type":{"type":["string","null"],"maxLength":8192},"benefit_plan":{"type":["string","null"],"maxLength":8192}},"required":["family_entry_index","row_index","type","benefit_plan"]}},"managed_care_organizations":{"type":"array","maxItems":4096,"items":{"type":"object","additionalProperties":false,"properties":{"family_entry_index":{"type":"integer","minimum":0,"maximum":4096},"row_index":{"type":"integer","minimum":0,"maximum":4096},"organization":{"type":["string","null"],"maxLength":8192}},"required":["family_entry_index","row_index","organization"]}}},"required":["requested_service_date","current_coverage_proven","dental_administrator","redetermination_date","enrollments","managed_care_labels","managed_care_organizations"],"description":"Nevada's returned dated enrollment records, when available. Separate from benefit usability: current_coverage_proven remains false. Managed-care labels and organizations are separate source repeaters and do not establish dental assignment. Unknown program or delivery model stays null. On each row, effective_date and end_date are the span the portal returned for that row; on an eligibility summary row that is the eligibility span for the dates asked about. They are not asserted to be the coverage start or end. decision_date is the portal's Date of Decision for an eligibility summary row, and redetermination_date is the portal's Redetermination Date for the member; both are published only on a check with current coverage proof and are null otherwise or when the portal shows none. None of these dates is asserted to be the coverage start date."},"id":{"type":"string","description":"Check id (chk_…). Poll GET /eligibility/{id} / get_eligibility with it."},"request_identity":{"type":["object","null"],"additionalProperties":false,"description":"On GET-by-id only: proof from the unique valid complete unexpired single-check idempotency receipt for this exact tenant, practice and check. Null when absent, invalid or ambiguous; do not infer patient identity from the masked member reference. Client recipe is the existing eligibilityIdempotencyPayload(single, original request) then UTF-8 SHA256 of recursively key-sorted JSON: kind='single'; payer_id/payerId, member_id/memberId, date_of_service/dateOfService, service_type/serviceType, date_of_birth/dateOfBirth, first_name/firstName, last_name/lastName, relationship, patient_first_name/patientFirstName, patient_last_name/patientLastName, patient_date_of_birth/patientDateOfBirth, zip_code/zipCode, address, subscriber_last_name/subscriberLastName; client_reference_id/clientReferenceId/client_reference/clientReference; raw270; practice_id/practiceId/organization_id/organizationId. First non-nullish alias wins, otherwise null; values unchanged. sandbox is true only for boolean true, string 'true', or wire='harness'; force_refresh is Boolean(force_refresh ?? forceRefresh). availity_payer_id is omitted unless either availity alias is defined, otherwise String(selected alias).trim(). procedure_code is omitted unless supplied, otherwise all defined procedure aliases must be valid strings, trimmed/uppercased CDT D plus four digits and agree; existing requested-CDT scope restrictions still apply. For X12 the original validated door.raw270 overrides raw270. Recursively sort object keys with JavaScript string sort, omit undefined object properties, keep array order and JSON.stringify primitive values; SHA256 lowercase hex. Never fill omitted dates/names from derived result fields. This proves the original request, not inferred current policy applicability; retain and compare the original request and owning practice binding.","properties":{"kind":{"type":"string","enum":["eligibility_idempotency_v1"]},"payload_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","example":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}},"required":["kind","payload_sha256"]},"practice_id":{"type":"string","description":"Practice this check ran for. The canonical scope field."},"organization_id":{"type":"string","deprecated":true,"description":"Deprecated alias for practice_id; same value."},"payer_id":{"type":"string","description":"Catalog payer id the check ran against (the id/eligibility_payer_id from GET /payers)."},"status":{"type":"string","enum":["pending","ok","inactive","failed"],"description":"pending: still running, poll by id. ok: served. inactive: served and coverage is terminated. failed: the check did not serve — read why for the reason and retry for what to do."},"usable":{"type":"boolean","description":"True only when why is live: benefit holds reported facts. Coverage is established only when active is explicitly true or false; null is unknown. When false, benefit is null — act on why instead."},"why":{"type":"string","enum":["live","needs_code","reconnect","payer_down","member_not_found","server_error","incomplete","invalid_request","cancelled"],"description":"The one field to branch on. live: usable benefits in benefit. needs_code: a one-time code is owed — submit it with complete_portal_mfa (Aetna is the exception: list_portal_mfa_challenges then complete_aetna_portal_mfa with the challenge id and generation), then re-run; do not reconnect. reconnect: recover the portal login with connect_portal_login using the saved credentials; no code is pending. A human code is required only if recovery returns needs_code. payer_down: payer side is down — retry later, not billed. member_not_found: the identity fields did not match a member — fix them and re-run (billed). server_error: our side, still pending, or a guarded automatic reconnect is in progress — retry or poll later, not billed, and do not start another Connect. incomplete: verification could not be completed — not billed; read error_code and failure_stage. invalid_request: the input was rejected before any payer call. cancelled: you cancelled this batch check before any payer call — not billed, and never a payer or login verdict."},"served_by":{"type":["string","null"],"enum":["payer_portal","eligibility_network",null],"description":"Which leg answered this check: payer_portal is a live payer-portal harvest, eligibility_network is a relayed X12 270/271. Null while status is pending and on failed checks — no leg served data, so there is nothing to attribute. Sandbox checks report payer_portal. Read this field to attribute a result; raw271 does not indicate the leg (see raw271)."},"auth_status":{"type":"string","enum":["ok","reauthentication_required","eligibility_network"],"description":"Health of the serving login: ok, reauthentication_required (the saved portal session needs recovery; this does not establish that MFA is required), or eligibility_network only when the network leg actually filled this row. Login health, not provenance — read served_by to attribute a result."},"session":{"type":"object","additionalProperties":false,"description":"State of this payer's saved portal login session. reconnecting means the guarded automatic email-code sign-in is in progress and the check should be polled. mfa_required true means a one-time code is owed now (see portal_login.complete_with); status expired means the session needs recovery through connect_portal_login; it does not mean a code is owed.","properties":{"status":{"type":"string","description":"Session state: e.g. code_required, expired, not_applicable."},"mfa_expired":{"type":"boolean","description":"Legacy session-expiry flag. Recover through connect_portal_login; only mfa_required true establishes that a code is owed."},"mfa_required":{"type":"boolean","description":"True when a one-time code is owed right now."},"mfa_required_at":{"type":["string","null"],"description":"UTC time the code became owed; null when none is owed."}},"required":["status","mfa_expired","mfa_required","mfa_required_at"]},"portal_login":{"type":"object","additionalProperties":false,"description":"The saved portal login behind this payer. status matches GET /v1/portal-logins. legacy_status keeps the previous vocabulary (ready, needs_human, portal_down, not_connected, none) for one release.","properties":{"status":{"type":"string","enum":["ready","reconnecting","needs_code","confirmation_pending","expired","not_connected","credentials_invalid","locked","portal_outage","quarantined","status_unknown","vault_error","none"],"description":"Same enum as GET /v1/portal-logins, plus none when this payer uses no portal login. reconnecting is poll-only and never asks the caller for a password or code."},"legacy_status":{"type":"string","enum":["ready","needs_human","portal_down","not_connected","none"],"description":"Previous portal_login.status vocabulary. Present for one release."},"message":{"type":["string","null"],"description":"Plain-words instruction safe to show the office."},"start_with":{"type":["string","null"],"enum":["connect_portal_login","complete_portal_mfa","complete_aetna_portal_mfa","observe_metlife_portal_mfa","wait","poll",null],"description":"MFA-first next verb: poll while reconnecting, complete_* when needs_code, wait on outage/quarantine, connect_portal_login when not_connected or expired."},"complete_with":{"type":["string","null"],"enum":["complete_portal_mfa","complete_aetna_portal_mfa",null],"description":"When set, a code is parked: call this verb with the code. Never call connect again first."}},"required":["status","legacy_status","message","start_with","complete_with"]},"benefit":{"type":["object","null"],"additionalProperties":false,"description":"Schema-allowlisted eligibility facts. Raw payer payloads and person/member identifiers are excluded.","properties":{"planId":{"type":["string","null"]},"planName":{"type":["string","null"]},"dateOfService":{"type":["string","null"]},"serviceType":{"type":["string","null"]},"network":{"type":["string","null"]},"active":{"type":["boolean","null"],"description":"True/false is confirmed member coverage. Null means member coverage could not be established; other reported facts remain available and the check is not billed."},"deductible":{"type":"object","additionalProperties":false,"properties":{"individual":{"type":["object","null"],"additionalProperties":false,"properties":{"amount":{"type":"number"},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"]},"family":{"type":["object","null"],"additionalProperties":false,"properties":{"amount":{"type":"number"},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"]},"remaining":{"type":["object","null"],"additionalProperties":false,"properties":{"amount":{"type":"number"},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"]}}},"oopMax":{"type":"object","additionalProperties":false,"properties":{"individual":{"type":["object","null"],"additionalProperties":false,"properties":{"amount":{"type":"number"},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"]},"family":{"type":["object","null"],"additionalProperties":false,"properties":{"amount":{"type":"number"},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"]},"remaining":{"type":["object","null"],"additionalProperties":false,"properties":{"amount":{"type":"number"},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"]}}},"annualMax":{"type":"object","additionalProperties":false,"properties":{"individual":{"type":["object","null"],"additionalProperties":false,"properties":{"amount":{"type":"number"},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"]},"family":{"type":["object","null"],"additionalProperties":false,"properties":{"amount":{"type":"number"},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"]},"remaining":{"type":["object","null"],"additionalProperties":false,"properties":{"amount":{"type":"number"},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"]}}},"orthoLifetime":{"type":"object","additionalProperties":false,"properties":{"individual":{"type":["object","null"],"additionalProperties":false,"properties":{"amount":{"type":"number"},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"]},"family":{"type":["object","null"],"additionalProperties":false,"properties":{"amount":{"type":"number"},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"]},"remaining":{"type":["object","null"],"additionalProperties":false,"properties":{"amount":{"type":"number"},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"]}}},"coinsurancePct":{"type":["number","null"]},"copay":{"type":["object","null"],"additionalProperties":false,"properties":{"amount":{"type":"number"},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"]},"priorAuthRequired":{"type":["boolean","null"]},"benefitCode":{"type":["string","null"]},"asOf":{"type":["string","null"]},"dental":{"type":["object","null"],"additionalProperties":false,"properties":{"plan":{"type":["object","null"],"additionalProperties":false,"properties":{"status":{"type":["string","null"]},"effectiveDate":{"type":["string","null"]},"planPeriodBeginDate":{"type":["string","null"]},"planPeriodEndDate":{"type":["string","null"]},"policyType":{"type":["string","null"]},"planType":{"type":["string","null"]},"groupNumber":{"type":["string","null"]},"section":{"type":["string","null"]},"relationship":{"type":["string","null"]},"dentalSystem":{"type":["string","null"]},"coordinationOfBenefits":{"type":["string","null"]},"enrollmentDate":{"type":["string","null"]},"missingToothClause":{"type":["string","null"]},"missingToothApplies":{"type":["boolean","null"]},"name":{"type":["string","null"]},"group_number":{"type":["string","null"]},"plan_number":{"type":["string","null"]},"begin":{"type":["string","null"]},"end":{"type":["string","null"]},"payer":{"type":["string","null"]}}},"accumulators":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"code":{"type":["string","null"]},"type":{"type":["string","null"]},"kind":{"type":"string","enum":["deductible","maximum","ortho_lifetime","other"],"description":"Closed accumulator kind derived from type/code. type is unchanged. deductible, maximum, ortho_lifetime, or other."},"unit":{"type":["string","null"]},"individual":{"type":"object","additionalProperties":false,"properties":{"inNetwork":{"type":"object","additionalProperties":false,"properties":{"amount":{"type":["number","null"]},"remaining":{"type":["number","null"]}}},"outNetwork":{"type":"object","additionalProperties":false,"properties":{"amount":{"type":["number","null"]},"remaining":{"type":["number","null"]}}}}},"family":{"type":"object","additionalProperties":false,"properties":{"inNetwork":{"type":"object","additionalProperties":false,"properties":{"amount":{"type":["number","null"]},"remaining":{"type":["number","null"]}}},"outNetwork":{"type":"object","additionalProperties":false,"properties":{"amount":{"type":["number","null"]},"remaining":{"type":["number","null"]}}}}}}}},"categories":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"code":{"type":["string","null"]},"coinsuranceInNetwork":{"type":["number","null"]},"coinsuranceOutNetwork":{"type":["number","null"]},"coinsuranceBasis":{"type":"string","enum":["plan_pays","patient_pays","unknown"],"description":"Meaning of coinsuranceInNetwork for this category: plan_pays, patient_pays, or unknown when unproven. coinsuranceInNetwork is unchanged."},"planPaysPctInNetwork":{"type":["number","null"]},"copayAmount":{"type":["number","null"]},"deductibleMetInNetwork":{"type":["boolean","null"]},"deductibleMetOutNetwork":{"type":["boolean","null"]},"waitingPeriod":{"description":"Waiting period or frequency/limitation fact as published on GET. Scalar, object, or array; not a person identifier.","type":["string","number","boolean","object","array","null"],"additionalProperties":true},"limitations":{"description":"Waiting period or frequency/limitation fact as published on GET. Scalar, object, or array; not a person identifier.","type":["string","number","boolean","object","array","null"],"additionalProperties":true},"lastServiceDate":{"type":["string","null"]},"subjectToReview":{"type":["boolean","null"]}}}},"history":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"One procedure from the payer's history. When the payer publishes adjudicated claim lines, the optional line facts below are filled from them: everything the Benefits Statement prints for the line.","properties":{"code":{"type":["string","null"]},"toothNumber":{"type":["string","null"]},"surfaces":{"type":["string","null"]},"description":{"type":["string","null"]},"serviceDate":{"type":["string","null"]},"network":{"type":["string","null"]},"line":{"type":["number","null"],"description":"Optional. The line number within its claim (1, 2, ...)."},"units":{"type":["number","null"],"description":"Optional. Units billed on this line."},"status":{"type":["string","null"],"description":"Optional. The payer's line status as written (e.g. Finalized, Finalized/Denial)."},"claimNumber":{"type":["string","null"],"description":"Optional. The payer's claim number this line belongs to; lines of one claim share it."},"servicingProvider":{"type":["string","null"],"description":"Optional. The servicing provider on this line, as the payer wrote it."},"paymentDate":{"type":["string","null"],"description":"Optional. Payment date (YYYY-MM-DD) when the payer states one."},"modifier":{"type":["string","null"],"description":"Optional. Procedure modifier as the payer wrote it."},"billedAmount":{"type":["number","null"],"description":"Optional. Amount billed on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"allowedAmount":{"type":["number","null"],"description":"Optional. Allowed amount on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"disallowedAmount":{"type":["number","null"],"description":"Optional. Disallowed amount on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"paidAmount":{"type":["number","null"],"description":"Optional. Amount the plan paid on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"coinsuranceAmount":{"type":["number","null"],"description":"Optional. Patient coinsurance on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"copayAmount":{"type":["number","null"],"description":"Optional. Patient copay on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"deductibleAmount":{"type":["number","null"],"description":"Optional. Amount applied to the deductible on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"cobAmount":{"type":["number","null"],"description":"Optional. Coordination-of-benefits amount on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"patientResponsibility":{"type":["number","null"],"description":"Optional. Total patient responsibility on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"patientPercent":{"type":["number","null"],"description":"Optional. The patient's coinsurance share the payer actually applied on this line, in percent from 0 to 100 (20 means 20%): coinsurance over allowed. Absent when nothing was allowed (for example a denied line)."}}}},"family":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"Coverage-level family facts only. Names, dates of birth, subscriber IDs, references, and arbitrary fields are never batch output.","properties":{"relationship":{"type":["string","null"]},"policies":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"groupNumber":{"type":["string","null"]},"planName":{"type":["string","null"]},"status":{"type":["string","null"]}}}}}}},"claims":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"One claim as the payer lists it: everything the Benefits Statement prints for the claim. Arbitrary mapper fields are never output.","properties":{"claimId":{"type":["string","null"]},"claimNumber":{"type":["string","null"]},"patientName":{"type":["string","null"]},"renderingProvider":{"type":["string","null"]},"payee":{"type":["string","null"]},"medicalGroup":{"type":["string","null"]},"patientAccountNo":{"type":["string","null"]},"claimStatus":{"type":["string","null"]},"payer":{"type":["string","null"]},"dateOfService":{"type":["string","null"]},"receivedDate":{"type":["string","null"]},"dateProcessed":{"type":["string","null"]},"billedAmount":{"type":["number","null"]},"paidAmount":{"type":["number","null"]},"memberResponsibility":{"type":["number","null"]},"network":{"type":["string","null"]}}}},"toothChart":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"toothNumber":{"type":"string"},"procedures":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"One procedure from the payer's history. When the payer publishes adjudicated claim lines, the optional line facts below are filled from them: everything the Benefits Statement prints for the line.","properties":{"code":{"type":["string","null"]},"toothNumber":{"type":["string","null"]},"surfaces":{"type":["string","null"]},"description":{"type":["string","null"]},"serviceDate":{"type":["string","null"]},"network":{"type":["string","null"]},"line":{"type":["number","null"],"description":"Optional. The line number within its claim (1, 2, ...)."},"units":{"type":["number","null"],"description":"Optional. Units billed on this line."},"status":{"type":["string","null"],"description":"Optional. The payer's line status as written (e.g. Finalized, Finalized/Denial)."},"claimNumber":{"type":["string","null"],"description":"Optional. The payer's claim number this line belongs to; lines of one claim share it."},"servicingProvider":{"type":["string","null"],"description":"Optional. The servicing provider on this line, as the payer wrote it."},"paymentDate":{"type":["string","null"],"description":"Optional. Payment date (YYYY-MM-DD) when the payer states one."},"modifier":{"type":["string","null"],"description":"Optional. Procedure modifier as the payer wrote it."},"billedAmount":{"type":["number","null"],"description":"Optional. Amount billed on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"allowedAmount":{"type":["number","null"],"description":"Optional. Allowed amount on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"disallowedAmount":{"type":["number","null"],"description":"Optional. Disallowed amount on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"paidAmount":{"type":["number","null"],"description":"Optional. Amount the plan paid on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"coinsuranceAmount":{"type":["number","null"],"description":"Optional. Patient coinsurance on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"copayAmount":{"type":["number","null"],"description":"Optional. Patient copay on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"deductibleAmount":{"type":["number","null"],"description":"Optional. Amount applied to the deductible on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"cobAmount":{"type":["number","null"],"description":"Optional. Coordination-of-benefits amount on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"patientResponsibility":{"type":["number","null"],"description":"Optional. Total patient responsibility on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"patientPercent":{"type":["number","null"],"description":"Optional. The patient's coinsurance share the payer actually applied on this line, in percent from 0 to 100 (20 means 20%): coinsurance over allowed. Absent when nothing was allowed (for example a denied line)."}}}}}}},"cob":{"type":["object","null"],"additionalProperties":false,"properties":{"method":{"type":["string","null"]},"applicable":{"type":["boolean","null"]}}},"preauth":{"type":["object","null"],"additionalProperties":false,"properties":{"procedureRequired":{"type":["boolean","null"]},"categories":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"code":{"type":["string","null"]}}}}}}}}}},"statement":{"type":["object","null"],"additionalProperties":false,"description":"The Veraxus Benefits Statement for this check, exactly as the dashboard PDF draws it, when usable: the same sections in the same order. Each section has a kind: kv (title + cells of [label, value]), notes (title + rows of {name, text}), table (table: title, note, columns of {key, label, weight}, rows keyed by column key), groups (title + groups of {name, table}), or paragraph (title + text). Every value is the text the statement prints. Use the typed benefit fields to compute; use statement to show what Veraxus shows.","properties":{"sections":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["kv","notes","table","groups","paragraph"]},"title":{"type":["string","null"]},"note":{"type":["string","null"]},"text":{"type":["string","null"]},"cells":{"type":"array","items":{"type":"array","items":{"type":"string"}}},"rows":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"text":{"type":"string"}}}},"table":{"type":"object","additionalProperties":false,"properties":{"title":{"type":["string","null"]},"note":{"type":["string","null"]},"columns":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"key":{"type":"string"},"label":{"type":"string"},"weight":{"type":"number"}}}},"rows":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Column key to the text the statement prints in that cell."}}}},"groups":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"table":{"type":"object","additionalProperties":false,"properties":{"title":{"type":["string","null"]},"note":{"type":["string","null"]},"columns":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"key":{"type":"string"},"label":{"type":"string"},"weight":{"type":"number"}}}},"rows":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Column key to the text the statement prints in that cell."}}}}}}}},"required":["kind"]}}}},"parsed":{"type":["object","null"],"additionalProperties":false,"description":"Schema-allowlisted normalized plan, accumulator, procedure, history, claim, and family coverage facts. Unstructured payer notes/messages are excluded because they may contain person identifiers.","properties":{"plan":{"type":["object","null"],"additionalProperties":false,"properties":{"status":{"type":["string","null"]},"effectiveDate":{"type":["string","null"]},"planPeriodBeginDate":{"type":["string","null"]},"planPeriodEndDate":{"type":["string","null"]},"policyType":{"type":["string","null"]},"planType":{"type":["string","null"]},"groupNumber":{"type":["string","null"]},"section":{"type":["string","null"]},"relationship":{"type":["string","null"]},"dentalSystem":{"type":["string","null"]},"coordinationOfBenefits":{"type":["string","null"]},"enrollmentDate":{"type":["string","null"]},"missingToothClause":{"type":["string","null"]},"missingToothApplies":{"type":["boolean","null"]},"name":{"type":["string","null"]},"group_number":{"type":["string","null"]},"plan_number":{"type":["string","null"]},"begin":{"type":["string","null"]},"end":{"type":["string","null"]},"payer":{"type":["string","null"]}}},"accumulators":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"code":{"type":["string","null"]},"type":{"type":["string","null"]},"kind":{"type":"string","enum":["deductible","maximum","ortho_lifetime","other"],"description":"Closed accumulator kind derived from type/code. type is unchanged. deductible, maximum, ortho_lifetime, or other."},"unit":{"type":["string","null"]},"individual":{"type":"object","additionalProperties":false,"properties":{"inNetwork":{"type":"object","additionalProperties":false,"properties":{"amount":{"type":["number","null"]},"remaining":{"type":["number","null"]}}},"outNetwork":{"type":"object","additionalProperties":false,"properties":{"amount":{"type":["number","null"]},"remaining":{"type":["number","null"]}}}}},"family":{"type":"object","additionalProperties":false,"properties":{"inNetwork":{"type":"object","additionalProperties":false,"properties":{"amount":{"type":["number","null"]},"remaining":{"type":["number","null"]}}},"outNetwork":{"type":"object","additionalProperties":false,"properties":{"amount":{"type":["number","null"]},"remaining":{"type":["number","null"]}}}}}}}},"categories":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"code":{"type":["string","null"]},"coinsuranceInNetwork":{"type":["number","null"]},"coinsuranceOutNetwork":{"type":["number","null"]},"coinsuranceBasis":{"type":"string","enum":["plan_pays","patient_pays","unknown"],"description":"Meaning of coinsuranceInNetwork for this category: plan_pays, patient_pays, or unknown when unproven. coinsuranceInNetwork is unchanged."},"planPaysPctInNetwork":{"type":["number","null"]},"copayAmount":{"type":["number","null"]},"deductibleMetInNetwork":{"type":["boolean","null"]},"deductibleMetOutNetwork":{"type":["boolean","null"]},"waitingPeriod":{"description":"Waiting period or frequency/limitation fact as published on GET. Scalar, object, or array; not a person identifier.","type":["string","number","boolean","object","array","null"],"additionalProperties":true},"limitations":{"description":"Waiting period or frequency/limitation fact as published on GET. Scalar, object, or array; not a person identifier.","type":["string","number","boolean","object","array","null"],"additionalProperties":true},"lastServiceDate":{"type":["string","null"]},"subjectToReview":{"type":["boolean","null"]}}}},"history":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"One procedure from the payer's history. When the payer publishes adjudicated claim lines, the optional line facts below are filled from them: everything the Benefits Statement prints for the line.","properties":{"code":{"type":["string","null"]},"toothNumber":{"type":["string","null"]},"surfaces":{"type":["string","null"]},"description":{"type":["string","null"]},"serviceDate":{"type":["string","null"]},"network":{"type":["string","null"]},"line":{"type":["number","null"],"description":"Optional. The line number within its claim (1, 2, ...)."},"units":{"type":["number","null"],"description":"Optional. Units billed on this line."},"status":{"type":["string","null"],"description":"Optional. The payer's line status as written (e.g. Finalized, Finalized/Denial)."},"claimNumber":{"type":["string","null"],"description":"Optional. The payer's claim number this line belongs to; lines of one claim share it."},"servicingProvider":{"type":["string","null"],"description":"Optional. The servicing provider on this line, as the payer wrote it."},"paymentDate":{"type":["string","null"],"description":"Optional. Payment date (YYYY-MM-DD) when the payer states one."},"modifier":{"type":["string","null"],"description":"Optional. Procedure modifier as the payer wrote it."},"billedAmount":{"type":["number","null"],"description":"Optional. Amount billed on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"allowedAmount":{"type":["number","null"],"description":"Optional. Allowed amount on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"disallowedAmount":{"type":["number","null"],"description":"Optional. Disallowed amount on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"paidAmount":{"type":["number","null"],"description":"Optional. Amount the plan paid on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"coinsuranceAmount":{"type":["number","null"],"description":"Optional. Patient coinsurance on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"copayAmount":{"type":["number","null"],"description":"Optional. Patient copay on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"deductibleAmount":{"type":["number","null"],"description":"Optional. Amount applied to the deductible on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"cobAmount":{"type":["number","null"],"description":"Optional. Coordination-of-benefits amount on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"patientResponsibility":{"type":["number","null"],"description":"Optional. Total patient responsibility on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"patientPercent":{"type":["number","null"],"description":"Optional. The patient's coinsurance share the payer actually applied on this line, in percent from 0 to 100 (20 means 20%): coinsurance over allowed. Absent when nothing was allowed (for example a denied line)."}}}},"family":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"Coverage-level family facts only. Names, dates of birth, subscriber IDs, references, and arbitrary fields are never batch output.","properties":{"relationship":{"type":["string","null"]},"policies":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"groupNumber":{"type":["string","null"]},"planName":{"type":["string","null"]},"status":{"type":["string","null"]}}}}}}},"claims":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"One claim as the payer lists it: everything the Benefits Statement prints for the claim. Arbitrary mapper fields are never output.","properties":{"claimId":{"type":["string","null"]},"claimNumber":{"type":["string","null"]},"patientName":{"type":["string","null"]},"renderingProvider":{"type":["string","null"]},"payee":{"type":["string","null"]},"medicalGroup":{"type":["string","null"]},"patientAccountNo":{"type":["string","null"]},"claimStatus":{"type":["string","null"]},"payer":{"type":["string","null"]},"dateOfService":{"type":["string","null"]},"receivedDate":{"type":["string","null"]},"dateProcessed":{"type":["string","null"]},"billedAmount":{"type":["number","null"]},"paidAmount":{"type":["number","null"]},"memberResponsibility":{"type":["number","null"]},"network":{"type":["string","null"]}}}},"toothChart":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"toothNumber":{"type":"string"},"procedures":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"One procedure from the payer's history. When the payer publishes adjudicated claim lines, the optional line facts below are filled from them: everything the Benefits Statement prints for the line.","properties":{"code":{"type":["string","null"]},"toothNumber":{"type":["string","null"]},"surfaces":{"type":["string","null"]},"description":{"type":["string","null"]},"serviceDate":{"type":["string","null"]},"network":{"type":["string","null"]},"line":{"type":["number","null"],"description":"Optional. The line number within its claim (1, 2, ...)."},"units":{"type":["number","null"],"description":"Optional. Units billed on this line."},"status":{"type":["string","null"],"description":"Optional. The payer's line status as written (e.g. Finalized, Finalized/Denial)."},"claimNumber":{"type":["string","null"],"description":"Optional. The payer's claim number this line belongs to; lines of one claim share it."},"servicingProvider":{"type":["string","null"],"description":"Optional. The servicing provider on this line, as the payer wrote it."},"paymentDate":{"type":["string","null"],"description":"Optional. Payment date (YYYY-MM-DD) when the payer states one."},"modifier":{"type":["string","null"],"description":"Optional. Procedure modifier as the payer wrote it."},"billedAmount":{"type":["number","null"],"description":"Optional. Amount billed on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"allowedAmount":{"type":["number","null"],"description":"Optional. Allowed amount on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"disallowedAmount":{"type":["number","null"],"description":"Optional. Disallowed amount on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"paidAmount":{"type":["number","null"],"description":"Optional. Amount the plan paid on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"coinsuranceAmount":{"type":["number","null"],"description":"Optional. Patient coinsurance on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"copayAmount":{"type":["number","null"],"description":"Optional. Patient copay on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"deductibleAmount":{"type":["number","null"],"description":"Optional. Amount applied to the deductible on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"cobAmount":{"type":["number","null"],"description":"Optional. Coordination-of-benefits amount on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"patientResponsibility":{"type":["number","null"],"description":"Optional. Total patient responsibility on this service line, in US dollars (e.g. 33.67), as the payer adjudicated it."},"patientPercent":{"type":["number","null"],"description":"Optional. The patient's coinsurance share the payer actually applied on this line, in percent from 0 to 100 (20 means 20%): coinsurance over allowed. Absent when nothing was allowed (for example a denied line)."}}}}}}},"cob":{"type":["object","null"],"additionalProperties":false,"properties":{"method":{"type":["string","null"]},"applicable":{"type":["boolean","null"]}}},"preauth":{"type":["object","null"],"additionalProperties":false,"properties":{"procedureRequired":{"type":["boolean","null"]},"categories":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"code":{"type":["string","null"]}}}}}},"procedures":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"code":{"type":["string","null"]},"procedureCode":{"type":["string","null"]},"cdt":{"type":["string","null"]},"description":{"type":["string","null"]},"service":{"type":["string","null"]},"serviceType":{"type":["string","null"]},"category":{"type":["string","null"]},"network":{"type":["string","null"]},"coverage":{"type":["string","null"]},"covered":{"type":["boolean","null"]},"coinsurancePct":{"type":["number","null"]},"coinsurance":{"type":["number","null"]},"copayAmount":{"type":["number","null"]},"copay":{"type":["number","null"]},"allowedAmount":{"type":["number","null"]},"contractedFee":{"type":["number","null"]},"fee":{"type":["number","null"]},"amount":{"type":["number","null"]},"patientPays":{"type":["number","null"]},"planPays":{"type":["number","null"]},"deductibleApplies":{"type":["boolean","null"]},"priorAuthRequired":{"type":["boolean","null"]},"frequency":{"type":["string","number","boolean","null"]},"frequencyLimit":{"type":["string","number","boolean","null"]},"remaining":{"type":["string","number","boolean","null"]},"limit":{"type":["string","number","boolean","null"]},"ageLimit":{"type":["string","number","boolean","null"]},"waitingPeriod":{"type":["string","number","boolean","null"]},"planPaysPct":{"type":["number","null"],"description":"Optional in-network plan share in percent. For payers that publish networkedBenefits[] (ddmo), Veraxus fills it only when every in-network tier agrees and plan + patient = 100; other payers publish their mapper's own labeled value."},"patientPaysPct":{"type":["number","null"],"description":"Optional in-network patient share in percent. For payers that publish networkedBenefits[] (ddmo), Veraxus fills it only when every in-network tier agrees and plan + patient = 100; other payers publish their mapper's own labeled value."},"outOfNetworkPlanPct":{"type":["number","null"],"description":"Optional out-of-network plan share in percent. For payers that publish networkedBenefits[] (ddmo), Veraxus fills it only when every out-of-network tier agrees and plan + patient = 100; other payers publish their mapper's own labeled value."},"outOfNetworkPatientPct":{"type":["number","null"],"description":"Optional out-of-network patient share in percent. For payers that publish networkedBenefits[] (ddmo), Veraxus fills it only when every out-of-network tier agrees and plan + patient = 100; other payers publish their mapper's own labeled value."}}}},"benefits":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"code":{"type":["string","null"]},"meaning":{"type":["string","null"]},"name":{"type":["string","null"]},"amount":{"type":["string","number","boolean","null"]},"percent":{"type":["string","number","boolean","null"]},"network":{"type":["string","null"]},"coverage_level":{"type":["string","null"]},"service_type_code":{"type":["string","null"]},"service_type_codes":{"type":"array","items":{"type":"string"}},"service":{"type":["string","null"]},"services":{"type":"array","items":{"type":"string"}},"procedure_code":{"type":["string","null"]},"time_qualifier":{"type":["string","null"]},"quantity":{"type":["string","number","boolean","null"]},"prior_auth":{"type":["string","null"]}}}}}},"error":{"type":["string","null"],"description":"Human-readable reason when the check did not serve; null on success. Pair with error_code."},"error_code":{"type":["string","null"],"description":"Machine code for error (e.g. retry when the lane is paused and the keep is warm, reconnect when the office must Connect, credentials_required when no login is saved, internal for a host fault, mfa_expired, member_not_found, payer_down when the saved login is quarantined or the payer portal is out, payer_unavailable, incomplete, date_of_service_unsupported when the payer portal answers current benefits only and the requested date_of_service is outside that answer (not billed; a past date of service cannot be answered and retry.ok is false; a later date names in retry.hint the day the same check is answered, on the portal's calendar or else UTC, with retry.ok true and retry_after; a date 365 or more days out (364 when the read day is UTC), or one that has passed by the time of the read, is retry.ok false), pending). server_error is only a host exception. Null on success."},"retryable":{"type":"boolean","description":"True when this failed check is safe to retry unchanged after retry_after seconds (paused lane + warm keep, or error_code date_of_service_unsupported for a later date the portal answers from a named day, as of the time of the read). Omitted when not retryable."},"retry_after":{"type":["integer","null"],"description":"Seconds to wait before retrying a retryable failed check. Null/omitted when not retryable. For error_code date_of_service_unsupported it counts from the time of the read to midnight of the named day on the snapshot calendar: GET and batch rows recompute it, and a keyed idempotent replay repeats the first value."},"retry":{"type":"object","additionalProperties":false,"description":"What to do next. ok true: safe to retry later as-is. ok false: retrying unchanged will not help — follow hint (submit a code, reconnect, or fix input). poll names the verb to poll a pending check.","properties":{"ok":{"type":"boolean","description":"True: safe to retry later unchanged. False: follow hint first."},"hint":{"type":["string","null"],"description":"What to do before retrying, in plain words."},"poll":{"type":"string","description":"Compatibility verb to poll a pending check (get_eligibility). Prefer poll_tool and poll_path."},"poll_tool":{"type":"string","description":"MCP tool to poll a pending check (get_eligibility)."},"poll_path":{"type":"string","description":"REST path to poll this check, filled as /v1/eligibility/{id}."}},"required":["ok"]},"billing":{"type":"object","additionalProperties":false,"description":"What this check cost. Branch on waived, not on reason: waived true means not billed (reason says why — sandbox, payer_unavailable, pending, idempotent_replay, invalid_request); waived false means billed and reason names the rate (live_check, or cache for a cached serve). A member miss is billed; a dead login, payer outage, or Veraxus failure is not.","properties":{"unit":{"type":"string","const":"eligibility_check","description":"Billing unit; always eligibility_check."},"cents":{"type":"integer","minimum":0,"description":"Amount billed for this check, in US cents; 0 when waived."},"currency":{"type":"string","const":"USD","description":"Always USD."},"waived":{"type":"boolean","description":"True when not billed (sandbox, payer outage, pending, or a Veraxus failure)."},"reason":{"type":["string","null"],"description":"When waived: why (sandbox, payer_unavailable, pending, idempotent_replay, invalid_request). When billed: the rate that applied (live_check, cache). Branch on waived, not on this field."}},"required":["unit","cents","currency","waived"]},"idempotent":{"type":"boolean","description":"True when this response was served from the short same-request deduplication window (an identical concurrent submission), not re-billed (billing.reason idempotent_replay). An Idempotency-Key replay instead returns the original envelope unchanged, so this field then reflects the original run."},"step":{"type":"string","description":"Present only on server_error: the coarse stage that failed (e.g. portal). Diagnostic, not actionable."},"warnings":{"type":"array","description":"Non-fatal input notes on a single-check response. relationship_normalized means an unknown relationship token was treated as other. Omitted when there are no warnings. Batch admission still rejects unknown relationship values.","items":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Stable machine string (relationship_normalized)."},"field":{"type":"string","description":"Input field the note applies to."},"message":{"type":"string","description":"Plain-words explanation, safe to show a person."}},"required":["code","field","message"]}},"enrichment":{"type":"string","enum":["pending","complete","failed"],"description":"Present when a background enrichment pass runs after the first answer. pending: poll get_eligibility for the richer payload; complete/failed: final."},"duration_ms":{"type":["integer","null"],"description":"Milliseconds the answering route took (portal replay or network). When no route answered, total time for the check. Null while pending or when an older row was never stamped. Published as duration_ms because latency_ms is a lab key stripped envelope-wide on MCP. Never PHI."},"failure_stage":{"type":["string","null"],"enum":["preflight","restore","probe","search","benefits","mapper","network","unknown",null],"description":"Coarse stage that failed: preflight, restore, probe, search, benefits, mapper, network, or unknown. Null on pending and on served checks. Derived from failCategory, hop, and errorClass. Never PHI."},"index":{"type":"integer","minimum":0,"maximum":49,"description":"Zero-based position of this row in the submitted checks array."},"client_reference_id":{"type":["string","null"],"description":"Echo of the opaque id you submitted for this row — use it to reconcile against your schedule."},"check_id":{"type":["string","null"],"description":"chk_… id once the row dispatched; null for rows rejected at intake. Poll get_eligibility with it."},"workflow_state":{"type":"string","enum":["queued","running","waiting","waiting_for_action","completed","failed","cancelled","rejected"]}},"required":["status","usable","why","error","error_code","retry","billing","index","client_reference_id","check_id"]}},"links":{"type":"object","additionalProperties":false,"description":"links.self is the canonical URL to poll for this batch's current state.","properties":{"self":{"type":"string","description":"Canonical URL of this batch resource."}},"required":["self"]}},"required":["batch_id","practice_id","organization_id","created_at","expires_at","status","submitted_count","accepted_count","rejected_count","active_limit_per_practice","summary","results","links"]},"EligibilityCheckRequest":{"type":"object","additionalProperties":false,"properties":{"practice_id":{"type":"string","description":"Practice returned by GET /organizations. Required for a company-wide key."},"organization_id":{"type":"string","deprecated":true,"description":"Deprecated alias for practice_id. If both are sent, they must match."},"payer_id":{"type":"string","description":"Exact id/eligibility_payer_id from GET /payers. Humana Dental uses humana or 65065 through the practice's Availity login. Never use vault_payer_id or mailbox_id."},"availity_payer_id":{"type":"string","enum":["00430D","65065","80314D","84103","ANTHEMXXDENTAL","WLPDEN"],"description":"Required with payer_id=availity. Select an insurer from list_payers request_capabilities.availity_payers. For Humana Dental, use 65065, or send payer_id=humana. The listed insurer IDs also work as eligibility payer_id aliases. Uses this practice's Availity login."},"member_id":{"type":"string","description":"Member/subscriber ID exactly as printed on the card. Required for a live check unless raw270 is sent."},"date_of_birth":{"type":"string","format":"date","description":"Subscriber date of birth, YYYY-MM-DD. Required for a live check. Not a promise that a network fill will run."},"first_name":{"type":"string","description":"Subscriber first name as the payer has it. Required for a live check."},"last_name":{"type":"string","description":"Subscriber last name as the payer has it. Required for a live check."},"relationship":{"type":"string","enum":["self","spouse","child","other"],"description":"Patient's relationship to the subscriber. Defaults to self; send with the patient_* fields for a dependent."},"patient_first_name":{"type":"string","description":"Dependent patient's first name when the patient is not the subscriber."},"patient_last_name":{"type":"string","description":"Dependent patient's last name when the patient is not the subscriber."},"patient_date_of_birth":{"type":"string","format":"date","description":"Dependent patient's date of birth, YYYY-MM-DD."},"date_of_service":{"type":"string","format":"date","description":"Appointment date, YYYY-MM-DD. Defaults to today."},"procedure_code":{"type":"string","maxLength":64,"pattern":"^\\s*[dD][0-9]{4}\\s*$","description":"Optional requested CDT for a single live nevada_medicaid check only. Trimmed and uppercased to D plus four digits; omitted keeps the worker's D0120 default. Not supported for other payers, sandbox, network, or batch checks."},"procedureCode":{"type":"string","maxLength":64,"pattern":"^\\s*[dD][0-9]{4}\\s*$","description":"Alias for procedure_code. Snake_case is canonical. Optional requested CDT for a single live nevada_medicaid check only. Trimmed and uppercased to D plus four digits; omitted keeps the worker's D0120 default. Not supported for other payers, sandbox, network, or batch checks.","deprecated":true},"service_type":{"type":"string","example":"dental_prophy","description":"Service to price (e.g. dental_prophy). Defaults to dental_prophy."},"zip_code":{"type":"string","description":"Subscriber ZIP when the payer's search needs it; usually optional."},"address":{"type":"string","maxLength":256,"description":"Member street address when the payer's search needs it; usually optional. Not required for every payer."},"subscriber_last_name":{"type":"string","maxLength":128,"description":"Cardholder or subscriber last name when the payer's search needs it; usually optional. Distinct from last_name."},"force_refresh":{"type":"boolean","default":false,"description":"Skip any cached answer and go to the payer now. Costs a live check."},"sandbox":{"type":"boolean","default":false,"description":"Run against the sandbox instead of a live payer. With a published DEMO member_id (see GET /me sandbox.members) the check is never billed; any other member_id is billed."},"idempotency_key":{"type":"string","maxLength":256,"description":"Optional body alias for Idempotency-Key."},"raw270":{"type":"string","description":"Raw X12 270. Posting one selects the X12 door, so a JSON response also carries raw271 — synthesized from whatever leg served the check. raw271 is a response format, not a provenance signal: read served_by."}},"anyOf":[{"required":["raw270"]},{"required":["payer_id","member_id","date_of_birth","first_name","last_name"]}]},"MeResponse":{"type":"object","description":"Who this credential is: exact caller identity, granted scopes, customer (tenant), practice count, and the sandbox members you can check for free.","properties":{"key":{"type":"object","description":"The authenticated credential. org_id is null for company-wide access. caller_id is the server-derived identity that delegated-consent assertions must bind; never accept a caller id from an onboarding request body.","properties":{"id":{"type":"string","description":"Key id."},"name":{"type":"string","description":"Label given to this key when it was minted."},"org_id":{"type":["string","null"],"description":"Practice this key is bound to; null for a company-wide key."},"caller_id":{"type":"string","maxLength":280,"pattern":"^(api_key|oauth_grant):[A-Za-z0-9_-]+$","description":"Exact server-derived caller identity. Sign this value as caller_id in delegated portal-consent assertions."},"scopes":{"type":"array","uniqueItems":true,"items":{"type":"string","enum":["eligibility","vault","portal_login_mutation","claims"]},"description":"Capabilities granted to this credential. Delegated portal onboarding, operation-bound MFA, revoke, and exact operation reads require portal_login_mutation."}},"required":["id","name","org_id","caller_id","scopes"]},"tenant":{"type":["object","null"],"description":"The customer account: price per billed check (price_cents) and the payer ids enabled for it.","properties":{"id":{"type":"string","description":"Customer account id."},"name":{"type":"string","description":"Customer company name."},"slug":{"type":"string","description":"URL-safe account handle."},"product_name":{"type":"string","description":"The product this account sells under."},"price_cents":{"type":"integer","description":"Price of one billed eligibility check, in US cents."},"billing_unit":{"type":"string","const":"eligibility_check","description":"Billing unit; always eligibility_check."},"enabled_payers":{"type":"array","items":{"type":"string"},"description":"Payer ids this account can check. Same ids as GET /payers."}},"required":["id","name","price_cents","billing_unit","enabled_payers"]},"organization_count":{"type":"integer","description":"How many practices exist under this account. List them with GET /organizations."},"organizations":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Reserved; use GET /organizations to list practices."},"sandbox":{"type":"object","description":"Free first checks: POST /eligibility with sandbox true and one of these member ids. Never billed.","properties":{"members":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Published DEMO members with the ids to send as member_id."},"billed":{"type":"boolean","const":false,"description":"Sandbox checks are never billed."},"tool":{"type":"string","description":"MCP verb that runs a sandbox check."}},"required":["members","billed"]},"network_fallback":{"type":"object","description":"Whether the eligibility network may fill a portal miss for this deployment. Portal is the product; enabled is the live flag. Non-secret.","properties":{"enabled":{"type":"boolean","description":"True only when this deployment's eligibility network fallback is on."},"note":{"type":"string","description":"Plain-words product copy for the current flag. Not a secret."}},"required":["enabled","note"]}},"required":["key","tenant","organization_count","sandbox"]},"PayerListResponse":{"type":"object","description":"Every licensed payer remains visible even when a delegated custody action is blocked, plus organization-scoped disabled mailbox cleanup/recovery rows. Use id as payer_id; never offer Sign in when revoke_only is true, and never offer Disconnect when revocation_enabled is false.","properties":{"payers":{"type":"array","description":"Every licensed catalog row and, when organization_id is supplied, safe disabled rows with enabled=false and revoke_only=true. Separate scoped onboarding/revocation capability fields govern each action. On an exact organization-scoped read, non-UCCI closed-allowlist Connect payers and DNoA publish onboarding_enabled=true; United Concordia remains limited to its separately released exact tn_verora/org_4ab6ddda scope. The composite operation stores credentials and invokes the canonical Connect engine internally. sandbox_mfa is restricted to the configured non-customer organization. Revocation remains separately gated and narrower than onboarding. login_saved=true exposes Disconnect only when revocation_enabled=true and its block code is null; login_saved=false is an exact-recovery tombstone, not an action.","items":{"type":"object","description":"One licensed payer or organization-scoped cleanup row. Visibility is independent of delegated onboarding and revocation capability.","properties":{"id":{"type":"string","description":"Exact catalog payer id for eligibility calls. Never substitute vault_payer_id or mailbox_id."},"eligibility_payer_id":{"type":"string","description":"Same exact value as id, named explicitly for eligibility routing."},"name":{"type":"string","description":"Payer display name."},"kind":{"type":"string","description":"Catalog kind when declared."},"vault_payer_id":{"type":"string","description":"Canonical shared-login mailbox id for Vault custody actions."},"mailbox_id":{"type":"string","description":"Same exact value as vault_payer_id."},"mailbox_name":{"type":"string","description":"Shared-login mailbox display name."},"requires_book_picker":{"type":"boolean","description":"True when this mailbox covers multiple eligibility books and each check must name the exact catalog payer."},"supported_payers":{"type":"array","items":{"type":"string"},"description":"Payer names covered by this mailbox login."},"stedi_id":{"type":["string","null"],"description":"Trading-partner id accepted as an eligibility alias, when present."},"aliases":{"type":"array","items":{"type":"string"},"description":"Other names and ids that resolve to this payer."},"edi_payer_ids":{"type":"array","items":{"type":"string"},"description":"Verified EDI / trading-partner ids that resolve to this catalog row (STEDI_PAYER, EDI_TO_CATALOG, Concordia and DDMI aliases). Unverified customer-reported ids are omitted."},"status":{"type":"string","enum":["live","available","network_only"],"description":"live: PORTAL_LIVE_PAYER_IDS. available: portal-eligibility payers not yet live. network_only: CONSOLE_STUB_PAYER_IDS, Ohio Delta network ids, or STEDI-only."},"enabled":{"type":"boolean","description":"True for a currently licensed catalog row; false only for an organization-scoped cleanup/recovery row."},"revoke_only":{"type":"boolean","description":"True only for a disabled cleanup/recovery row. It does not itself authorize Disconnect."},"login_saved":{"type":"boolean","description":"True when this organization still has a saved mailbox login."},"onboarding_enabled":{"type":"boolean","description":"True only when composite Vault onboarding is enabled for this authenticated tenant/organization/payer scope. Non-UCCI organization-scoped rows on the closed Connect allowlist are enabled because POST /portal/onboard invokes that canonical Connect engine internally; United Concordia still requires its exact separately released tenant/organization scope. Unscoped reads do not grant it. This is not proof that the credential has portal_login_mutation; separately verify key.scopes and key.caller_id through GET /v1/me."},"onboarding_block_code":{"type":["string","null"],"enum":["portal_login_recert_required","portal_login_sandbox_org_required","shared_portal_owner_required",null],"description":"Stable reason delegated Sign in is unavailable for this exact scope, or null when allowed. shared_portal_owner_required means manage this login from its connection owner practice. Require onboarding_enabled=true as well; missing or unknown capability evidence fails closed."},"revocation_enabled":{"type":"boolean","description":"True only when delegated revocation is admitted for this authenticated tenant/organization/payer scope. Separately verify portal_login_mutation in GET /v1/me key.scopes and bind key.caller_id; capability is not caller mutation authorization or a deletion receipt. DNoA and restricted sandbox_mfa are baseline paths; the tn_verora/org_4ab6ddda/united_concordia pilot is released for that exact tenant, organization, and payer; every other office and payer stays blocked, and the live per-org signal is onboarding_enabled / onboarding_block_code in GET /v1/payers."},"revocation_block_code":{"type":["string","null"],"enum":["portal_login_revoke_recert_required","portal_login_sandbox_org_required","shared_portal_owner_required",null],"description":"Null only when this exact scope is admitted. Shared-login child practices publish shared_portal_owner_required when custody must be managed from the connection owner practice. Other sandbox organizations publish portal_login_sandbox_org_required; uncertified scopes, including every office and payer other than the released tn_verora/org_4ab6ddda/united_concordia pilot, publish portal_login_revoke_recert_required. A missing, false, blocked, or unknown capability must not render Disconnect."},"connect_supported":{"type":"boolean","description":"True when POST /portal/connect is on the closed allowlist."},"mfa":{"type":"boolean","description":"Catalog mfa flag."},"mfa_types":{"type":"array","items":{"type":"string","enum":["sms_otp","email_otp","totp","push"]},"description":"Documented factor types. Empty when unknown."},"availability":{"type":"string","enum":["available","coming_soon"],"description":"Global benefit capability. available means a supported portal dispatch exists, not that this practice is ready. coming_soon means sign-in or captured benefits are unavailable; Connect capability is separate. Use verification preview for the exact practice and request."},"availability_reason":{"type":["string","null"],"enum":["sign_in_not_supported","benefits_not_captured",null],"description":"Why coming_soon: sign_in_not_supported or benefits_not_captured. Null when available."},"sign_in_method":{"type":"string","enum":["connect","saved_password","none"],"description":"connect = POST /v1/portal/connect (may ask for a code). saved_password = store credentials, each check signs in (DNoA). none = no Veraxus sign-in (TruAssure)."},"renews_without_code":{"type":["boolean","null"],"description":"Whether Veraxus renews an expired login without asking for a code. Null = not measured."},"request_capabilities":{"type":"object","additionalProperties":false,"description":"Request shapes this exact payer book can accept; practice enablement and connection readiness are assessed separately.","properties":{"availity_payers":{"type":"array","description":"Captured Availity insurer choices. Use id as availity_payer_id with payer_id=availity, or use id/aliases directly as eligibility payer_id. All use the practice's Availity login.","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}}},"required":["id","name","aliases"]}},"single":{"type":"boolean","description":"Whether single-patient requests are supported."},"batch":{"type":"boolean","description":"Whether day-book requests are supported."},"dependent":{"type":"boolean","description":"Whether the connector can select the requested dependent."},"dependent_requires_subscriber":{"type":"boolean","description":"Whether a dependent request must also carry subscriber identity."},"required_fields":{"type":"array","items":{"type":"string"},"description":"Required patient request field names."},"dependent_fields":{"type":"array","items":{"type":"string"},"description":"Additional field names used to identify a dependent."},"procedure_code":{"type":"string","enum":["optional","unsupported"],"description":"Whether a single request may specify a procedure code."},"default_procedure_code":{"type":["string","null"],"description":"Default procedure code, if this book defines one."},"batch_procedure_code":{"type":"boolean","description":"Whether batch rows may specify a procedure code."}},"required":["single","batch","dependent","dependent_requires_subscriber","required_fields","dependent_fields","procedure_code","default_procedure_code","batch_procedure_code"]},"shares_with":{"type":"array","items":{"type":"string"},"description":"Sibling catalog ids that share this vault password. Server-owned mailbox."},"rate_limit_per_min":{"type":["integer","null"],"description":"Catalog rateLimitPerMin."},"sandbox":{"type":"boolean","description":"True for unpaid certification payers."}},"required":["id","eligibility_payer_id","name","vault_payer_id","mailbox_id","mailbox_name","requires_book_picker","supported_payers","stedi_id","aliases","edi_payer_ids","status","enabled","revoke_only","login_saved","onboarding_enabled","onboarding_block_code","revocation_enabled","revocation_block_code","connect_supported","mfa","mfa_types","availability","availability_reason","sign_in_method","renews_without_code"]}}},"required":["payers"]},"PracticeListResponse":{"type":"object","description":"Practices under this account. Pass a practice id as practice_id on practice-scoped calls with a company-wide key.","properties":{"tenant_id":{"type":"string","description":"The customer account these practices belong to."},"total":{"type":"integer","description":"Total practices matching the query, across pages."},"next_cursor":{"type":["string","null"],"description":"Pass back as ?cursor= for the next page; null on the last page."},"organizations":{"type":"array","description":"One row per practice, in roster order.","items":{"type":"object","properties":{"id":{"type":"string","description":"Practice id — the value to send as practice_id."},"name":{"type":"string"},"slug":{"type":"string"},"kind":{"type":"string"},"region":{"type":"string"},"status":{"type":"string"},"npi":{"type":["string","null"],"description":"Practice NPI. Required on file before eligibility-network checks can run for this practice."},"tax_id":{"type":["string","null"],"description":"Practice EIN. Required on file before eligibility-network checks can run for this practice."},"code_email_address":{"type":["string","null"],"description":"Code-only address on codes.veraxus.ai for enrolled accounts; null otherwise. Do not set it on a payer account until Veraxus marks it receiving."},"code_email_receiving":{"type":"boolean","description":"True when receiving is released and the address has a fresh verified provider route, receiving-domain DNS, and application route. This describes routing readiness, not delivery of a particular message or permission for automatic payer sign-in. Do not set it on a payer account until Veraxus marks it receiving."}},"required":["id","name","code_email_address","code_email_receiving"]}}},"required":["tenant_id","total","organizations"]},"GettingStartedResponse":{"type":"object","description":"First-day integration guide. Same sequence as MCP getting_started.","properties":{"title":{"type":"string","description":"Guide title."},"docs_url":{"type":"string","description":"Human walkthrough URL."},"reference_url":{"type":"string","description":"HTML API reference at GET /v1/reference."},"billed":{"type":"boolean","description":"False: reading this guide is not billed."},"sequence":{"type":"array","description":"Six first-day steps, REST and MCP verbs each.","items":{"type":"object","properties":{"step":{"type":"integer","description":"1-based step number."},"title":{"type":"string","description":"Step title."},"rest":{"type":"string","description":"REST call for this step."},"mcp":{"type":"string","description":"MCP tool for this step."},"when":{"type":"string","description":"When to run this step."},"billed":{"type":"boolean","description":"Whether this step bills a live check."}},"required":["step","title","rest","mcp","when"]}},"sandbox":{"type":"object","description":"Unpaid DEMO members and the sandbox tool."},"live":{"type":"object","description":"Live check field list and payer routing."},"next":{"type":"object","description":"Next guide after this one (portal login)."},"rules":{"type":"array","items":{"type":"string"},"description":"Standing rules for the first day."},"markdown":{"type":"string","description":"Full markdown of the guide."},"before_you_submit":{"type":"object","description":"Preflight needing-sign-in, branch on why (including reconnect → retry.ok false), failed checks are HTTP 200 with status=failed, and subscribe to portal_login.state_changed / portal_login.status_changed / eligibility.failed."}},"required":["title","docs_url","billed","sequence","markdown"]},"SandboxMembersResponse":{"type":"object","description":"Published DEMO members for unpaid checks.","properties":{"members":{"type":"array","description":"DEMO member_id rows for check_sandbox_eligibility.","items":{"type":"object","properties":{"member_id":{"type":"string","description":"Send as member_id."},"plan":{"type":"string","description":"Plan label."},"group_number":{"type":"string","description":"Sandbox group number."},"active":{"type":"boolean","description":"False on the terminated DEMO member."},"notes":{"type":"string","description":"Coverage sketch, not a live harvest."}},"required":["member_id"]}},"billed":{"type":"boolean","const":false,"description":"Listing sandbox members is never billed."}},"required":["members","billed"]},"ClaimsGuideResponse":{"type":"object","description":"Vendor claims cookbook. Same sequence as MCP claims_guide.","properties":{"title":{"type":"string","description":"Guide title."},"docs_url":{"type":"string","description":"Human walkthrough URL."},"billed":{"type":"boolean","description":"False: reading this guide is not billed."},"sequence":{"type":"array","description":"End-to-end vendor filing steps."},"sandbox":{"type":"object","description":"DEMO members and expected outcomes."},"safety":{"type":"array","items":{"type":"string"},"description":"Safety rules vendors must implement."},"scopes":{"type":"object","description":"Scope requirements."},"errors":{"type":"array","description":"Compact error-code table."},"markdown":{"type":"string","description":"Full markdown of the guide."}},"required":["title","docs_url","billed","sequence","markdown"]},"PortalLoginGuideResponse":{"type":"object","description":"Portal-login cookbook. Same sequence as MCP portal_login_guide.","properties":{"title":{"type":"string","description":"Guide title."},"docs_url":{"type":"string","description":"Human walkthrough URL."},"person_required":{"type":"boolean","description":"True: a person must be at the desk."},"billed":{"type":"boolean","description":"False: this guide is not billed."},"sequence":{"type":"array","description":"Native Veraxus HITL: store, connect, paste code, confirm."},"vendor_flow":{"type":"array","description":"Vendor model: list payers → store credentials → connect → subscribe to portal_login.state_changed → switch on login_state."},"login_states":{"type":"array","description":"login_state values and next_action for vendor UI."},"availability":{"type":"array","description":"Payer availability and sign_in_method guidance from GET /v1/payers."},"verora_delegated":{"type":"object","additionalProperties":false,"description":"Separate Verora delegated workflow. For an organization-scoped payer row, onboarding_enabled=true admits one signed composite store-and-login operation. Licensed non-UCCI rows on the closed Connect allowlist use that same Connect engine internally; United Concordia remains limited to its separately released exact tn_verora/org_4ab6ddda scope. DNoA is the password-per-check custody path. payer_ids names only the static DNoA and sandbox_mfa fixtures, not the dynamic organization capability set. sandbox_mfa stays restricted to the configured non-customer organization. Revocation is a separate, narrower capability. Never follow delegated onboarding with native Connect.","properties":{"audience":{"type":"string","const":"Verora embedded only"},"payer_ids":{"type":"array","description":"Static DNoA/sandbox delegated fixtures only, not the dynamic organization capability set. Read onboarding_enabled from the exact organization-scoped payer row and separately require GET /v1/me caller authorization.","items":{"type":"string","enum":["dnoa","sandbox_mfa"]},"minItems":1,"maxItems":2},"required_scope":{"type":"string","const":"portal_login_mutation"},"caller_discovery":{"type":"string","const":"GET /v1/me → key.caller_id"},"caller_claim":{"type":"string","const":"caller_id"},"status_reads_are_pure":{"type":"boolean","const":true,"description":"True only for the static DNoA/sandbox exact-operation fixtures identified by payer_ids, not a universal no-state-change guarantee. An admitted UCCI observation may reconcile safe metadata, never replay a password, submit MFA, or perform revoke cleanup."},"onboarding_rest":{"type":"string","const":"POST /v1/portal/onboard"},"onboarding_mcp":{"type":"string","const":"onboard_portal_login"},"composite_store_and_connect":{"type":"boolean","const":true},"follow_up_connect":{"type":"boolean","const":false},"revocation_rest":{"type":"string","const":"POST /v1/portal/revoke"},"revocation_mcp":{"type":"string","const":"revoke_portal_login"},"sandbox_organization_required":{"type":"boolean","const":true},"sandbox_block_code":{"type":"string","const":"portal_login_sandbox_org_required"},"capability_fields":{"type":"array","items":{"type":"string"}},"onboarding_block_code":{"type":"string","const":"portal_login_recert_required"},"revocation_block_code":{"type":"string","const":"portal_login_revoke_recert_required"}},"required":["audience","payer_ids","required_scope","caller_discovery","caller_claim","status_reads_are_pure","onboarding_rest","onboarding_mcp","composite_store_and_connect","follow_up_connect","revocation_rest","revocation_mcp","sandbox_organization_required","sandbox_block_code","capability_fields","onboarding_block_code","revocation_block_code"]},"statuses":{"type":"array","description":"Machine status, meaning, and next verb."},"aetna":{"type":"object","description":"Aetna challenge_id / generation fields."},"rules":{"type":"array","items":{"type":"string"},"description":"Standing portal-login rules."},"markdown":{"type":"string","description":"Full markdown of the guide."},"before_you_submit":{"type":"object","description":"Preflight needing-sign-in, branch on why (including reconnect → retry.ok false), failed checks are HTTP 200 with status=failed, and subscribe to portal_login.state_changed / portal_login.status_changed / eligibility.failed."}},"required":["title","docs_url","person_required","billed","sequence","verora_delegated","markdown"]},"PortalLoginsResponse":{"type":"object","description":"Current portal-login health for one practice. Does not search a member.","properties":{"organization_id":{"type":"string","description":"Practice these logins belong to."},"portal_logins":{"type":"array","description":"One row per licensed portal payer.","items":{"type":"object","additionalProperties":false,"description":"One payer login on this practice. Use verification_admission for whether a new request may be attempted; login_state describes the connection. Unavailable benefits never publish legacy ready/Serving/alive.","properties":{"payer_id":{"type":"string","description":"Catalog payer id. Use this as eligibility payer_id."},"name":{"type":"string","description":"Payer display name."},"enabled":{"type":"boolean","description":"Whether this payer is currently enabled for new sign-in and checks."},"revoke_only":{"type":"boolean","description":"True for a disabled payer cleanup row. login_saved=true exposes Disconnect only when the matching payer catalog row has revocation_enabled=true; login_saved=false is a safe terminal revoke tombstone for ambiguous-response recovery and must not render a portal action."},"status":{"type":"string","enum":["ready","reconnecting","needs_code","confirmation_pending","expired","not_connected","credentials_invalid","locked","portal_outage","quarantined","status_unknown","vault_error"],"description":"Machine status for filters: ready, reconnecting (automatic email-code sign-in is in progress; poll), needs_code, confirmation_pending, expired (bounce; never needs_mint), not_connected, credentials_invalid, locked, portal_outage, quarantined, vault_error, status_unknown (checking/unverified). A bounce is expired unless the guarded automatic reconnect path is active."},"situation":{"type":"string","enum":["serving","renewing","code_owed","sign_in","not_connected","checking","unverified","payer_down","blocked","vault_error"],"description":"Closed desk situation: serving, renewing, code_owed, sign_in, not_connected, checking, unverified, payer_down, blocked, vault_error. Never status_unknown."},"situation_label":{"type":"string","description":"Desk English: Serving, Renewing, Code owed, Sign in, Not connected, Checking, Unverified, Payer down, Blocked, Vault unavailable."},"desk":{"type":"string","enum":["alive","needs_sign_in","needs_attention","enter_code","set_up"],"description":"Whether the front desk can proceed. alive means the office can run eligibility without signing in again. This is not situation=serving: a guessed-in-band session still paints alive. needs_attention means no desk action exists (blocked or vault_error); enter_code covers both a code and an approve hold; set_up is not_connected."},"login_state":{"type":"string","enum":["logged_in","renewing","checking","needs_code","needs_login","unavailable"],"description":"The one field a vendor UI should switch on: logged_in, renewing, checking, needs_code, needs_login, unavailable."},"login_state_reason":{"type":"string","description":"Stable snake_case why for login_state. Documented codes include password_saved_unverified, sign_in_not_supported, benefits_not_captured, plus the classifier reason (fresh_probe, code_owed, approve, worker_status_side_effects, not_connected, …)."},"checked_at":{"type":["string","null"],"description":"Newest authenticated evidence or probe time behind this state, ISO-8601 UTC. Null = never verified."},"next_action":{"type":"string","enum":["none","wait","store_credentials","connect","enter_code","approve_push"],"description":"What the vendor should do next: none, wait, store_credentials, connect, enter_code, approve_push."},"has_credentials":{"type":"boolean","description":"True when this practice has a saved mailbox login in the vault."},"verification_admission":{"type":"object","additionalProperties":false,"description":"Permission to attempt the exact practice/book/request. It does not attest a patient match or completed benefits. Submission rechecks it before dispatch.","properties":{"version":{"type":"string","const":"1","description":"Admission contract version."},"practice_id":{"type":"string","description":"Exact practice this decision applies to."},"payer_id":{"type":"string","description":"Exact canonical payer book; sibling books retain separate admission."},"mailbox_id":{"type":"string","description":"Shared-login action group; does not merge payer sessions."},"disposition":{"type":"string","enum":["proceed","wait","action_required","input_required","unsupported"],"description":"Permission to attempt, wait for evidence, complete setup, correct input, or use another supported source."},"reason":{"type":"string","description":"Machine-readable reason for the decision."},"message":{"type":"string","description":"Customer explanation of the decision."},"action":{"type":"object","additionalProperties":false,"description":"Next action and the party responsible for completing it.","properties":{"owner":{"type":"string","enum":["none","practice","customer","veraxus"],"description":"Party responsible for the action; none means no action is required."},"kind":{"type":"string","enum":["none","refresh_status","store_credentials","connect","enter_code","approve_push","correct_input"],"description":"Typed next action; an eligibility request never asks for credentials or a human code."},"href":{"type":["string","null"],"description":"Allowed console path for a practice action, or null."},"field":{"type":["string","null"],"description":"Request field to correct, or null; never contains a patient value."}},"required":["owner","kind","href","field"]},"checked_at":{"type":["string","null"],"format":"date-time","description":"Authenticated evidence timestamp, or null when none is available."},"assessed_at":{"type":"string","format":"date-time","description":"Time this admission decision was assessed."},"valid_until":{"type":"string","format":"date-time","description":"Decision freshness deadline; dispatch still rechecks admission."}},"required":["version","practice_id","payer_id","mailbox_id","disposition","reason","message","action","checked_at","assessed_at","valid_until"]},"request_capabilities":{"type":"object","additionalProperties":false,"description":"Request shapes this exact payer book can accept; practice enablement and connection readiness are assessed separately.","properties":{"availity_payers":{"type":"array","description":"Captured Availity insurer choices. Use id as availity_payer_id with payer_id=availity, or use id/aliases directly as eligibility payer_id. All use the practice's Availity login.","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}}},"required":["id","name","aliases"]}},"single":{"type":"boolean","description":"Whether single-patient requests are supported."},"batch":{"type":"boolean","description":"Whether day-book requests are supported."},"dependent":{"type":"boolean","description":"Whether the connector can select the requested dependent."},"dependent_requires_subscriber":{"type":"boolean","description":"Whether a dependent request must also carry subscriber identity."},"required_fields":{"type":"array","items":{"type":"string"},"description":"Required patient request field names."},"dependent_fields":{"type":"array","items":{"type":"string"},"description":"Additional field names used to identify a dependent."},"procedure_code":{"type":"string","enum":["optional","unsupported"],"description":"Whether a single request may specify a procedure code."},"default_procedure_code":{"type":["string","null"],"description":"Default procedure code, if this book defines one."},"batch_procedure_code":{"type":"boolean","description":"Whether batch rows may specify a procedure code."}},"required":["single","batch","dependent","dependent_requires_subscriber","required_fields","dependent_fields","procedure_code","default_procedure_code","batch_procedure_code"]},"availability":{"type":"string","enum":["available","coming_soon"]},"availability_reason":{"type":["string","null"],"enum":["sign_in_not_supported","benefits_not_captured",null]},"last_client_reference":{"type":["string","null"],"description":"Last vendor client_reference supplied on Connect, or null."},"challenge":{"type":["object","null"],"additionalProperties":false,"description":"Parked MFA challenge when status is needs_code or confirmation_pending.","properties":{"challenge_id":{"type":"string","description":"Exact parked challenge identifier."},"challenge_generation":{"type":"integer","minimum":1,"description":"Generation paired with challenge_id."},"type":{"type":"string","enum":["sms_otp","email_otp","totp","push"],"description":"From catalog mfaTypes[0] when known. Omitted when unknown."},"masked_destination":{"type":["string","null"],"description":"Masked delivery target when the portal supplied one."},"requested_at":{"type":"string","description":"UTC time the challenge was requested."},"expires_at":{"type":"string","description":"UTC expiry when the payer provides one. Required on united_concordia delegated challenges."}},"required":["challenge_id","challenge_generation"]},"evidence":{"type":"object","additionalProperties":false,"description":"Newest authenticated and failure clocks behind the classifier verdict.","properties":{"newestAuthenticatedAt":{"type":["string","null"]},"newestAuthenticatedSource":{"type":["string","null"],"enum":["probe","keepalive","serve","mint","vault",null]},"newestFailureAt":{"type":["string","null"]},"newestFailureKind":{"type":["string","null"]},"signInDueAt":{"type":["string","null"],"description":"Observed Keyspring sign-in expiry (auth_time plus 30 days), UTC. This clock alone does not prove current authentication."},"windowMs":{"type":["number","null"]},"windowSource":{"type":["string","null"],"enum":["measured","guessed","fallback","unmeasured","password_each_check",null]}}},"action":{"type":"string","enum":["none","check_now","renew_now","enter_code","resend_code","approve","sign_in","set_up"],"description":"Classifier desk action. Prefer next_action for vendor UI."},"reason":{"type":"string","description":"Classifier machine reason (snake_case)."},"renew":{"type":"object","additionalProperties":false,"properties":{"reconnectCost":{"type":"string","enum":["none","password_only","code"]},"lastAttemptAt":{"type":["string","null"]},"lastOutcome":{"type":["string","null"]},"nextDueAt":{"type":["string","null"]}}},"hold":{"type":"object","additionalProperties":false,"properties":{"holdKind":{"type":"string","enum":["code","approve"]},"sendReceipt":{"type":"boolean"},"expiresAt":{"type":["string","null"]}}},"autoRenew":{"type":"boolean","const":true,"description":"Present (true) when situation is renewing."},"health_event":{"type":["object","null"],"additionalProperties":false,"description":"Historical keep-health event. Never a Serving/Reconnect decision.","properties":{"kind":{"type":"string"},"at":{"type":"string"},"state":{"type":["string","null"]},"copy":{"type":"string"}}},"last_probe_class":{"type":["string","null"],"description":"Measured portal-access class: alive, sign_in, outage, or unknown."},"last_health_check":{"type":"string","description":"Plain-words measured portal access. A missing sample is not an outage."},"last_health_check_at":{"type":["string","null"],"description":"UTC time of that access sample, or null."},"keep_expiry_copy":{"type":"string","description":"Login-lifetime forecast. Never a Serving/Reconnect decision. Unmeasured when no worker or contract clock exists."},"cookie_names":{"type":"array","description":"Names only of persisted portal cookies (remember-this-device / session). Never values. Provider Tools remember-this-device is Okta DT.","items":{"type":"string"}},"last_sso_renew_outcome":{"type":["string","null"],"enum":["ok","login_required","interaction_required","ui_rendered","error",null],"description":"Dental HUB operator diagnostic: last prompt=none SSO renew outcome. Never a listed-status input."},"sso_silent_check":{"type":["object","null"],"additionalProperties":false,"required":["at","outcome"],"properties":{"at":{"type":"string","description":"UTC time of the post-mint silent check."},"outcome":{"type":"string","description":"Classifier label. Never an authorization code."}},"description":"Dental HUB operator diagnostic from the post-mint prompt=none check."},"sso_cookie_persistent":{"type":["boolean","string","null"],"enum":[true,false,"unknown",null],"description":"Dental HUB operator diagnostic: whether the final x-ms-cpim-sso hop carried a future Expires or Max-Age."},"login_saved":{"type":"boolean","description":"True when the password is still in the vault."},"message":{"type":"string","description":"Instruction safe to show the office."},"mfa_required":{"type":"boolean","description":"True when a one-time code is owed now."},"mfa_confirmation_pending":{"type":"boolean","description":"True when MetLife already has the code."},"code_sent_at":{"type":["string","null"],"description":"When the parked code was requested."},"start_with":{"type":["string","null"],"description":"store_credentials or connect_portal_login, else null."},"complete_with":{"type":["string","null"],"description":"complete_portal_mfa or complete_aetna_portal_mfa, else null."},"observe_with":{"type":["string","null"],"description":"observe_metlife_portal_mfa when Confirming."},"generation":{"type":["integer","null"],"description":"Keep generation when known."},"operation_id":{"type":["string","null"],"description":"Latest delegated onboarding or revoke operation for this payer. Use with operation_action and operation_status to recover an ambiguous POST response."},"operation_action":{"type":["string","null"],"enum":["portal_login_onboard","portal_login_revoke",null]},"operation_status":{"type":["string","null"],"enum":["received","credentials_stored","connect_started","needs_code","confirmation_pending","ready","failed","outage","revoking","revoked",null],"description":"Latest exact durable operation state, including intermediate and terminal outcomes."},"operation_ok":{"type":["boolean","null"]},"operation_stored":{"type":["boolean","null"]},"operation_revoked":{"type":["boolean","null"]},"operation_credentials_deleted":{"type":["boolean","null"]},"operation_sessions_invalidated":{"type":["boolean","null"]},"operation_message":{"type":["string","null"]},"operation_error_code":{"type":["string","null"],"description":"Stable terminal operation-status code, or null. sign_in_failed (retryable:false, human action required) means sign-in did not complete with this saved login; Veraxus will not retry. credentials_invalid (retryable:false) means the portal rejected the saved login; operation_error_reason is invalid_credentials, account_locked, or password_expired. Do not treat sign_in_failed as portal_outage."},"operation_error_reason":{"type":["string","null"],"enum":["invalid_credentials","account_locked","password_expired",null],"description":"Portal rejection class when operation_error_code is credentials_invalid. Null otherwise."},"operation_updated_at":{"type":["string","null"]},"onboarding_status":{"type":["string","null"],"enum":["needs_code","confirmation_pending",null],"description":"Resumable delegated onboarding state, or null when no active operation exists."},"revocation_status":{"type":["string","null"],"enum":["received","revoking",null],"description":"Refresh-safe delegated revocation state, or null when no revoke is active."},"challenges":{"type":"array","description":"Exact non-secret challenge tuples bound to operation_id.","items":{"type":"object","additionalProperties":false,"description":"Non-secret metadata for the exact parked MFA challenge.","properties":{"challenge_id":{"type":"string","description":"Exact parked challenge identifier."},"challenge_generation":{"type":"integer","minimum":1,"description":"Generation paired with challenge_id."},"type":{"type":"string","enum":["sms_otp","email_otp","totp","push"],"description":"From catalog mfaTypes[0] when known. Omitted when unknown."},"masked_destination":{"type":["string","null"],"description":"Masked delivery target when the portal supplied one."},"requested_at":{"type":"string","description":"UTC time the challenge was requested."},"expires_at":{"type":"string","description":"UTC expiry when the payer provides one. Required on united_concordia delegated challenges."}},"required":["challenge_id","challenge_generation"]}}},"required":["payer_id","enabled","revoke_only","status","situation_label","desk","login_state","login_state_reason","checked_at","next_action","has_credentials","cookie_names","login_saved","message","operation_id","operation_action","operation_status","operation_ok","operation_stored","operation_revoked","operation_credentials_deleted","operation_sessions_invalidated","operation_message","operation_error_code","operation_error_reason","operation_updated_at","onboarding_status","revocation_status","challenges"]}}},"required":["organization_id","portal_logins"]},"PortalLoginSnapshotResponse":{"type":"object","additionalProperties":false,"description":"Fast secret-free portal-login snapshot. Credential presence is read from the current vault row; connector state is the last canonical observation and becomes status_unknown when stale.","properties":{"organization_id":{"type":"string","description":"Practice these logins belong to."},"portal_logins":{"type":"array","description":"One secret-free cached connector state per licensed payer.","items":{"type":"object","additionalProperties":false,"properties":{"payer_id":{"type":"string"},"name":{"type":"string"},"enabled":{"type":"boolean"},"status":{"type":"string"},"last_status":{"type":["string","null"]},"login_state":{"type":"string","enum":["logged_in","renewing","checking","needs_code","needs_login","unavailable"]},"next_action":{"type":"string","enum":["none","wait","store_credentials","connect","enter_code","approve_push"]},"desk":{"type":"string","enum":["alive","needs_sign_in","needs_attention","enter_code","set_up"]},"situation_label":{"type":"string"},"has_credentials":{"type":"boolean"},"shares_with":{"type":"array","items":{"type":"string"}},"checked_at":{"type":["string","null"]},"last_health_check_at":{"type":["string","null"]},"snapshot_at":{"type":["string","null"]},"stale":{"type":"boolean"},"verification_admission":{"type":"object","additionalProperties":false,"description":"Permission to attempt the exact practice/book/request. It does not attest a patient match or completed benefits. Submission rechecks it before dispatch.","properties":{"version":{"type":"string","const":"1","description":"Admission contract version."},"practice_id":{"type":"string","description":"Exact practice this decision applies to."},"payer_id":{"type":"string","description":"Exact canonical payer book; sibling books retain separate admission."},"mailbox_id":{"type":"string","description":"Shared-login action group; does not merge payer sessions."},"disposition":{"type":"string","enum":["proceed","wait","action_required","input_required","unsupported"],"description":"Permission to attempt, wait for evidence, complete setup, correct input, or use another supported source."},"reason":{"type":"string","description":"Machine-readable reason for the decision."},"message":{"type":"string","description":"Customer explanation of the decision."},"action":{"type":"object","additionalProperties":false,"description":"Next action and the party responsible for completing it.","properties":{"owner":{"type":"string","enum":["none","practice","customer","veraxus"],"description":"Party responsible for the action; none means no action is required."},"kind":{"type":"string","enum":["none","refresh_status","store_credentials","connect","enter_code","approve_push","correct_input"],"description":"Typed next action; an eligibility request never asks for credentials or a human code."},"href":{"type":["string","null"],"description":"Allowed console path for a practice action, or null."},"field":{"type":["string","null"],"description":"Request field to correct, or null; never contains a patient value."}},"required":["owner","kind","href","field"]},"checked_at":{"type":["string","null"],"format":"date-time","description":"Authenticated evidence timestamp, or null when none is available."},"assessed_at":{"type":"string","format":"date-time","description":"Time this admission decision was assessed."},"valid_until":{"type":"string","format":"date-time","description":"Decision freshness deadline; dispatch still rechecks admission."}},"required":["version","practice_id","payer_id","mailbox_id","disposition","reason","message","action","checked_at","assessed_at","valid_until"]},"request_capabilities":{"type":"object","additionalProperties":false,"description":"Request shapes this exact payer book can accept; practice enablement and connection readiness are assessed separately.","properties":{"availity_payers":{"type":"array","description":"Captured Availity insurer choices. Use id as availity_payer_id with payer_id=availity, or use id/aliases directly as eligibility payer_id. All use the practice's Availity login.","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}}},"required":["id","name","aliases"]}},"single":{"type":"boolean","description":"Whether single-patient requests are supported."},"batch":{"type":"boolean","description":"Whether day-book requests are supported."},"dependent":{"type":"boolean","description":"Whether the connector can select the requested dependent."},"dependent_requires_subscriber":{"type":"boolean","description":"Whether a dependent request must also carry subscriber identity."},"required_fields":{"type":"array","items":{"type":"string"},"description":"Required patient request field names."},"dependent_fields":{"type":"array","items":{"type":"string"},"description":"Additional field names used to identify a dependent."},"procedure_code":{"type":"string","enum":["optional","unsupported"],"description":"Whether a single request may specify a procedure code."},"default_procedure_code":{"type":["string","null"],"description":"Default procedure code, if this book defines one."},"batch_procedure_code":{"type":"boolean","description":"Whether batch rows may specify a procedure code."}},"required":["single","batch","dependent","dependent_requires_subscriber","required_fields","dependent_fields","procedure_code","default_procedure_code","batch_procedure_code"]},"availability":{"type":"string","enum":["available","coming_soon"]},"availability_reason":{"type":["string","null"],"enum":["sign_in_not_supported","benefits_not_captured",null]},"login_state_reason":{"type":"string"}},"required":["payer_id","name","enabled","status","last_status","login_state","next_action","desk","situation_label","has_credentials","shares_with","checked_at","last_health_check_at","snapshot_at","stale"]}},"snapshot_at":{"type":["string","null"],"description":"Oldest observation time represented by this organization snapshot."},"stale":{"type":"boolean","description":"True when any listed payer lacks a canonical observation from the last ten minutes."},"refresh_after":{"type":["string","null"],"description":"Time the oldest observation leaves the ten-minute freshness window."}},"required":["organization_id","portal_logins","snapshot_at","stale","refresh_after"]},"CareingtonNetworkResponse":{"type":"object","description":"Careington is a leased PPO network. This is the office's own participation (plans, effective dates, fee schedule) read from its Careington portal login, plus the August payor-listing verdict for an optional carrier. Absent for practices without a Careington login (404 not_connected).","required":["organization_id","status","reason","participation","access","listing"],"properties":{"organization_id":{"type":"string","description":"The practice this participation belongs to.","example":"org_from_organizations"},"status":{"type":"string","enum":["ok","unavailable"],"description":"ok when the office's participation page was read now or within 24 hours; unavailable when the portal could not be read and the last read (if any) is shown.","example":"ok"},"reason":{"type":["string","null"],"enum":["soft_block","probe_failed","participation_unreadable",null],"description":"Why the office's participation page could not be read now. Null when status is ok.","example":null},"participation":{"type":"object","description":"The office's own Careington participation: plans it is on, effective dates, provider type, and the allowed amount per CDT code from the plan's discounts sheet.","required":["status","observed_at","reused","provider_type","specialty","plans","fee_link","fee_rows"],"properties":{"status":{"type":"string","enum":["participating","not_participating","unknown"],"description":"participating when the page lists at least one plan; not_participating when it lists none; unknown when it has never been read.","example":"participating"},"observed_at":{"type":["string","null"],"description":"When the participation page was last read.","example":"2026-09-26T13:00:00.000Z"},"reused":{"type":"boolean","description":"True when a read younger than 24 hours was reused.","example":true},"provider_type":{"type":["string","null"],"description":"Provider type printed on the page (for example GENERAL DENTIST or SPECIALIST).","example":"GENERAL DENTIST"},"specialty":{"type":["string","null"],"description":"Specialty printed on the page, when any.","example":null},"plans":{"type":"array","description":"Careington plans the office participates in.","items":{"type":"object","required":["plan_name","effective_date"],"properties":{"plan_name":{"type":"string","description":"Plan name as printed.","example":"Care Platinum Series PPO"},"effective_date":{"type":["string","null"],"description":"Plan effective date as printed, ISO date when parseable.","example":"2020-01-01"}}}},"fee_link":{"type":"string","enum":["absent","dead","parsed","unparsed"],"description":"Whether the plan's discounts sheet link existed and parsed.","example":"parsed"},"fee_rows":{"type":["array","null"],"description":"Allowed amount per CDT code from the plan's discounts sheet. Null when the sheet was absent or unparsed.","items":{"type":"object","required":["code","description","allowed"],"properties":{"code":{"type":"string","description":"CDT code.","example":"D0120"},"description":{"type":"string","description":"Procedure description as printed.","example":"Periodic oral evaluation - established patient"},"allowed":{"type":"number","description":"Allowed amount in dollars from the discounts sheet.","example":17}}}}}},"access":{"type":["object","null"],"description":"Present when the payer query was given: whether that carrier is printed as accessing the Careington network, judged through this office's own participation.","required":["status","reason","matches","disclaimer"],"properties":{"status":{"type":"string","enum":["listed","conditional","excluded","not_listed","ambiguous","not_applicable"],"example":"listed"},"reason":{"type":["string","null"],"description":"Why the verdict is not_applicable, when it is.","example":null},"matches":{"type":"array","description":"Payor-listing rows the carrier matched, each with its printed status and reasons.","items":{"type":"object","required":["id","name","status","reasons"],"properties":{"id":{"type":"string","description":"Listing row id.","example":"renaissance"},"name":{"type":"string","description":"Carrier or TPA name as printed.","example":"Renaissance"},"status":{"type":"string","enum":["listed","conditional","excluded"],"description":"Printed access status for this office.","example":"listed"},"reasons":{"type":"array","description":"Printed conditions or exclusions behind the status.","items":{"type":"string"},"example":[]}}}},"disclaimer":{"type":["string","null"],"description":"The listing's own disclaimer.","example":"The carrier, TPA or claims payor decides the network at claims processing."}}},"listing":{"type":"object","description":"Which payor listing the access verdict was judged against.","required":["month","sha256"],"properties":{"month":{"type":"string","description":"Listing month.","example":"2026-08"},"sha256":{"type":"string","description":"SHA-256 of the transcribed listing.","example":"0000000000000000000000000000000000000000000000000000000000000000"}}}},"additionalProperties":false},"PracticeInboxResponse":{"type":"object","description":"Payer mail that reached this practice's code address and was not used by Veraxus as a sign-in code: password resets, confirm-your-email, security notices, and codes that arrived when no Veraxus sign-in was waiting. A code Veraxus entered into a portal is never listed. Newest first, at most 50, each kept 72 hours.","required":["organization_id","code_email_address","code_email_receiving","retention_hours","messages"],"properties":{"organization_id":{"type":"string","description":"The practice this inbox belongs to."},"code_email_address":{"type":["string","null"],"description":"Code-only address on codes.veraxus.ai for enrolled accounts; null otherwise. Do not set it on a payer account until Veraxus marks it receiving."},"code_email_receiving":{"type":"boolean","description":"True when receiving is released and the address has a fresh verified provider route, receiving-domain DNS, and application route. This describes routing readiness, not delivery of a particular message or permission for automatic payer sign-in. Do not set it on a payer account until Veraxus marks it receiving."},"retention_hours":{"type":"integer","const":72,"description":"Hours a message is kept before deletion."},"messages":{"type":"array","maxItems":50,"description":"Messages, newest first. No bodies; read one with GET /v1/inbox/{id}.","items":{"type":"object","required":["id","sender_domain","sender_name","subject","kind","needs_action","preview","received_at","expires_at"],"properties":{"id":{"type":"string","description":"Stable message id within this practice."},"sender_domain":{"type":"string","description":"Sending domain, for example metlife.com."},"sender_name":{"type":"string","description":"Display name from the From header, or the sender domain."},"subject":{"type":"string","description":"Subject line. Codes, code-like tokens, and runs of four or more digits are masked; the open read returns the original."},"kind":{"type":"string","enum":["password_reset","email_change","sign_in_code","security_notice","other"],"description":"What the message looks like from its wording. A label for sorting, never proof of what the payer intended."},"needs_action":{"type":"boolean","description":"True for a password reset or confirm-your-email message: the payer is waiting on the practice."},"preview":{"type":"string","description":"First readable line of the text, at most 140 characters, with codes, code-like tokens, and runs of four or more digits masked."},"received_at":{"type":"string","description":"ISO-8601 time the message arrived."},"expires_at":{"type":"string","description":"ISO-8601 time the message is deleted."}}}}}},"PracticeInboxMessageResponse":{"type":"object","description":"One message in full. Text only: HTML is reduced to text before storage and there are no attachments. Each read writes a Veraxus audit row naming the credential.","required":["id","organization_id","from","sender_domain","subject","text","kind","code","action_link","links","received_at","expires_at"],"properties":{"id":{"type":"string","description":"Message id."},"organization_id":{"type":"string","description":"The practice this message belongs to."},"from":{"type":"string","description":"From header as sent, for example MetLife <no-reply@metlife.com>."},"sender_domain":{"type":"string","description":"Sending domain."},"subject":{"type":"string","description":"Subject line as sent."},"text":{"type":"string","maxLength":6000,"description":"Readable text of the message."},"kind":{"type":"string","enum":["password_reset","email_change","sign_in_code","security_notice","other"],"description":"What the message looks like from its wording. A label for sorting, never proof of what the payer intended."},"code":{"type":["string","null"],"pattern":"^[A-Z0-9]{4,12}$","example":"482913","description":"The one-time code when the message holds exactly one candidate: 4 to 8 digits, or a token of 4 to 12 capital letters and digits. Null when there is none or more than one."},"action_link":{"oneOf":[{"type":"object","required":["url","host"],"properties":{"url":{"type":"string","description":"An https link found in the message text."},"host":{"type":"string","description":"Hostname of that link. Show it beside the link."}}},{"type":"null"}],"description":"The reset, confirm, or verify link when one stands out; null otherwise."},"links":{"type":"array","items":{"type":"object","required":["url","host"],"properties":{"url":{"type":"string","description":"An https link found in the message text."},"host":{"type":"string","description":"Hostname of that link. Show it beside the link."}}},"description":"Every https link in the text, in order."},"received_at":{"type":"string","description":"ISO-8601 time the message arrived."},"expires_at":{"type":"string","description":"ISO-8601 time the message is deleted."}}},"PracticeAuthenticatorCodesResponse":{"type":"object","description":"Current and next 6-digit code for each saved login of this practice that holds an authenticator key. The key never leaves Veraxus. Every code lasts 30 seconds.","required":["organization_id","server_time","period_seconds","codes"],"properties":{"organization_id":{"type":"string","description":"The practice these codes belong to."},"server_time":{"type":"string","description":"ISO-8601 Veraxus time when the codes were computed. Count down on this clock, not the device's."},"period_seconds":{"type":"integer","const":30,"description":"Seconds each code lasts."},"codes":{"type":"array","description":"One row per saved login with an authenticator key. Empty when there is none.","items":{"type":"object","required":["id","name","payer_ids","code","valid_from","valid_until","next_code"],"properties":{"id":{"type":"string","pattern":"^[a-z0-9_]{1,64}$","description":"Catalog payer id of the saved login. Unique within the response."},"name":{"type":"string","description":"The login's name as Veraxus Portal logins shows it."},"payer_ids":{"type":"array","items":{"type":"string"},"description":"Every catalog payer this login's key is saved on. More than one for a shared login."},"code":{"type":"string","pattern":"^[0-9]{6}$","example":"482913","description":"The code the authenticator app shows now."},"valid_from":{"type":"string","description":"ISO-8601 start of the current code's 30 seconds."},"valid_until":{"type":"string","description":"ISO-8601 time the current code stops working."},"next_code":{"type":"string","pattern":"^[0-9]{6}$","example":"482913","description":"The code from valid_until for the following 30 seconds. Show it at valid_until, then fetch again."}}}}}},"PortalLoginOperationResponse":{"type":"object","description":"Exact secret-free delegated operation receipt for REST-only ambiguous-response recovery. MCP list_portal_logins does not expose payer_id/operation_id filters. UCCI may reconcile safe observed metadata without a credential/code send, payer probe, or revoke cleanup.","properties":{"organization_id":{"type":"string","description":"Exact practice bound to the operation."},"portal_login_operation":{"type":"object","additionalProperties":false,"description":"Exact secret-free delegated operation in the requested organization and payer scope.","properties":{"payer_id":{"type":"string"},"operation_id":{"type":"string"},"operation_action":{"type":"string","enum":["portal_login_onboard","portal_login_revoke"]},"operation_status":{"type":"string","enum":["received","credentials_stored","connect_started","needs_code","confirmation_pending","ready","failed","outage","revoking","revoked"]},"operation_ok":{"type":"boolean"},"operation_stored":{"type":["boolean","null"]},"operation_revoked":{"type":["boolean","null"]},"operation_credentials_deleted":{"type":["boolean","null"]},"operation_sessions_invalidated":{"type":["boolean","null"]},"operation_message":{"type":["string","null"]},"operation_error_code":{"type":["string","null"],"description":"Stable terminal operation-status code, or null. sign_in_failed (retryable:false, human action required) means sign-in did not complete with this saved login; Veraxus will not retry. credentials_invalid (retryable:false) means the portal rejected the saved login; operation_error_reason is invalid_credentials, account_locked, or password_expired. Do not treat sign_in_failed as portal_outage."},"operation_error_reason":{"type":["string","null"],"enum":["invalid_credentials","account_locked","password_expired",null],"description":"Portal rejection class when operation_error_code is credentials_invalid. Null otherwise."},"operation_updated_at":{"type":"string"},"operation_authenticated_at":{"type":["string","null"],"format":"date-time","description":"UTC authentication event for this exact operation, not proof of a currently authenticated session."},"current_session_status":{"type":"string","enum":["authenticated","needs_code","unknown","expired","quarantined","revoked"],"description":"Worker-observed current session state, distinct from historical operation_status=ready. expired on a ready delegated United Concordia operation means the portal session ended; send a fresh POST /portal/onboard with a new operation_id. Do not revoke. Unknown or unmeasured freshness must not be displayed as currently connected; a historical revoke cannot attest that no newer login exists."},"operation_observed_at":{"type":["string","null"],"format":"date-time","description":"UTC time of the worker observation; null when none is available."},"onboarding_status":{"type":["string","null"],"enum":["needs_code","confirmation_pending",null]},"revocation_status":{"type":["string","null"],"enum":["received","revoking",null]},"confirmation_pending":{"type":"boolean"},"challenges":{"type":"array","description":"Exact non-secret challenge tuples bound to this operation.","items":{"type":"object","additionalProperties":false,"description":"Non-secret metadata for the exact parked MFA challenge.","properties":{"challenge_id":{"type":"string","description":"Exact parked challenge identifier."},"challenge_generation":{"type":"integer","minimum":1,"description":"Generation paired with challenge_id."},"type":{"type":"string","enum":["sms_otp","email_otp","totp","push"],"description":"From catalog mfaTypes[0] when known. Omitted when unknown."},"masked_destination":{"type":["string","null"],"description":"Masked delivery target when the portal supplied one."},"requested_at":{"type":"string","description":"UTC time the challenge was requested."},"expires_at":{"type":"string","description":"UTC expiry when the payer provides one. Required on united_concordia delegated challenges."}},"required":["challenge_id","challenge_generation"]}}},"required":["payer_id","operation_id","operation_action","operation_status","operation_ok","operation_stored","operation_revoked","operation_credentials_deleted","operation_sessions_invalidated","operation_message","operation_error_code","operation_error_reason","operation_updated_at","onboarding_status","revocation_status","confirmation_pending","challenges"],"allOf":[{"if":{"properties":{"payer_id":{"const":"united_concordia"}},"required":["payer_id"]},"then":{"properties":{"challenges":{"items":{"type":"object","properties":{"challenge_id":{"type":"string"},"challenge_generation":{"type":"integer","minimum":1},"expires_at":{"type":"string","format":"date-time"}},"required":["challenge_id","challenge_generation","expires_at"]}}}}}]}},"required":["organization_id","portal_login_operation"]},"PortalMfaChallengesResponse":{"type":"object","description":"Exact pending MFA challenges. Never includes email content or a code.","properties":{"organization_id":{"type":"string","description":"Practice these challenges belong to."},"challenges":{"type":"array","description":"Unexpired parked challenges.","items":{"type":"object","properties":{"payer_id":{"type":"string","description":"Payer that sent the challenge."},"challenge_id":{"type":"string","description":"Exact id for complete_aetna_portal_mfa."},"challenge_generation":{"type":"integer","description":"Generation paired with challenge_id."},"type":{"type":"string","enum":["sms_otp","email_otp","totp","push"],"description":"From catalog mfaTypes[0] when known. Omitted when unknown."},"masked_destination":{"type":["string","null"],"description":"Masked delivery target when the portal supplied one."},"status":{"type":"string","description":"Parked challenge status."},"requested_at":{"type":"string","description":"UTC time the challenge was requested."},"expires_at":{"type":"string","description":"UTC expiry."}},"required":["payer_id","challenge_id"]}}},"required":["organization_id","challenges"]},"PortalConnectResponse":{"type":"object","description":"Result of connect_portal_login / POST /portal/connect.","properties":{"ok":{"type":"boolean","description":"True when the login is ready or a code is parked."},"payer_id":{"type":"string","description":"Payer that was connected."},"organization_id":{"type":"string","description":"Practice this login belongs to."},"status":{"type":"string","enum":["ready","needs_code","confirmation_pending","expired","not_connected","credentials_invalid","locked","portal_outage","quarantined","status_unknown","vault_error","connected"],"description":"ready, needs_code, confirmation_pending, expired, not_connected, credentials_invalid, locked, portal_outage, quarantined, vault_error, or status_unknown. connected is a legacy alias of ready and must not be used on list rows."},"message":{"type":"string","description":"Instruction safe to show the office."},"complete_with":{"type":["string","null"],"description":"complete_portal_mfa or complete_aetna_portal_mfa when a code is parked."},"observe_with":{"type":["string","null"],"description":"observe_metlife_portal_mfa when Confirming."},"confirmation_pending":{"type":"boolean","description":"True when MetLife already has the code."},"challenges":{"type":"array","description":"Aetna challenges when needs_code."},"generation":{"type":["integer","null"],"description":"Keep generation when known."},"shares_with":{"type":"array","items":{"type":"string"},"description":"Sibling catalog ids that share this login."},"client_reference":{"type":["string","null"],"description":"Echo of the vendor client_reference from this call, or null when omitted."},"error":{"type":"object","description":"Present when ok is false.","properties":{"code":{"type":"string","description":"Stable machine code."},"message":{"type":"string","description":"Plain-words explanation."},"retryable":{"type":"boolean","description":"True for portal_outage siblings."},"retry_after":{"type":["integer","null"],"description":"Seconds to wait before retry. Null when not retryable."}}}},"required":["ok","status"]},"PortalMfaCompleteResponse":{"type":"object","description":"Result of completing or observing a parked MFA challenge. Every operation-bound outcome includes the exact organization_id, payer_id, and operation_id verified from the durable operation.","properties":{"ok":{"type":"boolean","description":"True when the code was accepted or observation succeeded."},"status":{"type":"string","description":"ready, needs_code, confirmation_pending, failed, or portal_outage. portal_outage replaces the deprecated status outage."},"legacy_status":{"type":"string","enum":["outage"],"deprecated":true,"description":"Deprecated one-release alias: present only when status is portal_outage, always outage. Branch on status/onboarding_status."},"message":{"type":"string","description":"Instruction safe to show the office."},"mfa_state":{"type":"string","description":"Code-door lifecycle state for this code: requested, code_sent, submitted, accepted, persisted, ready, expired, lost, rejected, outage, or unknown. Present only when the code door classified the result."},"operator_message":{"type":"string","description":"Plain instruction for this lifecycle state (for example, sign in again after an expired code window)."},"mfa_retryable":{"type":"boolean","description":"True when a code may be entered again on the same hold. Distinct from error.retryable, which is about retrying the request."},"organization_id":{"type":"string","description":"Exact practice from the verified delegated operation, when operation-bound."},"payer_id":{"type":"string","description":"Exact payer from the verified delegated operation, when operation-bound."},"operation_id":{"type":"string","description":"Exact delegated onboarding operation when this MFA call completed one."},"attempt_id":{"type":"string","minLength":43,"maxLength":43,"pattern":"^[A-Za-z0-9_-]{43}$","description":"Exact one-shot authority for a code-bearing delegated MFA request. It is random and contains no OTP-derived material."},"replayed":{"type":"boolean","description":"False on the first admitted attempt receipt; true when the same attempt replays that durable receipt without another provider submission."},"confirmation_pending":{"type":"boolean","description":"True exactly when onboarding_status is confirmation_pending."},"onboarding_status":{"type":"string","description":"Updated durable onboarding state when operation_id was supplied. Outage completions emit portal_outage (same token as list_portal_logins); failed is unchanged."},"error":{"type":"object","description":"Present when the code was rejected or the challenge was unavailable.","properties":{"code":{"type":"string","description":"Stable machine code."},"message":{"type":"string","description":"Plain-words explanation."},"retryable":{"type":"boolean","description":"True for portal_outage siblings."},"retry_after":{"type":["integer","null"],"description":"Seconds to wait before retry. Null when not retryable."}}}},"required":["status"]},"PortalOnboardResponse":{"type":"object","description":"Durable receipt for one delegated, human-consented portal credential-store and connect operation. Never includes credentials, OTP, consent JWS, or a password-derived public digest.","properties":{"operation_id":{"type":"string","description":"Caller-minted durable operation id."},"organization_id":{"type":"string","description":"Practice this onboarding belongs to."},"payer_id":{"type":"string","description":"Catalog payer being onboarded."},"status":{"type":"string","enum":["received","credentials_stored","connect_started","needs_code","confirmation_pending","ready","failed","outage"],"description":"Durable onboarding state."},"ok":{"type":"boolean","description":"True only when status is ready."},"stored":{"type":"boolean","description":"Credential custody truth: false before storage or when storage failed; true from credentials_stored onward."},"message":{"type":"string","description":"Instruction safe to show the user."},"complete_with":{"type":["string","null"],"description":"MFA completion tool when needed."},"observe_with":{"type":["string","null"],"description":"MetLife observation tool when confirming."},"confirmation_pending":{"type":"boolean","description":"True after a MetLife code was submitted."},"challenges":{"type":"array","description":"Exact non-secret MFA challenge tuples bound to this operation.","items":{"type":"object","additionalProperties":false,"description":"Non-secret metadata for the exact parked MFA challenge.","properties":{"challenge_id":{"type":"string","description":"Exact parked challenge identifier."},"challenge_generation":{"type":"integer","minimum":1,"description":"Generation paired with challenge_id."},"type":{"type":"string","enum":["sms_otp","email_otp","totp","push"],"description":"From catalog mfaTypes[0] when known. Omitted when unknown."},"masked_destination":{"type":["string","null"],"description":"Masked delivery target when the portal supplied one."},"requested_at":{"type":"string","description":"UTC time the challenge was requested."},"expires_at":{"type":"string","description":"UTC expiry when the payer provides one. Required on united_concordia delegated challenges."}},"required":["challenge_id","challenge_generation"]}},"generation":{"type":["integer","null"],"description":"Keep generation when known."},"shares_with":{"type":"array","items":{"type":"string"},"description":"Sibling catalog ids sharing this login."},"error_code":{"type":["string","null"],"description":"Stable terminal/outage code, if any. sign_in_failed (retryable:false, human action required) means sign-in did not complete; start a new operation_id after the office signs in to the portal with the saved login directly. credentials_invalid (retryable:false) means the portal rejected the saved login."},"replayed":{"type":"boolean","description":"True when the exact operation request replayed its durable receipt."}},"allOf":[{"if":{"properties":{"status":{"enum":["credentials_stored","connect_started","needs_code","confirmation_pending","ready"]}},"required":["status"]},"then":{"properties":{"stored":{"const":true}}}}],"required":["operation_id","organization_id","payer_id","status","ok","stored","message","confirmation_pending","challenges","replayed"]},"PortalRevokeResponse":{"type":"object","description":"Exact durable receipt for a delegated portal-login revocation. Never includes credentials, session material, or the consent JWS.","properties":{"operation_id":{"type":"string","description":"Caller-minted durable operation id."},"organization_id":{"type":"string","description":"Exact practice that was authorized."},"payer_id":{"type":"string","description":"Exact payer that was authorized."},"status":{"type":"string","enum":["received","revoking","revoked","failed","outage"],"description":"Durable revocation state."},"ok":{"type":"boolean","description":"True only when status is revoked."},"revoked":{"type":"boolean","description":"True only after this durable revoke committed; historical proof for the exact operation, not evidence that no newer login exists."},"credentials_deleted":{"type":"boolean","description":"True only after this operation committed deletion of the canonical scoped credential-vault mailbox. Not an attestation about backups or non-current storage versions, or a newer login."},"sessions_invalidated":{"type":"boolean","description":"True only after this operation invalidated current artifacts at every scoped session authority. For admitted UCCI this includes current authoritative session state and local session artifacts, not payer-side logout or historical backups/versions; a newer login is outside this receipt."},"shares_with":{"type":"array","items":{"type":"string"},"description":"Sibling catalog ids whose canonical mailbox was revoked."},"message":{"type":"string","description":"Instruction safe to show the user."},"error_code":{"type":["string","null"],"description":"Stable terminal or outage code, otherwise null."},"replayed":{"type":"boolean","description":"True when an exact retry recovered the durable receipt."},"error":{"type":"object","description":"Closed public error envelope when revocation did not complete."}},"required":["operation_id","organization_id","payer_id","status","ok","revoked","credentials_deleted","sessions_invalidated","shares_with","message","error_code","replayed"]},"PortalOnboardRequest":{"type":"object","additionalProperties":false,"properties":{"organization_id":{"type":"string","description":"Practice bound into the delegated consent assertion."},"payer_id":{"type":"string","description":"Catalog payer id."},"portal_username":{"type":"string","maxLength":512,"description":"Portal username supplied by the consenting person for the exact capability-admitted payer."},"portal_password":{"type":"string","maxLength":4096,"writeOnly":true,"description":"Vaulted and never returned or written to the operation ledger."},"npi":{"type":["string","null"],"maxLength":32,"description":"Optional practice NPI stored with the canonical mailbox."},"operation_id":{"type":"string","minLength":16,"maxLength":256,"pattern":"^[A-Za-z0-9:_-]+$","description":"Caller-minted durable idempotency identity."},"request_nonce":{"type":"string","minLength":22,"maxLength":256,"pattern":"^[A-Za-z0-9_-]+$","description":"High-entropy base64url nonce bound into the JWS."},"actor_user_id":{"type":"string","maxLength":256,"description":"Verora user id bound into the delegated-consent assertion."},"consent_session_id":{"type":"string","maxLength":256,"description":"Verora consent-screen session bound into the assertion."},"delegated_consent":{"type":"string","maxLength":16384,"writeOnly":true,"description":"Compact RS256 JWS. Protected header must be alg=RS256, typ=veraxus-delegated-consent+jwt, and a pinned kid."}},"required":["organization_id","payer_id","portal_username","portal_password","operation_id","request_nonce","actor_user_id","consent_session_id","delegated_consent"]},"PortalRevokeRequest":{"type":"object","additionalProperties":false,"properties":{"organization_id":{"type":"string","description":"Practice bound into the delegated revoke assertion."},"payer_id":{"type":"string","description":"Catalog payer id."},"operation_id":{"type":"string","minLength":16,"maxLength":256,"pattern":"^[A-Za-z0-9:_-]+$","description":"Caller-minted durable revoke idempotency identity."},"request_nonce":{"type":"string","minLength":22,"maxLength":256,"pattern":"^[A-Za-z0-9_-]+$","description":"High-entropy base64url nonce bound into the revoke JWS."},"actor_user_id":{"type":"string","maxLength":256,"description":"Verora user id bound into the delegated-revoke assertion."},"consent_session_id":{"type":"string","maxLength":256,"description":"Verora consent-screen session bound into the revoke assertion."},"delegated_consent":{"type":"string","maxLength":16384,"writeOnly":true,"description":"Compact RS256 JWS with action=portal_login_revoke and the exact revoke audience."}},"required":["organization_id","payer_id","operation_id","request_nonce","actor_user_id","consent_session_id","delegated_consent"]},"PortalMfaRequest":{"type":"object","additionalProperties":false,"properties":{"organization_id":{"type":"string","minLength":1,"maxLength":128,"description":"Practice from GET /organizations. Required with operation_id, even for a practice-bound key. On standalone generic MFA, required for a company-wide key and omitted for a practice-bound key."},"payer_id":{"type":"string","description":"Payer owning the parked MFA operation."},"operation_id":{"type":"string","description":"Required to resume delegated onboarding. When present, canonical organization_id and payer_id are also required and all three must match the durable operation. Omitted only for the standalone generic MFA flow."},"challenge_id":{"type":"string","minLength":1,"maxLength":128,"description":"Aetna exact challenge id, or generic gen:<payer_id>:<generation> for needs_code holds. When present on generic MFA it must match the current hold."},"idempotency_key":{"type":"string","minLength":16,"maxLength":128,"description":"Fallback for Idempotency-Key on generic (non-operation_id) MFA."},"challenge_generation":{"type":"integer","minimum":1,"description":"Generation paired with challenge_id."},"attempt_id":{"type":"string","minLength":43,"maxLength":43,"pattern":"^[A-Za-z0-9_-]{43}$","description":"Required for operation-bound code submission. Canonical base64url encoding of exactly 32 random bytes; independent of the code."},"code":{"type":"string","writeOnly":true,"description":"One-time code; never stored in a public receipt or returned."},"observe_only":{"type":"boolean","description":"MetLife confirmation observation with no code or attempt id."},"client_reference":{"type":"string","maxLength":128,"description":"Opaque vendor correlation id. Echoed and stored on the 24h receipt."}},"required":["payer_id"],"allOf":[{"if":{"type":"object","required":["operation_id"],"properties":{"operation_id":{"type":"string"}}},"then":{"type":"object","required":["organization_id","payer_id"],"properties":{"organization_id":{"type":"string","minLength":1,"maxLength":128},"payer_id":{"type":"string"}}}}]},"PmsClaimClearinghouseStatus":{"type":"object","additionalProperties":false,"description":"One claim's status as the practice's clearinghouse reported it into the PMS. Oryx has no live status inquiry: these are the latest answers Oryx holds, read at call time. oryx_status_text comes from Oryx's status check for the claim id; every other field comes from the claim's own row in Oryx's sent claims (found only when patient_id was given). Oryx status literals pass through unchanged.","required":["claim_id","found","oryx_status_text","note","sent"],"properties":{"claim_id":{"type":"string","description":"Native PMS claim id, as requested."},"found":{"type":"boolean","description":"false when the PMS status check does not know this claim id."},"not_found_reason":{"type":"string","enum":["not_found"],"description":"Present when found is false."},"oryx_status_text":{"type":["string","null"],"description":"The PMS's status text for the claim, verbatim (for example Claim in process)."},"note":{"type":["string","null"],"description":"Set when no patient_id was given: only the status text was read, and sent and the clearinghouse answers are unknown."},"claim_number":{"type":["string","null"]},"patient_id":{"type":["string","null"],"description":"Native PMS patient id from the claim's own row."},"patient_policy_id":{"type":["string","null"]},"payer":{"type":["object","null"],"additionalProperties":false,"properties":{"remote_id":{"type":["string","null"]},"payer_id_code":{"type":["string","null"]},"name":{"type":["string","null"]},"claim_type":{"type":["string","null"]}}},"service_date_from":{"type":["string","null"],"description":"YYYY-MM-DD, earliest line date on the claim."},"service_date_to":{"type":["string","null"],"description":"YYYY-MM-DD, latest line date on the claim."},"oryx_status":{"type":"object","additionalProperties":false,"properties":{"name":{"type":["string","null"]},"display":{"type":["string","null"]}},"description":"The PMS's own status literal and label from the claim's row, unchanged (for example inProcess or acceptedPaid)."},"electronic":{"type":["boolean","null"],"description":"The PMS marks the claim electronic (sent through the clearinghouse)."},"sent":{"type":["boolean","null"],"description":"true when the claim is in the PMS's sent claims. false only when a complete, patient-filtered read of the sent claims in the searched window lacks it: a claim rejected at submission can sit in the PMS's rejected queue instead, and a wrong patient_id also reads false. null when unknown or when no patient_id was given."},"sent_on":{"type":["string","null"]},"era_received":{"type":["boolean","null"],"description":"The PMS recorded an electronic remittance (ERA) for this claim."},"inactive_policy":{"type":["boolean","null"]},"clearinghouse":{"type":"object","additionalProperties":false,"properties":{"claim_number":{"type":["string","null"],"description":"The clearinghouse's claim number."},"payer_reference_number":{"type":["string","null"],"description":"The payer's claim reference number, once the payer has it."},"oryx_unique_claim_id":{"type":["string","null"]},"status_message":{"type":["string","null"],"description":"The clearinghouse's latest status message, verbatim."}}},"status_history":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"date":{"type":["string","null"]},"status":{"type":["string","null"]},"status_display":{"type":["string","null"]},"action":{"type":["string","null"]},"clearinghouse_message":{"type":["string","null"]}}}}}},"PmsClaimStatusResponse":{"type":"object","additionalProperties":false,"required":["status","vendor","realm","checked_at","claims","hops"],"properties":{"status":{"type":"string","enum":["ok"]},"vendor":{"type":"string","enum":["oryx"]},"realm":{"type":["string","null"]},"checked_at":{"type":"string","description":"ISO-8601 time of this read."},"clearinghouse":{"type":["object","null"],"additionalProperties":false,"properties":{"code":{"type":["string","null"],"description":"The PMS's clearinghouse code, unchanged (Oryx NEA is Vyne)."},"vendor":{"type":["string","null"],"enum":["vyne",null],"description":"vyne when the code is Vyne's; null otherwise or when unknown."}}},"census_filter_honoured":{"type":["boolean","null"],"description":"false when the PMS ignored the patient filter on its sent claims; no claim is then reported sent false. null when no sent-claims read ran."},"claims":{"type":"array","items":{"$ref":"#/components/schemas/PmsClaimClearinghouseStatus"}},"hops":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"PMS calls made: method, path template, status, ms. Never values."},"client_reference":{"type":["string","null"]},"elapsed_ms":{"type":"integer"}}},"PmsClaimSubmitResult":{"type":"object","additionalProperties":false,"required":["claim_id","result"],"properties":{"claim_id":{"type":"string","example":"104857"},"patient_id":{"type":["string","null"]},"result":{"type":"string","enum":["submitted","submitted_unconfirmed","vendor_rejected","not_ready","not_electronic","changed","already_sent","send_unresolved","not_sent_aborted","unknown_outcome"],"description":"submitted: the PMS accepted it for its clearinghouse queue. submitted_unconfirmed: sent, but the PMS's answer did not name it; confirm with claims/status. vendor_rejected: the PMS refused it; nothing was sent. not_ready, not_electronic, changed: a guard refused it; nothing was sent. already_sent / send_unresolved: Veraxus already sent it, or a send of it is in flight or unknown. not_sent_aborted: it passed, but another claim failed a guard under on_guard_failure abort. unknown_outcome: it was in a send whose result is unknown; reconcile, never resend."},"detail":{"type":["string","null"],"description":"Plain-words reason; safe to show a person."},"line_fingerprint":{"type":["string","null"],"description":"The claim's current line_fingerprint in the PMS when it was read."},"oryx_result":{"type":["object","null"],"additionalProperties":false,"description":"The PMS's own per-claim answer when its submit response names the claim.","properties":{"status":{"type":["string","null"]},"message":{"type":["string","null"]},"validations":{"type":"array","items":{"type":"string"}}}},"readback":{"type":["object","null"],"additionalProperties":false,"description":"Reads after the send: whether the claim is still in the PMS's unsent queue, and the PMS's status text for it.","properties":{"in_unsent_queue":{"type":["boolean","null"]},"status_text":{"type":["string","null"],"example":"Claim in process"}}}}},"PmsClaimSubmitResponse":{"type":"object","additionalProperties":false,"required":["status","vendor","sent_count","refused_count","unknown_outcome","claims","hops"],"properties":{"status":{"type":"string","enum":["sent","partial","refused","unknown_outcome"],"description":"sent: every claim was sent. partial: some sent, some refused. refused: nothing was sent. unknown_outcome: the send left and its result is unknown (HTTP 502)."},"vendor":{"type":"string","enum":["oryx"]},"realm":{"type":["string","null"]},"submitted_at":{"type":["string","null"],"description":"ISO-8601 time of the one native POST; null when nothing was sent."},"dispatched":{"type":"boolean","description":"Whether the native POST was made."},"on_guard_failure":{"type":["string","null"],"enum":["abort","skip",null]},"sent_count":{"type":"integer"},"refused_count":{"type":"integer"},"unknown_outcome":{"type":"boolean"},"claims":{"type":"array","items":{"$ref":"#/components/schemas/PmsClaimSubmitResult"},"description":"In request order."},"hops":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"PMS calls made: method, path template, status, ms. Never values."},"client_reference":{"type":["string","null"]},"elapsed_ms":{"type":"integer"},"replayed":{"type":"boolean","description":"true when this is the stored receipt of an earlier request with the same Idempotency-Key."},"error":{"type":"object","additionalProperties":true,"description":"Present on 422 and 502: code pms_vendor_rejected or unknown_outcome."}}},"VendorAttestation":{"type":"object","additionalProperties":false,"required":["actor_user_id","consent_session_id","consented_at"],"properties":{"actor_user_id":{"description":"Vendor-app user id of the human who entered or approved the credential/Connect (≤200). Not a Veraxus console user. Recorded on the consumed hitl_grants row.","type":"string","minLength":1,"maxLength":200},"consent_session_id":{"description":"Vendor-side consent session or screen id (≤200) that bound this action to the human actor. Recorded on the consumed hitl_grants row.","type":"string","minLength":1,"maxLength":200},"consented_at":{"type":"string","description":"ISO-8601. Within the last 24h, not more than 5 minutes in the future. A standing_policy attestation states when the policy was enabled and is exempt from the 24h window."},"consent_kind":{"type":"string","enum":["session","standing_policy"],"description":"Default session: a human consented in this vendor session. standing_policy (pms_write only): the office enabled a standing writeback policy; consent_session_id is the vendor's policy record and the grant records it as policy:<id>."}}},"CredentialsListResponse":{"type":"object","description":"Vaulted logins with secrets redacted.","properties":{"organization_id":{"type":"string","description":"Practice these credentials belong to."},"credentials":{"type":"array","description":"One row per mailbox, including empty logins.","items":{"type":"object","properties":{"payer_id":{"type":"string","description":"vault_payer_id / mailbox id."},"name":{"type":"string","description":"Mailbox display name."},"username":{"type":["string","null"],"description":"Redacted username; never the password."},"npi":{"type":["string","null"],"description":"NPI stored on this login, if any."},"has_secret":{"type":"boolean","description":"True when a password is vaulted."},"has_totp_seed":{"type":"boolean","description":"True when an authenticator seed is vaulted. The seed is never returned."},"shares_with":{"type":"array","items":{"type":"string"},"description":"Sibling catalog ids on this mailbox."},"updated_at":{"type":["string","null"],"description":"Last vault write."},"credential_revision":{"type":["integer","null"],"description":"Monotonic integer for the canonical stored vault row. Increments by 1 on every password, username, or TOTP-seed write, including identical PUT retries. Null when no vault row exists. Shared-login aliases report the canonical row."},"last_client_reference":{"type":["string","null"],"description":"Vendor client_reference from the last PUT /v1/credentials that wrote this vault row, or null when that PUT omitted it. Shared-login aliases report the canonical row."}},"required":["payer_id","has_secret"]}}},"required":["organization_id","credentials"]},"CredentialsStoreResponse":{"type":"object","description":"Confirmation that credentials were vaulted. Password is never returned.","properties":{"organization_id":{"type":"string","description":"Practice the login was stored on."},"payer_id":{"type":"string","description":"Mailbox id that was written."},"username":{"type":"string","description":"Stored username."},"npi":{"type":["string","null"],"description":"Stored NPI, if sent."},"has_secret":{"type":"boolean","const":true,"description":"Always true after a successful store."},"stored":{"type":"boolean","const":true,"description":"Always true after a successful store."},"has_totp_seed":{"type":"boolean","description":"True when an authenticator seed was stored with this write. The seed is never returned."},"shares_with":{"type":"array","items":{"type":"string"},"description":"Sibling catalog ids that received the same login."},"client_reference":{"type":["string","null"],"description":"Echo of the vendor client_reference from this call, or null when omitted."},"credential_revision":{"type":"integer","minimum":1,"description":"Monotonic integer for the vault row this PUT wrote. Increments by 1 on every credential-material write, including identical retries. Shared-login aliases report the canonical stored row."},"credential_updated_at":{"type":"string","description":"ISO-8601 timestamp of this vault row's updated_at as written by this PUT."}},"required":["organization_id","payer_id","has_secret","stored"]},"PracticeResponse":{"type":"object","description":"One practice after create or update.","properties":{"id":{"type":"string","description":"Practice id — send as practice_id."},"tenant_id":{"type":"string","description":"Customer account this practice belongs to."},"name":{"type":"string","description":"Practice display name."},"slug":{"type":"string","description":"URL-safe handle."},"kind":{"type":"string","description":"practice, dso, or medical_group."},"region":{"type":"string","description":"Two-letter state when known."},"npi":{"type":["string","null"],"description":"10-digit NPI."},"tax_id":{"type":["string","null"],"description":"9-digit EIN."},"created":{"type":"boolean","description":"True when this call inserted the row."},"status":{"type":"string","description":"active."},"code_email_address":{"type":["string","null"],"description":"Code-only address on codes.veraxus.ai for enrolled accounts; null otherwise. Do not set it on a payer account until Veraxus marks it receiving."},"code_email_receiving":{"type":"boolean","description":"True when receiving is released and the address has a fresh verified provider route, receiving-domain DNS, and application route. This describes routing readiness, not delivery of a particular message or permission for automatic payer sign-in. Do not set it on a payer account until Veraxus marks it receiving."}},"required":["id","name","code_email_address","code_email_receiving"]},"PracticeImportResponse":{"type":"object","description":"Result of importing up to 500 practices.","properties":{"tenant_id":{"type":"string","description":"Customer account these practices belong to."},"practices":{"type":"array","description":"Upserted practice rows.","items":{"type":"object","properties":{"id":{"type":"string","description":"Practice id."},"name":{"type":"string","description":"Practice display name."},"npi":{"type":["string","null"],"description":"10-digit NPI."},"tax_id":{"type":["string","null"],"description":"9-digit EIN."},"created":{"type":"boolean","description":"True when this row was inserted."},"code_email_address":{"type":["string","null"],"description":"Code-only address on codes.veraxus.ai for enrolled accounts; null otherwise. Do not set it on a payer account until Veraxus marks it receiving."},"code_email_receiving":{"type":"boolean","description":"True when receiving is released and the address has a fresh verified provider route, receiving-domain DNS, and application route. This describes routing readiness, not delivery of a particular message or permission for automatic payer sign-in. Do not set it on a payer account until Veraxus marks it receiving."}},"required":["id","name","code_email_address","code_email_receiving"]}}},"required":["tenant_id","practices"]},"UsageResponse":{"type":"object","description":"30-day eligibility usage. recent rows never include source.","properties":{"billing_unit":{"type":"string","const":"eligibility_check","description":"Always eligibility_check."},"windowDays":{"type":"integer","description":"Lookback window in days."},"checks":{"type":"integer","description":"Total checks in the window."},"billedChecks":{"type":"integer","description":"Billed checks in the window."},"waivedChecks":{"type":"integer","description":"Waived checks in the window."},"cents":{"type":"integer","description":"Billed amount in US cents."},"currency":{"type":"string","description":"USD."},"unit":{"type":"string","description":"eligibility_check."},"priceCentsLive":{"type":"integer","description":"Live-check list price in cents."},"priceCentsCache":{"type":"integer","description":"Cached-check list price in cents."},"byOrg":{"type":"array","description":"Per-practice totals when the key is company-wide."},"byPayer":{"type":"array","description":"Per-payer totals."},"recent":{"type":"array","description":"Latest usage events with source stripped."}},"required":["billing_unit"]},"EligibilityListResponse":{"type":"object","description":"One practice's checks for one day, newest first, 50 per page. Rows are skinny: fetch GET /eligibility/{id} for the full envelope.","properties":{"practice_id":{"type":"string","description":"Practice these checks belong to."},"organization_id":{"type":"string","deprecated":true,"description":"Deprecated alias for practice_id; same value."},"date":{"type":"string","format":"date","description":"The UTC day this page covers."},"checks":{"type":"array","description":"Skinny rows, newest first: enough to find, attribute, and triage each check without member data.","items":{"type":"object","properties":{"id":{"type":"string","description":"Check id (chk_…) for GET /eligibility/{id}."},"payer_id":{"type":"string"},"usable":{"type":"boolean","description":"True when the check served writable remaining benefits (why is live)."},"why":{"$ref":"#/components/schemas/EligibilityResult/properties/why"},"status":{"$ref":"#/components/schemas/EligibilityResult/properties/status"},"served_by":{"$ref":"#/components/schemas/EligibilityResult/properties/served_by"},"created_at":{"type":"string","description":"UTC creation time of the check."},"enrichment":{"$ref":"#/components/schemas/EligibilityResult/properties/enrichment"}},"required":["id","payer_id","usable","why","status","served_by","created_at"]}},"next_cursor":{"type":["string","null"],"description":"Pass back as ?cursor= for the next page; null on the last page."}},"required":["practice_id","date","checks","next_cursor"]},"ClaimAddress":{"type":"object","additionalProperties":false,"description":"Postal address on a claim party. PHI.","properties":{"line1":{"type":"string","description":"PHI. Address line 1."},"line2":{"type":"string","description":"PHI. Address line 2."},"city":{"type":"string","description":"PHI. City."},"state":{"type":"string","description":"PHI. Two-letter state or province."},"zip":{"type":"string","description":"PHI. Postal code."}},"required":["line1","city","state","zip"]},"ClaimParty":{"type":"object","additionalProperties":false,"description":"Patient or subscriber on a claim draft. PHI.","properties":{"firstName":{"type":"string","description":"PHI. Given name as the payer has it."},"lastName":{"type":"string","description":"PHI. Family name as the payer has it."},"dob":{"type":"string","format":"date","description":"PHI. Date of birth, YYYY-MM-DD."},"gender":{"type":"string","enum":["M","F","U"],"description":"PHI. Gender code: M, F, or U."},"memberId":{"type":"string","description":"PHI. Member/subscriber id as printed on the card."},"relationship":{"type":"string","enum":["self","spouse","child","other"],"description":"Patient relationship to the subscriber. Defaults to self."},"address":{"$ref":"#/components/schemas/ClaimAddress"}},"required":["firstName","lastName","dob"]},"ClaimProcedureLine":{"type":"object","additionalProperties":false,"description":"One CDT procedure line on a claim or predetermination. PHI.","properties":{"procedureCode":{"type":"string","pattern":"^D\\d{4}$","description":"CDT procedure code (D####)."},"dateOfService":{"type":"string","format":"date","description":"Date of service, YYYY-MM-DD."},"fee":{"type":"integer","minimum":0,"description":"Submitted fee in integer US cents."},"tooth":{"type":"string","description":"PHI. ADA universal tooth (1–32, A–T, or supernumerary 51–82)."},"surface":{"type":"string","description":"PHI. Surface characters; subset of MOIDBFL."},"oralCavity":{"type":"string","description":"Oral cavity / quadrant / arch code."},"area":{"type":"string","description":"Area of oral cavity when not a tooth."},"quantity":{"type":"integer","minimum":1,"description":"Quantity; defaults to 1."},"diagnosisPointer":{"type":"array","items":{"type":"integer"},"description":"1-based pointers into icdCodes."},"attachmentRequired":{"type":"boolean","description":"Derived from the payer dictionary at validate time; blocks v1 submission."}},"required":["procedureCode","dateOfService","fee"]},"OtherCoverage":{"type":"object","additionalProperties":false,"description":"Coordination of benefits / other coverage. PHI.","properties":{"carrierName":{"type":"string","description":"Other carrier display name."},"groupNumber":{"type":"string","description":"Other coverage group number."},"groupName":{"type":"string","description":"Other coverage group name."},"subscriberId":{"type":"string","description":"PHI. Subscriber id on the other coverage."},"subscriber":{"$ref":"#/components/schemas/ClaimParty"},"payerId":{"type":"string","description":"Catalog eligibility_payer_id when the other carrier is a known payer."}},"required":["carrierName"]},"OrthoInfo":{"type":"object","additionalProperties":false,"description":"Orthodontic banding / months-remaining fields when isOrtho is true.","properties":{"isOrtho":{"type":"boolean","description":"True when this submission is orthodontic."},"applianceDate":{"type":"string","format":"date","description":"Appliance placement date, YYYY-MM-DD."},"monthsRemaining":{"type":"integer","minimum":0,"description":"Months of ortho treatment remaining."},"bandingFee":{"type":"integer","minimum":0,"description":"Banding fee in integer US cents."}},"required":["isOrtho"]},"ClaimDraftInput":{"type":"object","additionalProperties":false,"description":"Canonical claim/predetermination draft. Nested party, member, NPI, tax id, and remarks fields are PHI. POST /claims also accepts organization_id, organizationId, and idempotency_key, which are stripped before validation.","properties":{"payerId":{"type":"string","description":"Catalog id / eligibility_payer_id from GET /payers."},"transactionType":{"type":"string","enum":["claim","predetermination"],"description":"claim or predetermination."},"eligibilityCheckId":{"type":"string","description":"Provenance: the eligibility check the member came from."},"patient":{"$ref":"#/components/schemas/ClaimParty"},"subscriber":{"$ref":"#/components/schemas/ClaimParty"},"memberHccId":{"type":"string","description":"PHI. Payer-internal member id (Keyspring memberHccId) when known from the check."},"billingNpi":{"type":"string","description":"PHI. 10-digit billing NPI (Luhn over the 80840 prefix)."},"treatingNpi":{"type":"string","description":"PHI. 10-digit treating NPI (Luhn over the 80840 prefix)."},"billingTaxId":{"type":"string","description":"PHI. Billing EIN / tax id."},"locationId":{"type":"string","description":"Payer location / office identifier when required."},"procedures":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/ClaimProcedureLine"},"description":"Procedure lines. PHI."},"icdCodes":{"type":"array","items":{"type":"string"},"description":"ICD diagnosis codes."},"otherCoverage":{"description":"Other coverage / COB. Null clears. PHI.","oneOf":[{"$ref":"#/components/schemas/OtherCoverage"},{"type":"null"}]},"assignmentOnFile":{"type":"boolean","description":"Assignment of benefits on file."},"releaseOfInformation":{"type":"boolean","description":"Release of information on file."},"predeterminationNumber":{"type":"string","description":"Prior predetermination number when filing the matching claim."},"remarks":{"type":"string","description":"PHI. Claim remarks / narrative."},"ortho":{"$ref":"#/components/schemas/OrthoInfo"},"neaNumber":{"type":"string","description":"Keyspring NEA FastAttach number. Covers attachment_required without a file."}},"required":["payerId","transactionType","patient","subscriber","billingNpi","treatingNpi","procedures","assignmentOnFile","releaseOfInformation"]},"ValidationIssue":{"type":"object","additionalProperties":false,"description":"One validation error or warning. Messages never include PHI.","properties":{"path":{"type":"string","description":"JSON path of the field (e.g. procedures.0.tooth)."},"code":{"type":"string","description":"Stable machine code (npi_luhn, iso_date, tooth, …)."},"message":{"type":"string","description":"Plain-words explanation; safe to show a person."},"severity":{"type":"string","enum":["error","warning"],"description":"error blocks send; warning does not."}},"required":["path","code","message","severity"]},"DuplicateMatch":{"type":"object","additionalProperties":false,"description":"One duplicate hit from the ledger or a portal read hop. No PHI.","properties":{"source":{"type":"string","enum":["ledger","pendingClaims","memberClaims","memberTreatmentPlans"],"description":"Where the match was found."},"submissionId":{"type":"string","description":"Matching Veraxus submission id when source is ledger."},"portalClaimNumber":{"type":"string","description":"Matching portal claim/pred number when known."},"dateOfService":{"type":"string","format":"date","description":"Date of service on the matching row, YYYY-MM-DD."},"procedureCodes":{"type":"array","items":{"type":"string"},"description":"CDT codes on the matching row."}},"required":["source","dateOfService","procedureCodes"]},"DuplicateCheckResult":{"type":"object","additionalProperties":false,"description":"Portal + ledger duplicate scan captured at validate time.","properties":{"ranAt":{"type":"string","description":"UTC timestamp when the scan ran."},"expiresAt":{"type":"string","description":"UTC timestamp after which the scan must be rerun."},"matches":{"type":"array","items":{"$ref":"#/components/schemas/DuplicateMatch"},"description":"Hits. Empty means the scan ran and found none."},"overriddenBy":{"type":"string","description":"Actor who overrode a duplicate block."},"overrideReason":{"type":"string","description":"Human reason recorded with the override."}},"required":["ranAt","expiresAt","matches"]},"GateStatus":{"type":"object","additionalProperties":false,"description":"Layered write-lane gates. Live send requires allOpen true.","properties":{"envEnabled":{"type":"boolean","description":"True when CLAIMS_SUBMISSION is enabled for this deployment."},"orgEnabled":{"type":"boolean","description":"True when the practice has claimsWriteEnabled."},"payerAllowed":{"type":"boolean","description":"True when this payer is on the claims write allow-list."},"contractStatus":{"type":"string","enum":["provisional","captured","verified_live","missing"],"description":"Payer contract status, or missing when no row exists."},"transactionAllowed":{"type":"boolean","description":"False when the org is predetermination-only and the draft is a live claim."},"allOpen":{"type":"boolean","description":"True only when every gate is open."},"reasons":{"type":"array","items":{"type":"string"},"description":"Closed-gate reasons. Empty when allOpen is true."}},"required":["envEnabled","orgEnabled","payerAllowed","contractStatus","transactionAllowed","allOpen","reasons"]},"RejectionEdit":{"type":"object","additionalProperties":false,"description":"One portal or clearinghouse business-rejection edit. Messages never include PHI. Webhook deliveries drop field.","properties":{"source":{"type":"string","enum":["999","277ca","payer_portal"],"description":"Where the edit came from. Absent when the producer did not classify it."},"category":{"type":"string","description":"277CA STC01-1 claim status category when provided."},"code":{"type":"string","description":"277CA STC01-2 or 999 IK5/AK9 code, verbatim, when provided. Never invented."},"segment":{"type":"string","description":"999 segment position (e.g. \"IK3 CLM*1\") when provided."},"field":{"type":"string","description":"Payer field name when provided. Never present on webhook payloads."},"message":{"type":"string","description":"Payer or clearinghouse free text; safe to show a person."}},"required":["message"]},"X12ReportNote":{"type":"object","additionalProperties":false,"description":"One structural note from an X12 837D parse: a field the agreed mapping table marks disagreed/unresolved (left off ClaimDraftInput on purpose), or a data-quality warning. path is a loop/segment/element locator, never a data value.","properties":{"code":{"type":"string","description":"Stable machine code (e.g. payer_id_unresolved, claim_total_mismatch, line_dropped)."},"path":{"type":"string","description":"Loop/segment/element locator (e.g. 2300.REF*G3), never a data value."},"message":{"type":"string","description":"Plain-words explanation; safe to show a person."}},"required":["code","message"]},"X12Report":{"type":"object","additionalProperties":false,"description":"PHI-free structural report from an X12 837D parse (POST /claims x12 path). Never contains patient, subscriber, member, or provider identity data — only segment/element names, counts, and short machine codes.","properties":{"version":{"type":"string","enum":["005010X224A1","005010X224A2"],"description":"837D implementation-guide version this interchange declared (GS08 or ST03)."},"usageIndicator":{"type":"string","enum":["T","P"],"description":"ISA15 on the interchange itself: T (test) or P (production)."},"controlNumbers":{"type":"object","additionalProperties":false,"description":"Interchange/group/transaction control numbers. Routing metadata, not PHI.","properties":{"isa13":{"type":"string","description":"ISA13, cross-checked against IEA02."},"gs06":{"type":"string","description":"GS06, cross-checked against GE02."},"st02":{"type":"string","description":"ST02, cross-checked against SE02."}},"required":["isa13","gs06","st02"]},"segmentCount":{"type":"integer","minimum":0,"description":"Total segment count in the interchange."},"claimTotalCents":{"type":["integer","null"],"description":"CLM02 (claim total) converted to integer cents; null when absent or unparseable."},"proceduresTotalCents":{"type":"integer","minimum":0,"description":"sum(procedures[].fee) from this parse; compared against claimTotalCents as a data-quality signal only."},"payerIdSource":{"type":"string","enum":["explicit","crosswalk","unresolved"],"description":"How ClaimDraftInput.payerId was resolved: explicit (caller-supplied), crosswalk (2010BB payer id matched), or unresolved."},"mappedFields":{"type":"array","items":{"type":"string"},"description":"Dotted ClaimDraftInput field paths this parse populated from the X12."},"unmapped":{"type":"array","items":{"$ref":"#/components/schemas/X12ReportNote"},"description":"Fields the agreed mapping table marks disagreed/unresolved — present in the X12 but intentionally left off ClaimDraftInput, never silently dropped."},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/X12ReportNote"},"description":"Non-blocking data-quality notes (e.g. a claim-total mismatch, a dropped service line)."}},"required":["version","usageIndicator","controlNumbers","segmentCount","claimTotalCents","proceduresTotalCents","payerIdSource","mappedFields","unmapped","warnings"]},"X12ClaimDraftBody":{"type":"object","additionalProperties":false,"description":"X12 837D ingestion via JSON. Mutually exclusive with the structured ClaimDraftInput body — send either the structured fields or { x12, usage_indicator }, never both.","properties":{"x12":{"type":"string","description":"Raw 837D EDI text (ISA...IEA), UTF-8. Capped at 1 MiB."},"usage_indicator":{"type":"string","enum":["T","P"],"description":"Must equal the interchange's own ISA15 (else 400 x12_usage_indicator_mismatch). T (test) drafts may be reviewed and staged but the live-submit confirm is fail-closed (409 test_indicator_blocks_submit); P (production) behaves like any other draft."},"payerId":{"type":"string","description":"Catalog eligibility_payer_id. Required when the 2010BB payer id has no crosswalk entry, else 400 x12_payer_unmapped."},"payer_id":{"type":"string","description":"Alias for payerId."},"practice_id":{"type":"string","description":"Practice from GET /organizations. Required for a company-wide key. Canonical scope field."},"organization_id":{"type":"string","deprecated":true,"description":"Deprecated alias for practice_id."}},"required":["x12","usage_indicator"]},"ClaimSubmission":{"type":"object","additionalProperties":false,"description":"Public claim-submission wire. payerRequest is never returned. tenantId, keepKey, createdBy, confirmedBy, leaseUntil, and leaseOwner are omitted. Nested input, validation, duplicate_check, and gates keep domain (camelCase) field names. Party, NPI, tax id, and remarks inside input are PHI.","properties":{"id":{"type":"string","description":"Submission id (clm_…)."},"practice_id":{"type":"string","description":"Practice this submission belongs to. Canonical scope field."},"org_id":{"type":"string","deprecated":true,"description":"Deprecated alias for practice_id; same value."},"payer_id":{"type":"string","description":"Catalog eligibility_payer_id."},"state":{"type":"string","enum":["draft","validated","blocked","awaiting_confirm","queued","submitting","submitted","rejected","failed","unknown_outcome","voided","cancelled","staging","staged"],"description":"Submission state machine value."},"block_reason":{"type":["string","null"],"enum":["duplicate_in_ledger","duplicate_on_portal","attachment_required","gate_closed","contract_not_captured","validation_failed",null],"description":"Why the row is blocked; null when not blocked."},"failure_reason":{"type":["string","null"],"enum":["session_unavailable","preflight_failed","gate_closed_at_send","payload_hash_mismatch","request_build_error","reconciled_absent","lane_unavailable",null],"description":"Why the row failed; null when not failed."},"adjudication":{"type":"string","enum":["unknown","pending","in_process","paid","partially_paid","denied"],"description":"Portal adjudication snapshot."},"transaction_type":{"type":"string","enum":["claim","predetermination"],"description":"claim or predetermination."},"input":{"$ref":"#/components/schemas/ClaimDraftInput"},"payload_hash":{"type":["string","null"],"description":"SHA-256 of the frozen payer request; null before validate."},"fingerprint":{"type":"string","description":"Dedupe fingerprint for the live unique index."},"idempotency_key":{"type":"string","description":"Client Idempotency-Key that created this row."},"contract_version":{"type":"string","description":"Payer contract version frozen onto the row."},"validation":{"type":"array","items":{"$ref":"#/components/schemas/ValidationIssue"},"description":"Validation issues from the last validate. Empty array when none."},"duplicate_check":{"description":"Last duplicate scan, or null when it has not run.","oneOf":[{"$ref":"#/components/schemas/DuplicateCheckResult"},{"type":"null"}]},"gates":{"description":"Last gate snapshot, or null when it has not run.","oneOf":[{"$ref":"#/components/schemas/GateStatus"},{"type":"null"}]},"portal_claim_number":{"type":["string","null"],"description":"Portal claim/pred number after accept; null before."},"portal_response_keys":{"description":"Redacted response keys from the portal; null before a send.","oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"rejection_edits":{"description":"Portal rejection edits; null when none.","oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/RejectionEdit"}},{"type":"null"}]},"confirmed_at":{"type":["string","null"],"description":"UTC timestamp of human confirm; null before confirm."},"confirmation_method":{"type":["string","null"],"enum":["console_submit","vendor_attest","hitl",null],"description":"How the row was confirmed. null before confirm."},"sandbox":{"type":"boolean","description":"True when this row is a sandbox (DEMO) filing and never touches a live keep."},"write_kind":{"type":["string","null"],"enum":["submit","stage",null],"description":"submit = one live claim POST (confirm); stage = a draft parked in the payer portal (stage, never submitted). null before either action."},"stage_phase":{"type":["string","null"],"enum":["none","pending","staging","staged","arrived","failed","unknown",null],"description":"Staging sub-phase: staging (write in flight), staged (portal accepted the draft), arrived (drafts list showed it), failed (before send; a human may retry), unknown (sent but ambiguous; reconciled via the drafts list, never auto-retried). null when the row never staged."},"portal_draft_id":{"type":["string","null"],"description":"Portal-side draft id returned by the staging hop; null until staged or when the portal returns none."},"staged_at":{"type":["string","null"],"description":"UTC time the portal accepted the draft; null before."},"arrived_at":{"type":["string","null"],"description":"UTC time verify-arrival first saw the draft in the portal's drafts list; null before."},"stage_error":{"type":["string","null"],"description":"Redacted staging failure reason (never PHI); null when none."},"submit_attempt":{"type":"integer","minimum":0,"description":"Count of live submit attempts."},"usage_indicator":{"type":["string","null"],"enum":["T","P",null],"description":"Set only for a draft ingested from raw X12 (POST /claims x12 path). T (test) drafts may be staged but never live-submitted (409 test_indicator_blocks_submit). Null on JSON/structured drafts."},"x12_report":{"description":"PHI-free structural report from the X12 parse. Null on JSON/structured drafts.","oneOf":[{"$ref":"#/components/schemas/X12Report"},{"type":"null"}]},"created_at":{"type":"string","description":"UTC creation time."},"updated_at":{"type":"string","description":"UTC last-update time."}},"required":["id","practice_id","org_id","payer_id","state","block_reason","failure_reason","adjudication","transaction_type","input","payload_hash","fingerprint","idempotency_key","contract_version","validation","duplicate_check","gates","portal_claim_number","portal_response_keys","rejection_edits","confirmed_at","confirmation_method","sandbox","write_kind","stage_phase","portal_draft_id","staged_at","arrived_at","stage_error","submit_attempt","usage_indicator","x12_report","created_at","updated_at"]},"ClaimSubmissionEvent":{"type":"object","additionalProperties":false,"description":"Public event row from GET /claims/{id}/events. Domain fields submissionId and orgId are implied by the path. trace never contains bodies or PHI.","properties":{"id":{"type":"integer","description":"Monotonic event id."},"at":{"type":"string","description":"UTC timestamp."},"actor":{"type":"string","description":"user:<id>, api:<keyId>, lane, reconcile, or system."},"kind":{"type":"string","enum":["create","validate","gate","duplicate_scan","confirm","enqueue","lease","preflight","request","response","reconcile","void","cancel","override","error","attachment_stored","attachment_uploaded","attachment_failed","stage_request","stage_response","arrival_check"],"description":"Event kind."},"from_state":{"type":["string","null"],"enum":["draft","validated","blocked","awaiting_confirm","queued","submitting","submitted","rejected","failed","unknown_outcome","voided","cancelled","staging","staged",null],"description":"State before this event; null when not a transition."},"to_state":{"type":["string","null"],"enum":["draft","validated","blocked","awaiting_confirm","queued","submitting","submitted","rejected","failed","unknown_outcome","voided","cancelled","staging","staged",null],"description":"State after this event; null when not a transition."},"trace":{"description":"Redacted hop trace (method, path, status, keys). Never bodies. Null when none.","oneOf":[{"type":"object","additionalProperties":true,"properties":{"method":{"type":"string","description":"HTTP method."},"path":{"type":"string","description":"Request path; no query PHI."},"status":{"type":"integer","description":"HTTP status when known."},"requestKeys":{"type":"array","items":{"type":"string"},"description":"Top-level request JSON keys. Never values."},"responseKeys":{"type":"array","items":{"type":"string"},"description":"Top-level response JSON keys. Never values."},"durationMs":{"type":"integer","description":"Elapsed milliseconds."},"error":{"type":"string","description":"Transport error name; no payload."}}},{"type":"null"}]}},"required":["id","at","actor","kind","from_state","to_state","trace"]},"OrgClaimsSettings":{"type":"object","additionalProperties":false,"description":"Practice claims-write settings. NPI and tax id defaults are PHI.","properties":{"orgId":{"type":"string","description":"Practice id."},"claimsWriteEnabled":{"type":"boolean","description":"Master org switch for the claims write lane."},"liveClaimsEnabled":{"type":"boolean","description":"False means predeterminations only; live claims are blocked."},"defaultBillingNpi":{"type":"string","description":"PHI. Default billing NPI for new drafts."},"defaultTreatingNpi":{"type":"string","description":"PHI. Default treating NPI for new drafts."},"defaultTaxId":{"type":"string","description":"PHI. Default billing tax id for new drafts."},"requireTwoPersonConfirm":{"type":"boolean","description":"When true, confirm requires two distinct confirmedBy.id values within 24h."},"requireVeraxusHitl":{"type":"boolean","description":"When true, API confirm/void also require a Veraxus console HITL grant after vendor attestation. Off by default."},"updatedBy":{"type":"string","description":"Actor who last patched settings."},"updatedAt":{"type":"string","description":"UTC last-update time."}},"required":["orgId","claimsWriteEnabled","liveClaimsEnabled","requireTwoPersonConfirm","updatedAt"]},"PayerClaimsContract":{"type":"object","additionalProperties":false,"description":"Public projection of a payer claims contract from GET /claims/contracts/{payerId}. Never includes the request schema.","properties":{"payer_id":{"type":"string","description":"Catalog eligibility_payer_id."},"version":{"type":"string","description":"Contract version string (e.g. \"ddks-claims@0.1-provisional\")."},"status":{"type":"string","enum":["provisional","captured","verified_live"],"description":"provisional (bundle only), captured (HITL keys), or verified_live."},"captured_at":{"type":["string","null"],"description":"UTC capture time; null when not captured."},"notes":{"type":["string","null"],"description":"Operator notes; null when none."}},"required":["payer_id","version","status","captured_at","notes"]},"ClaimsStats":{"type":"object","additionalProperties":false,"description":"Practice claims-lane counters from GET /claims/stats (snake_case wire).","properties":{"by_state":{"type":"object","additionalProperties":{"type":"integer"},"description":"Count of rows per ClaimSubmissionState."},"unknown_outcome_open":{"type":"integer","minimum":0,"description":"Rows currently in unknown_outcome."},"oldest_unknown_age_ms":{"type":["integer","null"],"description":"Age in ms of the oldest unknown_outcome row; null when none."},"sandbox":{"type":"object","additionalProperties":false,"description":"Sandbox-only counters, excluded from live by_state.","properties":{"by_state":{"type":"object","additionalProperties":{"type":"integer"},"description":"Count of sandbox rows per state."},"unknown_outcome_open":{"type":"integer","minimum":0,"description":"Sandbox rows currently in unknown_outcome."}},"required":["by_state","unknown_outcome_open"]}},"required":["by_state","unknown_outcome_open","oldest_unknown_age_ms"]},"ClaimConfirmation":{"type":"object","additionalProperties":false,"description":"HMAC confirm token plus the exact sentence the vendor must display before attesting. Null on the wire when the row is blocked.","properties":{"token":{"type":"string","description":"HMAC confirm token. 10-minute TTL."},"expiresAt":{"type":"string","description":"ISO-8601 UTC expiry."},"payloadHash":{"type":"string","description":"SHA-256 hex of the frozen payer request."},"statement":{"type":"string","description":"Exact sentence the vendor must display to its user before attesting a confirm (submit) or void."},"stagingStatement":{"type":"string","description":"Exact sentence the vendor must display before POST /claims/{id}/stage (send to portal). Bound to stagingToken below, a DISTINCT token from `token` — a human who approved staging can never file a real claim with that approval, even against a different endpoint."},"stagingToken":{"type":"string","description":"HMAC token for POST /claims/{id}/stage only, bound to action \"stage\" and the DRAFT payload's hash — never valid for /claims/{id}/confirm. Absent when this row cannot stage (unproven payer, gate closed, or past awaiting_confirm)."},"stagingExpiresAt":{"type":"string","description":"ISO-8601 UTC expiry of stagingToken. Absent exactly when stagingToken is absent."},"stagingPayloadHash":{"type":"string","description":"SHA-256 hex of the frozen DRAFT payload stageDraft will send — distinct from payloadHash above, which is the submit-shaped build."}},"required":["token","expiresAt","payloadHash","statement","stagingStatement"]},"ImageMeta":{"type":"object","additionalProperties":false,"description":"Optional radiograph metadata. Only dateTaken, orientation, toothNumbers, and side are stored; extra keys are rejected. Echoed on REST; never sent on webhooks.","properties":{"dateTaken":{"type":"string","description":"Date the image was taken, YYYY-MM-DD."},"orientation":{"type":"string","description":"Image orientation label from the practice (≤32 characters)."},"toothNumbers":{"type":"array","items":{"type":"string"},"description":"ADA universal tooth numbers this image covers."},"side":{"type":"string","description":"Left, right, or both side label (≤16 characters)."}}},"ClaimAttachment":{"type":"object","additionalProperties":false,"description":"Stored claim attachment metadata. Ciphertext is never returned. filename is the vendor's own data and is returned on REST only (never on webhooks).","properties":{"id":{"type":"string","description":"Attachment id (att_…)."},"submissionId":{"type":"string","description":"Parent claim submission id (clm_…)."},"kind":{"type":"string","enum":["radiograph","perio_chart","photo","narrative","eob","other"],"description":"Attachment kind: radiograph, perio_chart, photo, narrative, eob, or other."},"payerTypeCode":{"type":["string","null"],"description":"Payer-specific document type code when the contract names one; null if unset."},"serviceLineIndexes":{"type":"array","items":{"type":"integer"},"description":"Zero-based procedure line indexes this file covers. Empty means claim-level."},"filename":{"type":["string","null"],"description":"Vendor filename. Returned on REST; never logged or sent on webhooks."},"contentType":{"type":["string","null"],"description":"MIME type supplied at intake."},"byteLength":{"type":"integer","description":"Decoded byte length of the stored file."},"sha256":{"type":"string","description":"SHA-256 hex of the plaintext bytes."},"state":{"type":"string","enum":["stored","uploading","attached","failed"],"description":"stored, uploading, attached, or failed."},"uploadAttempt":{"type":"integer","description":"Portal upload attempts so far (max 3)."},"portalAttachmentId":{"type":["string","null"],"description":"Id the payer portal assigned after a successful upload; null until attached."},"portalError":{"type":["string","null"],"description":"Last portal error token when state is failed; never a payload body. Null otherwise."},"imageMeta":{"description":"Echo of accepted ImageMeta keys only; null when none were sent.","oneOf":[{"$ref":"#/components/schemas/ImageMeta"},{"type":"null"}]},"createdAt":{"type":"string","description":"ISO-8601 UTC intake time."},"attachedAt":{"type":["string","null"],"description":"ISO-8601 UTC when the portal accepted the file; null until attached."}},"required":["id","submissionId","kind","payerTypeCode","serviceLineIndexes","filename","contentType","byteLength","sha256","state","uploadAttempt","portalAttachmentId","portalError","imageMeta","createdAt","attachedAt"]},"ClaimAttachmentCreate":{"type":"object","additionalProperties":false,"description":"JSON intake for POST /claims/{id}/attachments. Size and type limits are payer-specific (proven from the attachments contract). DICOM is rejected. Multipart/form-data with a file part plus the same fields is also accepted.","properties":{"kind":{"type":"string","enum":["radiograph","perio_chart","photo","narrative","eob","other"],"description":"Attachment kind: radiograph, perio_chart, photo, narrative, eob, or other."},"contentBase64":{"type":"string","description":"File bytes as standard base64. Checked against the payer byte limit before decode when Content-Length is present."},"contentType":{"type":"string","description":"MIME type of the file. Must be on the payer allow-list when the contract publishes one. DICOM is rejected."},"filename":{"type":"string","description":"Vendor filename. Dental HUB stem ≤100 characters; Sun Life Ix* pattern when the contract requires it."},"serviceLineIndexes":{"type":"array","items":{"type":"integer","minimum":0},"description":"Zero-based procedure line indexes this file covers. Omit or empty for claim-level."},"payerTypeCode":{"type":"string","description":"Optional payer document type code from the attachments contract."},"imageMeta":{"$ref":"#/components/schemas/ImageMeta","description":"Optional radiograph metadata (dateTaken, orientation, toothNumbers, side only)."},"organization_id":{"type":"string","description":"Practice from GET /organizations. Required for a company-wide key."},"organizationId":{"type":"string","description":"Alias for organization_id."}},"required":["kind","contentBase64","contentType"]},"ClaimVendorAttestation":{"type":"object","additionalProperties":false,"description":"Vendor attestation body for confirm/void: HMAC token plus the vendor-app user who confirmed the statement.","properties":{"token":{"type":"string","description":"HMAC confirm token from POST /claims confirmation.token."},"confirmedBy":{"type":"object","additionalProperties":false,"description":"The human in the vendor UI who confirmed. id is the vendor user id, not a Veraxus console user.","properties":{"id":{"type":"string","maxLength":128,"description":"Vendor user id (≤128). Distinct ids satisfy two-person policy."},"name":{"type":"string","maxLength":200,"description":"Display name. Not written to traces."},"role":{"type":"string","maxLength":64,"description":"Vendor role label."}},"required":["id"]},"confirmedAt":{"type":"string","description":"Optional ISO-8601 UTC timestamp of the vendor UI confirm."},"method":{"type":"string","enum":["vendor_ui"],"description":"Always vendor_ui: the attestation happened in the vendor application."},"organization_id":{"type":"string","description":"Practice from GET /organizations. Required for a company-wide key."},"hitl_grant":{"type":"string","description":"Approved HITL grant id (htg_…). Only when require_veraxus_hitl is on."}},"required":["token","confirmedBy","method"]},"WebhookEvent":{"type":"object","additionalProperties":false,"description":"HMAC-signed eligibility or claim event POSTed to the callback. Full benefits stay behind authenticated GET.","properties":{"id":{"type":"string","description":"Stable event id: eligibility:<checkId>, claim ledger id, or test:<deliveryId>. Deduplicate retries by this id."},"type":{"type":"string","enum":["eligibility.completed","eligibility.failed","claim.submitted","claim.acknowledged","claim.rejected","claim.failed","claim.unknown_outcome","claim.reconciled","claim.voided","claim.cancelled","claim.adjudication_updated","claim.attachment_uploaded","claim.attachment_failed","claim.staged","claim.stage_failed","claim.arrived_in_portal","portal_login.desk_changed","portal_login.status_changed","portal_login.state_changed","webhook.test","webhook.deactivated"],"description":"Eligibility completion/failure, claim lifecycle changes, a portal login's desk word changing, portal_login.status_changed, portal_login.state_changed, or webhook.test. claim.acknowledged is payer acceptance (277CA A1/A2 or portal received/accepted), not portal 2xx. eligibility.completed includes inactive coverage; failed enrichment is reported in data.enrichment without discarding served benefits. portal_login.desk_changed fires when GET /v1/portal-logins desk flips for a payer, e.g. alive to needs_sign_in. portal_login.status_changed fires on Connect, MFA, and those same keep-health flips with status/previous_status/generation/at. portal_login.state_changed fires when login_state flips; data.row is the published portal-logins item."},"createdAt":{"type":"string","description":"ISO-8601 UTC event time."},"tenantId":{"type":"string","description":"Customer account id (tn_…) the event belongs to."},"organizationId":{"type":"string","description":"Practice id (org_…) the eligibility check or claim belongs to; empty string on webhook.test."},"data":{"description":"Non-PHI snapshot. Submission events carry payer/state/sandbox. Attachment events carry { submissionId, attachmentId, kind, state, byteLength } and never filename or imageMeta.","oneOf":[{"type":"object","additionalProperties":false,"description":"Eligibility completion receipt. Fetch the authenticated result URL for benefits.","properties":{"checkId":{"type":"string","description":"Completed eligibility check id (chk_…)."},"payerId":{"type":"string","description":"Catalog eligibility payer id."},"status":{"type":"string","enum":["ok","inactive","failed"],"description":"Final check status."},"enrichment":{"type":["string","null"],"enum":["complete","failed",null],"description":"Later benefit collection outcome; null when not applicable."},"resultUrl":{"type":"string","description":"Authenticated GET URL for full benefits on api.veraxus.ai. Requires eligibility scope and access to the practice."}},"required":["checkId","payerId","status","enrichment","resultUrl"]},{"type":"object","additionalProperties":false,"description":"Submission lifecycle snapshot. Never PHI.","properties":{"submissionId":{"type":"string","description":"Claim submission id (clm_…); empty string on webhook.test."},"payerId":{"type":"string","description":"Catalog eligibility_payer_id; empty string on webhook.test."},"state":{"type":"string","description":"Submission state-machine value at event time."},"transactionType":{"type":"string","description":"claim or predetermination."},"portalClaimNumber":{"type":"string","description":"Portal claim/pred number when the payer assigned one."},"payerClaimControlNumber":{"type":"string","description":"Payer claim control number from 277CA or the portal, when the adapter supplied one. Omitted when unknown."},"acknowledgedAt":{"type":"string","description":"ISO-8601 UTC when the payer accepted the claim (277CA A1/A2 or portal equivalent). Present on claim.acknowledged when the adapter supplied it."},"source":{"type":"string","enum":["277ca","payer_portal"],"description":"On claim.acknowledged: 277ca when payerClaimControlNumber came from a 277CA; payer_portal when the portal reported received/accepted. Omitted on other events."},"reason":{"type":"string","enum":["reconciled_present","reconciled_absent","manual"],"description":"On claim.reconciled: reconciled_present when a READ hop recovered the portal number. On claim.failed after the reconcile window: reconciled_absent. manual is reserved for an operator reconcile. Omitted otherwise."},"adjudication":{"type":"string","description":"Portal adjudication snapshot: unknown, pending, in_process, paid, partially_paid, or denied."},"failureReason":{"type":"string","description":"Why the row failed; omitted when not failed."},"blockReason":{"type":"string","description":"Why the row is blocked; omitted when not blocked."},"rejectionEdits":{"type":"array","description":"Portal or clearinghouse rejection edits; omitted when none. Never PHI. Codes are verbatim from 277CA STC01-2 / 999 IK5/AK9 / the portal; never invented.","items":{"type":"object","additionalProperties":false,"properties":{"source":{"type":"string","enum":["999","277ca","payer_portal"],"description":"Where the edit came from. Absent when the producer did not classify it."},"category":{"type":"string","description":"277CA STC01-1 claim status category when provided."},"code":{"type":"string","description":"277CA STC01-2 or 999 IK5/AK9 code, verbatim, when the producer supplied one. Never invented."},"segment":{"type":"string","description":"999 segment position (e.g. \"IK3 CLM*1\") when provided."},"message":{"type":"string","description":"Payer or clearinghouse free text; safe to show a person."}},"required":["message"]}},"sandbox":{"type":"boolean","description":"True when the source row is a sandbox (DEMO) filing and never touched a live keep."}},"required":["submissionId","payerId","state","transactionType","sandbox"]},{"type":"object","additionalProperties":false,"description":"Attachment upload outcome. Never filename, never imageMeta, never ciphertext.","properties":{"submissionId":{"type":"string","description":"Parent claim submission id (clm_…)."},"attachmentId":{"type":"string","description":"Attachment id (att_…)."},"kind":{"type":"string","description":"Attachment kind (radiograph, perio_chart, photo, narrative, eob, or other)."},"state":{"type":"string","description":"Attachment state at event time (attached or failed)."},"byteLength":{"type":"integer","description":"Decoded byte length of the file."}},"required":["submissionId","attachmentId","kind","state","byteLength"]},{"type":"object","additionalProperties":false,"description":"Endpoint deactivated. POSTed to the customer's other active webhooks on auto-deactivation or PATCH active:false (reason customer). Recorded as a dead audit delivery (deactivated_audit) on the deactivated endpoint so a later active:true cannot POST it.","properties":{"webhookId":{"type":"string","description":"Deactivated webhook id (whk_…)."},"deactivatedAt":{"type":"string","description":"ISO-8601 UTC when the endpoint was deactivated."},"deactivatedReason":{"type":"string","enum":["consecutive_failures","destination_denied","customer"],"description":"Why the endpoint was deactivated."}},"required":["webhookId","deactivatedAt","deactivatedReason"]},{"type":"object","additionalProperties":false,"description":"A payer login's desk word changed (the same three-word truth GET /v1/portal-logins publishes as desk). Fields are snake_case to match that surface.","properties":{"organization_id":{"type":"string","description":"Practice this login belongs to."},"payer_id":{"type":"string","description":"Catalog payer id."},"from":{"type":"string","enum":["alive","needs_sign_in","needs_attention","enter_code","set_up"],"description":"Desk word before this change."},"to":{"type":"string","enum":["alive","needs_sign_in","needs_attention","enter_code","set_up"],"description":"Desk word after this change."},"reason":{"type":"string","description":"Closed machine reason, e.g. login_bounce_no_code."},"observed_at":{"type":"string","description":"ISO-8601 UTC when this desk word was observed."},"predicted_expiry_at":{"type":["string","null"],"description":"Forecast login expiry when known; null unless available."}},"required":["organization_id","payer_id","from","to","reason","observed_at","predicted_expiry_at"]},{"type":"object","additionalProperties":false,"description":"A payer login's login_state flipped. row is the full published GET /v1/portal-logins item.","properties":{"organization_id":{"type":"string","description":"Practice this login belongs to."},"payer_id":{"type":"string","description":"Catalog payer id."},"login_state":{"type":"string","description":"login_state after this change."},"previous_login_state":{"type":["string","null"],"description":"login_state before this change; null on first emit after a baseline."},"at":{"type":"string","description":"ISO-8601 UTC when this state was observed."},"row":{"type":"object","additionalProperties":true,"description":"Published GET /v1/portal-logins item for this payer."}},"required":["organization_id","payer_id","login_state","previous_login_state","at","row"]}]}},"required":["id","type","createdAt","tenantId","organizationId","data"]},"Webhook":{"type":"object","additionalProperties":false,"description":"Registered HTTPS endpoint. secret is returned only on create and rotate-secret.","properties":{"id":{"type":"string","description":"Webhook id (whk_…)."},"tenant_id":{"type":"string","description":"Customer account (tn_…) that owns this endpoint."},"organization_id":{"type":["string","null"],"description":"Practice override id (org_…), or null for the company default. Immutable after creation."},"url":{"type":"string","description":"HTTPS callback URL that receives HMAC-signed POSTs."},"events":{"type":"array","items":{"type":"string","enum":["eligibility.completed","eligibility.failed","claim.submitted","claim.acknowledged","claim.rejected","claim.failed","claim.unknown_outcome","claim.reconciled","claim.voided","claim.cancelled","claim.adjudication_updated","claim.attachment_uploaded","claim.attachment_failed","claim.staged","claim.stage_failed","claim.arrived_in_portal","portal_login.desk_changed","portal_login.status_changed","portal_login.state_changed","webhook.test","webhook.deactivated"]},"description":"Event type enum values this endpoint is subscribed to."},"active":{"type":"boolean","description":"False pauses deliveries without deleting the endpoint and emits webhook.deactivated (reason customer) to sibling endpoints."},"description":{"type":["string","null"],"description":"Optional operator label; never PHI. Null when unset."},"created_at":{"type":"string","description":"ISO-8601 UTC creation time."},"updated_at":{"type":"string","description":"ISO-8601 UTC last-update time."},"last_success_at":{"type":["string","null"],"description":"ISO-8601 UTC of the last HTTP 2xx delivery; null if none."},"last_failure_at":{"type":["string","null"],"description":"ISO-8601 UTC of the last failed attempt; null if none."},"consecutive_failures":{"type":"integer","description":"Failures since the last success; retries at 1m, 5m, 30m, 2h, 12h, then dead."},"deactivated_at":{"type":["string","null"],"description":"ISO-8601 UTC when the endpoint was deactivated; null while active. PATCH active:true clears it."},"deactivated_reason":{"type":["string","null"],"enum":["consecutive_failures","destination_denied","customer"],"description":"Why the endpoint was deactivated. Null while active. PATCH active:true clears it."},"previous_secret_expires_at":{"type":["string","null"],"description":"ISO-8601 UTC when the previous signing secret stops verifying. Set on rotate-secret for 24h; null when no overlap is active. The previous secret itself is never returned."},"secret":{"type":"string","readOnly":true,"description":"HMAC-SHA256 signing secret (whsec_…). Returned once on create and rotate-secret; never on GET or list. Store it; it cannot be retrieved later."}},"required":["id","tenant_id","url","events","active"]},"WebhookCreate":{"type":"object","additionalProperties":false,"description":"Register an HTTPS callback. secret is returned once on the created Webhook.","properties":{"organization_id":{"type":["string","null"],"description":"Omit or null for a company default. Set a practice id in this company to override the default for subscribed events."},"url":{"type":"string","description":"HTTPS callback URL that will receive HMAC-signed POSTs."},"events":{"type":"array","items":{"type":"string","enum":["eligibility.completed","eligibility.failed","claim.submitted","claim.acknowledged","claim.rejected","claim.failed","claim.unknown_outcome","claim.reconciled","claim.voided","claim.cancelled","claim.adjudication_updated","claim.attachment_uploaded","claim.attachment_failed","claim.staged","claim.stage_failed","claim.arrived_in_portal","portal_login.desk_changed","portal_login.status_changed","portal_login.state_changed","webhook.test","webhook.deactivated"]},"minItems":1,"description":"Non-empty list of event type enum values to subscribe to."},"description":{"type":"string","description":"Optional operator label; never PHI."}},"required":["url","events"]},"WebhookDelivery":{"type":"object","additionalProperties":false,"description":"One HMAC-signed POST attempt (or queued retry) for a webhook.","properties":{"id":{"type":"string","description":"Delivery attempt id (whd_…)."},"webhook_id":{"type":"string","description":"Parent webhook id (whk_…)."},"event_type":{"type":"string","description":"Event type enum that was or will be POSTed (same catalog as WebhookEvent.type)."},"event_id":{"type":"string","description":"Ledger event id, or test:<deliveryId> for webhook.test."},"submission_id":{"type":["string","null"],"description":"Related claim submission id (clm_…); null for webhook.test."},"payload":{"$ref":"#/components/schemas/WebhookEvent"},"attempt":{"type":"integer","description":"Zero-based retry count; 0 is the first POST."},"next_attempt_at":{"type":"string","description":"ISO-8601 UTC when the next retry fires (1m, 5m, 30m, 2h, 12h, then dead)."},"status":{"type":"string","enum":["pending","delivered","failed","dead"],"description":"pending, delivered, failed, or dead (retry schedule exhausted)."},"last_status_code":{"type":["integer","null"],"description":"HTTP status from the last POST; null before the first attempt."},"last_error":{"type":["string","null"],"description":"Transport or non-2xx error text; null when none."},"created_at":{"type":"string","description":"ISO-8601 UTC enqueue time."},"delivered_at":{"type":["string","null"],"description":"ISO-8601 UTC of the successful POST; null until delivered."}},"required":["id","webhook_id","event_type","event_id","payload","attempt","status"]},"LoginHealthResponse":{"type":"object","description":"Saved payer logins across a company's practices, each with its last recorded status. Read from a snapshot; no payer portal is contacted.","required":["tenant_id","generated_at","total_practices","next_cursor","practices","logins"],"properties":{"tenant_id":{"type":"string","description":"Your company's id."},"generated_at":{"type":"string","format":"date-time","description":"When this answer was built."},"newest_observed_at":{"type":["string","null"],"format":"date-time","description":"When the newest status in this page was recorded."},"total_practices":{"type":"integer","description":"Practices in the company, or 1 when one practice was named."},"next_cursor":{"type":["string","null"],"description":"Pass as cursor for the next page of practices. Null on the last page."},"practices":{"description":"One row per practice on this page.","type":"array","items":{"type":"object","required":["organization_id","name","auto_logins","auto_serving","auto_problems","manual_logins"],"properties":{"organization_id":{"type":"string","description":"Practice id."},"name":{"type":"string","description":"Practice name."},"auto_logins":{"type":"integer","description":"Logins with automatic sign-in on."},"auto_serving":{"type":"integer","description":"Of those, how many are serving."},"auto_problems":{"type":"integer","description":"Of those, how many need attention."},"manual_logins":{"type":"integer","description":"Logins with automatic sign-in off."}}}},"logins":{"description":"One row per saved login at those practices.","type":"array","items":{"type":"object","required":["organization_id","organization_name","payer_id","payer_name","auto_sign_in","status","status_label","detail"],"properties":{"organization_id":{"type":"string","description":"Practice id."},"organization_name":{"type":"string","description":"Practice name."},"payer_id":{"type":"string","description":"Payer id from GET /payers."},"payer_name":{"type":"string","description":"Payer name."},"auto_sign_in":{"type":"boolean","description":"Automatic sign-in is on for this login."},"status":{"type":"string","enum":["serving","checking","code","sign_in","down","unverified"],"description":"serving: answering checks. checking: being verified. code: waiting for a one-time code. sign_in: needs a sign-in. down: needs attention. unverified: no recent status."},"status_label":{"type":"string","description":"The same status in the words the console shows."},"detail":{"type":"string","description":"One sentence on why the login has this status."},"last_signed_in_at":{"type":["string","null"],"format":"date-time","description":"Last confirmed signed-in moment."},"last_failure_at":{"type":["string","null"],"format":"date-time","description":"Last recorded failure."},"observed_at":{"type":["string","null"],"format":"date-time","description":"When this status was recorded."}}}}}},"PracticeSetupResponse":{"type":"object","description":"Where each practice stands in setup: the same steps the console Home page draws.","required":["tenant_id","total","next_cursor","practices"],"properties":{"tenant_id":{"type":"string","description":"Your company's id."},"total":{"type":"integer","description":"Practices in the company, or 1 when one practice was named."},"next_cursor":{"type":["string","null"],"description":"Pass as cursor for the next page. Null on the last page."},"practices":{"description":"One row per practice on this page.","type":"array","items":{"type":"object","required":["organization_id","name","ready","steps_done","steps_total","next_step","steps","saved_logins","code_email","ok_checks_30d","last_ok_check_at"],"properties":{"organization_id":{"type":"string","description":"Practice id."},"name":{"type":"string","description":"Practice name."},"ready":{"type":"boolean","description":"Every setup step is done."},"steps_done":{"type":"integer","description":"Steps finished."},"steps_total":{"type":"integer","description":"Steps in all."},"next_step":{"type":["object","null"],"description":"The step the customer should act on, if any.","properties":{"id":{"type":"string","description":"Step id."},"label":{"type":"string","description":"Step name."},"detail":{"type":"string","description":"What to do."}}},"steps":{"description":"The four setup steps, in order.","type":"array","items":{"type":"object","required":["id","label","state","detail"],"properties":{"id":{"type":"string","enum":["added","logins","code_email","first_check"]},"label":{"type":"string","description":"Step name as the console shows it."},"state":{"type":"string","enum":["done","current","waiting","todo"],"description":"current: the customer's next step. waiting: someone else is on it, either Veraxus switching the code address on or the office filling in its onboarding sheet."},"detail":{"type":"string","description":"One sentence: what is true now, or what to do."}}}},"saved_logins":{"type":"integer","description":"Payer logins with a saved password."},"code_email":{"type":["object","null"],"description":"The practice's code address. Null when the company is not enrolled.","properties":{"address":{"type":"string","description":"The practice's code email address."},"receiving":{"type":"boolean","description":"Veraxus has confirmed mail to this address arrives."},"mail_seen":{"type":"boolean","description":"A payer has sent at least one message here."}}},"ok_checks_30d":{"type":"integer","description":"Real checks that returned benefits in the last 30 days. Sandbox checks are not counted."},"last_ok_check_at":{"type":["string","null"],"format":"date-time","description":"Last real check that returned benefits. Sandbox checks are not counted."}}}}}},"VaultLoginsResponse":{"type":"object","description":"One practice's Portal vault. Passwords and recovery codes are never returned.","required":["organization_id","logins"],"properties":{"organization_id":{"type":"string","description":"Practice id."},"logins":{"description":"One row per payer portal.","type":"array","items":{"type":"object","required":["id","payer_id","portal","company","portal_url","email","username","has_password","has_recovery_code","sign_in_login_saved","sign_in_login_differs","sign_in_username","auto_sign_in","code_destination","updated_at"],"properties":{"id":{"type":"string","description":"Portal id within the vault."},"payer_id":{"type":"string","description":"Payer id from GET /payers."},"portal":{"type":"string","description":"Portal name."},"company":{"type":"string","description":"Payer company the portal belongs to."},"portal_url":{"type":"string","description":"The portal's sign-in page."},"email":{"type":"string","description":"Email on the payer account. Empty when none is saved."},"username":{"type":"string","description":"Empty when none is saved."},"has_password":{"type":"boolean","description":"A password is saved."},"has_recovery_code":{"type":"boolean","description":"A recovery code is saved."},"sign_in_login_saved":{"type":"boolean","description":"Veraxus has a login saved to sign in with."},"sign_in_login_differs":{"type":"boolean","description":"That sign-in login is not the one saved here."},"sign_in_username":{"type":["string","null"],"description":"Username Veraxus signs in with, when exactly one is saved."},"auto_sign_in":{"type":"boolean","description":"Automatic sign-in is on. Changed in the console only."},"code_destination":{"type":"string","enum":["veraxus","authenticator","external","none"],"description":"Where this payer's sign-in codes come from: the practice's Veraxus address, a saved authenticator Veraxus makes codes from, another mailbox, or nowhere known."},"updated_at":{"type":["string","null"],"format":"date-time","description":"Last change to this vault entry."}}}}}},"ConnectorRequest":{"type":"object","required":["id","payer_name","portal_url","requested_at"],"properties":{"id":{"type":"string","description":"Request id."},"payer_name":{"type":"string","description":"The payer's name, cleaned up."},"portal_url":{"type":["string","null"],"description":"Where the office signs in, as origin and path only."},"requested_at":{"type":"string","format":"date-time","description":"When the practice asked."}}},"ConnectorRequestListResponse":{"type":"object","required":["organization_id","requests"],"properties":{"organization_id":{"type":"string","description":"Practice id."},"requests":{"type":"array","description":"Newest first.","items":{"$ref":"#/components/schemas/ConnectorRequest"}}}},"ConnectorRequestCreate":{"type":"object","additionalProperties":false,"required":["payer_name"],"properties":{"organization_id":{"type":"string","description":"Required for a company-wide key."},"payer_name":{"type":"string","minLength":2,"maxLength":120,"description":"The payer's name as it appears on a patient's card."},"portal_url":{"type":"string","maxLength":300,"description":"Where the office signs in. The query string and fragment are dropped before it is stored."}}},"ConnectorRequestCreateResponse":{"type":"object","required":["organization_id","already_requested","request"],"properties":{"organization_id":{"type":"string","description":"Practice id."},"already_requested":{"type":"boolean","description":"True when this practice asked for the same payer in the last 30 days."},"request":{"$ref":"#/components/schemas/ConnectorRequest","description":"The request on file."}}},"PeopleResponse":{"type":"object","required":["tenant_id","people"],"properties":{"tenant_id":{"type":"string","description":"Your company's id."},"people":{"description":"Everyone with console access.","type":"array","items":{"type":"object","required":["id","name","email","role","added_at"],"properties":{"id":{"type":"string","description":"User id."},"name":{"type":"string","description":"The person's name."},"email":{"type":"string","description":"The person's sign-in email."},"role":{"type":"string","enum":["admin","member"]},"added_at":{"type":["string","null"],"format":"date-time","description":"When this person was added to the company."}}}}}},"BillingResponse":{"type":"object","required":["tenant_id","price_cents","current_period","last_30_days","payment_method","invoices"],"properties":{"tenant_id":{"type":"string","description":"Your company's id."},"price_cents":{"description":"List prices.","type":"object","required":["live","cached"],"properties":{"live":{"type":"integer","description":"Price of one live check, in US cents."},"cached":{"type":"integer","description":"Price of one cached check, in US cents."}}},"current_period":{"description":"The current billing month.","type":"object","required":["start","end","cents","checks"],"properties":{"start":{"type":"string","description":"First day of the billing month, UTC."},"end":{"type":"string","description":"First day of the next billing month, UTC."},"cents":{"type":"integer","description":"Billed amount in US cents."},"checks":{"type":"integer","description":"Billed checks."}}},"last_30_days":{"description":"The last 30 days.","type":"object","required":["cents","checks"],"properties":{"cents":{"type":"integer","description":"Billed amount in US cents."},"checks":{"type":"integer","description":"Billed checks."}}},"payment_method":{"description":"The payment method on file.","type":"object","required":["on_file","brand","last4"],"properties":{"on_file":{"type":"boolean","description":"A card or bank account is on file."},"brand":{"type":["string","null"],"description":"Card brand or bank name."},"last4":{"type":["string","null"],"description":"Last four digits."}}},"invoices":{"description":"Recent invoices, newest first.","type":"array","items":{"type":"object","required":["id","number","cents","status","hosted_url","pdf_url","created_at","period_start","period_end"],"properties":{"id":{"type":"string","description":"Invoice id."},"number":{"type":["string","null"],"description":"Invoice number."},"cents":{"type":"integer","description":"Invoice amount in US cents."},"status":{"type":"string","description":"Invoice status, for example paid or open."},"hosted_url":{"type":["string","null"],"description":"Page where the invoice can be viewed and paid."},"pdf_url":{"type":["string","null"],"description":"PDF download."},"created_at":{"type":["string","null"],"format":"date-time","description":"When the invoice was created."},"period_start":{"type":["string","null"],"description":"First day billed."},"period_end":{"type":["string","null"],"description":"Last day billed."}}}}}},"AgreementsResponse":{"type":"object","required":["tenant_id","agreements"],"properties":{"tenant_id":{"type":"string","description":"Your company's id."},"agreements":{"description":"One row per agreement.","type":"array","items":{"type":"object","required":["id","name","version","signed","signed_at","signer_name","signer_title"],"properties":{"id":{"type":"string","enum":["baa","msa","sow"]},"name":{"type":"string","description":"Agreement name."},"version":{"type":"string","description":"Current version of the agreement."},"signed":{"type":"boolean","description":"The current version is signed."},"signed_at":{"type":["string","null"],"format":"date-time","description":"When it was signed."},"signer_name":{"type":["string","null"],"description":"Who signed."},"signer_title":{"type":["string","null"],"description":"Their title."}}}}}},"PortalLoginIntakeRequest":{"type":"object","additionalProperties":false,"required":["submission_id","revision"],"properties":{"organization_id":{"type":"string","description":"Practice from GET /organizations. Required for a company-wide key; a practice-bound key may omit it. The caller names the practice by id; Veraxus never matches it by name."},"npi":{"type":"string","pattern":"^[0-9]{10}$","description":"Optional cross-check. When the practice has an NPI on file and this differs, the whole call is 409 organization_identity_mismatch and nothing is saved."},"submission_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{7,127}$","description":"The caller's id for this submission. Saved as last_client_reference on each login it writes, so later portal-login rows and webhooks can be tied back to it."},"revision":{"type":"integer","minimum":1,"description":"Starts at 1 and goes up each time the practice resubmits. The same revision sent again returns the stored result; a lower one than the newest applied returns status superseded."},"attestation":{"$ref":"#/components/schemas/VendorAttestation"},"hitl_grant":{"type":"string","description":"Approved HITL grant id (htg_…). Alias of X-Veraxus-Hitl-Grant when the header is absent."},"logins":{"type":"array","maxItems":40,"description":"One row per login, so one row per vault_payer_id.","items":{"type":"object","additionalProperties":false,"required":["row_id","payer_id","username","password"],"properties":{"row_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$","description":"The caller's id for this row. Unique within the call. Echoed on the matching result item."},"payer_id":{"type":"string","description":"vault_payer_id / mailbox id from GET /payers. Shared logins (Keyspring, Dental HUB, Provider Tools) are one row."},"username":{"type":"string","maxLength":200,"description":"Portal username."},"password":{"type":"string","maxLength":200,"writeOnly":true,"description":"Portal password. Vaulted. Never returned and never stored on the receipt."},"account_email":{"type":"string","format":"email","description":"The email on this payer account, where the payer sends sign-in codes. Send the practice's code email when the office changed the account to it. Omit to leave the saved value."},"account_action":{"type":"string","enum":["email_changed","account_created"],"description":"What the office did on the payer's site. Recorded as stated."},"mfa_enabled":{"type":"boolean","description":"The office's own statement that sign-in codes are switched on. Nothing is tested."}}}},"requested_portals":{"type":"array","maxItems":40,"description":"Portals the practice uses that Veraxus cannot sign in to yet: not in GET /payers, or listed there as coming_soon. Each is filed as a connector request. When the office also gave a username and a password, that login is kept on a Portal Vault card for the practice that only Veraxus staff can see, so it is waiting when the connector is built. Nothing signs in with it. With either the username or the password missing, the row is a name only. A row whose name is exactly one catalog payer, and that carries a login, is kept where that payer lives: as its sign-in login when a practice can sign in to it through Veraxus (including a payer whose checks are still coming soon), or on that payer's own card when it cannot. Only a portal with no place in the catalog gets a card named as the office typed it.","items":{"type":"object","additionalProperties":false,"required":["row_id","name"],"properties":{"row_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$","description":"The caller's id for this row. Unique within the call. Echoed on the matching result item."},"name":{"type":"string","maxLength":120,"description":"The payer or portal name, as the office wrote it."},"portal_url":{"type":"string","maxLength":300,"description":"Where the office signs in, when known. Kept on the card only when it is https."},"username":{"type":"string","maxLength":200,"description":"Portal username, when the office gave one."},"password":{"type":"string","maxLength":200,"writeOnly":true,"description":"Portal password, when the office gave one. Vaulted. Never returned."},"account_email":{"type":"string","format":"email","description":"The email on this payer account. Same meaning as on a logins row."},"account_action":{"type":"string","enum":["email_changed","account_created"],"description":"What the office did on the payer's site. Recorded as stated."},"mfa_enabled":{"type":"boolean","description":"The office's own statement that sign-in codes are switched on. Nothing is tested."}}}},"top_carriers":{"type":"array","maxItems":20,"description":"The practice's most common carriers. Kept on the receipt as a priority signal; nothing else is done with it.","items":{"type":"object","additionalProperties":false,"required":["row_id","name"],"properties":{"row_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$","description":"The caller's id for this row. Unique within the call. Echoed on the matching result item."},"name":{"type":"string","maxLength":200,"description":"Carrier name as the practice wrote it."},"payer_id":{"type":"string","description":"Catalog payer id when the name matches one."},"provider":{"type":"string","maxLength":200,"description":"Which provider this applies to."},"network":{"type":"string","enum":["in","out"],"description":"In or out of network."}}}}}},"PortalLoginIntakeItem":{"type":"object","required":["row_id","kind","payer_id","state","reason","message"],"properties":{"row_id":{"type":"string","description":"The row_id sent for this row."},"kind":{"type":"string","enum":["login","requested_portal"],"description":"Which list the row came from: logins or requested_portals."},"payer_id":{"type":["string","null"],"description":"The login's vault_payer_id. Null for a requested portal, except when its name is a catalog payer: then that payer, whether the row was saved for it or parked as payer_in_catalog."},"state":{"type":"string","enum":["saved","updated","unchanged","requested","parked"],"description":"saved: no login existed and it is saved now. updated: the saved login changed (for a logins row, same username with a new password or account email). unchanged: identical to what is saved. requested: a connector request is on file and no login was sent. parked: nothing changed for this row; reason says why. A requested portal that carried a login reports saved, updated or unchanged."},"reason":{"type":["string","null"],"description":"Set when state is parked. username_differs (a login with another username is saved; a person replaces it in the console), serving_login_differs (the portal is signed in right now with a different password, so the saved login is treated as proven and left as it is), automatic_sign_in_on (turn it off before changing this login), payer_not_available (a practice cannot sign in to this payer through Veraxus and it has no card to keep a login on), shared_login (this practice signs in through another practice's login), unknown_payer, not_a_payer_portal (the row names a cloud practice system such as Oryx or Curve; it is connected on Cloud PMS Connections, and its login is neither saved nor requested here), or for a requested portal payer_in_catalog (its name is a catalog payer and the row had no login for a payer Veraxus signs in to, matched more than one payer, or repeated a login already in the call), invalid_payer_name, invalid_portal_url, too_many_requests (a name-only row; a row with a login is still stored)."},"message":{"type":"string","description":"One plain sentence for a person."},"code_destination":{"type":"string","enum":["veraxus","external","none"],"description":"Where this login's sign-in codes go, read from the saved account email: veraxus when it is a codes.veraxus.ai address."}}},"PortalLoginIntakeReceipt":{"type":"object","required":["receipt_id","organization_id","submission_id","revision","status","items","code_email"],"properties":{"receipt_id":{"type":"string","description":"Stable id for this submission's receipt."},"organization_id":{"type":"string","description":"The practice the logins were saved for."},"submission_id":{"type":"string","description":"The submission_id sent on the call."},"revision":{"type":"integer","description":"The revision this result describes. On status superseded, the newer revision already applied."},"status":{"type":"string","enum":["ingested","needs_attention","superseded"],"description":"ingested: every row ended saved, updated, unchanged or requested. needs_attention: at least one row is parked. superseded: a newer revision was already applied and this call changed nothing."},"items":{"type":"array","description":"One result per login and requested portal, in the order sent. Empty on status superseded.","items":{"$ref":"#/components/schemas/PortalLoginIntakeItem"}},"top_carriers":{"type":"array","description":"The top carriers as received.","items":{"type":"object","additionalProperties":true}},"code_email":{"type":["object","null"],"description":"The practice's code email, read when the response is built. Do not put it on a payer account until receiving is true.","required":["address","receiving"],"properties":{"address":{"type":"string","format":"email"},"receiving":{"type":"boolean"}}}}}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Canonical retry key, scoped to operation and practice. Reuse with the same payload returns the same receipt; reuse with another payload returns 409. JSON bodies may send idempotency_key as an alias when this header is absent; both present and different is 400 idempotency_key_mismatch.","schema":{"type":"string","minLength":1,"maxLength":256}},"HitlGrant":{"name":"X-Veraxus-Hitl-Grant","in":"header","required":false,"description":"Approved HITL grant id (htg_…). Required to complete store-credentials or connect unless the credential has portal_login_mutation and a valid attestation object. A bearer token without this header and without attestation receives 403 hitl_required.","schema":{"type":"string","minLength":1,"maxLength":128}}},"responses":{"Error500":{"description":"Unexpected Veraxus error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error502":{"description":"Upstream payer or portal returned a bad gateway. Retry when error.retryable is true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error503":{"description":"Veraxus or the payer portal is temporarily unavailable. Includes portal_outage (retryable). Wait retry_after seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/reference":{"get":{"tags":["Account"],"summary":"HTML API reference","description":"Renders GET /v1/openapi.json in the browser with a pinned Redoc script from cdn.jsdelivr.net. HTML Accept on GET /v1/openapi.json is the same 200 representation; this path stays.","operationId":"getApiReference","security":[],"responses":{"200":{"description":"HTML API reference.","content":{"text/html":{"schema":{"type":"string"},"example":"demo"}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/getting-started":{"get":{"tags":["Account"],"summary":"Read the first-check integration guide","description":"Six-step walkthrough from connection through an unpaid sandbox check and a live billed check. This is the REST twin of MCP getting_started and https://veraxus.ai/docs#start.","operationId":"getGettingStarted","security":[],"responses":{"200":{"description":"Integration guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GettingStartedResponse"},"example":{"title":"demo","docs_url":"demo","billed":false,"sequence":[{"step":1,"title":"demo","rest":"demo","mcp":"demo","when":"demo"}],"markdown":"demo"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/me":{"get":{"tags":["Account"],"summary":"Read the authenticated customer and key","description":"Returns the exact server-derived caller_id and granted scopes for this API key or OAuth grant. Delegated portal-consent JWS claims must bind this caller_id.","operationId":"getMe","responses":{"200":{"description":"Identity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"},"example":{"key":{"id":"demo","name":"demo","org_id":"demo","caller_id":"api_key:key_demo","scopes":["eligibility"]},"tenant":{"id":"demo","name":"demo","price_cents":1,"billing_unit":"eligibility_check","enabled_payers":["demo"]},"organization_count":1,"sandbox":{"members":[{}],"billed":false}}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/sandbox/members":{"get":{"tags":["Account"],"summary":"List sandbox DEMO members","operationId":"listSandboxMembers","description":"Practice members for unpaid checks. Each row is a published DEMO member_id for POST /eligibility with sandbox: true (MCP: list_sandbox_members, then check_sandbox_eligibility). Never billed. No PHI.","responses":{"200":{"description":"DEMO roster","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxMembersResponse"},"example":{"members":[{"member_id":"demo"}],"billed":false}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"This credential requires the eligibility scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/payers":{"get":{"tags":["Account"],"summary":"List supported portal-login payer identifiers","operationId":"listPayers","description":"Returns every licensed payer even when delegated onboarding or revocation is blocked. Use id or eligibility_payer_id as payer_id; vault_payer_id and mailbox_id group credentials, not eligibility routes. Enabled flags and null block codes describe authenticated tenant/organization/payer capability, not caller mutation authorization. Before offering Sign in or Disconnect, separately verify portal_login_mutation in GET /v1/me key.scopes and bind key.caller_id. On an exact organization-scoped read, licensed non-UCCI closed-allowlist Connect payers and DNoA publish onboarding_enabled=true; POST /portal/onboard stores credentials and invokes the canonical Connect engine internally. United Concordia remains limited to its separately released exact tn_verora/org_4ab6ddda scope. An unscoped read does not authorize onboarding. sandbox_mfa is restricted to the configured non-customer organization, otherwise portal_login_sandbox_org_required. Revocation remains separately gated and uncertified revocation scopes return portal_login_revoke_recert_required. organization_id is optional for catalog reads, but required for scoped onboarding evidence and verified against the authenticated tenant/key.","parameters":[{"name":"organization_id","in":"query","required":false,"description":"Optional practice returned by GET /organizations. A practice-bound key may omit it.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Payer list. Each row also documents availability, availability_reason, sign_in_method, and renews_without_code (filled at runtime by the capability registry).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayerListResponse"},"example":{"payers":[{"id":"demo","eligibility_payer_id":"demo","name":"demo","vault_payer_id":"demo","mailbox_id":"demo","mailbox_name":"demo","requires_book_picker":false,"supported_payers":["demo"],"stedi_id":"demo","aliases":["demo"],"edi_payer_ids":["demo"],"status":"live","enabled":false,"revoke_only":false,"login_saved":false,"onboarding_enabled":false,"onboarding_block_code":"portal_login_recert_required","revocation_enabled":false,"revocation_block_code":"portal_login_revoke_recert_required","connect_supported":false,"mfa":false,"mfa_types":["sms_otp"],"availability":"available","availability_reason":"sign_in_not_supported","sign_in_method":"connect","renews_without_code":false}]}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The authenticated key cannot access the requested practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The requested practice is not on this customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/eligibility":{"post":{"tags":["Eligibility"],"summary":"Run one eligibility check","operationId":"checkEligibility","description":"Returns a normalized customer-safe result. A long-running check returns 202 and a check id for GET /eligibility/{id}. The eligibility wire never posts the password. A confirmed dead keep may trigger the canonical scheduled Connect path only when all guarded automatic email-code conditions pass; if its bounded wait elapses, the result is error_code=reconnecting with session.status and portal_login.status reconnecting, and start_with=poll. A missing vault login remains error_code=credentials_required with portal_login.status=not_connected. Otherwise a cold keep or confirmed bounce fails closed with why=reconnect. Parked needs_code is why=needs_code — complete MFA, do not Connect. Live billed checks require a ready keep. Procedure rows (benefit.dental.procedures[] and parsed.procedures[]) may carry optional canonical shares: planPaysPct and patientPaysPct (in-network plane, tiers with network in), outOfNetworkPlanPct and outOfNetworkPatientPct (out-of-network plane, tiers with network out), and boolean deductibleApplies. For payers that publish networkedBenefits[] (ddmo), Veraxus fills a plane from the row's own labeled tiers only when every tier of that plane agrees and plan + patient = 100, sets deductibleApplies true when every tier states it applies and false when every tier states it does not, never overwrites a key the row already carries, and never computes a share from an unlabeled percent. When the tiers disagree the plane is absent and the per-tier carrier networkedBenefits[] holds each tier: networkTier, network (in|out), reportedBenefitPct, reportedBenefitFraction, patientPaysPct, the raw deductibleApplies, and meaning. Batch receipts carry only the flat keys; the per-tier carrier is on GET /eligibility/{id}. Other payers publish their mapper's own labeled value in these keys.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Prevents duplicate execution and billing for the same practice request.","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligibilityCheckRequest"},"example":{"payer_id":"sandbox_mfa","member_id":"DEMO-4401","date_of_birth":"1980-01-15","first_name":"Ada","last_name":"Lovelace","sandbox":true}},"application/edi-x12":{"schema":{"type":"string","description":"Raw X12 270."},"example":"ISA*00*          *00*          *ZZ*SANDBOX*ZZ*VERAXUS*260916*1200*^*00501*000000001*0*T*:~"}}},"responses":{"200":{"description":"Terminal eligibility result or X12 271.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligibilityResult"},"example":{"status":"pending","usable":false,"why":"live","error":"demo","error_code":"demo","retry":{"ok":false},"billing":{"unit":"eligibility_check","cents":0,"currency":"USD","waived":false}}},"application/edi-x12":{"schema":{"type":"string"},"example":"demo"}}},"202":{"description":"Check accepted and still running.","headers":{"Location":{"description":"Canonical URL of the durable check resource to poll.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligibilityResult"},"example":{"status":"pending","usable":false,"why":"live","error":"demo","error_code":"demo","retry":{"ok":false},"billing":{"unit":"eligibility_check","cents":0,"currency":"USD","waived":false}}}}},"400":{"description":"Invalid eligibility request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency key conflicts with another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected Veraxus error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"$ref":"#/components/responses/Error502"},"503":{"description":"Eligibility dispatch is temporarily unavailable.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Eligibility"],"summary":"List a practice's checks for one day","operationId":"listEligibility","parameters":[{"name":"practice_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"organization_id","in":"query","required":false,"deprecated":true,"description":"Deprecated alias for practice_id. If both are sent, they must match.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"date","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cursor-paginated check list without member IDs. Rows carry id, payer_id, usable, why, status, served_by, created_at, and enrichment when non-null.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligibilityListResponse"},"example":{"practice_id":"demo","date":"1980-01-15","checks":[{"id":"demo","payer_id":"demo","usable":false,"why":"live","status":"pending","served_by":"payer_portal","created_at":"demo"}],"next_cursor":"demo"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}},"description":"List a practice's checks for one day"}},"/eligibility/{id}":{"get":{"tags":["Eligibility"],"summary":"Read the current state of one check","operationId":"getEligibility","description":"Returns the same EligibilityResult as POST /eligibility, rebuilt from the stored check. Procedure rows (benefit.dental.procedures[] and parsed.procedures[]) may carry optional canonical shares: planPaysPct and patientPaysPct (in-network plane, tiers with network in), outOfNetworkPlanPct and outOfNetworkPatientPct (out-of-network plane, tiers with network out), and boolean deductibleApplies. For payers that publish networkedBenefits[] (ddmo), Veraxus fills a plane from the row's own labeled tiers only when every tier of that plane agrees and plan + patient = 100, sets deductibleApplies true when every tier states it applies and false when every tier states it does not, never overwrites a key the row already carries, and never computes a share from an unlabeled percent. When the tiers disagree the plane is absent and the per-tier carrier networkedBenefits[] holds each tier: networkTier, network (in|out), reportedBenefitPct, reportedBenefitFraction, patientPaysPct, the raw deductibleApplies, and meaning. Batch receipts carry only the flat keys; the per-tier carrier is on GET /eligibility/{id}. Other payers publish their mapper's own labeled value in these keys.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Completed eligibility result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligibilityResult"},"example":{"status":"pending","usable":false,"why":"live","error":"demo","error_code":"demo","retry":{"ok":false},"billing":{"unit":"eligibility_check","cents":0,"currency":"USD","waived":false}}}}},"202":{"description":"Check is still running. Poll this URL; the body is the same pending receipt as POST.","headers":{"Location":{"description":"Canonical URL of the durable check resource to poll.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligibilityResult"},"example":{"status":"pending","usable":false,"why":"live","error":"demo","error_code":"demo","retry":{"ok":false},"billing":{"unit":"eligibility_check","cents":0,"currency":"USD","waived":false}}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Check not found in the authenticated scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/benefit-forms:render-source":{"post":{"tags":["Eligibility"],"summary":"Render retained reported benefits","operationId":"renderSourceBenefitForm","description":"Render-only use of the existing customer-safe statement model and PDF generator. Initially restricted to eligible tn_verora credentials and explicit org_gabriel. Fixed Pulp branding. No eligibility check, payer request, usage charge, source signing authority or data application is created. The closed projection contains reported facts; generic plan-paid percentages retain unknown network and review requirements. Original network data is absent in this version. No original Source JSON, secret/proof, arbitrary sections, HTML, check ID or custom branding is accepted. Missing values remain unknown. Source/provider/patient verification authority and complete original archive/readback remain the native consumer's responsibility. Original observed/committed timestamps must agree with asOf and chronology. Details are bounded to 32KiB complete serialized JSON; whole input to 64KiB. PDFs retain normal generation metadata and may differ on a later render; native retains its first proven artifact.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","oneOf":[{"type":"object","properties":{"organization_id":{"type":"string","minLength":1,"maxLength":128},"render_contract_version":{"type":"number","const":2},"source_kind":{"type":"string","const":"sally_stedi_result_v1"},"operation_id":{"type":"string","pattern":"^(?:pulp-[a-f0-9]{64}|portal:[a-f0-9]{64}|[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12})$"},"attempt_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$"},"source_digest":{"type":"string","pattern":"^[a-f0-9]{64}$"},"observed_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"committed_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"original_network":{"type":"null"},"subject":{"type":"object","properties":{"member_id":{"type":"string","minLength":1,"maxLength":128},"payer_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$"},"date_of_service":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"required":["member_id","payer_id","date_of_service"],"additionalProperties":false},"benefit":{"type":"object","properties":{"active":{"type":["boolean","null"]},"network":{"type":"string","const":"unknown"},"asOf":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"deductible":{"type":"object","properties":{"individual":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":90071992547409.9,"multipleOf":0.01},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]},"family":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":90071992547409.9,"multipleOf":0.01},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]},"remaining":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":90071992547409.9,"multipleOf":0.01},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]}},"required":["individual","family","remaining"],"additionalProperties":false},"annualMax":{"type":"object","properties":{"individual":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":90071992547409.9,"multipleOf":0.01},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]},"remaining":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":90071992547409.9,"multipleOf":0.01},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]}},"required":["individual","remaining"],"additionalProperties":false},"orthoLifetime":{"type":"object","properties":{"individual":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":90071992547409.9,"multipleOf":0.01},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]},"remaining":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":90071992547409.9,"multipleOf":0.01},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]}},"required":["individual","remaining"],"additionalProperties":false},"stale":{"type":"boolean"},"remainingStale":{"type":"boolean"}},"required":["active","network","asOf","deductible","annualMax","orthoLifetime","stale","remainingStale"],"additionalProperties":false},"reported_categories":{"maxItems":9,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","enum":["preventive","basic","major","orthodontics","endodontic","periodontal","oral_surgery","implants","prosthodontics"]},"plan_paid_pct":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"network":{"type":"string","const":"unknown"},"qualifiers":{"anyOf":[{"type":"object","properties":{"varies_by_procedure":{"type":["boolean","null"]},"action_required":{"type":["boolean","null"]},"deductible_applies":{"type":["boolean","null"]},"conflicting_rates":{"type":"boolean"}},"required":["varies_by_procedure","action_required","deductible_applies","conflicting_rates"],"additionalProperties":false},{"type":"null"}]}},"required":["key","plan_paid_pct","network","qualifiers"],"additionalProperties":false}},"reported_details":{"maxItems":2000,"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["frequency","exclusion","rule","note"]},"title":{"type":"string","maxLength":120},"items":{"maxItems":30,"type":"array","items":{"type":"string","maxLength":2048}},"quality":{"type":"string","const":"needs_review"}},"required":["kind","title","items"],"additionalProperties":false}},"reported_procedure_count":{"type":"integer","minimum":0,"maximum":2000},"reported_procedures":{"maxItems":2000,"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":1999},"code":{"anyOf":[{"type":"string","pattern":"^D\\d{4}$"},{"type":"null"}]},"name":{"anyOf":[{"type":"string","maxLength":8192},{"type":"null"}]},"category":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"covered":{"type":["boolean","null"]},"details":{"maxItems":2000,"type":"array","items":{"type":"object","properties":{"label":{"type":"string","maxLength":120},"value":{"type":"string","maxLength":8192},"needs_review":{"type":"boolean"}},"required":["label","value","needs_review"],"additionalProperties":false}}},"required":["index","code","name","category","covered","details"],"additionalProperties":false}}},"required":["organization_id","source_kind","operation_id","attempt_id","source_digest","observed_at","committed_at","original_network","subject","benefit","reported_categories","reported_details"],"additionalProperties":false},{"type":"object","properties":{"organization_id":{"type":"string","minLength":1,"maxLength":128},"render_contract_version":{"type":"number","const":2},"source_kind":{"type":"string","const":"sally_verification_snapshot_v1"},"operation_id":{"type":"null"},"attempt_id":{"anyOf":[{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$"},{"type":"null"}]},"source_digest":{"type":"string","pattern":"^[a-f0-9]{64}$"},"observed_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"committed_at":{"type":"null"},"original_network":{"type":"null"},"subject":{"type":"object","properties":{"member_id":{"type":"null"},"payer_id":{"type":"null"},"date_of_service":{"type":"null"}},"required":["member_id","payer_id","date_of_service"],"additionalProperties":false},"benefit":{"type":"object","properties":{"active":{"type":["boolean","null"]},"network":{"type":"string","const":"unknown"},"asOf":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"deductible":{"type":"object","properties":{"individual":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":90071992547409.9,"multipleOf":0.01},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]},"family":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":90071992547409.9,"multipleOf":0.01},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]},"remaining":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":90071992547409.9,"multipleOf":0.01},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]}},"required":["individual","family","remaining"],"additionalProperties":false},"annualMax":{"type":"object","properties":{"individual":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":90071992547409.9,"multipleOf":0.01},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]},"remaining":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":90071992547409.9,"multipleOf":0.01},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]}},"required":["individual","remaining"],"additionalProperties":false},"orthoLifetime":{"type":"object","properties":{"individual":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":90071992547409.9,"multipleOf":0.01},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]},"remaining":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":90071992547409.9,"multipleOf":0.01},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]}},"required":["individual","remaining"],"additionalProperties":false},"stale":{"type":"boolean"},"remainingStale":{"type":"boolean"}},"required":["active","network","asOf","deductible","annualMax","orthoLifetime","stale","remainingStale"],"additionalProperties":false},"reported_categories":{"maxItems":9,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","enum":["preventive","basic","major","orthodontics","endodontic","periodontal","oral_surgery","implants","prosthodontics"]},"plan_paid_pct":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"network":{"type":"string","const":"unknown"},"qualifiers":{"anyOf":[{"type":"object","properties":{"varies_by_procedure":{"type":["boolean","null"]},"action_required":{"type":["boolean","null"]},"deductible_applies":{"type":["boolean","null"]},"conflicting_rates":{"type":"boolean"}},"required":["varies_by_procedure","action_required","deductible_applies","conflicting_rates"],"additionalProperties":false},{"type":"null"}]}},"required":["key","plan_paid_pct","network","qualifiers"],"additionalProperties":false}},"reported_details":{"maxItems":2000,"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["frequency","exclusion","rule","note"]},"title":{"type":"string","maxLength":120},"items":{"maxItems":30,"type":"array","items":{"type":"string","maxLength":2048}},"quality":{"type":"string","const":"needs_review"}},"required":["kind","title","items"],"additionalProperties":false}},"reported_procedure_count":{"type":"integer","minimum":0,"maximum":2000},"reported_procedures":{"maxItems":2000,"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":1999},"code":{"anyOf":[{"type":"string","pattern":"^D\\d{4}$"},{"type":"null"}]},"name":{"anyOf":[{"type":"string","maxLength":8192},{"type":"null"}]},"category":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"covered":{"type":["boolean","null"]},"details":{"maxItems":2000,"type":"array","items":{"type":"object","properties":{"label":{"type":"string","maxLength":120},"value":{"type":"string","maxLength":8192},"needs_review":{"type":"boolean"}},"required":["label","value","needs_review"],"additionalProperties":false}}},"required":["index","code","name","category","covered","details"],"additionalProperties":false}},"coverage_role":{"type":"string","enum":["primary","secondary"]},"source_verified_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"imported_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["organization_id","render_contract_version","source_kind","operation_id","attempt_id","source_digest","observed_at","committed_at","original_network","subject","benefit","reported_categories","reported_details","reported_procedure_count","reported_procedures","coverage_role","source_verified_at","imported_at"],"additionalProperties":false}]},"example":{"organization_id":"org_gabriel","source_kind":"sally_stedi_result_v1","operation_id":"pulp-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","attempt_id":"attempt_demo_01","source_digest":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","observed_at":"2026-09-16T12:00:00.000Z","committed_at":"2026-09-16T12:00:00.000Z","original_network":null,"subject":{"member_id":"DEMO-4401","payer_id":"sandbox_mfa","date_of_service":"2026-09-16"},"benefit":{"active":null,"network":"unknown","asOf":"2026-09-16T12:00:00.000Z","deductible":{"individual":null,"family":null,"remaining":null},"annualMax":{"individual":null,"remaining":null},"orthoLifetime":{"individual":null,"remaining":null},"stale":false,"remainingStale":false},"reported_categories":[],"reported_details":[]}}}},"responses":{"200":{"description":"Private reported-evidence PDF; does not assert a Veraxus verification or current eligibility.","headers":{"X-Content-Sha256":{"schema":{"type":"string","pattern":"^[a-f0-9]{64}$"},"description":"SHA256 of these exact PDF bytes."},"X-Render-Input-Sha256":{"schema":{"type":"string","pattern":"^[a-f0-9]{64}$"},"description":"SHA256 of closed input JSON with object keys recursively sorted, arrays retained in order."},"X-Benefit-Form-Kind":{"schema":{"type":"string","const":"source_evidence"}}},"content":{"application/pdf":{"schema":{"type":"string","format":"binary"},"example":"demo"}}},"400":{"description":"Refused malformed, incomplete or contradictory display input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Eligibility scope and exact allowed tenant/practice required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Complete serialized display input exceeds 64KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/eligibility/{id}/benefit-form":{"get":{"tags":["Eligibility"],"summary":"Download a stored benefits statement","operationId":"getEligibilityBenefitForm","description":"Uses the existing Veraxus PDF generator and the stored check's complete customer-safe statement sections. Requires eligibility scope and access to the check's tenant and practice. No new payer check or charge. Default branding is Veraxus; the fixed Pulp brand is available only to tn_verora. No remote logo, arbitrary benefit input, or browser renderer is accepted. Missing facts remain unknown and the statement is not a guarantee of payment.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brand","in":"query","required":false,"schema":{"type":"string","enum":["veraxus","pulp"],"default":"veraxus"}}],"responses":{"200":{"description":"Completed usable check rendered as a private PDF attachment; filename contains no member identifier.","headers":{"Content-Disposition":{"schema":{"type":"string"},"description":"Attachment with a safe branded filename."}},"content":{"application/pdf":{"schema":{"type":"string","format":"binary"},"example":"demo"}}},"202":{"description":"Check remains pending. Poll the check resource; no PDF is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligibilityResult"},"example":{"status":"pending","usable":false,"why":"live","error":"demo","error_code":"demo","retry":{"ok":false},"billing":{"unit":"eligibility_check","cents":0,"currency":"USD","waived":false}}}}},"400":{"description":"Unsupported brand or query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, revoked, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Eligibility scope or requested brand is forbidden.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Check not found in the authenticated tenant and practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Check has no usable benefits statement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/eligibility/preview":{"post":{"tags":["Eligibility"],"operationId":"previewVerification","summary":"Preview a practice's verification requests without billing","description":"Validate a single request or 1–50 day-book rows for one authorized practice. Returns a decision per row and grouped actions without a member lookup, sign-in or MFA. Missing patient fields are input actions. Unsupported dependent requests preserve the actual identity. Submission and dispatch re-evaluate current admission; this response never authorizes a paid retry.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationPreviewRequest"},"example":{"checks":[{"client_reference_id":"demo_value_0001","payer_id":"demo","date_of_service":"1980-01-15"}]}}}},"responses":{"200":{"description":"Secret-free practice/book/request decisions; no check or charge created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationPreviewResponse"},"example":{"version":"1","practice_id":"demo","assessed_at":"2026-09-16T12:00:00.000Z","summary":{"proceed":0,"wait":0,"action_required":0,"input_required":0,"unsupported":0},"actions":[{"id":"demo","mailbox_id":"demo","payer_ids":["demo"],"reason":"demo","message":"demo","action":{"owner":"none","kind":"none","href":"demo","field":"demo"},"affected_count":1,"client_reference_ids":["demo"],"indexes":[0]}],"results":[{"index":0,"client_reference_id":"demo","payer_id":"demo","verification_admission":{"version":"1","practice_id":"demo","payer_id":"demo","mailbox_id":"demo","disposition":"proceed","reason":"demo","message":"demo","action":{"owner":"none","kind":"none","href":"demo","field":"demo"},"checked_at":"2026-09-16T12:00:00.000Z","assessed_at":"2026-09-16T12:00:00.000Z","valid_until":"2026-09-16T12:00:00.000Z"}}]}}}},"400":{"description":"Invalid preview input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Practice or eligibility scope forbidden.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/eligibility/batches":{"post":{"tags":["Eligibility"],"summary":"Submit a durable practice eligibility batch","operationId":"createEligibilityBatch","description":"Accepts a JSON body of at most 512 KiB containing 1–50 rows for exactly one practice. Admission is atomic: the active bulk limit is 50 per practice, while every other practice under the same customer has an independent 50-check capacity. A 429 rejects the whole submission without partial enqueue. Every accepted row commits an encrypted durable dispatch job in that same transaction. Recovery retries only before the durable payer-call boundary; once external execution starts, an uncertain outcome is waived and failed rather than replaying the payer request. Terminal jobs erase the encrypted retry payload. Each row's opaque client_reference_id is echoed for schedule reconciliation; do not place PHI in it. Durable receipts and their idempotency keys are retained for 24 hours.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligibilityBatchRequest"},"example":{"checks":[{"client_reference_id":"demo_value_0001","payer_id":"demo","member_id":"demo","first_name":"demo","last_name":"demo","date_of_service":"1980-01-15","date_of_birth":"1980-01-15"}]}}}},"responses":{"200":{"description":"Complete batch, from either a first submission or an idempotent replay.","headers":{"Location":{"description":"Canonical URL of the durable batch resource.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}},"Idempotency-Replayed":{"description":"true when this response replays an existing operation-scoped receipt.","schema":{"type":"boolean"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligibilityBatchResponse"},"example":{"batch_id":"demo","practice_id":"demo","organization_id":"demo","created_at":"2026-09-16T12:00:00.000Z","expires_at":"2026-09-16T12:00:00.000Z","status":"pending","submitted_count":0,"accepted_count":0,"rejected_count":0,"active_limit_per_practice":50,"summary":{"pending":0,"usable":0,"failed":0,"rejected":0},"results":[{"status":"pending","usable":false,"why":"live","error":"demo","error_code":"demo","retry":{"ok":false},"billing":{"unit":"eligibility_check","cents":0,"currency":"USD","waived":false},"index":0,"client_reference_id":"demo","check_id":"demo"}],"links":{"self":"demo"}}}}},"202":{"description":"Batch accepted; one or more rows are pending.","headers":{"Location":{"description":"Canonical URL of the durable batch resource.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}},"Idempotency-Replayed":{"description":"true when this response replays an existing operation-scoped receipt.","schema":{"type":"boolean"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligibilityBatchResponse"},"example":{"batch_id":"demo","practice_id":"demo","organization_id":"demo","created_at":"2026-09-16T12:00:00.000Z","expires_at":"2026-09-16T12:00:00.000Z","status":"pending","submitted_count":0,"accepted_count":0,"rejected_count":0,"active_limit_per_practice":50,"summary":{"pending":0,"usable":0,"failed":0,"rejected":0},"results":[{"status":"pending","usable":false,"why":"live","error":"demo","error_code":"demo","retry":{"ok":false},"billing":{"unit":"eligibility_check","cents":0,"currency":"USD","waived":false},"index":0,"client_reference_id":"demo","check_id":"demo"}],"links":{"self":"demo"}}}}},"400":{"description":"Malformed batch, scope conflict, or invalid idempotency fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential cannot access this practice or its tenant has not signed the BAA.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency key was reused with another batch payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body exceeds the published batch limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Canonical batch submissions require application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"This practice's 50-check active bulk capacity would be exceeded; nothing was enqueued.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected Veraxus error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"$ref":"#/components/responses/Error502"},"503":{"description":"The encrypted durable dispatcher is unavailable; no checks were accepted.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/eligibility/batches/{batch_id}":{"get":{"tags":["Eligibility"],"summary":"Read current batch and row status","operationId":"getEligibilityBatch","description":"Returns current check state rather than a stale submission snapshot. Row reconciliation uses client_reference_id; member IDs are never returned.","parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"wait_seconds","in":"query","required":false,"description":"Park up to this many seconds and return as soon as the batch is complete. 0 (default) is a single snapshot. Max 20.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"practice_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"organization_id","in":"query","required":false,"deprecated":true,"description":"Deprecated alias for practice_id. If both are sent, they must match.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Current batch state. Pending responses include Retry-After.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligibilityBatchResponse"},"example":{"batch_id":"demo","practice_id":"demo","organization_id":"demo","created_at":"2026-09-16T12:00:00.000Z","expires_at":"2026-09-16T12:00:00.000Z","status":"pending","submitted_count":0,"accepted_count":0,"rejected_count":0,"active_limit_per_practice":50,"summary":{"pending":0,"usable":0,"failed":0,"rejected":0},"results":[{"status":"pending","usable":false,"why":"live","error":"demo","error_code":"demo","retry":{"ok":false},"billing":{"unit":"eligibility_check","cents":0,"currency":"USD","waived":false},"index":0,"client_reference_id":"demo","check_id":"demo"}],"links":{"self":"demo"}}}}},"400":{"description":"Conflicting or missing practice scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Batch not found in the authenticated practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected Veraxus error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/eligibility/batches/{batch_id}/cancel":{"post":{"tags":["Eligibility"],"summary":"Cancel batch checks that have not reached the payer","operationId":"cancelEligibilityBatch","description":"Closes every check in the batch that is still queued or held and has not reached the payer, or only the listed check_ids. A cancelled row reads status failed with why cancelled, error_code cancelled and 0 cents. Rows already with the payer or already finished are left alone and reported. The batch completes once every remaining row is done or cancelled. Calling it again is a no-op.","parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"practice_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"organization_id","in":"query","required":false,"deprecated":true,"description":"Deprecated alias for practice_id. If both are sent, they must match.","schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"practice_id":{"type":"string","description":"Practice the batch belongs to. Required for a company-wide key."},"organization_id":{"type":"string","deprecated":true,"description":"Deprecated alias for practice_id."},"check_ids":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"},"description":"Checks to cancel. Omit to cancel every check in the batch that has not reached the payer."}}},"example":{"practice_id":"demo","organization_id":"demo","check_ids":["demo"]}}}},"responses":{"200":{"description":"What was cancelled, what was left alone, and the batch as it stands now.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"batch_id":{"type":"string","description":"Batch the cancel ran on."},"practice_id":{"type":"string","description":"Practice the batch belongs to."},"cancelled":{"type":"array","items":{"type":"string"},"description":"Checks closed by this call. Nothing was sent to the payer and nothing was billed."},"already_started":{"type":"array","items":{"type":"string"},"description":"Checks a worker holds or that already reached the payer. Not cancelled."},"already_finished":{"type":"array","items":{"type":"string"},"description":"Checks that were already done, failed or cancelled."},"not_cancellable":{"type":"array","items":{"type":"string"},"description":"Checks Veraxus is holding for a billing review. Not cancelled."},"not_in_batch":{"type":"array","items":{"type":"string"},"description":"Requested ids that are not checks of this batch."},"batch":{"$ref":"#/components/schemas/EligibilityBatchResponse"}},"required":["batch_id","practice_id","cancelled","already_started","already_finished","not_cancellable","not_in_batch","batch"]},"example":{"batch_id":"demo","practice_id":"demo","cancelled":["demo"],"already_started":["demo"],"already_finished":["demo"],"not_cancellable":["demo"],"not_in_batch":["demo"],"batch":{"batch_id":"demo","practice_id":"demo","organization_id":"demo","created_at":"2026-09-16T12:00:00.000Z","expires_at":"2026-09-16T12:00:00.000Z","status":"pending","submitted_count":0,"accepted_count":0,"rejected_count":0,"active_limit_per_practice":50,"summary":{"pending":0,"usable":0,"failed":0,"rejected":0},"results":[{"status":"pending","usable":false,"why":"live","error":"demo","error_code":"demo","retry":{"ok":false},"billing":{"unit":"eligibility_check","cents":0,"currency":"USD","waived":false},"index":0,"client_reference_id":"demo","check_id":"demo"}],"links":{"self":"demo"}}}}}},"400":{"description":"Conflicting or missing practice scope, or check_ids is not a non-empty list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Batch not found in the authenticated practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected Veraxus error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/eligibility/batch":{"post":{"tags":["Eligibility"],"summary":"Submit an eligibility batch (deprecated v1 adapter)","operationId":"createEligibilityBatchLegacy","deprecated":true,"description":"Compatibility adapter for existing integrations. New integrations use POST /eligibility/batches with Idempotency-Key and client_reference_id, then poll the batch resource.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligibilityBatchLegacyRequest"},"example":{"checks":[{"payer_id":"demo","member_id":"demo","first_name":"demo","last_name":"demo","date_of_birth":"1980-01-15"}]}}}},"responses":{"200":{"description":"Batch is complete.","headers":{"Location":{"description":"Canonical URL of the durable batch resource.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}},"Idempotency-Replayed":{"description":"true when this response replays an existing operation-scoped receipt.","schema":{"type":"boolean"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligibilityBatchResponse"},"example":{"batch_id":"demo","practice_id":"demo","organization_id":"demo","created_at":"2026-09-16T12:00:00.000Z","expires_at":"2026-09-16T12:00:00.000Z","status":"pending","submitted_count":0,"accepted_count":0,"rejected_count":0,"active_limit_per_practice":50,"summary":{"pending":0,"usable":0,"failed":0,"rejected":0},"results":[{"status":"pending","usable":false,"why":"live","error":"demo","error_code":"demo","retry":{"ok":false},"billing":{"unit":"eligibility_check","cents":0,"currency":"USD","waived":false},"index":0,"client_reference_id":"demo","check_id":"demo"}],"links":{"self":"demo"}}}}},"202":{"description":"Batch accepted and pending.","headers":{"Location":{"description":"Canonical URL of the durable batch resource.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}},"Idempotency-Replayed":{"description":"true when this response replays an existing operation-scoped receipt.","schema":{"type":"boolean"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligibilityBatchResponse"},"example":{"batch_id":"demo","practice_id":"demo","organization_id":"demo","created_at":"2026-09-16T12:00:00.000Z","expires_at":"2026-09-16T12:00:00.000Z","status":"pending","submitted_count":0,"accepted_count":0,"rejected_count":0,"active_limit_per_practice":50,"summary":{"pending":0,"usable":0,"failed":0,"rejected":0},"results":[{"status":"pending","usable":false,"why":"live","error":"demo","error_code":"demo","retry":{"ok":false},"billing":{"unit":"eligibility_check","cents":0,"currency":"USD","waived":false},"index":0,"client_reference_id":"demo","check_id":"demo"}],"links":{"self":"demo"}}}}},"400":{"description":"Invalid batch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency key conflicts with another batch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body exceeds the published batch limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Practice bulk capacity exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected Veraxus error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"$ref":"#/components/responses/Error502"},"503":{"description":"Batch dispatch is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credentials":{"get":{"tags":["Portal logins"],"summary":"List vaulted logins with secrets redacted","operationId":"listCredentials","parameters":[{"name":"organization_id","in":"query","required":false,"description":"Practice id from GET /organizations. Portal-login and credential routes use this query name (not practice_id). Required for a company-wide key; a practice-bound key may omit it.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Practice payer-login inventory with all secrets redacted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialsListResponse"},"example":{"organization_id":"demo","credentials":[{"payer_id":"sandbox_mfa","name":"Sandbox MFA","username":"sandbox.user","npi":null,"has_secret":true,"has_totp_seed":false,"shares_with":[],"updated_at":"2026-09-16T12:00:00.000Z","credential_revision":1,"last_client_reference":null}]}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}},"description":"List vaulted logins with secrets redacted"},"put":{"tags":["Portal logins"],"summary":"Store a practice's payer credentials with approved HITL","operationId":"storeCredentials","description":"Veraxus-native credential storage. Requires an approved HITL grant, or portal_login_mutation plus attestation. A bearer token without those is 403 hitl_required. pk_sandbox_ certification keys cannot PUT /credentials. Capability-admitted Verora delegated clients use the separate composite POST /portal/onboard operation and never follow that operation with POST /portal/connect. sandbox_mfa is the restricted non-customer MFA certification payer. Does not Connect or mint; call POST /portal/connect next. Same-username password and authenticator-seed updates succeed. Replacing a saved username on a row that already has a password is 409 portal_login_identity_change_not_supported (managed account change; do not reconnect). 400 invalid_totp_seed when totp_seed is not valid base32. 503 vault_unreadable when the vault cannot be written. 200 includes credential_revision (monotonic, +1 per credential-material write including identical retries) and credential_updated_at (the vault row's updated_at as written). GET lists credential_revision and last_client_reference from the canonical stored row.","parameters":[{"$ref":"#/components/parameters/HitlGrant"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payer_id","portal_username","portal_password"],"properties":{"organization_id":{"type":"string","description":"Practice from GET /organizations. Required for a company-wide key; a practice-bound key may omit it."},"payer_id":{"type":"string","description":"vault_payer_id / mailbox id from GET /payers. Shared logins (Keyspring, Dental HUB, Provider Tools) store once."},"portal_username":{"type":"string","description":"Portal username. username is accepted as an alias."},"portal_password":{"type":"string","writeOnly":true,"description":"Portal password. Vaulted. Never returned. password is accepted as an alias."},"totp_seed":{"type":"string","writeOnly":true,"description":"Optional authenticator-app seed (base32). Vaulted like the password. Never returned."},"npi":{"type":"string","description":"Optional NPI stored on this login."},"portal_url":{"type":"string","description":"Cloud PMS vendors only (oryx, curve): the practice's own address on that vendor, like https://yourpractice.myoryx.com or https://yourpractice.curvehero.com. Omit to keep the saved address. portalUrl is accepted as an alias. 400 invalid_request for non-PMS payers, an invalid address, or another vendor's address."},"hitl_grant":{"type":"string","description":"Approved HITL grant id (htg_…). Alias of X-Veraxus-Hitl-Grant when the header is absent."},"client_reference":{"type":"string","maxLength":128,"description":"Opaque vendor correlation id. Echoed on the 200 body."},"attestation":{"$ref":"#/components/schemas/VendorAttestation"}}},"example":{"payer_id":"sandbox_mfa","portal_username":"sandbox.user","portal_password":"sandbox-password","hitl_grant":"htg_approved_demo_01","attestation":{"actor_user_id":"vendor_user_demo","consent_session_id":"consent_demo_01","consented_at":"2026-09-16T12:00:00.000Z"}}}}},"responses":{"200":{"description":"Credentials were encrypted and stored for the practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialsStoreResponse"},"example":{"organization_id":"demo","payer_id":"sandbox_mfa","has_secret":true,"stored":true,"username":"sandbox.user","npi":null,"has_totp_seed":false,"shares_with":[],"client_reference":null,"credential_revision":1,"credential_updated_at":"2026-09-16T12:00:00.000Z"}}}},"400":{"description":"Invalid payer or credential payload (unknown_payer, payer_not_licensed, invalid_totp_seed, invalid_client_reference).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"BAA, practice access, or HITL approval is required. A bearer token alone cannot store credentials; retry with an approved hitl_grant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"portal_login_identity_change_not_supported: a password is already saved for a different username. Password rotation for the existing username works. Changing the portal account requires a managed account change. Do not reconnect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"description":"Vault cannot be written (vault_unreadable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Portal logins"],"summary":"Deprecated credential-only deletion","operationId":"deleteCredentials","deprecated":true,"description":"Always fails closed and never releases a worker session. Use POST /portal/revoke with delegated human consent only when the exact caller/organization/payer reports revocation_enabled=true and a null block code. The UCCI pilot is released for tn_verora / org_4ab6ddda / united_concordia; every other office and payer stays blocked, and uncertified scopes remain blocked with portal_login_revoke_recert_required.","responses":{"204":{"description":"Not returned. Credential-only deletion is disabled and always fails closed with 409."},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Credential-only deletion is disabled; use delegated portal revoke.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/portal/guide":{"get":{"tags":["Portal logins"],"summary":"Read the portal-login guide","description":"Two separate workflows: the native Veraxus four-step HITL sequence and capability-admitted Verora composite onboarding. On an exact organization-scoped payer row, licensed non-UCCI closed-allowlist Connect payers and DNoA can publish onboarding_enabled=true; United Concordia remains limited to its separately released exact tn_verora/org_4ab6ddda scope. One signed onboard stores credentials and invokes the canonical Connect engine internally; it is never followed by native Connect. Revocation is separately gated and narrower than onboarding. Exact delegated-operation polling and operation-bound MFA submission currently use REST, not the incomplete MCP input schemas. This is the REST twin of MCP portal_login_guide and https://veraxus.ai/docs#portal-login.","operationId":"getPortalLoginGuide","security":[],"responses":{"200":{"description":"Portal login guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalLoginGuideResponse"},"example":{"title":"demo","docs_url":"demo","person_required":false,"billed":false,"sequence":["demo"],"verora_delegated":{"audience":"Verora embedded only","payer_ids":["dnoa"],"required_scope":"portal_login_mutation","caller_discovery":"GET /v1/me → key.caller_id","caller_claim":"caller_id","status_reads_are_pure":true,"onboarding_rest":"POST /v1/portal/onboard","onboarding_mcp":"onboard_portal_login","composite_store_and_connect":true,"follow_up_connect":false,"revocation_rest":"POST /v1/portal/revoke","revocation_mcp":"revoke_portal_login","sandbox_organization_required":true,"sandbox_block_code":"portal_login_sandbox_org_required","capability_fields":["demo"],"onboarding_block_code":"portal_login_recert_required","revocation_block_code":"portal_login_revoke_recert_required"},"markdown":"demo"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/portal/onboard":{"post":{"tags":["Portal logins"],"summary":"Store and connect a portal login with delegated human consent","description":"Verora composite onboarding requires portal_login_mutation and onboarding_enabled=true on the exact organization-scoped payer row. Licensed non-UCCI payers on the closed Connect allowlist are admitted through this one operation; it stores credentials and invokes the canonical Connect engine internally. United Concordia remains limited to its separately released exact tn_verora/org_4ab6ddda scope. DNoA is the password-per-check custody path. sandbox_mfa makes no external portal request and is restricted to the configured non-customer organization. Call GET /me and bind its exact server-derived key.caller_id into a short-lived, one-time RS256 assertion; caller_id is not a request-body field. The assertion authorizes one composite store-and-login operation without creating or auto-approving a generic HITL grant. Never follow it with POST /portal/connect. Bind issuer, audience, tenant, practice, payer, caller, actor, consent session, action=portal_login_onboard, operation id, nonce, iat/exp, and jti. Secrets never enter the assertion or receipt. Recover ambiguous responses through exact-operation REST polling, without automatically rereading or reposting the password. DNoA ready proves custody only; admitted UCCI ready plus operation_authenticated_at proves a historical authentication event, not indefinitely current authentication.","operationId":"onboardPortalLogin","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalOnboardRequest"},"example":{"organization_id":"demo","payer_id":"demo","portal_username":"demo","portal_password":"demo","operation_id":"demo_value_0001x","request_nonce":"demo_value_0001xxxxxxx","actor_user_id":"demo","consent_session_id":"demo","delegated_consent":"demo"}}}},"responses":{"200":{"description":"Ready or waiting for an exact MFA code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalOnboardResponse"},"example":{"operation_id":"demo","organization_id":"demo","payer_id":"demo","status":"received","ok":false,"stored":true,"message":"demo","confirmation_pending":false,"challenges":[{"challenge_id":"demo","challenge_generation":1}],"replayed":false}}}},"202":{"description":"Durable operation is in progress or confirmation_pending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalOnboardResponse"},"example":{"operation_id":"demo","organization_id":"demo","payer_id":"demo","status":"received","ok":false,"stored":true,"message":"demo","confirmation_pending":false,"challenges":[{"challenge_id":"demo","challenge_generation":1}],"replayed":false}}}},"400":{"description":"A durably admitted onboarding operation reached failed. The response is the exact bound receipt with a top-level error_code. Pre-admission validation failures use the standard error envelope.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PortalOnboardResponse"},{"$ref":"#/components/schemas/Error"}]}}}},"401":{"description":"Missing, expired, or invalid API credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"portal_login_mutation scope, BAA, practice access, or delegated consent verification is required. Delegated consent failures include error.reason: unknown_kid, bad_signature, header_invalid, claims_invalid, iss_aud_mismatch, action_mismatch, request_mismatch, expired, not_yet_valid, sandbox_fixture.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"operation_id, jti, request fingerprint, or MFA binding conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"description":"A durably admitted onboarding operation reached outage. The response is the exact bound receipt with a top-level error_code. Pre-admission verifier or vault failures use the standard error envelope.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PortalOnboardResponse"},{"$ref":"#/components/schemas/Error"}]}}}}}}},"/portal/revoke":{"post":{"tags":["Portal logins"],"summary":"Revoke a portal login with delegated human consent","description":"Delegated revocation requires portal_login_mutation verified through GET /v1/me key.scopes, separately from revocation_enabled=true with a null block code for the exact tenant/organization/payer. Baseline DNoA and restricted non-customer sandbox_mfa are separate from the tn_verora / org_4ab6ddda / united_concordia pilot, which is released for that exact tenant, organization, and payer; every other office and payer stays blocked, and the live per-org signal is onboarding_enabled / onboarding_block_code in GET /v1/payers. For sandbox_mfa, a missing configured non-customer organization or a foreign organization returns HTTP 503 portal_login_sandbox_org_required before consent verification or mutation admission. Use a separately authorized revoke operation; bind server-derived key.caller_id from GET /me into the RS256 assertion with action=portal_login_revoke and the distinct revoke audience. For admitted UCCI, success requires authoritative current session-artifact invalidation followed by committed scoped vault deletion. This does not attest payer-side logout, backups, or non-current storage versions. Historical deletion flags do not prove no newer login exists. Exact polling never performs cleanup; only an explicitly authorized retry of the original revoke operation may resume it. Secrets and session material are never returned.","operationId":"revokePortalLogin","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalRevokeRequest"},"example":{"organization_id":"demo","payer_id":"demo","operation_id":"demo_value_0001x","request_nonce":"demo_value_0001xxxxxxx","actor_user_id":"demo","consent_session_id":"demo","delegated_consent":"demo"}}}},"responses":{"200":{"description":"Session and credentials were durably revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalRevokeResponse"},"example":{"operation_id":"demo","organization_id":"demo","payer_id":"demo","status":"received","ok":false,"revoked":false,"credentials_deleted":false,"sessions_invalidated":false,"shares_with":["demo"],"message":"demo","error_code":"demo","replayed":false}}}},"202":{"description":"The exact durable revocation is received or in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalRevokeResponse"},"example":{"operation_id":"demo","organization_id":"demo","payer_id":"demo","status":"received","ok":false,"revoked":false,"credentials_deleted":false,"sessions_invalidated":false,"shares_with":["demo"],"message":"demo","error_code":"demo","replayed":false}}}},"400":{"description":"Revocation failed or the payload is invalid.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PortalRevokeResponse"},{"$ref":"#/components/schemas/Error"}]}}}},"401":{"description":"Missing, expired, or invalid API credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"portal_login_mutation scope, BAA, practice access, or delegated consent verification is required. Delegated consent failures include error.reason: unknown_kid, bad_signature, header_invalid, claims_invalid, iss_aud_mismatch, action_mismatch, request_mismatch, expired, not_yet_valid, sandbox_fixture.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Operation identity, consent replay, or active operation conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"description":"A durably admitted delegated revoke reached outage, or a payer without delegated cleanup certification was rejected before admission with portal_login_revoke_recert_required. sandbox_mfa is also rejected before admission with portal_login_sandbox_org_required unless organization_id is the configured non-customer sandbox. No worker release is attempted by this launch contract.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PortalRevokeResponse"},{"$ref":"#/components/schemas/Error"}]}}}}}}},"/portal/connect":{"post":{"tags":["Portal logins"],"summary":"Connect with previously vaulted credentials","description":"MFA-first: call GET /portal/mfa (list_portal_mfa_challenges) then GET /portal-logins before this. Do not Connect when a hold is parked (needs_code / confirmation_pending) or when status is ready. Connect exactly once for not_connected, or expired after the serving authority confirms login_bounce. Requires an approved HITL grant or portal_login_mutation plus attestation. pk_sandbox_ certification keys cannot POST /portal/connect. Posts the vaulted password once; the body must not include the password. Returns 200 ready or needs_code, 202 confirmation_pending, 400 credentials_required / credentials_invalid / unsupported_connect_payer, 423 locked, 429 connect_budget_exhausted, 503 portal_outage / quarantined / vault_error. Echoes client_reference.","operationId":"connectPortalLogin","parameters":[{"$ref":"#/components/parameters/HitlGrant"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":16,"maxLength":128},"description":"One Connect per key. 24h receipt TTL. Replay with the same body returns the stored receipt with replayed:true. Different body is 409 idempotency_mismatch. In-progress is 409 attempt_in_progress."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payer_id"],"properties":{"organization_id":{"type":"string","description":"Practice from GET /organizations. Required for a company-wide key; a practice-bound key may omit it."},"payer_id":{"type":"string","description":"Including sandbox_mfa and sandbox_push for certification."},"hitl_grant":{"type":"string","description":"Approved HITL grant id (htg_…). Alias of X-Veraxus-Hitl-Grant when the header is absent."},"idempotency_key":{"type":"string","minLength":16,"maxLength":128,"description":"Alias of Idempotency-Key when the header is absent."},"client_reference":{"type":"string","maxLength":128,"description":"Opaque vendor correlation id. Echoed on the receipt."},"attestation":{"$ref":"#/components/schemas/VendorAttestation"}}},"example":{"payer_id":"sandbox_mfa","hitl_grant":"htg_approved_demo_01","attestation":{"actor_user_id":"vendor_user_demo","consent_session_id":"consent_demo_01","consented_at":"2026-09-16T12:00:00.000Z"}}}}},"responses":{"200":{"description":"ready or needs_code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalConnectResponse"},"example":{"ok":true,"status":"needs_code","payer_id":"sandbox_mfa","message":"Enter the one-time code.","complete_with":"complete_portal_mfa","observe_with":null,"confirmation_pending":false,"challenges":[],"generation":1,"shares_with":[],"client_reference":null}}}},"202":{"description":"confirmation_pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalConnectResponse"},"example":{"ok":true,"status":"needs_code","payer_id":"sandbox_mfa","message":"Enter the one-time code.","complete_with":"complete_portal_mfa","observe_with":null,"confirmation_pending":false,"challenges":[],"generation":1,"shares_with":[],"client_reference":null}}}},"400":{"description":"Credentials or supported payer required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"BAA, practice access, or HITL approval is required. A bearer token alone cannot connect a portal login; retry with an approved hitl_grant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency-Key mismatch or an attempt is already in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"Portal account is locked (status=locked). Do not retry Connect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"connect_budget_exhausted: this practice and login mailbox is inside the 10-minute cooldown after a failed sign-in or has reached 6 failed sign-ins per 24h. error.retry_after is seconds; error.next_allowed_at is ISO-8601. Successful fresh sign-ins, accepted needs_code / confirmation_pending holds, and already-ready logins consume no budget. Sandbox certification payers are exempt. PORTAL_CONNECT_BUDGET=0 disables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"description":"Portal worker unavailable or quarantined.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pms/vendors":{"get":{"tags":["Cloud PMS"],"summary":"List cloud PMS vendors","operationId":"listPmsVendors","description":"Cloud practice-management systems Veraxus can operate (oryx, curve). Connect a practice's PMS login with POST /portal/connect and payer_id equal to the vendor id; there is no separate PMS connect route. second_factor is totp_optional when Veraxus computes the code from a saved authenticator key, email_optional when the vendor emails a code that is completed with POST /portal/mfa.","responses":{"200":{"description":"Vendors.","content":{"application/json":{"schema":{"type":"object","required":["vendors"],"properties":{"vendors":{"type":"array","items":{"type":"object","required":["id","name","address_example","second_factor"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"address_example":{"type":"string"},"second_factor":{"type":"string"}}}}}},"example":{"vendors":[{"id":"demo","name":"demo","address_example":"demo","second_factor":"demo"}]}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/pms/connections":{"get":{"tags":["Cloud PMS"],"summary":"Read cloud PMS connection status","operationId":"listPmsConnections","description":"Status of the practice's saved login per licensed PMS vendor, from that vendor's own status reader. Never signs in. Connect with POST /portal/connect and payer_id equal to the vendor id.","parameters":[{"name":"organization_id","in":"query","required":false,"schema":{"type":"string"},"description":"Practice from GET /organizations. Required for a company-wide key; a practice-bound key may omit it."}],"responses":{"200":{"description":"Connections.","content":{"application/json":{"schema":{"type":"object","required":["connections"],"properties":{"connections":{"type":"array","items":{"type":"object","required":["vendor","status","realm","last_authenticated_at","last_served_at","last_failure_at","checked_at"],"properties":{"vendor":{"type":"string"},"status":{"type":"string","enum":["ready","not_connected","needs_code","credentials_invalid","quarantined","portal_outage","expired"]},"realm":{"type":["string","null"]},"last_authenticated_at":{"type":["string","null"],"format":"date-time","description":"Newest authenticated identity probe or keepalive on the saved login. Null when none is recorded."},"last_served_at":{"type":["string","null"],"format":"date-time","description":"When an operation last completed on the saved login. Null when none is recorded."},"last_failure_at":{"type":["string","null"],"format":"date-time","description":"Newest recorded probe, keepalive or session failure. Null when none is recorded."},"checked_at":{"type":"string","format":"date-time","description":"When this response was built, not evidence time."}}}}}},"example":{"connections":[{"vendor":"demo","status":"ready","realm":"demo","last_authenticated_at":"2026-09-16T12:00:00.000Z","last_served_at":"2026-09-16T12:00:00.000Z","last_failure_at":"2026-09-16T12:00:00.000Z","checked_at":"2026-09-16T12:00:00.000Z"}]}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"BAA, practice access, or eligibility scope is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/pms/{vendor}/operations":{"get":{"tags":["Cloud PMS"],"summary":"List cloud PMS operations","operationId":"listPmsOperations","description":"Operations a PMS vendor exposes, each marked read or write.","parameters":[{"name":"vendor","in":"path","required":true,"schema":{"type":"string","enum":["oryx","curve"]},"description":"Cloud PMS vendor id from GET /pms/vendors."}],"responses":{"200":{"description":"Operations.","content":{"application/json":{"schema":{"type":"object","required":["operations"],"properties":{"operations":{"type":"array","items":{"type":"object","required":["name","kind","summary","input"],"properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["read","write"]},"provenance":{"type":"string"},"module":{"type":"string"},"summary":{"type":"string"},"input":{"type":"object","additionalProperties":true},"input_schema":{"type":"object","additionalProperties":true,"description":"JSON Schema 2020-12 for a reviewed operation input, when available. Validate the exact operation's input against this schema."},"calls":{"type":"array","items":{"type":"string"}}}}}}},"example":{"operations":[{"name":"demo","kind":"read","summary":"demo","input":{}}]}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"unknown_pms_vendor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/pms/{vendor}/execute/{operation}":{"post":{"tags":["Cloud PMS"],"summary":"Execute a cloud PMS operation","operationId":"executePmsOperation","x-oryx-operation-inputs":{"getClaimDraftData":{"$ref":"#/components/schemas/OryxClaimDraftDataInput"},"createClaim":{"$ref":"#/components/schemas/OryxCreateClaimInput"},"updateClaim":{"$ref":"#/components/schemas/OryxUpdateClaimInput"},"updateClaimNarrative":{"$ref":"#/components/schemas/OryxClaimNarrativeInput"},"validateClaims":{"$ref":"#/components/schemas/OryxValidateClaimsInput"},"submitClaims":{"$ref":"#/components/schemas/OryxSubmitClaimsInput"},"submitClaimToClearinghouse":{"$ref":"#/components/schemas/OryxSubmitClaimToClearinghouseInput"},"submitClaimsToClearinghouse":{"$ref":"#/components/schemas/OryxSubmitClaimsToClearinghouseInput"},"resubmitClaim":{"$ref":"#/components/schemas/OryxResubmitClaimInput"},"saveClaimAttachment":{"$ref":"#/components/schemas/OryxSaveClaimAttachmentInput"},"saveAndSubmitClaimAttachment":{"$ref":"#/components/schemas/OryxSaveAndSubmitClaimAttachmentInput"},"submitClaimAttachment":{"$ref":"#/components/schemas/OryxSubmitClaimAttachmentInput"},"submitClaimAttachmentBatch":{"$ref":"#/components/schemas/OryxSubmitClaimAttachmentBatchInput"},"uploadPatientDocument":{"$ref":"#/components/schemas/OryxUploadPatientDocumentInput"}},"description":"Reads replay the practice's saved login and never sign in; 409 not_connected means Connect first (POST /portal/connect, payer_id equal to the vendor id). projected is null for operations whose shape is not yet captured: use raw. Writes are exactly-once and need an approved hitl_grant, or portal_login_mutation plus attestation, exactly like POST /portal/connect; they are never retried. 502 unknown_outcome means the result is unknown: reconcile with a read before acting again.","parameters":[{"name":"vendor","in":"path","required":true,"schema":{"type":"string","enum":["oryx","curve"]},"description":"Cloud PMS vendor id from GET /pms/vendors."},{"name":"operation","in":"path","required":true,"schema":{"type":"string"},"description":"Operation name from GET /pms/{vendor}/operations."},{"$ref":"#/components/parameters/HitlGrant"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":16,"maxLength":128},"description":"Writes only. One execution per key; replay returns the stored receipt."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"organization_id":{"type":"string","description":"Practice from GET /organizations."},"input":{"description":"Use the schema linked by x-oryx-operation-inputs for the selected Oryx claim operation. Other PMS operations use their live catalog input fields. Verora drafts enter Oryx through getClaimDraftData then createClaim; uploadPatientDocument uploads file bytes, saveClaimAttachment links their native IDs, and claim submission and attachment submission have separate receipts. This is a separate workflow from POST /claims (payer-portal drafts).","anyOf":[{"$ref":"#/components/schemas/OryxClaimDraftDataInput"},{"$ref":"#/components/schemas/OryxCreateClaimInput"},{"$ref":"#/components/schemas/OryxUpdateClaimInput"},{"$ref":"#/components/schemas/OryxClaimNarrativeInput"},{"$ref":"#/components/schemas/OryxValidateClaimsInput"},{"$ref":"#/components/schemas/OryxSubmitClaimsInput"},{"$ref":"#/components/schemas/OryxSubmitClaimToClearinghouseInput"},{"$ref":"#/components/schemas/OryxSubmitClaimsToClearinghouseInput"},{"$ref":"#/components/schemas/OryxResubmitClaimInput"},{"$ref":"#/components/schemas/OryxSaveClaimAttachmentInput"},{"$ref":"#/components/schemas/OryxSaveAndSubmitClaimAttachmentInput"},{"$ref":"#/components/schemas/OryxSubmitClaimAttachmentInput"},{"$ref":"#/components/schemas/OryxSubmitClaimAttachmentBatchInput"},{"$ref":"#/components/schemas/OryxUploadPatientDocumentInput"},{"type":"object","additionalProperties":true,"description":"Input for other catalog operations."}]},"idempotency_key":{"type":"string","minLength":16,"maxLength":128},"hitl_grant":{"type":"string"},"client_reference":{"type":"string","maxLength":128},"attestation":{"$ref":"#/components/schemas/VendorAttestation"}}},"example":{"organization_id":"demo","input":{"patientId":"demo_value_0001"},"idempotency_key":"demoxxxxxxxxxxxx","hitl_grant":"demo","client_reference":"demo","attestation":{"actor_user_id":"demo","consent_session_id":"demo","consented_at":"demo"}}}}},"responses":{"200":{"description":"Operation result.","content":{"application/json":{"schema":{"type":"object","required":["status","operation","kind","http_status","hops","realm"],"properties":{"status":{"type":"string","enum":["ok"]},"operation":{"type":"string"},"kind":{"type":"string","enum":["read","write"]},"provenance":{"type":"string"},"projected":{"description":"Null when the operation's shape is not yet captured."},"raw":{},"http_status":{"type":"integer"},"hops":{"type":"array","items":{"type":"object","additionalProperties":true}},"realm":{"type":["string","null"]},"client_reference":{"type":["string","null"]}}},"example":{"status":"ok","operation":"demo","kind":"read","http_status":1,"hops":[{}],"realm":"demo"}}}},"400":{"description":"invalid_input, payer_not_licensed, or attestation_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"BAA, scope, or HITL approval is required for a write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"unknown_pms_vendor or unknown_operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"not_connected (error.reason: no_keep, login_bounce, realm_missing), an idempotency conflict, or pms_write_refused: a guarded write sent nothing (error.reason not_ready, not_electronic, changed, already_sent, filter_unconfirmed, send_unresolved).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"pms_vendor_rejected: Oryx rejected the one write, including HTTP 200 with success:false. Inspect raw and reconcile before changing the approved intent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"description":"unknown_outcome: a write's result is unknown. Never retried; reconcile with a read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"pms_unavailable (error.reason: soft_block, probe_failed, quarantined).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pms/{vendor}/claims/status":{"post":{"tags":["Cloud PMS"],"summary":"Read claim status from the clearinghouse (batch)","operationId":"readPmsClaimStatuses","description":"Reads what the practice's clearinghouse (Vyne, for an Oryx practice whose clearinghouse code is NEA) reported back into the PMS for each claim. Send each claim with its patient_id (and service_date when known). The PMS's status check gives oryx_status_text for the claim id; the claim's own row in the PMS's sent claims gives the PMS status, sent date, clearinghouse claim number, payer reference number, the clearinghouse status message, the status history and whether an ERA arrived. Without patient_id only the status text is read. The PMS has no live status inquiry to the clearinghouse, so this returns the latest answer the PMS holds, read now. Replays the practice's saved PMS login and never signs in. Each call reads the clearinghouse code once and 1 status check per claim; with patient ids it also reads the PMS date-filter setting once and 1 to 3 pages of sent claims per patient. Keep one call in flight per practice and stay under about 20 PMS calls a minute; for a practice-wide sweep use POST /pms/oryx/execute/listSentClaims.","parameters":[{"name":"vendor","in":"path","required":true,"schema":{"type":"string","enum":["oryx","curve"]},"description":"Cloud PMS vendor id from GET /pms/vendors. Claim status is available for oryx."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["organization_id"],"description":"Send claims (with patient_id for the clearinghouse answers) or claim_ids (status text only), not both.","properties":{"organization_id":{"type":"string","description":"Practice from GET /organizations."},"claims":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"object","additionalProperties":false,"required":["claim_id"],"properties":{"claim_id":{"type":"string","pattern":"^[1-9][0-9]{0,17}$","example":"104857","description":"Native PMS claim id."},"patient_id":{"type":"string","pattern":"^[1-9][0-9]{0,17}$","example":"2048","description":"The claim's native PMS patient id. Without it only the status text is read."},"service_date":{"type":"string","format":"date","description":"YYYY-MM-DD. Narrows the search to 30 days either side; without it the 365 days ending today are searched."}}},"description":"1 to 10 claims."},"claim_ids":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","pattern":"^[1-9][0-9]{0,17}$","example":"104857"},"description":"1 to 10 native PMS claim ids for the status text alone (sent is null)."},"client_reference":{"type":"string","maxLength":128}}},"example":{"organization_id":"demo"}}}},"responses":{"200":{"description":"Claim statuses, in request order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PmsClaimStatusResponse"},"example":{"status":"ok","vendor":"oryx","realm":"demo","checked_at":"demo","claims":[{"claim_id":"demo","found":false,"oryx_status_text":"demo","note":"demo","sent":false}],"hops":[{}]}}}},"400":{"description":"invalid_input (1 to 10 claims with numeric claim_id and patient_id, YYYY-MM-DD service_date; claims or claim_ids, not both) or payer_not_licensed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"BAA or eligibility scope is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"unknown_pms_vendor, or unknown_operation when the vendor has no claim status read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"not_connected (error.reason: no_keep, login_bounce, realm_missing): Connect the practice's PMS login first. Do not retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"description":"pms_read_failed (error.reason, http_status, hops). Do not retry unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"pms_unavailable (error.reason: soft_block, probe_failed, quarantined). The login is kept; retry later with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pms/{vendor}/claims/submit":{"post":{"tags":["Cloud PMS"],"summary":"Send approved claims through the clearinghouse (batch)","operationId":"submitPmsClaims","description":"Sends 1 to 25 approved claims through the practice's clearinghouse (Vyne, for an Oryx practice whose clearinghouse code is NEA) in one native PMS POST, as the office's claim-queue Send does, and records each as sent in the PMS. Reads first: the practice's unsent queue for the last 365 days (up to 10 pages). A claim passes only when it is there as readyForSubmission, is an electronic claim, belongs to patient_id when given, and its lines still hash to expected_line_fingerprint (the line_fingerprint from listUnsentClaims at approval) and its total to expected_total. on_guard_failure abort (default) sends nothing when any claim fails; skip sends the passing claims. Veraxus sends a claim once whatever the Idempotency-Key: a claim it already sent, or whose send is in flight or unknown, answers already_sent or send_unresolved. The one POST is never retried. Readback: the unsent queue once more and the PMS's status check per sent claim; the clearinghouse claim number appears in POST /pms/{vendor}/claims/status once the PMS's queue hands the claim to the clearinghouse. Needs the practice's PMS write admission, an Idempotency-Key and an approved hitl_grant or a vendor attestation. Same operation: POST /pms/oryx/execute/submitClaimsToClearinghouse.","parameters":[{"name":"vendor","in":"path","required":true,"schema":{"type":"string","enum":["oryx","curve"]},"description":"Cloud PMS vendor id from GET /pms/vendors. Claim submission is available for oryx."},{"$ref":"#/components/parameters/HitlGrant"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":16,"maxLength":128},"description":"Required. One send per key; a replay returns the stored receipt."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["organization_id","claims"],"properties":{"organization_id":{"type":"string","description":"Practice from GET /organizations."},"claims":{"type":"array","minItems":1,"maxItems":25,"description":"1 to 25 distinct approved claims.","items":{"type":"object","additionalProperties":false,"required":["claim_id","expected_line_fingerprint"],"properties":{"claim_id":{"type":"string","pattern":"^[1-9][0-9]{0,17}$","example":"104857","description":"Native PMS claim id (the unsent row's remote_id)."},"patient_id":{"type":"string","pattern":"^[1-9][0-9]{0,17}$","example":"2048","description":"Optional; the unsent row must belong to this patient."},"expected_line_fingerprint":{"type":"string","pattern":"^[0-9a-f]{64}$","example":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","description":"line_fingerprint from listUnsentClaims when the send was approved."},"expected_total":{"type":"number","minimum":0,"example":412.5,"description":"Optional approved total; must match to the cent."}}}},"on_guard_failure":{"type":"string","enum":["abort","skip"],"default":"abort"},"idempotency_key":{"type":"string","minLength":16,"maxLength":128,"description":"Body alternative to the Idempotency-Key header."},"hitl_grant":{"type":"string"},"attestation":{"$ref":"#/components/schemas/VendorAttestation"},"client_reference":{"type":"string","maxLength":128}}},"example":{"organization_id":"demo","claims":[{"claim_id":"104857","expected_line_fingerprint":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"}]}}}},"responses":{"200":{"description":"Per-claim results, in request order (status sent, partial or refused).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PmsClaimSubmitResponse"},"example":{"status":"sent","vendor":"oryx","sent_count":1,"refused_count":1,"unknown_outcome":false,"claims":[{"claim_id":"104857","result":"submitted"}],"hops":[{}]}}}},"400":{"description":"invalid_input (1 to 25 distinct claims, numeric claim_id, 64-hex expected_line_fingerprint, on_guard_failure abort or skip), invalid_request (Idempotency-Key required) or payer_not_licensed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"BAA, scope, or HITL approval is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"unknown_pms_vendor, or unknown_operation when the vendor has no claim submission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"not_connected (error.reason: no_keep, login_bounce, realm_missing), or an idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"pms_vendor_rejected: the PMS refused every claim in the send; nothing was sent. Per-claim results are included.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PmsClaimSubmitResponse"},{"$ref":"#/components/schemas/Error"}]}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"description":"unknown_outcome: the send left and its result is unknown. The claims marked unknown_outcome stay held; reconcile with claims/status, never resend. Also pms_read_failed when a guard read failed (nothing sent).","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PmsClaimSubmitResponse"},{"$ref":"#/components/schemas/Error"}]}}}},"503":{"description":"pms_unavailable (error.reason: soft_block, probe_failed, quarantined). Nothing was sent; retry later with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pms/{vendor}/claims/{claim_id}/status":{"get":{"tags":["Cloud PMS"],"summary":"Read one claim's status from the clearinghouse","operationId":"readPmsClaimStatus","description":"Same read as POST /pms/{vendor}/claims/status for one claim; pass patient_id (and service_date when known) as query parameters. A claim the PMS does not know answers 200 with found false.","parameters":[{"name":"vendor","in":"path","required":true,"schema":{"type":"string","enum":["oryx","curve"]},"description":"Cloud PMS vendor id from GET /pms/vendors. Claim status is available for oryx."},{"name":"claim_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[1-9][0-9]{0,17}$"},"example":"104857","description":"Native PMS claim id."},{"name":"organization_id","in":"query","required":true,"schema":{"type":"string"},"description":"Practice from GET /organizations."},{"name":"patient_id","in":"query","required":false,"schema":{"type":"string","pattern":"^[1-9][0-9]{0,17}$"},"example":"2048","description":"The claim's native PMS patient id. Without it only the status text is read."},{"name":"service_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"YYYY-MM-DD. Narrows the search to 30 days either side."},{"name":"client_reference","in":"query","required":false,"schema":{"type":"string","maxLength":128}}],"responses":{"200":{"description":"The claim's status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PmsClaimStatusResponse"},"example":{"status":"ok","vendor":"oryx","realm":"demo","checked_at":"demo","claims":[{"claim_id":"demo","found":false,"oryx_status_text":"demo","note":"demo","sent":false}],"hops":[{}]}}}},"400":{"description":"invalid_input (1 to 10 claims with numeric claim_id and patient_id, YYYY-MM-DD service_date; claims or claim_ids, not both) or payer_not_licensed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"BAA or eligibility scope is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"unknown_pms_vendor, or unknown_operation when the vendor has no claim status read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"not_connected (error.reason: no_keep, login_bounce, realm_missing): Connect the practice's PMS login first. Do not retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"description":"pms_read_failed (error.reason, http_status, hops). Do not retry unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"pms_unavailable (error.reason: soft_block, probe_failed, quarantined). The login is kept; retry later with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/portal-mfa":{"get":{"tags":["Portal logins"],"summary":"Deprecated alias for GET /portal/mfa","deprecated":true,"operationId":"legacyListPortalMfaChallenges","security":[],"description":"Permanent redirect to GET /portal/mfa. Sunset: 2026-10-01. Every method on this path 308s before authentication; follow Location to the canonical route for BAA and key checks.","responses":{"308":{"description":"Permanent redirect to GET /portal/mfa. No body. Authentication is not evaluated on this alias.","headers":{"Location":{"schema":{"type":"string"}},"Sunset":{"schema":{"type":"string"}},"Deprecation":{"schema":{"type":"string"}}}}}},"post":{"tags":["Portal logins"],"summary":"Deprecated alias for POST /portal/mfa","deprecated":true,"operationId":"legacyCompletePortalMfa","security":[],"description":"Permanent redirect to POST /portal/mfa. Sunset: 2026-10-01. Every method on this path 308s before authentication; follow Location to the canonical route for HITL, BAA, and key checks.","responses":{"308":{"description":"Permanent redirect to POST /portal/mfa. No body. Authentication is not evaluated on this alias.","headers":{"Location":{"schema":{"type":"string"}},"Sunset":{"schema":{"type":"string"}},"Deprecation":{"schema":{"type":"string"}}}}}}},"/portal/mfa":{"get":{"tags":["Portal logins"],"summary":"List pending portal MFA challenges","description":"First read when resuming sign-in: union of Aetna exact challenges and generic needs_code holds (challenge_id gen:<payer_id>:<generation>). Never returns a code. Call this before Connect on an interrupted run. A pending hold gets the code on that hold.","operationId":"listPortalMfaChallenges","parameters":[{"name":"organization_id","in":"query","required":false,"description":"Practice id from GET /organizations. Portal-login and credential routes use this query name (not practice_id). Required for a company-wide key; a practice-bound key may omit it.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Exact, unexpired challenges for the practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalMfaChallengesResponse"},"example":{"organization_id":"demo","challenges":[{"payer_id":"sandbox_mfa","challenge_id":"gen:sandbox_mfa:1","challenge_generation":1,"type":"email_otp","masked_destination":"t***@example.com","status":"pending","requested_at":"2026-09-16T12:00:00.000Z","expires_at":"2026-09-16T12:00:00.000Z"}]}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"BAA or practice access is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}},"post":{"tags":["Portal logins"],"summary":"Complete or observe a parked MFA challenge","description":"Most standalone payers use payer_id and code. MetLife confirmation_pending is observed with observe_only true and no code; a submitted code is never replayed. Operation-bound delegated MFA uses this REST endpoint because the MCP input lacks attempt_id. It requires portal_login_mutation, the same admitted caller, original onboarding operation_id, organization_id, payer_id, and a fresh attempt_id matching Idempotency-Key. When the onboarding receipt supplies a current needs_code challenge_id and challenge_generation, every payer must return that exact tuple and submit only its code, never credentials. Operationless native MFA cannot consume a delegated hold. There is no delegated MFA renewal/resend endpoint or automatic password remint. Expiry, rejection, outage, or confirmed login bounce does not authorize password replay. Every bound outcome returns the verified operation/organization/payer triple.","operationId":"completePortalMfa","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":16,"maxLength":128},"description":"For operation-bound code submission must byte-equal attempt_id (43 chars). For generic MFA, 16–128 chars; replay returns the stored receipt with replayed:true."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalMfaRequest"},"examples":{"native":{"summary":"Standalone code","description":"Authenticated customer API key, signed BAA, and a licensed connect payer. Body is payer_id and code. A company-wide key also sends organization_id; a practice-bound key may omit it. HITL grant, attestation, and portal_login_mutation are not required. attempt_id is forbidden without operation_id. Extra keys fail for Aetna. Not a pk_sandbox_ certification request.","value":{"payer_id":"sandbox_mfa","code":"123456"}},"delegated":{"summary":"Operation-bound code","description":"portal_login_mutation. Exact organization_id, payer_id, and operation_id are required even for a practice-bound key, plus attempt_id matching Idempotency-Key. organization_id here is synthetic (from GET /organizations). A pk_sandbox_ key may POST /portal/mfa only with that operation binding on the configured sandbox organization.","value":{"organization_id":"org_from_organizations","payer_id":"sandbox_mfa","operation_id":"op_demo_portal_01","challenge_id":"gen:sandbox_mfa:1","challenge_generation":1,"attempt_id":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA","code":"123456"}}}}}},"responses":{"200":{"description":"Challenge completed or observed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalMfaCompleteResponse"},"example":{"status":"ready","ok":true,"message":"Login saved."}}}},"202":{"description":"Challenge confirmation remains pending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalMfaCompleteResponse"},"example":{"status":"ready","ok":true,"message":"Login saved."}}}},"400":{"description":"Invalid, stale, or mismatched challenge payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"For operation-bound MFA, portal_login_mutation is required. BAA and practice access are always required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Delegated operation/challenge/attempt mismatch, or the exact attempt is already in progress. An in-progress replay returns a bound PortalMfaCompleteResponse with replayed=true and never resubmits the code.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PortalMfaCompleteResponse"},{"$ref":"#/components/schemas/Error"}]}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"description":"Payer portal is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/portal-logins":{"get":{"tags":["Portal logins"],"summary":"Read payer login health without searching a member","description":"Without operation filters, returns current payer-login health. For delegated onboarding or revoke recovery, send organization_id, payer_id, and operation_id together: exact reads require portal_login_mutation and the same admitted server-derived caller_id. This filtered REST endpoint is required; MCP list_portal_logins lacks payer_id and operation_id inputs. It never reads or reposts a password, submits MFA, probes the payer, or resumes cleanup. An admitted UCCI read may reconcile safe observational metadata from its exact session authority. Nested portal_login_operation.operation_status and operation_authenticated_at describe the historical exact outcome; current_session_status and operation_observed_at describe current observation. Unknown or unmeasured freshness must not display connected. Historical deletion flags do not prove a mailbox is empty after a newer login. Ambiguous onboarding recovery is observation only, without automatic password replay.","operationId":"listPortalLogins","parameters":[{"name":"organization_id","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Practice scope. Required with payer_id and operation_id for an exact operation read."},{"name":"payer_id","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Exact payer scope. Must be sent with organization_id and operation_id."},{"name":"operation_id","in":"query","required":false,"schema":{"type":"string","minLength":16,"maxLength":256},"description":"Exact delegated operation. Must be sent with organization_id and payer_id; the authenticated caller must match the operation's admitted caller."}],"responses":{"200":{"description":"Current payer-login health (switch on login_state; status and desk keep their v1.1 meanings), or the exact secret-free delegated operation when all three filters and the exact admitted caller match.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PortalLoginsResponse"},{"$ref":"#/components/schemas/PortalLoginOperationResponse"}]},"example":{"organization_id":"demo","portal_logins":[{"payer_id":"sandbox_mfa","enabled":false,"revoke_only":false,"status":"ready","situation_label":"demo","desk":"alive","login_state":"logged_in","login_state_reason":"demo","checked_at":"demo","next_action":"none","has_credentials":true,"cookie_names":["demo"],"login_saved":true,"message":"demo","operation_id":"demo","operation_action":"portal_login_onboard","operation_status":"received","operation_ok":false,"operation_stored":false,"operation_revoked":false,"operation_credentials_deleted":false,"operation_sessions_invalidated":false,"operation_message":"demo","operation_error_code":"demo","operation_error_reason":"invalid_credentials","operation_updated_at":"demo","onboarding_status":"needs_code","revocation_status":"received","challenges":[{"challenge_id":"demo","challenge_generation":1}]}]}}}},"400":{"description":"Exact operation read filters are incomplete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential cannot access this practice, or an exact operation read lacks portal_login_mutation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Operation was not found for this exact caller, practice, and payer scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/portal-logins/snapshot":{"get":{"tags":["Portal logins"],"summary":"Read the last portal-login observations without contacting payer portals","description":"Fast read for vendor Vault screens. Credential presence comes from the current encrypted-vault row. Connector status comes from the last canonical GET /portal-logins observation and is replaced with status_unknown/checking after ten minutes, so stale data never authorizes Connect, MFA, or eligibility. This endpoint never contacts a payer portal, reads a password, submits MFA, or mutates a session. Refresh canonical state with GET /portal-logins outside the page-load critical path.","operationId":"listPortalLoginSnapshot","parameters":[{"name":"organization_id","in":"query","required":false,"description":"Practice id from GET /organizations. Portal-login and credential routes use this query name (not practice_id). Required for a company-wide key; a practice-bound key may omit it.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Secret-free cached connector state plus current credential presence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalLoginSnapshotResponse"},"example":{"organization_id":"org_from_organizations","portal_logins":[{"payer_id":"sandbox_mfa","name":"Sandbox MFA","enabled":true,"status":"ready","last_status":"ready","login_state":"logged_in","next_action":"none","desk":"alive","situation_label":"Serving","has_credentials":true,"shares_with":[],"checked_at":"2026-09-16T12:00:00.000Z","last_health_check_at":"2026-09-16T12:00:00.000Z","snapshot_at":"2026-09-16T12:00:00.000Z","stale":false}],"snapshot_at":"2026-09-16T12:00:00.000Z","stale":false,"refresh_after":"2026-09-16T12:00:00.000Z"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/network/careington":{"get":{"tags":["Network"],"summary":"Read this practice's Careington leased-network participation and a carrier's payor-listing verdict","description":"Careington is a leased PPO network, not a payer: its member search knows only Careington card holders. This read returns the office's own Fee Schedules and Participating Providers page (plans, effective dates, provider type, allowed amount per CDT code) from the saved Careington login, reused for 24 hours, and, when payer is given, whether that carrier is printed on the current payor listing as accessing the network under this office's participation. Never signs in. 404 not_connected when the practice has no Careington login, so practices outside Careington are never affected.","operationId":"readCareingtonNetwork","parameters":[{"name":"organization_id","in":"query","required":false,"description":"Practice id from GET /organizations. Portal-login and credential routes use this query name (not practice_id). Required for a company-wide key; a practice-bound key may omit it.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"payer","in":"query","required":false,"description":"Carrier name or catalog payer id to judge against the payor listing (for example Renaissance, metlife).","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"state","in":"query","required":false,"description":"Two-letter office state for the listing's state exclusions.","schema":{"type":"string","minLength":2,"maxLength":2}}],"responses":{"200":{"description":"Participation from the office's own portal page plus the listing verdict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CareingtonNetworkResponse"},"example":{"organization_id":"org_from_organizations","status":"ok","reason":"soft_block","participation":{"status":"participating","observed_at":"2026-09-26T13:00:00.000Z","reused":true,"provider_type":"GENERAL DENTIST","specialty":null,"plans":[{"plan_name":"Care Platinum Series PPO","effective_date":"2020-01-01"}],"fee_link":"absent","fee_rows":[{"code":"D0120","description":"Periodic oral evaluation - established patient","allowed":17}]},"access":{"status":"listed","reason":null,"matches":[{"id":"renaissance","name":"Renaissance","status":"listed","reasons":["demo"]}],"disclaimer":"The carrier, TPA or claims payor decides the network at claims processing."},"listing":{"month":"2026-08","sha256":"0000000000000000000000000000000000000000000000000000000000000000"}}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"This practice has no Careington portal login (not_connected).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/inbox":{"get":{"tags":["Inbox"],"summary":"List payer mail held for a practice's code address","description":"Lists mail that reached the practice's codes.veraxus.ai address and was not used by Veraxus as a sign-in code. A code Veraxus entered into a portal is never listed, so a code appears here only when no Veraxus sign-in was waiting for it. Metadata only: digit runs in the subject and preview are masked. Requires the inbox scope, which no key has unless it was minted with it. Never contacts a payer portal. Do not cache.","operationId":"listPracticeInbox","parameters":[{"name":"organization_id","in":"query","required":false,"description":"Practice id from GET /organizations. Portal-login and credential routes use this query name (not practice_id). Required for a company-wide key; a practice-bound key may omit it.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Messages for this practice, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PracticeInboxResponse"},"example":{"organization_id":"demo","code_email_address":"demo","code_email_receiving":false,"retention_hours":72,"messages":[{"id":"demo","sender_domain":"demo","sender_name":"demo","subject":"demo","kind":"password_reset","needs_action":false,"preview":"demo","received_at":"demo","expires_at":"demo"}]}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the inbox scope (insufficient_scope) or cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"description":"Stored mail cannot be read right now (inbox_unavailable). Never reported as an empty inbox.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inbox/{id}":{"get":{"tags":["Inbox"],"summary":"Read one message, including its one-time code or reset link","description":"Returns the text of one message, the one-time code when exactly one candidate exists, and its https links. Every call writes a Veraxus audit row naming the credential and, when given, actor_user_id; call it only when a person opens the message. Requires the inbox scope. Do not cache or log the response.","operationId":"readPracticeInboxMessage","parameters":[{"name":"id","in":"path","required":true,"description":"Message id from GET /inbox.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"}},{"name":"organization_id","in":"query","required":false,"description":"Practice id from GET /organizations. Portal-login and credential routes use this query name (not practice_id). Required for a company-wide key; a practice-bound key may omit it.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"actor_user_id","in":"query","required":false,"description":"Your id for the person opening the message. Recorded on the audit row.","schema":{"type":"string","pattern":"^[A-Za-z0-9_.:@-]{1,128}$"}}],"responses":{"200":{"description":"The message text, extracted code, and links.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PracticeInboxMessageResponse"},"example":{"id":"demo","organization_id":"demo","from":"demo","sender_domain":"demo","subject":"demo","text":"demo","kind":"password_reset","code":"482913","action_link":{"url":"demo","host":"demo"},"links":[{"url":"demo","host":"demo"}],"received_at":"demo","expires_at":"demo"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the inbox scope (insufficient_scope) or cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The message expired or is not in this practice's inbox (message_not_found).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"description":"Stored mail cannot be read right now (inbox_unavailable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inbox/authenticator-codes":{"get":{"tags":["Inbox"],"summary":"Live authenticator codes for a practice's saved logins","description":"For every saved payer login of this practice that holds an authenticator key, returns the 6-digit code the office's authenticator app shows now, the code for the next 30 seconds, and when the current one stops working. The key itself is never returned. A shared login is one row. Empty codes means no login of this practice has an authenticator key. Poll once per period boundary while a person is looking, never in the background. Veraxus writes one audit row per credential, actor_user_id and practice per 15 minutes. Requires the inbox scope. Never contacts a payer portal. Do not cache, store, or log the response.","operationId":"listPracticeAuthenticatorCodes","parameters":[{"name":"organization_id","in":"query","required":false,"description":"Practice id from GET /organizations. Portal-login and credential routes use this query name (not practice_id). Required for a company-wide key; a practice-bound key may omit it.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"actor_user_id","in":"query","required":false,"description":"Your id for the person looking at the codes. Recorded on the audit row.","schema":{"type":"string","pattern":"^[A-Za-z0-9_.:@-]{1,128}$"}}],"responses":{"200":{"description":"Current and next code for each saved login with an authenticator key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PracticeAuthenticatorCodesResponse"},"example":{"organization_id":"demo","server_time":"demo","period_seconds":30,"codes":[{"id":"demo","name":"demo","payer_ids":["demo"],"code":"482913","valid_from":"demo","valid_until":"demo","next_code":"482913"}]}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the inbox scope (insufficient_scope) or cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"description":"Saved authenticator keys cannot be read right now (inbox_unavailable). Never reported as an empty list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/portal-logins/needing-code":{"get":{"tags":["Portal logins"],"summary":"List portal logins with a parked one-time-code challenge","description":"Pure read: lists currently parked challenges and never advances, retries, or reconciles a delegated operation.","operationId":"listPortalLoginsNeedingCode","parameters":[{"name":"organization_id","in":"query","required":false,"description":"Practice id from GET /organizations. Portal-login and credential routes use this query name (not practice_id). Required for a company-wide key; a practice-bound key may omit it.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Portal logins currently waiting for a one-time code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalLoginsResponse"},"example":{"organization_id":"demo","portal_logins":[{"payer_id":"demo","enabled":false,"revoke_only":false,"status":"ready","situation_label":"demo","desk":"alive","login_state":"logged_in","login_state_reason":"demo","checked_at":"demo","next_action":"none","has_credentials":false,"cookie_names":["demo"],"login_saved":false,"message":"demo","operation_id":"demo","operation_action":"portal_login_onboard","operation_status":"received","operation_ok":false,"operation_stored":false,"operation_revoked":false,"operation_credentials_deleted":false,"operation_sessions_invalidated":false,"operation_message":"demo","operation_error_code":"demo","operation_error_reason":"invalid_credentials","operation_updated_at":"demo","onboarding_status":"needs_code","revocation_status":"received","challenges":[{"challenge_id":"demo","challenge_generation":1}]}]}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/portal-logins/needing-sign-in":{"get":{"tags":["Portal logins"],"summary":"List portal logins whose desk word is needs_sign_in","description":"Pure read: filters the same rows list_portal_logins returns down to desk === needs_sign_in (no code owed, no setup pending, a person must sign back in). Never advances, retries, or reconciles a delegated operation.","operationId":"listPortalLoginsNeedingSignIn","parameters":[{"name":"organization_id","in":"query","required":false,"description":"Practice id from GET /organizations. Portal-login and credential routes use this query name (not practice_id). Required for a company-wide key; a practice-bound key may omit it.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Portal logins whose desk word is currently needs_sign_in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalLoginsResponse"},"example":{"organization_id":"demo","portal_logins":[{"payer_id":"demo","enabled":false,"revoke_only":false,"status":"ready","situation_label":"demo","desk":"alive","login_state":"logged_in","login_state_reason":"demo","checked_at":"demo","next_action":"none","has_credentials":false,"cookie_names":["demo"],"login_saved":false,"message":"demo","operation_id":"demo","operation_action":"portal_login_onboard","operation_status":"received","operation_ok":false,"operation_stored":false,"operation_revoked":false,"operation_credentials_deleted":false,"operation_sessions_invalidated":false,"operation_message":"demo","operation_error_code":"demo","operation_error_reason":"invalid_credentials","operation_updated_at":"demo","onboarding_status":"needs_code","revocation_status":"received","challenges":[{"challenge_id":"demo","challenge_generation":1}]}]}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/organizations":{"get":{"tags":["Practices"],"summary":"List practices","operationId":"listOrganizations","description":"Cursor-paginated practice roster for this customer. Filter with q (name substring or 10-digit NPI). Default page size 50, maximum 100. Pass next_cursor as cursor. Never dumps the full roster.","parameters":[{"name":"q","in":"query","required":false,"description":"Name substring or 10-digit NPI.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 50, maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from next_cursor on the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Cursor-paginated practice roster.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PracticeListResponse"},"example":{"tenant_id":"demo","total":1,"organizations":[{"id":"demo","name":"demo","code_email_address":"demo@codes.veraxus.ai","code_email_receiving":false}]}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}},"post":{"tags":["Practices"],"summary":"Create or update one practice","operationId":"createOrganization","responses":{"200":{"description":"Existing practice returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PracticeResponse"},"example":{"id":"demo","name":"demo","code_email_address":"demo@codes.veraxus.ai","code_email_receiving":false}}}},"201":{"description":"Practice created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PracticeResponse"},"example":{"id":"demo","name":"demo","code_email_address":"demo@codes.veraxus.ai","code_email_receiving":false}}}},"400":{"description":"Invalid practice payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Company-wide credential and signed BAA required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Practice identity conflicts with an existing practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}},"description":"Create or update one practice"}},"/organizations/import":{"post":{"tags":["Practices"],"summary":"Import up to 500 practices","operationId":"importPractices","responses":{"200":{"description":"Practice import results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PracticeImportResponse"},"example":{"tenant_id":"demo","practices":[{"id":"demo","name":"demo","code_email_address":"demo@codes.veraxus.ai","code_email_receiving":false}]}}}},"400":{"description":"Invalid practice import payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Company-wide credential and signed BAA required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}},"description":"Import up to 500 practices"}},"/usage":{"get":{"tags":["Account"],"summary":"Read 30-day practice usage","operationId":"listUsage","responses":{"200":{"description":"Thirty-day eligibility usage summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"},"example":{"billing_unit":"eligibility_check"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}},"description":"Read 30-day practice usage"}},"/claims/guide":{"get":{"tags":["Claims"],"summary":"Read the claims integration guide","description":"Vendor end-to-end filing cookbook: eligibility, create with Idempotency-Key, confirmation.statement, vendor_ui attestation, outcomes, sandbox DEMO members, and error codes. REST twin of MCP claims_guide and https://veraxus.ai/docs#claims. No claims scope required.","operationId":"getClaimsGuide","security":[],"responses":{"200":{"description":"Claims integration guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimsGuideResponse"},"example":{"title":"demo","docs_url":"demo","billed":false,"sequence":["demo"],"markdown":"demo"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/claims":{"post":{"tags":["Claims"],"summary":"Create a claim or predetermination draft","operationId":"createClaimDraft","security":[{"bearerAuth":["claims"]}],"description":"Create a claim or predetermination draft, validate it against the payer contract, and run a portal duplicate scan. Does not file anything. Returns 200 on first create and on Idempotency-Key replay. Nested party, member, NPI, tax id, and remarks fields are PHI. Accepts EITHER a structured JSON draft OR raw X12 837D (JSON { x12, usage_indicator } wrapper, or a raw application/edi-x12 / text/plain+X-X12 body) — never both on the same call. sandbox: true (or DEMO member ids) is the Veraxus unpaid sandbox and never loads a portal keep. X12 usage_indicator T is the interchange ISA15 test flag: those drafts may be staged but live-submit confirm is fail-closed (409 test_indicator_blocks_submit). T is not sandbox.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Canonical retry key. Body idempotency_key is accepted when this header is absent. When both are present they must match; mismatch is 400 idempotency_key_mismatch.","schema":{"type":"string","minLength":1,"maxLength":256}},{"name":"organization_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"X-Usage-Indicator","in":"header","required":false,"description":"Required for raw X12 bodies (application/edi-x12 or text/plain): T (test) or P (production). JSON { x12, usage_indicator } requests read the body field instead; this header is not consulted on that path. The value must equal the interchange's own ISA15 or the whole request is rejected fail-closed (400 x12_usage_indicator_mismatch).","schema":{"type":"string","enum":["T","P"]}},{"name":"X-Payer-Id","in":"header","required":false,"description":"Catalog eligibility_payer_id for the raw-EDI path, used when the 2010BB payer id has no crosswalk entry.","schema":{"type":"string"}},{"name":"X-X12","in":"header","required":false,"description":"Set to 1 together with Content-Type: text/plain to mark the body as raw 837D EDI (an alternative to Content-Type: application/edi-x12).","schema":{"type":"string","enum":["1"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Either a structured ClaimDraftInput (plus optional practice scope) OR an X12ClaimDraftBody. practice_id, organization_id, organizationId, and idempotency_key are stripped before draft validation on the structured shape. organization_id is a deprecated alias for practice_id.","oneOf":[{"type":"object","allOf":[{"$ref":"#/components/schemas/ClaimDraftInput"}],"properties":{"practice_id":{"type":"string","description":"Practice from GET /organizations. Required for a company-wide key."},"organization_id":{"type":"string","deprecated":true,"description":"Deprecated alias for practice_id."},"organizationId":{"type":"string","deprecated":true,"description":"Deprecated alias for practice_id."},"idempotency_key":{"type":"string","description":"Body alias for the canonical Idempotency-Key header. Used when the header is absent. When both are present they must be equal; a mismatch is 400 idempotency_key_mismatch. Never silently ignored."},"sandbox":{"type":"boolean","description":"True to file a sandbox claim (never billed, never loadKeep). Also auto when patient/subscriber memberId is DEMO-####."}}},{"$ref":"#/components/schemas/X12ClaimDraftBody"}]},"example":{"payerId":"demo","transactionType":"claim","patient":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"subscriber":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"billingNpi":"demo","treatingNpi":"demo","procedures":[{"procedureCode":"D0120","dateOfService":"1980-01-15","fee":0}],"assignmentOnFile":false,"releaseOfInformation":false}},"application/edi-x12":{"schema":{"type":"string","description":"Raw 837D EDI bytes (ISA...IEA), capped at 1 MiB. Pair with the required X-Usage-Indicator header and optional X-Payer-Id."},"example":"ISA*00*          *00*          *ZZ*SANDBOX*ZZ*VERAXUS*260916*1200*^*00501*000000001*0*T*:~"},"text/plain":{"schema":{"type":"string","description":"Raw 837D EDI bytes when header X-X12: 1 is set; otherwise this content type is not a recognized draft shape. Pair with X-Usage-Indicator and optional X-Payer-Id."},"example":"ISA*00*          *00*          *ZZ*SANDBOX*ZZ*VERAXUS*260916*1200*^*00501*000000001*0*T*:~"}}},"responses":{"200":{"description":"Existing draft replayed for this Idempotency-Key, or the new row.","content":{"application/json":{"schema":{"type":"object","properties":{"submission":{"$ref":"#/components/schemas/ClaimSubmission"},"validation":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationIssue"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/ValidationIssue"}}},"required":["errors","warnings"]},"gates":{"oneOf":[{"$ref":"#/components/schemas/GateStatus"},{"type":"null"}]},"duplicate_check":{"oneOf":[{"$ref":"#/components/schemas/DuplicateCheckResult"},{"type":"null"}]},"confirmation":{"oneOf":[{"$ref":"#/components/schemas/ClaimConfirmation"},{"type":"null"}],"description":"Present when the row is awaiting_confirm (or submitted, for void). Null when blocked."}},"required":["submission","validation","gates","duplicate_check","confirmation"]},"example":{"submission":{"id":"demo","practice_id":"demo","org_id":"demo","payer_id":"demo","state":"draft","block_reason":"duplicate_in_ledger","failure_reason":"session_unavailable","adjudication":"unknown","transaction_type":"claim","input":{"payerId":"demo","transactionType":"claim","patient":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"subscriber":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"billingNpi":"demo","treatingNpi":"demo","procedures":[{"procedureCode":"D0120","dateOfService":"1980-01-15","fee":0}],"assignmentOnFile":false,"releaseOfInformation":false},"payload_hash":"demo","fingerprint":"demo","idempotency_key":"demo","contract_version":"demo","validation":[{"path":"demo","code":"demo","message":"demo","severity":"error"}],"duplicate_check":{"ranAt":"demo","expiresAt":"demo","matches":[{"source":"ledger","dateOfService":"1980-01-15","procedureCodes":["demo"]}]},"gates":{"envEnabled":false,"orgEnabled":false,"payerAllowed":false,"contractStatus":"provisional","transactionAllowed":false,"allOpen":false,"reasons":["demo"]},"portal_claim_number":"demo","portal_response_keys":["demo"],"rejection_edits":[{"message":"demo"}],"confirmed_at":"demo","confirmation_method":"console_submit","sandbox":false,"write_kind":"submit","stage_phase":"none","portal_draft_id":"demo","staged_at":"demo","arrived_at":"demo","stage_error":"demo","submit_attempt":0,"usage_indicator":"T","x12_report":{"version":"005010X224A1","usageIndicator":"T","controlNumbers":{"isa13":"demo","gs06":"demo","st02":"demo"},"segmentCount":0,"claimTotalCents":1,"proceduresTotalCents":0,"payerIdSource":"explicit","mappedFields":["demo"],"unmapped":[{"code":"demo","message":"demo"}],"warnings":[{"code":"demo","message":"demo"}]},"created_at":"demo","updated_at":"demo"},"validation":{"errors":[{"path":"demo","code":"demo","message":"demo","severity":"error"}],"warnings":[{"path":"demo","code":"demo","message":"demo","severity":"error"}]},"gates":{"envEnabled":false,"orgEnabled":false,"payerAllowed":false,"contractStatus":"provisional","transactionAllowed":false,"allOpen":false,"reasons":["demo"]},"duplicate_check":{"ranAt":"demo","expiresAt":"demo","matches":[{"source":"ledger","dateOfService":"1980-01-15","procedureCodes":["demo"]}]},"confirmation":{"token":"demo","expiresAt":"demo","payloadHash":"demo","statement":"demo","stagingStatement":"demo"}}}}},"400":{"description":"Invalid draft; Idempotency-Key header missing (idempotency_key_required); header and body idempotency_key differ (idempotency_key_mismatch); or an X12 problem: x12_delimiters, x12_envelope, x12_version_unsupported, x12_not_837, x12_multiple_claims, x12_missing_required, x12_usage_indicator_mismatch, or x12_payer_unmapped (no payerId supplied and the 2010BB payer id has no crosswalk entry).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (legacy_code scope_required) when the credential lacks the claims scope; otherwise the key cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Claims submission is dark unless CLAIMS_SUBMISSION is enabled for the deployment and the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency key conflicts, duplicate live fingerprint, closed write gates, or test_indicator_blocks_submit (a usage_indicator T draft was sent to confirm instead of stage).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"X12 payload exceeds the 1 MiB size cap (x12_too_large).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}},"get":{"tags":["Claims"],"summary":"List claim submissions","operationId":"listClaims","description":"Cursor-paginated list for one practice. Filter by state, payerId, and created-at range. Nested input on each item is PHI.","parameters":[{"name":"organization_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"state","in":"query","required":false,"style":"form","explode":false,"description":"Comma-separated ClaimSubmissionState values (state[]).","schema":{"type":"array","items":{"type":"string","enum":["draft","validated","blocked","awaiting_confirm","queued","submitting","submitted","rejected","failed","unknown_outcome","voided","cancelled","staging","staged"]}}},{"name":"payerId","in":"query","required":false,"description":"Filter by catalog eligibility_payer_id.","schema":{"type":"string"}},{"name":"payer_id","in":"query","required":false,"description":"Alias for payerId.","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Inclusive created-at lower bound (ISO-8601).","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Inclusive created-at upper bound (ISO-8601).","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from next_cursor.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Page of submissions. Pass next_cursor back as cursor.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ClaimSubmission"}},"next_cursor":{"type":["string","null"]}},"required":["items","next_cursor"]},"example":{"items":[{"id":"demo","practice_id":"demo","org_id":"demo","payer_id":"demo","state":"draft","block_reason":"duplicate_in_ledger","failure_reason":"session_unavailable","adjudication":"unknown","transaction_type":"claim","input":{"payerId":"demo","transactionType":"claim","patient":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"subscriber":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"billingNpi":"demo","treatingNpi":"demo","procedures":[{"procedureCode":"D0120","dateOfService":"1980-01-15","fee":0}],"assignmentOnFile":false,"releaseOfInformation":false},"payload_hash":"demo","fingerprint":"demo","idempotency_key":"demo","contract_version":"demo","validation":[{"path":"demo","code":"demo","message":"demo","severity":"error"}],"duplicate_check":{"ranAt":"demo","expiresAt":"demo","matches":[{"source":"ledger","dateOfService":"1980-01-15","procedureCodes":["demo"]}]},"gates":{"envEnabled":false,"orgEnabled":false,"payerAllowed":false,"contractStatus":"provisional","transactionAllowed":false,"allOpen":false,"reasons":["demo"]},"portal_claim_number":"demo","portal_response_keys":["demo"],"rejection_edits":[{"message":"demo"}],"confirmed_at":"demo","confirmation_method":"console_submit","sandbox":false,"write_kind":"submit","stage_phase":"none","portal_draft_id":"demo","staged_at":"demo","arrived_at":"demo","stage_error":"demo","submit_attempt":0,"usage_indicator":"T","x12_report":{"version":"005010X224A1","usageIndicator":"T","controlNumbers":{"isa13":"demo","gs06":"demo","st02":"demo"},"segmentCount":0,"claimTotalCents":1,"proceduresTotalCents":0,"payerIdSource":"explicit","mappedFields":["demo"],"unmapped":[{"code":"demo","message":"demo"}],"warnings":[{"code":"demo","message":"demo"}]},"created_at":"demo","updated_at":"demo"}],"next_cursor":"demo"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (legacy_code scope_required) when the credential lacks the claims scope; otherwise the key cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Claims submission is dark unless CLAIMS_SUBMISSION is enabled for the deployment and the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/claims/{id}":{"get":{"tags":["Claims"],"summary":"Read one claim submission","operationId":"getClaimSubmission","description":"Returns the public wire for one submission. payerRequest is never returned. Nested input is PHI.","parameters":[{"name":"id","in":"path","required":true,"description":"Claim submission id (clm_…).","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"organization_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Current submission.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"submission":{"$ref":"#/components/schemas/ClaimSubmission"}},"required":["submission"]},"example":{"submission":{"id":"demo","practice_id":"demo","org_id":"demo","payer_id":"demo","state":"draft","block_reason":"duplicate_in_ledger","failure_reason":"session_unavailable","adjudication":"unknown","transaction_type":"claim","input":{"payerId":"demo","transactionType":"claim","patient":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"subscriber":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"billingNpi":"demo","treatingNpi":"demo","procedures":[{"procedureCode":"D0120","dateOfService":"1980-01-15","fee":0}],"assignmentOnFile":false,"releaseOfInformation":false},"payload_hash":"demo","fingerprint":"demo","idempotency_key":"demo","contract_version":"demo","validation":[{"path":"demo","code":"demo","message":"demo","severity":"error"}],"duplicate_check":{"ranAt":"demo","expiresAt":"demo","matches":[{"source":"ledger","dateOfService":"1980-01-15","procedureCodes":["demo"]}]},"gates":{"envEnabled":false,"orgEnabled":false,"payerAllowed":false,"contractStatus":"provisional","transactionAllowed":false,"allOpen":false,"reasons":["demo"]},"portal_claim_number":"demo","portal_response_keys":["demo"],"rejection_edits":[{"message":"demo"}],"confirmed_at":"demo","confirmation_method":"console_submit","sandbox":false,"write_kind":"submit","stage_phase":"none","portal_draft_id":"demo","staged_at":"demo","arrived_at":"demo","stage_error":"demo","submit_attempt":0,"usage_indicator":"T","x12_report":{"version":"005010X224A1","usageIndicator":"T","controlNumbers":{"isa13":"demo","gs06":"demo","st02":"demo"},"segmentCount":0,"claimTotalCents":1,"proceduresTotalCents":0,"payerIdSource":"explicit","mappedFields":["demo"],"unmapped":[{"code":"demo","message":"demo"}],"warnings":[{"code":"demo","message":"demo"}]},"created_at":"demo","updated_at":"demo"}}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (legacy_code scope_required) when the credential lacks the claims scope; otherwise the key cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Claims submission is dark unless CLAIMS_SUBMISSION is enabled for the deployment and the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/claims/{id}/events":{"get":{"tags":["Claims"],"summary":"List events for one claim submission","operationId":"listClaimEvents","description":"Timeline of state transitions and redacted hops. Traces never include bodies or PHI.","parameters":[{"name":"id","in":"path","required":true,"description":"Claim submission id (clm_…).","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"organization_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Events newest-last.","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/ClaimSubmissionEvent"}}},"required":["events"]},"example":{"events":[{"id":1,"at":"demo","actor":"demo","kind":"create","from_state":"draft","to_state":"draft","trace":{"method":"demo","path":"demo","status":1,"requestKeys":["demo"],"responseKeys":["demo"],"durationMs":1,"error":"demo"}}]}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (legacy_code scope_required) when the credential lacks the claims scope; otherwise the key cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Claims submission is dark unless CLAIMS_SUBMISSION is enabled for the deployment and the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/claims/{id}/revalidate":{"post":{"tags":["Claims"],"summary":"Revalidate a claim draft","operationId":"revalidateClaim","description":"Re-run contract validation, gates, and the portal duplicate scan. Does not file anything.","parameters":[{"name":"id","in":"path","required":true,"description":"Claim submission id (clm_…).","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"organization_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"organization_id":{"type":"string","description":"Practice from GET /organizations. Required for a company-wide key."}}},"example":{"organization_id":"demo"}}}},"responses":{"200":{"description":"Updated submission plus split validation and gates.","content":{"application/json":{"schema":{"type":"object","properties":{"submission":{"$ref":"#/components/schemas/ClaimSubmission"},"validation":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationIssue"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/ValidationIssue"}}},"required":["errors","warnings"]},"gates":{"oneOf":[{"$ref":"#/components/schemas/GateStatus"},{"type":"null"}]}},"required":["submission","validation","gates"]},"example":{"submission":{"id":"demo","practice_id":"demo","org_id":"demo","payer_id":"demo","state":"draft","block_reason":"duplicate_in_ledger","failure_reason":"session_unavailable","adjudication":"unknown","transaction_type":"claim","input":{"payerId":"demo","transactionType":"claim","patient":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"subscriber":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"billingNpi":"demo","treatingNpi":"demo","procedures":[{"procedureCode":"D0120","dateOfService":"1980-01-15","fee":0}],"assignmentOnFile":false,"releaseOfInformation":false},"payload_hash":"demo","fingerprint":"demo","idempotency_key":"demo","contract_version":"demo","validation":[{"path":"demo","code":"demo","message":"demo","severity":"error"}],"duplicate_check":{"ranAt":"demo","expiresAt":"demo","matches":[{"source":"ledger","dateOfService":"1980-01-15","procedureCodes":["demo"]}]},"gates":{"envEnabled":false,"orgEnabled":false,"payerAllowed":false,"contractStatus":"provisional","transactionAllowed":false,"allOpen":false,"reasons":["demo"]},"portal_claim_number":"demo","portal_response_keys":["demo"],"rejection_edits":[{"message":"demo"}],"confirmed_at":"demo","confirmation_method":"console_submit","sandbox":false,"write_kind":"submit","stage_phase":"none","portal_draft_id":"demo","staged_at":"demo","arrived_at":"demo","stage_error":"demo","submit_attempt":0,"usage_indicator":"T","x12_report":{"version":"005010X224A1","usageIndicator":"T","controlNumbers":{"isa13":"demo","gs06":"demo","st02":"demo"},"segmentCount":0,"claimTotalCents":1,"proceduresTotalCents":0,"payerIdSource":"explicit","mappedFields":["demo"],"unmapped":[{"code":"demo","message":"demo"}],"warnings":[{"code":"demo","message":"demo"}]},"created_at":"demo","updated_at":"demo"},"validation":{"errors":[{"path":"demo","code":"demo","message":"demo","severity":"error"}],"warnings":[{"path":"demo","code":"demo","message":"demo","severity":"error"}]},"gates":{"envEnabled":false,"orgEnabled":false,"payerAllowed":false,"contractStatus":"provisional","transactionAllowed":false,"allOpen":false,"reasons":["demo"]}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (legacy_code scope_required) when the credential lacks the claims scope; otherwise the key cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Claims submission is dark unless CLAIMS_SUBMISSION is enabled for the deployment and the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Illegal state for revalidate, or closed write gates.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/claims/{id}/cancel":{"post":{"tags":["Claims"],"summary":"Cancel a claim draft","operationId":"cancelClaimDraft","description":"Cancel a draft that has not been sent. Cannot cancel a live or submitted row.","parameters":[{"name":"id","in":"path","required":true,"description":"Claim submission id (clm_…).","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"organization_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"organization_id":{"type":"string","description":"Practice from GET /organizations. Required for a company-wide key."}}},"example":{"organization_id":"demo"}}}},"responses":{"200":{"description":"Cancelled submission.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"submission":{"$ref":"#/components/schemas/ClaimSubmission"}},"required":["submission"]},"example":{"submission":{"id":"demo","practice_id":"demo","org_id":"demo","payer_id":"demo","state":"draft","block_reason":"duplicate_in_ledger","failure_reason":"session_unavailable","adjudication":"unknown","transaction_type":"claim","input":{"payerId":"demo","transactionType":"claim","patient":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"subscriber":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"billingNpi":"demo","treatingNpi":"demo","procedures":[{"procedureCode":"D0120","dateOfService":"1980-01-15","fee":0}],"assignmentOnFile":false,"releaseOfInformation":false},"payload_hash":"demo","fingerprint":"demo","idempotency_key":"demo","contract_version":"demo","validation":[{"path":"demo","code":"demo","message":"demo","severity":"error"}],"duplicate_check":{"ranAt":"demo","expiresAt":"demo","matches":[{"source":"ledger","dateOfService":"1980-01-15","procedureCodes":["demo"]}]},"gates":{"envEnabled":false,"orgEnabled":false,"payerAllowed":false,"contractStatus":"provisional","transactionAllowed":false,"allOpen":false,"reasons":["demo"]},"portal_claim_number":"demo","portal_response_keys":["demo"],"rejection_edits":[{"message":"demo"}],"confirmed_at":"demo","confirmation_method":"console_submit","sandbox":false,"write_kind":"submit","stage_phase":"none","portal_draft_id":"demo","staged_at":"demo","arrived_at":"demo","stage_error":"demo","submit_attempt":0,"usage_indicator":"T","x12_report":{"version":"005010X224A1","usageIndicator":"T","controlNumbers":{"isa13":"demo","gs06":"demo","st02":"demo"},"segmentCount":0,"claimTotalCents":1,"proceduresTotalCents":0,"payerIdSource":"explicit","mappedFields":["demo"],"unmapped":[{"code":"demo","message":"demo"}],"warnings":[{"code":"demo","message":"demo"}]},"created_at":"demo","updated_at":"demo"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (legacy_code scope_required) when the credential lacks the claims scope; otherwise the key cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Claims submission is dark unless CLAIMS_SUBMISSION is enabled for the deployment and the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Illegal state for cancel (already live or terminal).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/claims/{id}/confirm":{"post":{"tags":["Claims"],"summary":"Confirm and queue a claim for portal submit","operationId":"confirmClaim","description":"Queue a validated draft for portal submit. Requires the claims scope. Body is a vendor attestation: the HMAC token from POST /claims plus the vendor user who saw confirmation.statement. Veraxus HITL (403 hitl_required + grant_id) runs only when the practice sets require_veraxus_hitl, after the attestation is validated. Hash mismatch is 409. When the keep lane is paused, confirm returns 202 { state: queued, note }.","security":[{"bearerAuth":["claims"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Claim submission id (clm_…).","schema":{"type":"string","minLength":1,"maxLength":128}},{"$ref":"#/components/parameters/HitlGrant"},{"name":"organization_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimVendorAttestation"},"example":{"token":"demo","confirmedBy":{"id":"demo"},"method":"vendor_ui"}}}},"responses":{"200":{"description":"Final submission after confirm (or after the lane already ran).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"submission":{"$ref":"#/components/schemas/ClaimSubmission"}},"required":["submission"]},"example":{"submission":{"id":"demo","practice_id":"demo","org_id":"demo","payer_id":"demo","state":"draft","block_reason":"duplicate_in_ledger","failure_reason":"session_unavailable","adjudication":"unknown","transaction_type":"claim","input":{"payerId":"demo","transactionType":"claim","patient":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"subscriber":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"billingNpi":"demo","treatingNpi":"demo","procedures":[{"procedureCode":"D0120","dateOfService":"1980-01-15","fee":0}],"assignmentOnFile":false,"releaseOfInformation":false},"payload_hash":"demo","fingerprint":"demo","idempotency_key":"demo","contract_version":"demo","validation":[{"path":"demo","code":"demo","message":"demo","severity":"error"}],"duplicate_check":{"ranAt":"demo","expiresAt":"demo","matches":[{"source":"ledger","dateOfService":"1980-01-15","procedureCodes":["demo"]}]},"gates":{"envEnabled":false,"orgEnabled":false,"payerAllowed":false,"contractStatus":"provisional","transactionAllowed":false,"allOpen":false,"reasons":["demo"]},"portal_claim_number":"demo","portal_response_keys":["demo"],"rejection_edits":[{"message":"demo"}],"confirmed_at":"demo","confirmation_method":"console_submit","sandbox":false,"write_kind":"submit","stage_phase":"none","portal_draft_id":"demo","staged_at":"demo","arrived_at":"demo","stage_error":"demo","submit_attempt":0,"usage_indicator":"T","x12_report":{"version":"005010X224A1","usageIndicator":"T","controlNumbers":{"isa13":"demo","gs06":"demo","st02":"demo"},"segmentCount":0,"claimTotalCents":1,"proceduresTotalCents":0,"payerIdSource":"explicit","mappedFields":["demo"],"unmapped":[{"code":"demo","message":"demo"}],"warnings":[{"code":"demo","message":"demo"}]},"created_at":"demo","updated_at":"demo"}}}}},"202":{"description":"Queued; lane paused, will execute automatically.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"state":{"type":"string","const":"queued","description":"Always queued."},"note":{"type":"string","description":"queued; lane paused, will execute automatically"}},"required":["state","note"]},"example":{"state":"queued","note":"demo"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (legacy_code scope_required) without the claims scope. hitl_required only when require_veraxus_hitl is on (error.grant_id is the pending grant).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"properties":{"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"hitl_required, hitl_invalid, or forbidden."},"message":{"type":"string","description":"Plain-words explanation, safe to show a person."},"grant_id":{"type":"string","description":"Pending HITL grant id (htg_…). Present on hitl_required."},"action":{"type":"string","enum":["submit_claim","void_claim","stage_claim"],"description":"HITL action; submit_claim for this operation."}},"required":["code","message"]}},"required":["error"]},{"$ref":"#/components/schemas/Error"}]}}}},"404":{"description":"Claims submission is dark unless CLAIMS_SUBMISSION is enabled for the deployment and the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Confirm requires awaiting_confirm (duplicate_submission), closed write gates, or a paused lane after the row left queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/claims/{id}/void":{"post":{"tags":["Claims"],"summary":"Void a submitted claim","operationId":"voidClaim","description":"Request a portal void. Same vendor-attestation body as confirm. HITL action void_claim only when require_veraxus_hitl is on. Requires the claims scope.","security":[{"bearerAuth":["claims"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Claim submission id (clm_…).","schema":{"type":"string","minLength":1,"maxLength":128}},{"$ref":"#/components/parameters/HitlGrant"},{"name":"organization_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimVendorAttestation"},"example":{"token":"demo","confirmedBy":{"id":"demo"},"method":"vendor_ui"}}}},"responses":{"200":{"description":"Voided or void-requested submission.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"submission":{"$ref":"#/components/schemas/ClaimSubmission"}},"required":["submission"]},"example":{"submission":{"id":"demo","practice_id":"demo","org_id":"demo","payer_id":"demo","state":"draft","block_reason":"duplicate_in_ledger","failure_reason":"session_unavailable","adjudication":"unknown","transaction_type":"claim","input":{"payerId":"demo","transactionType":"claim","patient":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"subscriber":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"billingNpi":"demo","treatingNpi":"demo","procedures":[{"procedureCode":"D0120","dateOfService":"1980-01-15","fee":0}],"assignmentOnFile":false,"releaseOfInformation":false},"payload_hash":"demo","fingerprint":"demo","idempotency_key":"demo","contract_version":"demo","validation":[{"path":"demo","code":"demo","message":"demo","severity":"error"}],"duplicate_check":{"ranAt":"demo","expiresAt":"demo","matches":[{"source":"ledger","dateOfService":"1980-01-15","procedureCodes":["demo"]}]},"gates":{"envEnabled":false,"orgEnabled":false,"payerAllowed":false,"contractStatus":"provisional","transactionAllowed":false,"allOpen":false,"reasons":["demo"]},"portal_claim_number":"demo","portal_response_keys":["demo"],"rejection_edits":[{"message":"demo"}],"confirmed_at":"demo","confirmation_method":"console_submit","sandbox":false,"write_kind":"submit","stage_phase":"none","portal_draft_id":"demo","staged_at":"demo","arrived_at":"demo","stage_error":"demo","submit_attempt":0,"usage_indicator":"T","x12_report":{"version":"005010X224A1","usageIndicator":"T","controlNumbers":{"isa13":"demo","gs06":"demo","st02":"demo"},"segmentCount":0,"claimTotalCents":1,"proceduresTotalCents":0,"payerIdSource":"explicit","mappedFields":["demo"],"unmapped":[{"code":"demo","message":"demo"}],"warnings":[{"code":"demo","message":"demo"}]},"created_at":"demo","updated_at":"demo"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (legacy_code scope_required) without the claims scope. hitl_required only when require_veraxus_hitl is on. HITL action is void_claim.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"properties":{"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"hitl_required, hitl_invalid, or forbidden."},"message":{"type":"string","description":"Plain-words explanation, safe to show a person."},"grant_id":{"type":"string","description":"Pending HITL grant id (htg_…). Present on hitl_required."},"action":{"type":"string","const":"void_claim","description":"HITL action; void_claim for this operation."}},"required":["code","message"]}},"required":["error"]},{"$ref":"#/components/schemas/Error"}]}}}},"404":{"description":"Claims submission is dark unless CLAIMS_SUBMISSION is enabled for the deployment and the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Illegal state for void, or payload hash missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/claims/{id}/stage":{"post":{"tags":["Claims"],"summary":"Send a claim to the payer portal as a draft (stage, never submit)","operationId":"stageClaim","description":"Two-click model. This call creates a saved draft of the claim or predetermination in the payer's provider portal and never submits it; a second person submits inside the portal. Requires the claims scope. Body is the same vendor-attestation SHAPE as confirm, but token = confirmation.stagingToken — a DISTINCT token from confirm's, bound to action \"stage\" and the draft payload's hash, never confirmation.token — plus the vendor user who saw confirmation.stagingStatement. Veraxus HITL (403 hitl_required + grant_id, action stage_claim) runs only when the practice sets require_veraxus_hitl, after the attestation is validated. Hash mismatch is 409. Requires the payer's staging contract ≥ captured or a founder staging override on this one claim (POST /api/ops/claims-staging-override); otherwise 409 claims_gate_closed. A payer with no proven draft surface returns 409 staging_contract_incomplete. Exactly one portal write per call; an ambiguous send leaves stage_phase unknown and is reconciled with POST /claims/{id}/verify-arrival, never re-sent.","security":[{"bearerAuth":["claims"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Claim submission id (clm_…).","schema":{"type":"string","minLength":1,"maxLength":128}},{"$ref":"#/components/parameters/HitlGrant"},{"name":"organization_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimVendorAttestation"},"example":{"token":"demo","confirmedBy":{"id":"demo"},"method":"vendor_ui"}}}},"responses":{"200":{"description":"Submission after staging: state staging or staged, stage_phase, portal_draft_id, staged_at (write_kind stage).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"submission":{"$ref":"#/components/schemas/ClaimSubmission"}},"required":["submission"]},"example":{"submission":{"id":"demo","practice_id":"demo","org_id":"demo","payer_id":"demo","state":"draft","block_reason":"duplicate_in_ledger","failure_reason":"session_unavailable","adjudication":"unknown","transaction_type":"claim","input":{"payerId":"demo","transactionType":"claim","patient":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"subscriber":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"billingNpi":"demo","treatingNpi":"demo","procedures":[{"procedureCode":"D0120","dateOfService":"1980-01-15","fee":0}],"assignmentOnFile":false,"releaseOfInformation":false},"payload_hash":"demo","fingerprint":"demo","idempotency_key":"demo","contract_version":"demo","validation":[{"path":"demo","code":"demo","message":"demo","severity":"error"}],"duplicate_check":{"ranAt":"demo","expiresAt":"demo","matches":[{"source":"ledger","dateOfService":"1980-01-15","procedureCodes":["demo"]}]},"gates":{"envEnabled":false,"orgEnabled":false,"payerAllowed":false,"contractStatus":"provisional","transactionAllowed":false,"allOpen":false,"reasons":["demo"]},"portal_claim_number":"demo","portal_response_keys":["demo"],"rejection_edits":[{"message":"demo"}],"confirmed_at":"demo","confirmation_method":"console_submit","sandbox":false,"write_kind":"submit","stage_phase":"none","portal_draft_id":"demo","staged_at":"demo","arrived_at":"demo","stage_error":"demo","submit_attempt":0,"usage_indicator":"T","x12_report":{"version":"005010X224A1","usageIndicator":"T","controlNumbers":{"isa13":"demo","gs06":"demo","st02":"demo"},"segmentCount":0,"claimTotalCents":1,"proceduresTotalCents":0,"payerIdSource":"explicit","mappedFields":["demo"],"unmapped":[{"code":"demo","message":"demo"}],"warnings":[{"code":"demo","message":"demo"}]},"created_at":"demo","updated_at":"demo"}}}}},"400":{"description":"Invalid request (missing attestation).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (legacy_code scope_required) without the claims scope. hitl_required only when require_veraxus_hitl is on (error.grant_id is the pending grant, action stage_claim).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Claims submission is dark unless CLAIMS_SUBMISSION is enabled for the deployment and the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"conflict when the row is not awaiting_confirm or the token no longer matches the payload; claims_gate_closed when the staging gate is closed; staging_contract_incomplete when the payer has no proven draft surface; lane_paused when the keep lane is paused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/claims/{id}/verify-arrival":{"post":{"tags":["Claims"],"summary":"Verify a staged draft arrived in the payer portal","operationId":"verifyClaimArrival","description":"Read-only check of the payer portal's drafts list for a staged submission. Sets stage_phase arrived and arrived_at when the draft is there; leaves the row unchanged otherwise. Never re-sends the draft and never submits. Also the reconcile path for stage_phase unknown.","security":[{"bearerAuth":["claims"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Claim submission id (clm_…).","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"organization_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"organization_id":{"type":"string","description":"Practice from GET /organizations. Required for a company-wide key."}}},"example":{"organization_id":"demo"}}}},"responses":{"200":{"description":"Submission after the drafts-list check.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"submission":{"$ref":"#/components/schemas/ClaimSubmission"}},"required":["submission"]},"example":{"submission":{"id":"demo","practice_id":"demo","org_id":"demo","payer_id":"demo","state":"draft","block_reason":"duplicate_in_ledger","failure_reason":"session_unavailable","adjudication":"unknown","transaction_type":"claim","input":{"payerId":"demo","transactionType":"claim","patient":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"subscriber":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"billingNpi":"demo","treatingNpi":"demo","procedures":[{"procedureCode":"D0120","dateOfService":"1980-01-15","fee":0}],"assignmentOnFile":false,"releaseOfInformation":false},"payload_hash":"demo","fingerprint":"demo","idempotency_key":"demo","contract_version":"demo","validation":[{"path":"demo","code":"demo","message":"demo","severity":"error"}],"duplicate_check":{"ranAt":"demo","expiresAt":"demo","matches":[{"source":"ledger","dateOfService":"1980-01-15","procedureCodes":["demo"]}]},"gates":{"envEnabled":false,"orgEnabled":false,"payerAllowed":false,"contractStatus":"provisional","transactionAllowed":false,"allOpen":false,"reasons":["demo"]},"portal_claim_number":"demo","portal_response_keys":["demo"],"rejection_edits":[{"message":"demo"}],"confirmed_at":"demo","confirmation_method":"console_submit","sandbox":false,"write_kind":"submit","stage_phase":"none","portal_draft_id":"demo","staged_at":"demo","arrived_at":"demo","stage_error":"demo","submit_attempt":0,"usage_indicator":"T","x12_report":{"version":"005010X224A1","usageIndicator":"T","controlNumbers":{"isa13":"demo","gs06":"demo","st02":"demo"},"segmentCount":0,"claimTotalCents":1,"proceduresTotalCents":0,"payerIdSource":"explicit","mappedFields":["demo"],"unmapped":[{"code":"demo","message":"demo"}],"warnings":[{"code":"demo","message":"demo"}]},"created_at":"demo","updated_at":"demo"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (legacy_code scope_required) when the credential lacks the claims scope; otherwise the key cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Claims submission is dark unless CLAIMS_SUBMISSION is enabled for the deployment and the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"conflict when the row was never staged; staging_contract_incomplete when the payer has no proven drafts-list hop; lane_paused when the keep lane is paused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/claims/{id}/reconcile":{"post":{"tags":["Claims"],"summary":"Reconcile an ambiguous claim submission","operationId":"reconcileClaim","description":"Read-only portal search to resolve unknown_outcome. Never retries the live POST. Manual trigger; the host also reconciles on a schedule.","parameters":[{"name":"id","in":"path","required":true,"description":"Claim submission id (clm_…).","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"organization_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"organization_id":{"type":"string","description":"Practice from GET /organizations. Required for a company-wide key."}}},"example":{"organization_id":"demo"}}}},"responses":{"200":{"description":"Submission after reconcile.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"submission":{"$ref":"#/components/schemas/ClaimSubmission"}},"required":["submission"]},"example":{"submission":{"id":"demo","practice_id":"demo","org_id":"demo","payer_id":"demo","state":"draft","block_reason":"duplicate_in_ledger","failure_reason":"session_unavailable","adjudication":"unknown","transaction_type":"claim","input":{"payerId":"demo","transactionType":"claim","patient":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"subscriber":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"billingNpi":"demo","treatingNpi":"demo","procedures":[{"procedureCode":"D0120","dateOfService":"1980-01-15","fee":0}],"assignmentOnFile":false,"releaseOfInformation":false},"payload_hash":"demo","fingerprint":"demo","idempotency_key":"demo","contract_version":"demo","validation":[{"path":"demo","code":"demo","message":"demo","severity":"error"}],"duplicate_check":{"ranAt":"demo","expiresAt":"demo","matches":[{"source":"ledger","dateOfService":"1980-01-15","procedureCodes":["demo"]}]},"gates":{"envEnabled":false,"orgEnabled":false,"payerAllowed":false,"contractStatus":"provisional","transactionAllowed":false,"allOpen":false,"reasons":["demo"]},"portal_claim_number":"demo","portal_response_keys":["demo"],"rejection_edits":[{"message":"demo"}],"confirmed_at":"demo","confirmation_method":"console_submit","sandbox":false,"write_kind":"submit","stage_phase":"none","portal_draft_id":"demo","staged_at":"demo","arrived_at":"demo","stage_error":"demo","submit_attempt":0,"usage_indicator":"T","x12_report":{"version":"005010X224A1","usageIndicator":"T","controlNumbers":{"isa13":"demo","gs06":"demo","st02":"demo"},"segmentCount":0,"claimTotalCents":1,"proceduresTotalCents":0,"payerIdSource":"explicit","mappedFields":["demo"],"unmapped":[{"code":"demo","message":"demo"}],"warnings":[{"code":"demo","message":"demo"}]},"created_at":"demo","updated_at":"demo"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (legacy_code scope_required) when the credential lacks the claims scope; otherwise the key cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Claims submission is dark unless CLAIMS_SUBMISSION is enabled for the deployment and the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Illegal state for reconcile, or paused lane.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/claims/contracts/{payerId}":{"get":{"tags":["Claims"],"summary":"Read a payer claims contract","operationId":"getClaimsContract","description":"Public contract projection: status and version so a client can show capture-pending. Does not return the request schema.","parameters":[{"name":"payerId","in":"path","required":true,"description":"Catalog eligibility_payer_id.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Public contract projection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayerClaimsContract"},"example":{"payer_id":"demo","version":"demo","status":"provisional","captured_at":"demo","notes":"demo"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (legacy_code scope_required) when the credential lacks the claims scope; otherwise the key cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Claims submission is dark unless CLAIMS_SUBMISSION is enabled for the deployment and the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/claims/settings":{"get":{"tags":["Claims"],"summary":"Read practice claims settings","operationId":"getClaimsSettings","description":"Practice write-lane switches and default NPIs. Default NPI and tax id are PHI.","parameters":[{"name":"organization_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Current settings.","content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"$ref":"#/components/schemas/OrgClaimsSettings"}},"required":["settings"]},"example":{"settings":{"orgId":"demo","claimsWriteEnabled":false,"liveClaimsEnabled":false,"requireTwoPersonConfirm":false,"updatedAt":"demo"}}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (legacy_code scope_required) when the credential lacks the claims scope; otherwise the key cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Claims submission is dark unless CLAIMS_SUBMISSION is enabled for the deployment and the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}},"patch":{"tags":["Claims"],"summary":"Update practice claims settings","operationId":"updateClaimsSettings","description":"Requires the claims scope. Default NPI and tax id are PHI.","security":[{"bearerAuth":["claims"]}],"parameters":[{"name":"organization_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"organization_id":{"type":"string","description":"Practice from GET /organizations. Required for a company-wide key."},"organizationId":{"type":"string","description":"Alias for organization_id."},"claimsWriteEnabled":{"type":"boolean","description":"Master org switch for the claims write lane."},"liveClaimsEnabled":{"type":"boolean","description":"False means predeterminations only."},"defaultBillingNpi":{"type":"string","description":"PHI. Default billing NPI for new drafts."},"defaultTreatingNpi":{"type":"string","description":"PHI. Default treating NPI for new drafts."},"defaultTaxId":{"type":"string","description":"PHI. Default billing tax id for new drafts."},"requireTwoPersonConfirm":{"type":"boolean","description":"When true, confirm requires a second person."}}},"example":{"organization_id":"demo","organizationId":"demo","claimsWriteEnabled":false,"liveClaimsEnabled":false,"defaultBillingNpi":"demo","defaultTreatingNpi":"demo","defaultTaxId":"demo","requireTwoPersonConfirm":false}}}},"responses":{"200":{"description":"Updated settings.","content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"$ref":"#/components/schemas/OrgClaimsSettings"}},"required":["settings"]},"example":{"settings":{"orgId":"demo","claimsWriteEnabled":false,"liveClaimsEnabled":false,"requireTwoPersonConfirm":false,"updatedAt":"demo"}}}}},"400":{"description":"Invalid settings patch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (legacy_code scope_required) when the credential lacks the claims scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Claims submission is dark unless CLAIMS_SUBMISSION is enabled for the deployment and the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/claims/stats":{"get":{"tags":["Claims"],"summary":"Read practice claims-lane stats","operationId":"getClaimsStats","description":"Counts by state plus open unknown_outcome aging. No PHI.","parameters":[{"name":"organization_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Current counters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimsStats"},"example":{"by_state":{},"unknown_outcome_open":0,"oldest_unknown_age_ms":1}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (legacy_code scope_required) when the credential lacks the claims scope; otherwise the key cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Claims submission is dark unless CLAIMS_SUBMISSION is enabled for the deployment and the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/claims/{id}/attachments":{"get":{"tags":["Claims"],"summary":"List attachments for a claim submission","operationId":"listClaimAttachments","security":[{"bearerAuth":["claims"]}],"description":"Returns stored attachment metadata for one submission. filename is returned (vendor data). Ciphertext is never returned. imageMeta echoes accepted keys only. Requires the claims scope.","parameters":[{"name":"id","in":"path","required":true,"description":"Claim submission id (clm_…).","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"organization_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Attachments for this submission.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/ClaimAttachment"},"description":"Attachment metadata rows. Never ciphertext."}},"required":["attachments"]},"example":{"attachments":[{"id":"demo","submissionId":"demo","kind":"radiograph","payerTypeCode":"demo","serviceLineIndexes":[1],"filename":"demo","contentType":"demo","byteLength":1,"sha256":"demo","state":"stored","uploadAttempt":1,"portalAttachmentId":"demo","portalError":"demo","imageMeta":{"dateTaken":"demo","orientation":"demo","toothNumbers":["demo"],"side":"demo"},"createdAt":"demo","attachedAt":"demo"}]}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (legacy_code scope_required) when the credential lacks the claims scope; otherwise the key cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Claim submission not found, or claims submission is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}},"post":{"tags":["Claims"],"summary":"Add an attachment to a claim submission","operationId":"addClaimAttachment","security":[{"bearerAuth":["claims"]}],"description":"Store an encrypted attachment on a draft. JSON { kind, contentBase64, contentType, filename, serviceLineIndexes, payerTypeCode, imageMeta } or multipart/form-data with a file part plus the same fields. Payer byte/type limits are enforced from Content-Length before decode when present. DICOM is rejected. Live portal upload is not performed here. Requires the claims scope.","parameters":[{"name":"id","in":"path","required":true,"description":"Claim submission id (clm_…).","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"organization_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimAttachmentCreate"},"example":{"kind":"radiograph","contentBase64":"demo","contentType":"demo"}},"multipart/form-data":{"schema":{"type":"object","additionalProperties":false,"description":"Multipart twin of ClaimAttachmentCreate. The file part is named file.","properties":{"file":{"type":"string","format":"binary","description":"File part. Size is checked against the payer limit before bytes are decoded."},"kind":{"type":"string","enum":["radiograph","perio_chart","photo","narrative","eob","other"],"description":"Attachment kind: radiograph, perio_chart, photo, narrative, eob, or other."},"contentType":{"type":"string","description":"MIME type when not taken from the file part. DICOM is rejected."},"filename":{"type":"string","description":"Vendor filename override; defaults to the file part name."},"serviceLineIndexes":{"type":"string","description":"JSON array or comma-separated zero-based procedure line indexes."},"payerTypeCode":{"type":"string","description":"Optional payer document type code from the attachments contract."},"imageMeta":{"type":"string","description":"JSON ImageMeta (dateTaken, orientation, toothNumbers, side only)."},"organization_id":{"type":"string","description":"Practice from GET /organizations. Required for a company-wide key."}},"required":["file","kind"]},"example":"ISA*00*          *00*          *ZZ*SANDBOX*ZZ*VERAXUS*260916*1200*^*00501*000000001*0*T*:~"}}},"responses":{"200":{"description":"Stored attachment metadata. Never ciphertext.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"attachment":{"$ref":"#/components/schemas/ClaimAttachment"}},"required":["attachment"]},"example":{"attachment":{"id":"demo","submissionId":"demo","kind":"radiograph","payerTypeCode":"demo","serviceLineIndexes":[1],"filename":"demo","contentType":"demo","byteLength":1,"sha256":"demo","state":"stored","uploadAttempt":1,"portalAttachmentId":"demo","portalError":"demo","imageMeta":{"dateTaken":"demo","orientation":"demo","toothNumbers":["demo"],"side":"demo"},"createdAt":"demo","attachedAt":"demo"}}}}},"400":{"description":"attachment_type_not_allowed (including DICOM) or invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (legacy_code scope_required) when the credential lacks the claims scope; otherwise the key cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Claim submission not found, or claims submission is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"attachment_contract_incomplete when a hop is unproven; attachment_locked when the row is past awaiting_confirm.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"attachment_too_large: the file exceeds the payer-specific proven limit (Content-Length is checked before decode when present).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/claims/{id}/attachments/{attId}":{"delete":{"tags":["Claims"],"summary":"Remove a stored attachment","operationId":"deleteClaimAttachment","security":[{"bearerAuth":["claims"]}],"description":"Deletes an attachment only while it is stored and the submission is not past awaiting_confirm. Requires the claims scope.","parameters":[{"name":"id","in":"path","required":true,"description":"Claim submission id (clm_…).","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"attId","in":"path","required":true,"description":"Claim attachment id (att_…).","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"organization_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Attachment removed.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","description":"True when the stored attachment was deleted."}},"required":["ok"]},"example":{"ok":false}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (legacy_code scope_required) when the credential lacks the claims scope; otherwise the key cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"attachment_not_found, or the claim submission is missing, or claims submission is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"attachment_locked when the file is no longer stored or the submission is past awaiting_confirm.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/claims/{id}/attachments/override":{"post":{"tags":["Claims"],"summary":"Override a required-attachment block","operationId":"overrideClaimAttachment","security":[{"bearerAuth":["claims"]}],"description":"Record an audited reason to file without a required attachment. Requires permission claims:override_attachment (claims + vault scopes on the API key).","parameters":[{"name":"id","in":"path","required":true,"description":"Claim submission id (clm_…).","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"organization_id","in":"query","required":false,"description":"Practice returned by GET /organizations. Required for a company-wide key.","schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"reason":{"type":"string","description":"Audited reason the practice is filing without a required attachment."},"organization_id":{"type":"string","description":"Practice from GET /organizations. Required for a company-wide key."}},"required":["reason"]},"example":{"reason":"demo"}}}},"responses":{"200":{"description":"Submission after the override (typically unblocked).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"submission":{"$ref":"#/components/schemas/ClaimSubmission"}},"required":["submission"]},"example":{"submission":{"id":"demo","practice_id":"demo","org_id":"demo","payer_id":"demo","state":"draft","block_reason":"duplicate_in_ledger","failure_reason":"session_unavailable","adjudication":"unknown","transaction_type":"claim","input":{"payerId":"demo","transactionType":"claim","patient":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"subscriber":{"firstName":"demo","lastName":"demo","dob":"1980-01-15"},"billingNpi":"demo","treatingNpi":"demo","procedures":[{"procedureCode":"D0120","dateOfService":"1980-01-15","fee":0}],"assignmentOnFile":false,"releaseOfInformation":false},"payload_hash":"demo","fingerprint":"demo","idempotency_key":"demo","contract_version":"demo","validation":[{"path":"demo","code":"demo","message":"demo","severity":"error"}],"duplicate_check":{"ranAt":"demo","expiresAt":"demo","matches":[{"source":"ledger","dateOfService":"1980-01-15","procedureCodes":["demo"]}]},"gates":{"envEnabled":false,"orgEnabled":false,"payerAllowed":false,"contractStatus":"provisional","transactionAllowed":false,"allOpen":false,"reasons":["demo"]},"portal_claim_number":"demo","portal_response_keys":["demo"],"rejection_edits":[{"message":"demo"}],"confirmed_at":"demo","confirmation_method":"console_submit","sandbox":false,"write_kind":"submit","stage_phase":"none","portal_draft_id":"demo","staged_at":"demo","arrived_at":"demo","stage_error":"demo","submit_attempt":0,"usage_indicator":"T","x12_report":{"version":"005010X224A1","usageIndicator":"T","controlNumbers":{"isa13":"demo","gs06":"demo","st02":"demo"},"segmentCount":0,"claimTotalCents":1,"proceduresTotalCents":0,"payerIdSource":"explicit","mappedFields":["demo"],"unmapped":[{"code":"demo","message":"demo"}],"warnings":[{"code":"demo","message":"demo"}]},"created_at":"demo","updated_at":"demo"}}}}},"400":{"description":"reason is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"missing permission claims:override_attachment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Claim submission not found, or claims submission is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Override is not applicable in the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/webhooks":{"post":{"tags":["Webhooks"],"summary":"Register a webhook","operationId":"createWebhook","description":"POSTed JSON is signed. Headers: Content-Type: application/json, Veraxus-Event: <type>, Veraxus-Delivery: <id>, Veraxus-Signature: t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>. After rotate-secret, deliveries carry two v1 values (new then old) for 24h; accept any v1 that matches the secret you hold. Reject timestamps more than 5 minutes from your clock. Delivery timeout is 10 seconds; HTTP 3xx is a failure (redirects are not followed). Body cap is 256 KiB; oversized payloads are marked dead. 20 consecutive failures or a denied destination deactivate the endpoint (webhook.deactivated). Retry schedule: 1m, 5m, 30m, 2h, 12h, then dead. At-least-once: deduplicate by payload.id. Node:\n\n```\nimport { createHmac, timingSafeEqual } from \"node:crypto\";\nfunction verify(secret, header, body, nowSec = Math.floor(Date.now() / 1000)) {\n  const v1s = [];\n  let t;\n  for (const piece of header.split(\",\")) {\n    const i = piece.indexOf(\"=\");\n    const k = piece.slice(0, i).trim();\n    const v = piece.slice(i + 1).trim();\n    if (k === \"t\") t = v;\n    else if (k === \"v1\") v1s.push(v);\n  }\n  if (!t || Math.abs(nowSec - Number(t)) > 300) return false;\n  const expected = createHmac(\"sha256\", secret).update(`${t}.${body}`).digest(\"hex\");\n  return v1s.some((v1) => timingSafeEqual(Buffer.from(expected, \"utf8\"), Buffer.from(v1, \"utf8\")));\n}\n```\n\nPayloads never include patient, subscriber, or procedure fields.\n\nOmit organization_id (or set null) for a company default across all practices. Set organization_id for a practice override. An active practice subscription replaces company defaults for its subscribed event types. Scope is fixed at creation; create a new endpoint to change it. Existing endpoints remain company defaults.\n\nSubscribe to eligibility.completed and eligibility.failed to avoid polling slow checks. The event is queued when the stored check is terminal and enrichment has finished (complete or failed), and includes data.checkId, status, enrichment, and resultUrl. GET data.resultUrl using an eligibility-scoped credential authorized for the practice to retrieve the full benefits; fetching a saved result does not run another check. No historical results are replayed on subscription. Notifications are delivered at least once: deduplicate by payload id, including retries. Dispatch runs every minute; delivery may take longer under load or retries.\n\nSubscribe to portal_login.desk_changed to learn a payer login's desk word flipped (alive, needs_sign_in, needs_attention, enter_code, set_up — the same word GET /v1/portal-logins publishes as desk) without polling that list. data carries organization_id, payer_id, from, to, reason, observed_at, and predicted_expiry_at (null unless a forecast is available).\n\nSubscribe to portal_login.status_changed for Connect, MFA, and keep-health transitions. data carries organization_id, payer_id, status, previous_status, generation, at, and optional client_reference.\n\nSubscribe to portal_login.state_changed when GET /v1/portal-logins login_state flips. data carries organization_id, payer_id, login_state, previous_login_state, at, and row (the full published portal-logins item).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreate"},"example":{"url":"demo","events":["eligibility.completed"]}}}},"responses":{"201":{"description":"Created. secret is in the body once.","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"}},"required":["webhook"]},"example":{"webhook":{"id":"demo","tenant_id":"demo","url":"demo","events":["eligibility.completed"],"active":false}}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Company-wide credential with vault scope required. OAuth grant owner must be a current company admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Webhook or delivery not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}},"get":{"tags":["Webhooks"],"summary":"List webhooks","operationId":"listWebhooks","description":"Secrets are never listed.","responses":{"200":{"description":"Company webhooks.","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}},"required":["webhooks"]},"example":{"webhooks":[{"id":"demo","tenant_id":"demo","url":"demo","events":["eligibility.completed"],"active":false}]}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Company-wide credential with vault scope required. OAuth grant owner must be a current company admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Webhook or delivery not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/webhooks/test":{"post":{"tags":["Webhooks"],"summary":"Enqueue a webhook.test delivery","operationId":"testWebhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Webhook id (whk_…) to enqueue webhook.test for."}},"required":["id"]},"example":{"id":"demo"}}}},"responses":{"202":{"description":"Queued.","content":{"application/json":{"schema":{"type":"object","properties":{"delivery":{"$ref":"#/components/schemas/WebhookDelivery"}}},"example":{"delivery":{"id":"demo","webhook_id":"demo","event_type":"demo","event_id":"demo","payload":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}},"attempt":1,"status":"pending"}}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Company-wide credential with vault scope required. OAuth grant owner must be a current company admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Webhook or delivery not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}},"description":"Enqueue a webhook.test delivery"}},"/webhooks/deliveries":{"get":{"tags":["Webhooks"],"summary":"List deliveries for a webhook","operationId":"listWebhookDeliveries","parameters":[{"name":"webhook_id","in":"query","required":true,"description":"Webhook id (whk_…).","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"pending, delivered, failed, or dead.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"next_cursor from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Delivery page.","content":{"application/json":{"schema":{"type":"object","properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"},"description":"Delivery attempts for this webhook."},"next_cursor":{"type":["string","null"],"description":"Pass back as cursor; null on the last page."}}},"example":{"deliveries":[{"id":"demo","webhook_id":"demo","event_type":"demo","event_id":"demo","payload":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}},"attempt":1,"status":"pending"}],"next_cursor":"demo"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Company-wide credential with vault scope required. OAuth grant owner must be a current company admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Webhook or delivery not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}},"description":"List deliveries for a webhook"}},"/webhooks/{id}":{"get":{"tags":["Webhooks"],"summary":"Read a webhook","operationId":"getWebhook","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id (whk_…).","schema":{"type":"string","minLength":1,"maxLength":80}}],"responses":{"200":{"description":"Webhook without secret.","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"}}},"example":{"webhook":{"id":"demo","tenant_id":"demo","url":"demo","events":["eligibility.completed"],"active":false}}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Company-wide credential with vault scope required. OAuth grant owner must be a current company admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Webhook or delivery not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}},"description":"Read a webhook"},"patch":{"tags":["Webhooks"],"summary":"Update a webhook","operationId":"patchWebhook","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id (whk_…).","schema":{"type":"string","minLength":1,"maxLength":80}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"HTTPS callback URL that receives HMAC-signed POSTs."},"events":{"type":"array","items":{"type":"string","enum":["eligibility.completed","eligibility.failed","claim.submitted","claim.acknowledged","claim.rejected","claim.failed","claim.unknown_outcome","claim.reconciled","claim.voided","claim.cancelled","claim.adjudication_updated","claim.attachment_uploaded","claim.attachment_failed","claim.staged","claim.stage_failed","claim.arrived_in_portal","portal_login.desk_changed","portal_login.status_changed","portal_login.state_changed","webhook.test","webhook.deactivated"]},"description":"Replacement event type enum list."},"active":{"type":"boolean","description":"False pauses deliveries without deleting the endpoint and emits webhook.deactivated (reason customer) to sibling endpoints."},"description":{"type":["string","null"],"description":"Optional operator label; never PHI. Null clears."}}},"example":{"url":"demo","events":["eligibility.completed"],"active":false,"description":"demo"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"}}},"example":{"webhook":{"id":"demo","tenant_id":"demo","url":"demo","events":["eligibility.completed"],"active":false}}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Company-wide credential with vault scope required. OAuth grant owner must be a current company admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Webhook or delivery not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}},"description":"Update a webhook"},"delete":{"tags":["Webhooks"],"summary":"Delete a webhook","operationId":"deleteWebhook","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id (whk_…).","schema":{"type":"string","minLength":1,"maxLength":80}}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","description":"True when the webhook was removed."}}},"example":{"deleted":false}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Company-wide credential with vault scope required. OAuth grant owner must be a current company admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Webhook or delivery not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}},"description":"Delete a webhook"}},"/webhooks/{id}/rotate-secret":{"post":{"tags":["Webhooks"],"summary":"Rotate the signing secret","operationId":"rotateWebhookSecret","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id (whk_…).","schema":{"type":"string","minLength":1,"maxLength":80}}],"description":"Issues a new whsec_ secret (returned once). The previous secret stays valid for 24 hours (previous_secret_expires_at). During that window every delivery carries two signatures: Veraxus-Signature: t=<unix>,v1=<hex-new>,v1=<hex-old>. Verify by matching any v1 with the secret you hold. After the window the old secret is dropped.","responses":{"200":{"description":"New secret shown once. Previous secret remains valid until previous_secret_expires_at.","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"}}},"example":{"webhook":{"id":"demo","tenant_id":"demo","url":"demo","events":["eligibility.completed"],"active":false}}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Company-wide credential with vault scope required. OAuth grant owner must be a current company admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Webhook or delivery not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/webhooks/{id}/test":{"post":{"tags":["Webhooks"],"summary":"Enqueue webhook.test for this id","operationId":"testWebhookById","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id (whk_…).","schema":{"type":"string","minLength":1,"maxLength":80}}],"responses":{"202":{"description":"Queued.","content":{"application/json":{"schema":{"type":"object","properties":{"delivery":{"$ref":"#/components/schemas/WebhookDelivery"}}},"example":{"delivery":{"id":"demo","webhook_id":"demo","event_type":"demo","event_id":"demo","payload":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}},"attempt":1,"status":"pending"}}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Company-wide credential with vault scope required. OAuth grant owner must be a current company admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Webhook or delivery not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}},"description":"Enqueue webhook.test for this id"}},"/webhooks/{id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"List deliveries","operationId":"listWebhookDeliveriesById","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id (whk_…).","schema":{"type":"string","minLength":1,"maxLength":80}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Delivery page.","content":{"application/json":{"schema":{"type":"object","properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"},"description":"Delivery attempts for this webhook."},"next_cursor":{"type":["string","null"],"description":"Pass back as cursor; null on the last page."}}},"example":{"deliveries":[{"id":"demo","webhook_id":"demo","event_type":"demo","event_id":"demo","payload":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}},"attempt":1,"status":"pending"}],"next_cursor":"demo"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Company-wide credential with vault scope required. OAuth grant owner must be a current company admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Webhook or delivery not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}},"description":"List deliveries"}},"/webhooks/{id}/deliveries/{deliveryId}/redeliver":{"post":{"tags":["Webhooks"],"summary":"Redeliver one attempt","operationId":"redeliverWebhookDelivery","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id (whk_…).","schema":{"type":"string","minLength":1,"maxLength":80}},{"name":"deliveryId","in":"path","required":true,"description":"Delivery attempt id (whd_…).","schema":{"type":"string"}}],"responses":{"200":{"description":"Queued for retry.","content":{"application/json":{"schema":{"type":"object","properties":{"delivery":{"$ref":"#/components/schemas/WebhookDelivery"}}},"example":{"delivery":{"id":"demo","webhook_id":"demo","event_type":"demo","event_id":"demo","payload":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}},"attempt":1,"status":"pending"}}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Company-wide credential with vault scope required. OAuth grant owner must be a current company admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Webhook or delivery not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}},"description":"Redeliver one attempt"}},"/health/logins":{"get":{"tags":["Portal logins"],"summary":"Read saved-login health across practices","operationId":"listLoginHealth","description":"The console Health page as data: every saved payer login at each practice with its last recorded status, and a per-practice count. Read from the status snapshot Veraxus keeps; it never contacts a payer portal, never signs in and never returns a secret. A company-wide key pages through practices 25 at a time (maximum 100); name one practice, or use a practice-bound key, to read just that practice. Requires the eligibility scope.","parameters":[{"name":"organization_id","in":"query","required":false,"description":"Practice id from GET /organizations. Required for a company-wide key on a single-practice route; a practice-bound key may omit it. The X-Organization-Id header is accepted as well.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Practices per page. Default 25, maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from next_cursor on the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Login health for one page of practices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginHealthResponse"},"example":{"tenant_id":"tn_sample_juniper","generated_at":"2026-10-01T23:22:37.017Z","newest_observed_at":"2026-10-01T23:22:15.759Z","total_practices":3,"next_cursor":null,"practices":[{"organization_id":"org_sample_cedar","name":"Cedar Grove Family Dental","auto_logins":1,"auto_serving":0,"auto_problems":1,"manual_logins":1}],"logins":[{"organization_id":"org_sample_cedar","organization_name":"Cedar Grove Family Dental","payer_id":"aetna","payer_name":"Aetna","auto_sign_in":true,"status":"code","status_label":"Needs a code","detail":"Portal is waiting for a code","last_signed_in_at":null,"last_failure_at":null,"observed_at":"2026-10-01T23:22:15.759Z"},{"organization_id":"org_sample_cedar","organization_name":"Cedar Grove Family Dental","payer_id":"dnoa","payer_name":"DNoA","auto_sign_in":false,"status":"serving","status_label":"Serving","detail":"Signed in 2 minutes ago","last_signed_in_at":"2026-10-01T23:20:02.000Z","last_failure_at":null,"observed_at":"2026-10-01T23:22:15.759Z"}]}}}},"400":{"description":"limit is not a whole number from 1 to 100.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, or cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The named practice is not on this company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/setup":{"get":{"tags":["Practices"],"summary":"Read each practice's setup progress","operationId":"listPracticeSetup","description":"The console Home page as data: for each practice, the four setup steps (practice added, payer logins, code email, first check), which one is next, and the facts behind them, including the practice's code email address. A company-wide key pages through practices 25 at a time (maximum 100); name one practice, or use a practice-bound key, to read just that practice. Requires the eligibility scope.","parameters":[{"name":"organization_id","in":"query","required":false,"description":"Practice id from GET /organizations. Required for a company-wide key on a single-practice route; a practice-bound key may omit it. The X-Organization-Id header is accepted as well.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Practices per page. Default 25, maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from next_cursor on the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Setup progress for one page of practices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PracticeSetupResponse"},"example":{"tenant_id":"tn_sample_juniper","total":3,"next_cursor":"org_sample_lakeshore","practices":[{"organization_id":"org_sample_cedar","name":"Cedar Grove Family Dental","ready":true,"steps_done":4,"steps_total":4,"next_step":null,"steps":[{"id":"added","label":"Practice added","state":"done","detail":"The practice is on file."},{"id":"logins","label":"Payer logins","state":"done","detail":"7 logins saved."},{"id":"code_email","label":"Code email","state":"done","detail":"Payer mail is arriving at this practice's code address."},{"id":"first_check","label":"First check","state":"done","detail":"87 checks returned benefits in the last 30 days."}],"saved_logins":7,"code_email":{"address":"cedar-grove-family-dental@codes.veraxus.ai","receiving":true,"mail_seen":true},"ok_checks_30d":87,"last_ok_check_at":"2026-10-01T21:38:11.811Z"}]}}}},"400":{"description":"limit is not a whole number from 1 to 100.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, or cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The named practice is not on this company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/vault":{"get":{"tags":["Portal logins"],"summary":"List one practice's Portal vault","operationId":"listVaultLogins","description":"The console Portal vault as data: each payer portal the practice can keep a login for, the username and account email saved, whether a password and recovery code are on file, whether Veraxus has a sign-in login, and whether automatic sign-in is on. Passwords and recovery codes are never returned. To save a login use PUT /credentials or POST /portal/onboard. Automatic sign-in is switched in the console only. Requires the vault scope.","parameters":[{"name":"organization_id","in":"query","required":false,"description":"Practice id from GET /organizations. Required for a company-wide key on a single-practice route; a practice-bound key may omit it. The X-Organization-Id header is accepted as well.","schema":{"type":"string"}}],"responses":{"200":{"description":"The practice's vault with secrets removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VaultLoginsResponse"},"example":{"organization_id":"org_sample_cedar","logins":[{"id":"claimconnect","payer_id":"aetna","portal":"ClaimConnect","company":"Aetna Dental","portal_url":"https://www.aetna.com/provweb/","email":"cedar-grove-family-dental@codes.veraxus.ai","username":"cedargrove_office","has_password":true,"has_recovery_code":false,"sign_in_login_saved":true,"sign_in_login_differs":false,"sign_in_username":"cedargrove_office","auto_sign_in":true,"code_destination":"veraxus","updated_at":"2026-09-30T18:04:11.000Z"}]}}}},"400":{"description":"A company-wide credential did not name a practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, or cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The named practice is not on this company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/connector-requests":{"get":{"tags":["Practices"],"summary":"List a practice's connector requests","operationId":"listConnectorRequests","description":"Payer portals this practice has asked Veraxus to build, newest first, from the last 90 days. Requires the eligibility scope.","parameters":[{"name":"organization_id","in":"query","required":false,"description":"Practice id from GET /organizations. Required for a company-wide key on a single-practice route; a practice-bound key may omit it. The X-Organization-Id header is accepted as well.","schema":{"type":"string"}}],"responses":{"200":{"description":"The practice's requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorRequestListResponse"},"example":{"organization_id":"org_sample_lakeshore","requests":[{"id":"aud_5a6cc070","payer_name":"Sun Life Dental","portal_url":"https://provider.sunlife.example/login","requested_at":"2026-10-01T23:22:46.448Z"}]}}}},"400":{"description":"A company-wide credential did not name a practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, or cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The named practice is not on this company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}},"post":{"tags":["Practices"],"summary":"Ask for a payer portal that is not supported yet","operationId":"createConnectorRequest","description":"Records that a practice needs a payer portal Veraxus does not connect yet. Send the payer's name and, when known, where the office signs in. Do not send a username, password or patient detail: the body takes these fields only, and any other field is refused. The web address is stored as origin and path. Asking for the same payer again within 30 days returns the first request with already_requested true. It does not sign in, store a login, or contact the payer, and it does not promise a delivery date. Requires the vault scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorRequestCreate"},"example":{"organization_id":"org_sample_lakeshore","payer_name":"Sun Life Dental","portal_url":"https://provider.sunlife.example/login"}}}},"responses":{"200":{"description":"This payer was already requested for the practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorRequestCreateResponse"},"example":{"organization_id":"org_sample_lakeshore","already_requested":true,"request":{"id":"aud_5a6cc070","payer_name":"Sun Life Dental","portal_url":"https://provider.sunlife.example/login","requested_at":"2026-10-01T23:22:46.448Z"}}}}},"201":{"description":"The request was recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorRequestCreateResponse"},"example":{"organization_id":"org_sample_lakeshore","already_requested":false,"request":{"id":"aud_5a6cc070","payer_name":"Sun Life Dental","portal_url":"https://provider.sunlife.example/login","requested_at":"2026-10-01T23:22:46.448Z"}}}}},"400":{"description":"Missing or unusable payer_name, an unusable portal_url, or an unknown field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, or cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The named practice is not on this company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"This practice has sent 25 requests in the last 30 days.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/people":{"get":{"tags":["Account"],"summary":"List the people on the company account","operationId":"listPeople","description":"The console People page as data: everyone with console access to this company, with their role. Read-only; people are invited and removed in the console. Requires a company-wide key with the vault scope.","responses":{"200":{"description":"People with console access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeopleResponse"},"example":{"tenant_id":"tn_sample_juniper","people":[{"id":"usr_sample_avery","name":"Avery Stone","email":"avery@juniper-systems.example","role":"admin","added_at":"2026-09-12T15:30:00.000Z"}]}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A company-wide credential with the required scope is needed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/billing":{"get":{"tags":["Account"],"summary":"Read prices, this month's usage and invoices","operationId":"getBilling","description":"The console Billing page as data: the price of a live and a cached check, usage in the current billing month and the last 30 days, whether a payment method is on file, and recent invoices with their links. Card and bank details beyond brand and last four are never returned. Requires a company-wide key with the eligibility scope.","responses":{"200":{"description":"Billing summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingResponse"},"example":{"tenant_id":"tn_sample_juniper","price_cents":{"live":35,"cached":5},"current_period":{"start":"2026-10-01","end":"2026-11-01","cents":1120,"checks":32},"last_30_days":{"cents":4095,"checks":117},"payment_method":{"on_file":true,"brand":"visa","last4":"4242"},"invoices":[{"id":"in_sample_0001","number":"JUNIPER-0009","cents":3850,"status":"paid","hosted_url":"https://invoice.example/i/sample","pdf_url":"https://invoice.example/i/sample/pdf","created_at":"2026-10-01T00:05:00.000Z","period_start":"2026-09-01","period_end":"2026-09-30"}]}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A company-wide credential with the required scope is needed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/agreements":{"get":{"tags":["Account"],"summary":"Read which agreements are signed","operationId":"listAgreements","description":"The console Legal page as data: the Business Associate Agreement, Master Services Agreement and Statement of Work, each with its current version and whether that version is signed, when, and by whom. Agreements are signed by a person in the console; there is no API to sign one. Requires a company-wide key with the eligibility scope.","responses":{"200":{"description":"Agreement status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgreementsResponse"},"example":{"tenant_id":"tn_sample_juniper","agreements":[{"id":"baa","name":"Business Associate Agreement","version":"2026.08.31","signed":true,"signed_at":"2026-09-12T15:41:00.000Z","signer_name":"Avery Stone","signer_title":"Head of Operations"},{"id":"msa","name":"Master Services Agreement","version":"2026.09.01","signed":false,"signed_at":null,"signer_name":null,"signer_title":null},{"id":"sow","name":"Statement of Work","version":"2026.09.01","signed":false,"signed_at":null,"signer_name":null,"signer_title":null}]}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A company-wide credential with the required scope is needed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"/portal-logins/intake":{"post":{"tags":["Portal logins"],"summary":"Save every portal login from one practice submission","operationId":"savePortalLoginIntake","description":"Saves the logins a practice wrote on one onboarding submission, in one call. Each login is saved for sign-in (the PUT /credentials writer) and on the practice's Portal vault record with the email on the payer account. It stores logins only: it never signs in, never requests a code, and never turns automatic sign-in on. Requires the vault scope, a signed BAA, and the same consent as PUT /credentials: an approved HITL grant, or portal_login_mutation plus attestation. Consent is required whenever any row carries a login, for a catalog payer or not; a submission that stores no login needs none. A login for a portal outside the catalog is kept on a staff-only Portal Vault card for when that connector is built. A sign-in login is saved for any payer a practice can sign in to through Veraxus (sign_in_method connect or saved_password on GET /payers), whether its checks are available or still coming soon, and whether or not the company's payer list includes it: that list gates Eligibility, not setting up a login. This is what the staff Portals page lists and signs in from. A saved login whose portal is signed in right now is treated as proven: a different password for it is parked as serving_login_differs, never applied. Sending the same submission_id and revision again returns the stored result with Idempotency-Replayed: true and writes nothing a second time, so resending is the recovery path after a timeout. A higher revision applies corrections: a new password for the same username is saved; a different username is parked for a person. A lower revision than the newest applied returns status superseded. Rows that cannot be saved are parked with a reason and the rest of the call still applies. 4xx is permanent; 503 vault_unreadable and timeouts are safe to retry.","parameters":[{"$ref":"#/components/parameters/HitlGrant"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalLoginIntakeRequest"},"example":{"organization_id":"org_sample_lakeshore","npi":"1234567893","submission_id":"sheet_sample_0001","revision":1,"attestation":{"actor_user_id":"signer_sample_avery","consent_session_id":"sheet_sample_0001","consented_at":"2026-09-16T12:00:00.000Z"},"logins":[{"row_id":"s5r1","payer_id":"aetna","username":"lakeshore-frontdesk","password":"sample-not-a-real-password","account_email":"lakeshoredental@codes.veraxus.ai","account_action":"email_changed","mfa_enabled":true}],"requested_portals":[{"row_id":"s5r14","name":"Sample Mutual Dental","portal_url":"https://provider.samplemutual.example/login","username":"lakeshore-frontdesk","password":"sample-not-a-real-password","account_email":"lakeshoredental@codes.veraxus.ai","account_action":"account_created","mfa_enabled":true}],"top_carriers":[{"row_id":"s4r1","name":"Aetna","payer_id":"aetna","provider":"All providers","network":"in"}]}}}},"responses":{"200":{"description":"The submission was applied, or an earlier result was returned. Read status and each item's state.","headers":{"Idempotency-Replayed":{"description":"true when this is the stored result of an earlier identical call.","schema":{"type":"string","enum":["true"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalLoginIntakeReceipt"},"example":{"receipt_id":"pli_0f3a9c2d7b1e4a5c8d6f","organization_id":"org_sample_lakeshore","submission_id":"sheet_sample_0001","revision":1,"status":"needs_attention","code_email":{"address":"lakeshoredental@codes.veraxus.ai","receiving":true},"items":[{"row_id":"s5r1","kind":"login","payer_id":"aetna","state":"saved","reason":null,"message":"Login saved.","code_destination":"veraxus"},{"row_id":"s5r2","kind":"login","payer_id":"cigna","state":"parked","reason":"username_differs","message":"A login with a different username is already saved. A person replaces it in the Veraxus console."},{"row_id":"s5r14","kind":"requested_portal","payer_id":null,"state":"saved","reason":null,"message":"Login saved for when this portal is built. Connector requested.","code_destination":"veraxus"}],"top_carriers":[{"row_id":"s4r1","name":"Aetna","payer_id":"aetna","provider":"All providers","network":"in"}]}}}},"400":{"description":"invalid_request with field_errors (a path and message per bad field), or attestation_required when the consent record is missing, malformed, or older than 24 hours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"hitl_required without an approved grant or portal_login_mutation; baa_required; insufficient_scope; or the credential cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The named practice is not on this company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"organization_identity_mismatch when npi is not this practice's; intake_revision_conflict when this revision was already sent with different content; attempt_in_progress while another request is still saving this submission; read the result again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"description":"vault_unreadable. Nothing is final; send the same call again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Portal logins"],"summary":"Read the result of a saved submission","operationId":"getPortalLoginIntake","description":"Returns the stored result for a submission_id without sending the logins again. Use it after an ambiguous POST response. Pure read: it never saves, signs in, or contacts a payer. Requires the vault scope.","parameters":[{"name":"organization_id","in":"query","required":false,"description":"Practice from GET /organizations. Required for a company-wide key; a practice-bound key may omit it.","schema":{"type":"string"}},{"name":"submission_id","in":"query","required":true,"description":"The submission_id sent on POST /portal-logins/intake.","schema":{"type":"string"}}],"responses":{"200":{"description":"The newest applied revision's result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalLoginIntakeReceipt"},"example":{"receipt_id":"pli_0f3a9c2d7b1e4a5c8d6f","organization_id":"org_sample_lakeshore","submission_id":"sheet_sample_0001","revision":1,"status":"needs_attention","code_email":{"address":"lakeshoredental@codes.veraxus.ai","receiving":true},"items":[{"row_id":"s5r1","kind":"login","payer_id":"aetna","state":"saved","reason":null,"message":"Login saved.","code_destination":"veraxus"},{"row_id":"s5r2","kind":"login","payer_id":"cigna","state":"parked","reason":"username_differs","message":"A login with a different username is already saved. A person replaces it in the Veraxus console."},{"row_id":"s5r14","kind":"requested_portal","payer_id":null,"state":"saved","reason":null,"message":"Login saved for when this portal is built. Connector requested.","code_destination":"veraxus"}],"top_carriers":[{"row_id":"s4r1","name":"Aetna","payer_id":"aetna","provider":"All providers","network":"in"}]}}}},"400":{"description":"submission_id is missing, or a company-wide credential did not name a practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the vault scope, or cannot access this practice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"intake_not_found, or the named practice is not on this company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"attempt_in_progress while another request is still saving this submission; read the result again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}}},"webhooks":{"eligibility.completed":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_eligibility_completed","summary":"Receive eligibility.completed","description":"Veraxus POSTs eligibility.completed to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["eligibility.completed"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"eligibility.failed":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_eligibility_failed","summary":"Receive eligibility.failed","description":"Veraxus POSTs eligibility.failed to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["eligibility.failed"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"claim.submitted":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_claim_submitted","summary":"Receive claim.submitted","description":"Veraxus POSTs claim.submitted to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["claim.submitted"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"claim.acknowledged":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_claim_acknowledged","summary":"Receive claim.acknowledged","description":"Veraxus POSTs claim.acknowledged to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["claim.acknowledged"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"claim.rejected":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_claim_rejected","summary":"Receive claim.rejected","description":"Veraxus POSTs claim.rejected to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["claim.rejected"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"claim.failed":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_claim_failed","summary":"Receive claim.failed","description":"Veraxus POSTs claim.failed to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["claim.failed"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"claim.unknown_outcome":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_claim_unknown_outcome","summary":"Receive claim.unknown_outcome","description":"Veraxus POSTs claim.unknown_outcome to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["claim.unknown_outcome"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"claim.reconciled":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_claim_reconciled","summary":"Receive claim.reconciled","description":"Veraxus POSTs claim.reconciled to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["claim.reconciled"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"claim.voided":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_claim_voided","summary":"Receive claim.voided","description":"Veraxus POSTs claim.voided to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["claim.voided"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"claim.cancelled":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_claim_cancelled","summary":"Receive claim.cancelled","description":"Veraxus POSTs claim.cancelled to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["claim.cancelled"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"claim.adjudication_updated":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_claim_adjudication_updated","summary":"Receive claim.adjudication_updated","description":"Veraxus POSTs claim.adjudication_updated to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["claim.adjudication_updated"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"claim.attachment_uploaded":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_claim_attachment_uploaded","summary":"Receive claim.attachment_uploaded","description":"Veraxus POSTs claim.attachment_uploaded to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["claim.attachment_uploaded"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"claim.attachment_failed":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_claim_attachment_failed","summary":"Receive claim.attachment_failed","description":"Veraxus POSTs claim.attachment_failed to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["claim.attachment_failed"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"claim.staged":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_claim_staged","summary":"Receive claim.staged","description":"Veraxus POSTs claim.staged to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["claim.staged"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"claim.stage_failed":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_claim_stage_failed","summary":"Receive claim.stage_failed","description":"Veraxus POSTs claim.stage_failed to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["claim.stage_failed"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"claim.arrived_in_portal":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_claim_arrived_in_portal","summary":"Receive claim.arrived_in_portal","description":"Veraxus POSTs claim.arrived_in_portal to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["claim.arrived_in_portal"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"portal_login.desk_changed":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_portal_login_desk_changed","summary":"Receive portal_login.desk_changed","description":"Veraxus POSTs portal_login.desk_changed to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["portal_login.desk_changed"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"portal_login.status_changed":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_portal_login_status_changed","summary":"Receive portal_login.status_changed","description":"Veraxus POSTs portal_login.status_changed to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["portal_login.status_changed"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"portal_login.state_changed":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_portal_login_state_changed","summary":"Receive portal_login.state_changed","description":"Veraxus POSTs portal_login.state_changed to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["portal_login.state_changed"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"webhook.test":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_webhook_test","summary":"Receive webhook.test","description":"Veraxus POSTs webhook.test to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["webhook.test"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}},"webhook.deactivated":{"post":{"tags":["Webhooks"],"operationId":"receiveWebhook_webhook_deactivated","summary":"Receive webhook.deactivated","description":"Veraxus POSTs webhook.deactivated to the registered HTTPS callback. HMAC-signed as Veraxus-Signature. Payloads never include PHI. Acknowledge with 2xx; HTTP 3xx is a failure.","parameters":[{"name":"Veraxus-Event","in":"header","required":true,"schema":{"type":"string","enum":["webhook.deactivated"]},"description":"Event type for this delivery."},{"name":"Veraxus-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery attempt id (whd_…)."},{"name":"Veraxus-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"demo","type":"eligibility.completed","createdAt":"demo","tenantId":"demo","organizationId":"demo","data":{"checkId":"demo","payerId":"demo","status":"ok","enrichment":"complete","resultUrl":"demo"}}}}},"responses":{"200":{"description":"Vendor acknowledged the delivery."},"400":{"description":"Vendor rejected the payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"}}}}},"x-mcp":{"url":"https://api.veraxus.ai/mcp","transport":"streamable-http","protocolVersion":"2026-07-28","protocolVersions":["2026-07-28","2025-11-25","2025-06-18","2025-03-26"],"lifecycle":{"modern":"stateless server/discover and per-request metadata","legacy":"initialize handshake compatibility through 2025-11-25"},"oauth":{"authorization_server":"https://app.veraxus.ai"}}}