Explorer/API Reference/Eligibility Adapter API
Eligibility Adapter API v1.0.0 Stable 3 endpoints
Domain: eligibility-adapter · API spec: packages/resolved/eligibility-adapter-openapi.yaml

Contracted interface for the state-provided eligibility evaluation adapter. The blueprint calls these endpoints to perform program eligibility evaluations. States implement this interface against whatever backend system they use — a rules engine, a legacy case management platform, or any other system. The blueprint treats the adapter as a black box.

Each call represents one evaluation for one application and one program. All request schemas extend AdapterRequest, which includes a metadata passthrough field the blueprint sets for correlation. Adapters must echo metadata back unchanged in the response. See docs/architecture/cross-cutting/adapters.md.

Base URL: https://adapter.example.com

Evaluate

Eligibility evaluation endpoints.

▶ POST /evaluate/expedited-screening Evaluate expedited SNAP screening

Determines whether an application qualifies for expedited SNAP processing based on household-level financial criteria (7 CFR § 273.2(i)). Called at submission before caseworker assignment. Member-level data is not required for the baseline criteria; states may extend the request via overlay if their rules engine needs additional context.

Request body required
▶ ExpeditedScreeningRequest
metadata object Opaque correlation context set by the blueprint. Echo back unchanged in the response. The adapter must not inspect or modify this field.
▶ household Household required Household-level data used in SNAP expedited screening criteria.
roomers array[object] Non-household members who share the living space and pay rent separately.
type string required Whether the roomer is a household member counted in another capacity or a non-member contact.
enummember contact
id string (uuid) required Identifier of the member or contact record.
amountPaidForRent number (float) Amount the roomer pays for rent.
mealsIncludedWithRent boolean Whether meals are included with the roomer's rent payment.
utilitiesIncludedInRent boolean Whether utility costs are included in the rent payment.
isSubsidizedHousing boolean Whether the household lives in subsidized or public housing. Affects the SNAP utility standard deduction.
receivedTanfInAnotherState boolean Whether the household has received TANF benefits in another state. Required for multi-state TANF coordination.
Responses
200 Expedited screening result.
▶ ExpeditedScreeningResponse
metadata object required Echoed back unchanged from the request. The blueprint uses this to map the response to its internal records without exposing resource identities to the adapter.
expedited boolean required Whether the application qualifies for expedited SNAP processing.
400 The request is malformed or contains invalid parameters.
▶ BadRequest
code string required Machine-readable error code.
message string required Human-readable error description.
details array[object] Additional error details.
500 An unexpected error occurred on the server.
▶ InternalError
code string required Machine-readable error code.
message string required Human-readable error description.
details array[object] Additional error details.
▶ POST /evaluate/medicaid-ex-parte Evaluate Medicaid ex parte

Determines Medicaid eligibility for one applicant using electronic data exchange results, without requiring applicant-provided documentation. Called once per applicant after all Medicaid electronic checks complete. Applications that can be fully determined ex parte are closed automatically without caseworker intervention (42 CFR § 435.916).

Request body required
▶ MedicaidExParteRequest
metadata object Opaque correlation context set by the blueprint. Echo back unchanged in the response. The adapter must not inspect or modify this field.
program string required The program being evaluated.
enumsnap medicaid chip tanf aca
member object required The applicant being evaluated.
income array[oneOf] Income records for this member.
expenses array[object] Expense records for this member.
assets array[oneOf] Asset records for this member.
employment array[oneOf] Employment records for this member.
healthCoverage array[oneOf] Health coverage records for this member.
▶ electronicChecks array[ElectronicCheckResult] required Results from FDSH FTI, FDSH Medicare/VCI, and other Medicaid data exchange calls for this applicant.
serviceType string The data exchange service that performed the check.
enumfdsh_ssa fdsh_vlp fdsh_fti fdsh_medicare fdsh_vci ssa_ievs irs_ievs swica uib save enrollment_check incarceration_check
result string High-level outcome of the service call.
enumconclusive inconclusive partial error
receivedAt string (date-time) When the result was received.
serviceResult object Service-type-specific result payload. Shape varies by serviceType — see data-exchange-adapter-openapi.yaml for the schema per service type.
Responses
200 Medicaid ex parte evaluation result.
▶ ProgramDecision
metadata object required Echoed back unchanged from the request. The blueprint uses this to map the response to its internal records without exposing resource identities to the adapter.
program string required The program this decision applies to.
enumsnap medicaid chip tanf aca
▶ status DecisionStatus required The eligibility outcome.
No additional fields
▶ path DecisionPath How the decision was reached.
No additional fields
denialReasonCode string Machine-readable reason code when status is denied or ineligible.
400 The request is malformed or contains invalid parameters.
▶ BadRequest
code string required Machine-readable error code.
message string required Human-readable error description.
details array[object] Additional error details.
500 An unexpected error occurred on the server.
▶ InternalError
code string required Machine-readable error code.
message string required Human-readable error description.
details array[object] Additional error details.
▶ POST /evaluate/determination Evaluate final determination

