How to show network status to patients without overpromising.

Three states, and what each one means

1. Listed. The insurer's directory for this plan lists the provider. In the API: in_network: true, answer: "listed", and at least one item in evidence, each with source.type and source.as_of.
2. No listing found in current data. The current directory data for this plan has no listing for this provider. In the API: in_network: null, answer: "not_found", an empty evidence list, and an explanation that says so in plain words.
3. Unknown. You have no answer to show. The request failed or was busy, the plan ID did not match a plan (the response then has plan: null and no as_of), or the patient has not told you their plan yet.

The API never returns in_network: false. That is on purpose. A directory can lag behind a new contract, list a provider under a group rather than by name, or be read before a change. "We did not find it" is a true statement. "They are out of network" is a guess. Every response repeats this in its notes.

One provider shows two of the states side by side:

# one provider, two marketplace plans in North Carolina
curl -H "Authorization: Bearer $INPLAN_KEY" \
  "https://api.inplan.io/v1/check?npi=1376006148&plan_id=17414NC0010004"
curl -H "Authorization: Bearer $INPLAN_KEY" \
  "https://api.inplan.io/v1/check?npi=1376006148&plan_id=73943NC0070030"

17414NC0010004  AmeriHealth Caritas Next Bronze Essential + No Referrals
  "in_network": true, "answer": "listed",
  "explanation": "The insurer's network directory lists this provider for this plan.",
  "evidence": [{ "plan_year": 2026, "network_tier": "PREFERRED",
                 "source": { "type": "insurer_directory", "as_of": "2026-08-12" } }]

73943NC0070030  Connect Silver 3600 Indiv Med Deductible
  "in_network": null, "answer": "not_found",
  "explanation": "No listing found in current directory data for this provider and plan.",
  "evidence": []

Never turn "not found" into "out of network"

The most common mistake is one line of code: inNetwork ? "In network" : "Out of network". A null falls into the second branch and becomes a claim nobody made. Treat null as its own state with its own label, colour and next step. A grey "Not found" with a prompt to confirm is honest. A red "Out of network" is not.

Map the response to a status in one place, and make every screen read that status:

type Status = 'listed' | 'not_found' | 'unknown';

function statusFor(httpStatus: number, body: any): Status {
  if (httpStatus !== 200) return 'unknown';         // busy, timeout, rate_limited, ...
  const d = body.data;
  if (d.in_network === true && d.evidence.length > 0) return 'listed';
  if (d.answer === 'not_found' && d.plan && d.as_of) return 'not_found';
  return 'unknown';                                 // plan ID did not match, or an answer you do not handle
}

Some plans have no provider network to check, such as a stand-alone drug plan. The API answers those with no_provider_network. The right UI for that answer is no network badge at all.

Show the directory date

Every listing carries the date its directory was read, in evidence[].source.as_of. Show it next to the answer, in words a patient reads quickly: "Insurer directory, read 12 Aug 2026". Do not write "live" or "real-time". A date tells the patient how much weight to give the answer. For a not-found answer, show the top-level as_of: the date of the data behind that answer.

Per plan, per location, per year

Network status belongs to a plan, not to an insurer or a provider. The family physician above is listed in 199 marketplace plans from 8 insurers and 146 Medicare Advantage plans from 4 organizations, and still has no listing in the Cigna silver plan we checked. So:

• Ask for the plan, not the insurer. "Do you take Cigna?" has no single answer. Show the plan name from plan.plan_name next to the badge so the patient can compare it with their card.
• Name the location. A provider who works at several offices may not be in network at every one. Show the address the patient will visit, and ask them to confirm that location when they book.
• Keep plan years apart. evidence[].plan_year says which year a listing is for. A listing for next year's plan is not a listing for this year's.
• Show the extra fields as the directory's words. network_tier (for example PREFERRED) can change what a visit costs. accepting_new_patients on Medicare Advantage listings is what the directory says, not a booking guarantee. Write "Directory says: accepting new patients".

Check again before booking

Search results can use a cached answer; booking should not. Call /v1/check again when the patient confirms a time, store the request_id and as_of with the appointment, and show the patient the same answer they will be held to. If the second call comes back unknown, let the booking go ahead without a network badge and tell the patient to confirm with the plan.

Wording that works, and wording to avoid

Name the provider with their credential ("Jane Rivera, MD"), and keep the wording the same on search, profile and booking screens.

What the three states look like

[ Listed ]  Jane Rivera, MD
Listed in AmeriHealth Caritas Next Bronze Essential + No Referrals
Insurer directory, read 12 Aug 2026 · Preferred tier
Directories change. Confirm with the office when you book.

[ Not found ]  Jane Rivera, MD
We did not find this provider in the directory for
Connect Silver 3600 Indiv Med Deductible (data as of 27 Jul 2026).
This does not mean they are out of network. Ask the plan or the office.

[ Unknown ]  Jane Rivera, MD
We could not check this plan right now.
Choose your plan, or call the number on your insurance card.

The provider name is illustrative; the plans and dates are the real answers above. Field details: answers and evidence. Why status is per plan: NPI vs plan network. Run both calls in the playground with no key.