Get your first simulated eligibility result.

What machine-to-machine means

Your server sends JSON directly to Verora and receives JSON back. No team member has to retype the case into a portal, and no patient-facing browser stores the integration secret. An MCP client can put a natural-language assistant on top of this same API; the API remains the single source of truth.

Step 1 — Exchange your client credential

Client credentials are environment-bound. The resulting access token is short-lived and used only by your server.

curl --request POST https://dev.veroraai.com/api/oauth/token \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$VERORA_CLIENT_ID" \
  --data-urlencode "client_secret=$VERORA_CLIENT_SECRET"

Step 2 — Send the scheduled appointment

Every verification requires an Idempotency-Key. Include one scheduled_treatment with a service date and one line per billable procedure. Fees are whole cents; omit a fee instead of guessing. Reusing the key for the same logical request safely returns the original job.

curl --request POST https://dev.veroraai.com/api/v1/verifications \
  --header "Authorization: Bearer $VERORA_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: treatment-example-001" \
  --data '{
    "customer_reference": "treatment-example-001",
    "patient": {
      "first_name": "Taylor",
      "last_name": "Example",
      "date_of_birth": "1990-01-01"
    },
    "coverages": [{
      "role": "primary",
      "payer": { "id": "sandbox-payer" },
      "member_id": "sandbox-member-001",
      "relationship_to_subscriber": "self"
    }],
    "provider": { "npi": "1234567893" },
    "service_date": "2026-08-10",
    "scheduled_treatment": {
      "treatment_reference": "treatment-001",
      "appointment_reference": "appointment-001",
      "procedures": [
        {
          "procedure_reference": "line-001",
          "code": "D1110",
          "fee_cents": 12000
        }
      ]
    },
    "test": { "scenario": "verified" }
  }'

Step 3 — Read the normalized result

Use the verification ID from the accepted response. Store it alongside your own reference so operations can trace a single request without exposing raw payer responses.

curl --request GET "https://dev.veroraai.com/api/v1/verifications/$VERORA_VERIFICATION_ID" \
  --header "Authorization: Bearer $VERORA_ACCESS_TOKEN"

{
  "verification_id": "elig_01H9...",
  "status": "succeeded",
  "environment": "sandbox",
  "simulated": true,
  "result": {
    "outcome": "eligible",
    "source": "payer",
    "treatment_analysis": {
      "status": "complete",
      "service_date": "2026-08-10",
      "totals": {
        "fee_cents": 12000,
        "estimated_insurance_cents": 7000,
        "estimated_patient_cents": 5000
      }
    },
    "coverage_opportunities": [],
    "data_requests": [
      {
        "field": "procedure_history",
        "code": "D0274",
        "status": "confirmation_required",
        "reason": "frequency_not_confirmed",
        "requested_facts": ["last_service_date", "completed_occurrence_count"]
      }
    ]
  }
}

What the partner gathers

1. Treated patient: name and date of birth only.
2. Coverage identity: exactly one primary coverage and, when present, one secondary. Each coverage carries payer ID or name, member ID, relationship to subscriber, and group number when available. For a non-self relationship, include the subscriber's first name, last name, and date of birth; Verora never assumes a missing relationship is self.
3. Treating provider: the NPI that should be used for the eligibility check.
4. Appointment facts: service date plus scheduled CDT codes, tooth number, and surfaces when relevant.
5. Office fees: the submitted fee for each line so Verora can calculate dollars instead of only percentages.
6. Missing facts: read missing_information and data_requests, then let the partner's agent ask the office only for what would materially improve the answer.

The verification API does not write to the PMS. The partner gathers these facts from systems it is already authorized to access—such as its PMS integration, scheduling, or digital intake—and controls how the verification result is displayed. Separately licensed EOB posting requires a practice-approved, certified integration. Never include PMS credentials in API requests or agent prompts.

The value Verora adds

The result includes treatment_analysis for estimated insurance and patient dollars, assumptions, caveats, and exact missing inputs. It also includes filtered coverage_opportunities only when frequency is positively cleared. Unknown frequency is returned as a non-actionable data_requests item. The response does not expose Verora’s internal rules, traces, scores, raw payer payloads, or clinical decision logic.

When both primary and secondary plans independently verify, cob_estimate provides a labeled pre-service estimate or bounded range. It never claims to be an adjudicated patient balance, and an unknown coordination method remains an explicit pending fact.

Step 4 — Answer only the history Verora requests

If data_requests names procedure_history, retrieve only that CDT code's exact last completed date and count from a partner-authorized source. Submit it as an immutable revision. A zero count requires a null date. Do not send appointment notes or invent a frequency rule.

curl --request POST "https://dev.veroraai.com/api/v1/verifications/$VERORA_VERIFICATION_ID/revisions" \
  --header "Authorization: Bearer $VERORA_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: history-answer-001" \
  --data '{
    "changed_facts": {
      "procedure_history": [{
        "code": "D0274",
        "last_service_date": "2026-02-01",
        "completed_occurrence_count": 1,
        "source": "partner_pms",
        "source_reference": "history-27"
      }]
    }
  }'