Runs final eligibility determination for one applicant (or household) and one program after caseworker review is complete. Called once per program with pending decisions after intake.application.review_completed fires.

Use IndividualDeterminationRequest for per-applicant programs (medicaid, chip, tanf, ccdf) and HouseholdDeterminationRequest for household programs (snap).

Request body required
Variant 1
metadata object Opaque correlation context set by the blueprint. Echo back unchanged in the response. The adapter must not inspect or modify this field.
program string required The program being evaluated.
enumsnap medicaid chip tanf aca
member object required The applicant being evaluated.
income array[oneOf] Income records for this member.
expenses array[object] Expense records for this member.
assets array[oneOf] Asset records for this member.
employment array[oneOf] Employment records for this member.
healthCoverage array[oneOf] Health coverage records for this member.
verificationSummary array[object] required Status of verification obligations relevant to this applicant and program.
category string The type of verification (e.g., income, identity, residency).
status string Current status of the verification obligation.
enumpending inconclusive satisfied waived cannot_verify
memberId string (uuid) Identifier of the intake domain member this verification applies to. Passed through from intake for correlation — the adapter does not resolve this identifier.
Variant 2
metadata object Opaque correlation context set by the blueprint. Echo back unchanged in the response. The adapter must not inspect or modify this field.
program string required The program being evaluated.
enumsnap medicaid chip tanf aca
members array[object] required All members in the household benefit unit.
income array[oneOf] Income records for this member.
expenses array[object] Expense records for this member.
assets array[oneOf] Asset records for this member.
employment array[oneOf] Employment records for this member.
healthCoverage array[oneOf] Health coverage records for this member.
household object required Household-level data used in benefit calculation.
roomers array[object] Non-household members who share the living space and pay rent separately.
type string required Whether the roomer is a household member counted in another capacity or a non-member contact.
enummember contact
id string (uuid) required Identifier of the member or contact record.
amountPaidForRent number (float) Amount the roomer pays for rent.
mealsIncludedWithRent boolean Whether meals are included with the roomer's rent payment.
utilitiesIncludedInRent boolean Whether utility costs are included in the rent payment.
isSubsidizedHousing boolean Whether the household lives in subsidized or public housing. Affects the SNAP utility standard deduction.
receivedTanfInAnotherState boolean Whether the household has received TANF benefits in another state. Required for multi-state TANF coordination.
verificationSummary array[object] required Status of verification obligations relevant to this household and program.
category string The type of verification (e.g., income, identity, residency).
status string Current status of the verification obligation.
enumpending inconclusive satisfied waived cannot_verify
memberId string (uuid) Identifier of the intake domain member this verification applies to. Passed through from intake for correlation — the adapter does not resolve this identifier.
Responses
200 Final determination result.
▶ ProgramDecision
metadata object required Echoed back unchanged from the request. The blueprint uses this to map the response to its internal records without exposing resource identities to the adapter.
program string required The program this decision applies to.
enumsnap medicaid chip tanf aca
▶ status DecisionStatus required The eligibility outcome.
No additional fields
▶ path DecisionPath How the decision was reached.
No additional fields
denialReasonCode string Machine-readable reason code when status is denied or ineligible.
400 The request is malformed or contains invalid parameters.
▶ BadRequest
code string required Machine-readable error code.
message string required Human-readable error description.
details array[object] Additional error details.
500 An unexpected error occurred on the server.
▶ InternalError
code string required Machine-readable error code.
message string required Human-readable error description.
details array[object] Additional error details.