> ## Documentation Index
> Fetch the complete documentation index at: https://agents.nanonets.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Check Eligibility

> Runs a real-time insurance eligibility check on Stedi, falling back to pVerify.

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:

1. 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.
2. It sends a real-time eligibility check. A date of service in the future is sent as today, because CMS rejects future dates.
3. 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:

```logql theme={null}
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.

```sql theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.