Step 5 — Retrieve the filtered Benefit Form

When capabilities reports benefit_form_artifacts: true, retrieve HTML by default or request PDF. The response headers bind the form to the exact result revision, result hash, and artifact hash. This is still a pre-service estimate—not a promise of payment.

curl --request GET "https://dev.veroraai.com/api/v1/verifications/$VERORA_VERIFICATION_ID/benefit-form" \
  --header "Authorization: Bearer $VERORA_ACCESS_TOKEN" \
  --header "Accept: application/pdf" \
  --output verora-benefit-form.pdf

Reference

Start with capability discovery and the verification lifecycle. Credentials select the environment; callers never put an environment selector in the request body. Revisions and feedback are optional Release 2 operations—check capabilities before using them.

• POST /api/oauth/token — exchange one environment-bound client credential for a short-lived access token.
• GET /api/v1/capabilities — read the authenticated public feature and minimum-fact profile.
• POST /api/v1/verifications/validate — free pre-flight validation (no queue, no payer dial, no billable usage).
• POST /api/v1/verifications — queue one verification. Optional force_fresh: true always dials the payer (still billable). Returns 202 Accepted and the verification ID.
• GET /api/v1/verifications/{verificationId} — retrieve status and result. from_cache / verified_at label freshness; verified_at is when the payer was contacted, not when the cache was served.
• GET /api/v1/payers?q=… — search payers; returned id values are accepted as coverages[].payer.id.
• GET /api/v1/developer/usage — partner usage/quota for this credential (unpriced accounts are labeled, never shown as $0).
• GET /api/v1/verifications/{verificationId}/benefit-form — retrieve feature-gated filtered HTML or canonical PDF bound to the immutable result.
• POST /api/v1/verifications/{verificationId}/revisions — create an immutable successor from corrected facts when enabled.
• POST /api/v1/verifications/{verificationId}/feedback — record append-only evidence using the returned result revision and hash when enabled.

Install the Verora agent plugin

One client supports Codex and Claude Code. Use Node.js 22 or newer, verify the checksum, and extract the plugin into a stable folder. The download contains no credentials or private Verora engines; your application license determines the available workflows.

Download plugin v0.2.0 · SHA-256 checksum

curl --fail --location --remote-name https://dev.veroraai.com/plugins/verora/verora-plugin-0.2.0.zip
curl --fail --location --remote-name https://dev.veroraai.com/plugins/verora/verora-plugin-0.2.0.zip.sha256
shasum -a 256 -c verora-plugin-0.2.0.zip.sha256
unzip verora-plugin-0.2.0.zip

Set VERORA_API_BASE_URL to https://dev.veroraai.com without an API path. Inject your own VERORA_CLIENT_ID and VERORA_CLIENT_SECRET through the agent launcher's environment or your secret manager. Use a sandbox credential first. Keep credentials out of command arguments, repository files and agent conversations. Each credential selects its approved application environment.

codex plugin marketplace add /absolute/path/to/verora-plugin-0.2.0
codex plugin add verora@verora

claude --plugin-dir /absolute/path/to/verora-plugin-0.2.0/plugins/verora

Replace the absolute path with your extracted folder. Restart existing agent sessions after configuring their launch environment. Ask the agent to call whoami, inspect get_capabilities, and discover its licensed tools before testing. Confirm the intended account and sandbox environment before submitting the synthetic verification above. Sandbox calls omit practice workspace IDs.

Claim and received EOB workflows require separate permissions from your Verora operator. The extracted README includes the simulated verification-to-EOB pilot and receipt replay check. Live environments expose only your customer-approved practice workspaces. EOB automation defaults off; live posting additionally requires the practice's explicit policy and native certification. Preparing an EOB does not post a payment.

Sandbox scenarios

Set test.scenario only in sandbox. Scenarios are deterministic so your CI suite has stable expected outcomes.

• verified — Eligible result. A successful simulated eligibility response.
• inactive — Ineligible result. A completed response with inactive coverage.
• incomplete — Unknown result. A normalized result that requires more data.
• manual_review — Unknown result. A fixture for your manual-review branch.
• payer_timeout — Retryable failure. A deterministic failed job to exercise safe retry handling.

Live testing is a controlled readiness gate

It performs real eligibility checks. It is deliberately not a switch on a sandbox request or a self-service signup funnel. Accounts are sales-assisted. Live / live_test access requires: an executed SBAA recorded by a Verora operator, per-application environment approval, an operator-provisioned developer workspace bound to a practice with NPI + tax ID, a matching provider NPI on each request, and commercial terms set by Verora (unpriced accounts do not invent a rate). test.scenario is rejected on live credentials with test_scenario_not_permitted — it is never silently ignored.

Errors & support

Keep the environment, verification ID, request ID, UTC timestamp, and error code. Do not send authorization headers or patient details to support.

About webhooks. Poll the verification URL as the source of truth. When GET /api/v1/capabilities reports signed_webhooks: true, feature-gated REST endpoint registration and replay are available for at-least-once notifications. Keep signing secrets in a server-side secret manager; polling remains canonical.