Sometimes you don't have an insurance card or payer information - just a patient's name, date of birth, and address. The Discovery API fills that gap, helping your app identify active coverage before running any eligibility or benefit checks.

How Discovery Works

  • Minimal inputs: Typically firstName, lastName, dateOfBirth, and state
  • Search and match: Discovery queries payer networks and other data sources to find potential coverage matches
  • Optimised for speed: The first successful match is returned via webhook (P95 < 15 seconds) to ensure the patient is not kept waiting
  • False positives: zipCode can be included in the request to filter out any false positives that might be returned

Webhooks

As with other asychronous Sohar APIs, webhooks are our recommended approach.

  • Immediate updates when a match is found
  • Minimal polling/infra noise
  • Easy to build out API orchestrations

Polling

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

  • Poll with backoff (e.g., 1s → 2s → 4s → stop by 1m or earlier if done)
  • Stop polling when the status is not "pending"

We can build upon our polling function for Verification, making it generic to also handle the Discovery API.

async function waitForResponse<T extends { status: string }>(
  url: string,
  maxDurationMs: number // e.g. 24 * 60 * 60 * 1000 for 24h, or 60 * 1000 for 1m
): Promise<T> {
  let delay = 1000;
  const deadline = Date.now() + maxDurationMs;
  while (Date.now() < deadline) {
    const response = await api<T>(url);
    if (response.status !== "pending") return response;
    await new Promise((resolve) => setTimeout(resolve, delay));
    delay = Math.min(delay * 2, 15000);
  }
  throw new Error("response_timeout");
}

What You Get Back

If successful, a complete Discovery response includes:

  • Payer information: the matched payer name and ID
  • Member data: member ID and updated demographic information

Practical Guidance

  • Clean inputs: Even minor typos or formatting errors can affect match quality
  • Cache results: Reuse Discovery results across the patient's next visits or re-verifications
  • Use Verification next: Discovery is designed as a precursor - once you know the payer, confirm coverage through Verification

Where This Fits in Flows

  • Discovery → Verification: Find the payer, then confirm eligibility and benefits
  • Discovery → Verification → Cost Estimate: Go from unknown coverage to full transparency
  • Verification → Discovery: Identify a secondary payer for coordination of benefits