Verification 101 - Instantly Confirming Coverage and Benefits

Once you've identified a patient's payer, the next question is: "Are they covered?" Verification answers that asynchronously so your app stays fast and resilient.

How Verification Works

  • Fire-and-forget: You submit a Verification request, we immediately return an ID
  • Processing window: We resolve the request typically in seconds (P90 = 10 seconds) with a maximum resolution time of 24 hours for edge cases
  • No client retries needed: While a request is processing, a call to the Get Verification API will return a "pending" status until it's complete
  • One check per month: Eligibility rarely changes daily, cache results and re-verify monthly (or sooner if the patient reports a change)

Webhooks

Best for real-time UX and fewer network calls - this is our recommended approach.

  • Immediate updates when payers respond
  • Minimal polling/infra noise
  • Easy to build out API orchestrations

Polling

If you can't host webhooks yet, poll the Get Verification API until the status is no longer "pending".

  • Poll with backoff (e.g., 1s → 2s → 4s → stop by 24h or earlier if done)
  • Stop polling when the status is not "pending"
async function waitForVerification(id) {
    let delay = 1000;
    const deadline = Date.now() + 24*60*60*1000;
    while (Date.now() < deadline) {
    	const v = await api(`/v2/verifications/${id}`);
        if (v.status !== "pending") return v;
        await new Promise(r => setTimeout(r, delay));
        delay = Math.min(delay * 2, 15000);
    }
    throw new Error('verification_timeout_24h');
}

What You Get Back

When complete, a Verification includes:

  • Eligibility: eligible/ineligible and a timestamp
  • Plan details: plan name, coverage dates
  • Benefits: copay, coinsurance, deductible, out-of-pocket

Store and display the Verification payload and timestamp until the beginning of the next month.

Practical Guidance

  • Don't retry POSTs for "time out" concerns - just use the returned verificationId and wait (webhook or GET)
  • Monthly cadence: Re-verify on a schedule (e.g., first of the month) or on patient-triggered events (new card, appointment scheduled)
  • Downstream chaining: Once the request is complete, trigger Network Status automatically

Where This Fits in Flows

  • Discovery → Verification: confirm coverage after finding the payer and member ID
  • Verification → Network Status: determine network status for the patient