Stedi home page
Docs

Eligibility response shapes

After you send an eligibility or insurance discovery check, the payer returns an X12 271 response containing the patient's benefits information. Stedi transforms the 271 response from the original X12 EDI into JSON, making it easier to read, understand, and ingest into your system.

Response shapes

Stedi returns one of two response shapes, depending on the endpoint you called. Both contain the same benefits information, organized differently. You can identify them by the top-level array that organizes the patient's benefits information - either plans or benefitsInformation.

Top-level arrayEndpoints
plansReal-Time Eligibility Check JSON
benefitsInformationBatch Eligibility Check, Insurance Discovery, Real-Time Eligibility Check Raw X12, Real-Time Eligibility Check JSON - Legacy

This documentation refers to the response shapes by their top-level array throughout. An example labeled plans applies only to the Real-Time Eligibility Check JSON endpoint. An example labeled benefitsInformation applies to the other four endpoints.

plans array

Applies to: Real-Time Eligibility Check JSON

The plans array groups benefits under their associated health plan. A response can contain multiple plans. For example, a patient with medical, dental, and vision coverage through the same payer receives one plans object for each health plan.

Each plan contains a benefits object. Within it:

  • The statuses array reports whether the patient has coverage, and for which services.
  • Every other kind of benefit is its own named array, such as coPayment or deductible. For example, plans[0].benefits.coPayment contains the co-payments for the first plan.
  • Every benefit entry contains a service object that identifies the applicable service.
{
  "id": "ec_550e8400-e29b-41d4-a716-446655440000",
  "payerId": "87726",
  "payer": {
    "type": "PAYER",
    "name": { "organization": "HUMANA" }
  },
  "x12": "...",
  "subscriber": {
    "memberId": "123456789",
    "dates": {
      "plan": { "start": "2024-01-01" },
      "service": { "start": "2024-09-17" }
    }
  },
  "plans": [
    {
      "benefits": {
        "statuses": [
          {
            "status": "ACTIVE_COVERAGE",
            "coverageLevel": "EMPLOYEE_ONLY",
            "insuranceType": "PREFERRED_PROVIDER_ORGANIZATION_PPO",
            "network": { "indicator": "IN_AND_OUT_OF_NETWORK" },
            "planCoverageDescription": "Humana Gold Plan",
            "service": {
              "system": "STC",
              "value": "30",
              "definition": "Health Benefit Plan Coverage"
            },
            "messages": ["Medicare PPO"]
          }
        ],
        "coPayment": [
          {
            "amount": "2000",
            "coverageLevel": "INDIVIDUAL",
            "insuranceType": "PREFERRED_PROVIDER_ORGANIZATION_PPO",
            "network": { "indicator": "IN_NETWORK" },
            "service": {
              "system": "STC",
              "value": "49",
              "definition": "Hospital - Room and Board"
            },
            "timePeriod": "ADMISSION",
            "messages": ["INPATIENT HOSPITAL ROOM AND BOARD"]
          }
        ]
      }
    }
  ]
}

benefitsInformation array

Applies to: Batch Eligibility Check, Insurance Discovery, Real-Time Eligibility Check Raw X12, Real-Time Eligibility Check JSON - Legacy

The benefitsInformation array returns every benefit in a single, flat list with no plan grouping. When a patient has more than one plan, entries for every plan appear in the same array.

Each benefitsInformation[].code property identifies either a coverage status or a type of benefit. Each entry's serviceTypeCodes array identifies the applicable service types.

  • An entry with a code of 1 (Active Coverage) reports that the patient has active coverage for the service types in serviceTypeCodes, such as 30 (Health Benefit Plan Coverage).
  • An entry with a code of C (Deductible) reports a specific benefit for those service types, with the amount in benefitAmount.
"planInformation": {
  "groupNumber": "186084",
  "planNumber": "UVdQAC5j6f"
},
"planDateInformation": {
  "plan": "20240101-20241231"
},
"benefitsInformation": [
  {
    "code": "1",
    "name": "Active Coverage",
    "serviceTypeCodes": ["30"],
    "serviceTypes": ["Health Benefit Plan Coverage"],
    "planCoverage": "CHOICE PLUS",
    "insuranceTypeCode": "C1",
    "insuranceType": "Commercial",
    "inPlanNetworkIndicatorCode": "W",
    "inPlanNetworkIndicator": "Not Applicable",
    "additionalInformation": [
      { "description": "PROVIDER IS OUT NETWORK FOR MEMBER" }
    ]
  },
  {
    "code": "C",
    "name": "Deductible",
    "serviceTypeCodes": ["30"],
    "serviceTypes": ["Health Benefit Plan Coverage"],
    "benefitAmount": "0",
    "coverageLevelCode": "FAM",
    "coverageLevel": "Family",
    "timeQualifierCode": "23",
    "timeQualifier": "Calendar Year",
    "inPlanNetworkIndicatorCode": "Y",
    "inPlanNetworkIndicator": "Yes"
  }
]

Compare the response shapes

Stedi builds both shapes from the same X12 271 response. They differ in how they organize that information, what they name each property, and how they handle data that doesn't conform to the spec.

What's different

The first difference is how the responses organize the patient's benefits information. Every value of benefitsInformation[].code has an equivalent named array in the plans shape, and most map one to one. For example, a code of B in benefitsInformation becomes the coPayment array in plans. The exception is coverage status, where codes 1 through 8 all map to the statuses array in plans.

The following tabs show a $2,000 in-network co-payment for hospital room and board in each shape.

"plans": [
  {
    "benefits": {
      "coPayment": [
        {
          "amount": "2000",
          "coverageLevel": "INDIVIDUAL",
          "network": { "indicator": "IN_NETWORK" },
          "service": {
            "system": "STC",
            "value": "49",
            "definition": "Hospital - Room and Board"
          },
          "timePeriod": "ADMISSION"
        }
      ]
    }
  }
]
"benefitsInformation": [
  {
    "code": "B",
    "name": "Co-Payment",
    "benefitAmount": "2000",
    "coverageLevelCode": "IND",
    "coverageLevel": "Individual",
    "serviceTypeCodes": ["49"],
    "serviceTypes": ["Hospital - Room and Board"],
    "timeQualifierCode": "36",
    "timeQualifier": "Admission",
    "inPlanNetworkIndicatorCode": "Y",
    "inPlanNetworkIndicator": "Yes"
  }
]

The response shapes also differ in how they handle invalid data.

  • plans: Stedi validates entries against their types. A cost-share entry with missing or unexpected data, such as a deductible with no amount or a co-payment with a percentage instead of an amount, appears in benefits.invalidEntries instead of the standard array. An invalid entry can contain amount, percent, and quantity at the same time, so it preserves exactly what the payer sent, and its invalidReasons property explains why it's non-standard.
  • benefitsInformation: Stedi passes payer data through as is, including values that don't conform to the spec.

What's similar

Outside the benefits themselves, both shapes return the same information:

  • id and eligibilitySearchId: Stedi's identifier for this eligibility check, and the identifier that groups checks for the same patient into one eligibility search.
  • payer, provider, and subscriber: The payer's business name and identifier, the entity that submitted the check, and the primary policyholder for the plan.
  • errors: The payer's AAA rejection errors, which explain why a payer rejected the check.
  • warnings: Issues with your request that can affect the results.
  • x12: The raw X12 EDI 271 response from the payer.
  • meta: Metadata Stedi uses for tracking and troubleshooting.

Determine patient benefits

Eligibility PDF
Active coverage and benefits

On this page

Response shapesplans arraybenefitsInformation arrayCompare the response shapesWhat's differentWhat's similarDetermine patient benefits