Check Eligibility - Nanonets Agents Platform

This document covers eligibility_check, the insurance eligibility tool exposed through the Agents Platform. The tool checks a patient’s coverage with an eligibility vendor and returns plan status, deductibles, out-of-pocket figures, copays and coinsurance. Stedi is the default vendor. When Stedi cannot answer, the tool retries the same check on pVerify.

Authentication and enablement

The tool uses Nanonets-wide vendor accounts, so the agent supplies no credentials. It is off by default; enable it on the agent. Stedi needs STEDI_API_KEY set on the worker. When it is not set, every call goes to pVerify.

Inputs

Required:

patient_first_name, patient_last_name
patient_dob: MM/DD/YYYY.
patient_state: 2-letter code. It is used to prefer an in-state payer match.
insurance_carrier_name: the carrier as a human would write it, such as Aetna or Blue Cross Blue Shield of California.
member_id
provider_npi, provider_first_name, provider_last_name: the rendering provider.

Optional:

appointment_date: YYYY-MM-DD. Defaults to tomorrow. The date of service runs from the day after this date to the day after that.
practice_type_code: 21 checks mental-health benefits (X12 service type MH). Leave it empty for general plan coverage (X12 30).
provider: stedi (the default) or pverify. With stedi, a failed Stedi check is retried on pVerify. With pverify, Stedi is not called.

Vendor selection and fallback

With provider: "stedi" the tool does the following:

It resolves the carrier name to a Stedi payer ID through Stedi’s payer search. Only payers that support eligibility are considered, and one operating in patient_state is preferred.
It sends a real-time eligibility check. A date of service in the future is sent as today, because CMS rejects future dates.
It falls back to pVerify if any of these happens: Stedi is not configured, no payer matches, the request fails, Stedi returns a non-200 status, or the payer refuses the lookup and returns no plans (an AAA error such as “Subscriber Not Found”).

When pVerify is used, the carrier name is matched to a pVerify payer code by an LLM against pVerify’s payer list.

Outputs

structuredContent has the same shape whichever vendor answers:

Field	Meaning
`provider`	`stedi` or `pverify`: the vendor that answered
`fallback_reason`	Why Stedi was skipped. Present only on a pVerify answer that followed a Stedi attempt.
`fallback_code`	A short code for that reason, such as `payer_unmatched`, `payer_error_75` or `http_451`. Present with `fallback_reason`.
`payer_code`, `payer_name`	The vendor’s payer ID and name
`dos_start`, `dos_end`	The date-of-service range, `MM/DD/YYYY`
`eligibility`	The response in pVerify’s `EligibilitySummary` shape (`PlanCoverageSummary`, `HBPC_Deductible_OOP_Summary`, `MentalHealthSummary`, `MiscellaneousInfoSummary`, …)
`ambiguous_tiers`	Stedi only. True when the payer returned several different mental-health copay or coinsurance values on one network side. The first value is used.
`stedi_response`	Stedi only. The raw Stedi response without its X12 echo, for fields the pVerify shape does not carry. Kept on the step and in `${VAR_n}`, but not shown to the model.

On a Stedi answer, eligibility fills plan status, plan name, policy type, plan dates, gender, network flag, member ID, the deductible and out-of-pocket figures, and the mental-health copay, coinsurance and covered flags. Stedi errors returned alongside plans (for example one service type refused) go into ExceptionNotes and do not mark the check as failed. pVerify-only sections stay empty: Medicare, coordination of benefits, specialist office, PCP/auth and the payer’s free-text notes. Read those from stedi_response when a step needs them. A benefit the payer did not return is left blank. It is never reported as $0.00. The result is registered as an eligibility_check task variable, so a later step can pass ${VAR_n}.eligibility.PlanCoverageSummary. It is not injected into calls automatically.

Monitoring

Every call writes one log line, eligibility_check: vendor outcome, carrying field_agent_id, field_agent_group_id, field_workspace_id, field_task_id, eligibility_vendor (stedi, pverify, or none when no vendor answered), and stedi_fallback_code (pverify_requested when the call set provider: "pverify" and Stedi was not tried). The line holds IDs and codes only, never patient or payer text. In Loki:

sum by (field_agent_group_id, eligibility_vendor) (
  count_over_time({service_name="nanonets-agents"} |= "eligibility_check: vendor outcome" [24h])
)

The stored step records the same thing, so counts can also come from the database. Match on base_tool_name: agents can call the tool under an alias, such as aph_eligibility_check. fallback_code is set on a pVerify answer that followed a Stedi attempt, for example payer_unmatched, payer_error_75, http_451 or not_configured. Steps from before Stedi carry no provider and count as pVerify.

SELECT a.agent_group_id, max(a.name) AS agent,
       CASE WHEN (s.result::jsonb->>'isError')::boolean THEN 'failed'
            ELSE coalesce(s.result::jsonb->'structuredContent'->>'provider', 'pverify') END AS vendor,
       s.result::jsonb->'structuredContent'->>'fallback_code' AS fallback_code,
       count(*) AS checks
FROM steps s JOIN agents a ON a.id = s.agent_id
WHERE coalesce(s.base_tool_name, s.tool_name) = 'eligibility_check' AND s.status = 'completed'
  AND s.created_at > now() - interval '7 days'
GROUP BY 1, 3, 4 ORDER BY 1, checks DESC;

Errors

The tool returns an error when the arguments are invalid, or when pVerify also fails after a Stedi attempt. In the second case the message carries both failures.

Cost and side effects

Each vendor call is a billable eligibility transaction. A fallback makes two calls. The tool does not write to any EHR. Use an EHR’s push-eligibility-results tool for that.

​Authentication and enablement

​Inputs

​Vendor selection and fallback

​Outputs

​Monitoring

​Errors

​Cost and side effects