Stedi home page
Docs

Real-Time Eligibility Check (270/271) JSON - Legacy

Submit a real-time 270/271 eligibility check in JSON format

POST/change/medicalnetwork/eligibility/v3

This is the legacy JSON endpoint. We won't deprecate it, and you can continue using it in production. We recommend using Real-Time Eligibility Check JSON for new integrations - its updated request and response shapes are more intuitive for both developers and AI agents. Of course, you're free to upgrade at any time.

Real-time eligibility checks are ideal for in-person patient visits, telehealth appointments, and other scenarios where you need immediate information about a patient's coverage.

  1. Call this endpoint with a JSON payload.
  2. Stedi translates your request to the X12 270 EDI format and sends it to the payer.
  3. The endpoint returns a synchronous response from the payer in both JSON and raw X12 EDI format. The response contains the patient's eligibility and benefits information. Note that our documentation lists all enums officially allowed in the eligibility response. Some payers return non-compliant values, which Stedi passes through as is.

Authorizations

Authorization
RequiredHeader

A Stedi API Key for authentication. Supports both test and production API keys.

Headers

X-Forwarded-For
String

(CMS requests only): Starting November 8, 2025, the Centers for Medicare & Medicaid Services (CMS) requires submitters to include network IP addresses from an eligibility request's point of origin through receipt by the HETS system. To comply with this requirement, you may need to include this header in requests to CMS.

When present, this header should contain a comma-separated list of upstream IP addresses, starting with the originating system and continuing through every intermediary. You can exclude your IP address from the list. Note that Stedi blocks eligibility requests to CMS when any IP address in the chain – the originating IP address or any in the X-Forwarded-For header – is located outside the United States.

Visit CMS traceability requirements for details and examples.

Body

application/json
controlNumber
StringDeprecatedLength: 9

Stedi generates a control number for each eligibility check, so you don’t need to include this property in your request.

dependents
Array of ObjectsItems: 1

A dependent for which you want to retrieve benefits information.

  • You can only submit one dependent per eligibility check.
  • Only include the patient's information here when they are listed as a dependent on the subscriber's insurance plan AND the payer cannot uniquely identify them through information outside the subscriber's policy. For example, if the dependent has their own member ID number, you should identify them in the subscriber object instead. This includes member IDs that differ only by a suffix, such as 01, because the patient can still be uniquely identified.
  • Most Medicaid plans don't support dependents, with a few exceptions. Sending this array to payers that don't support dependents will either cause an error, or the payer may ignore the information and return results for the subscriber instead.
  • Each payer has different requirements, so you should supply the fields necessary for each payer to identify the dependent in their system. However, we strongly recommend including the dependent's date of birth in the request when available because many payers return errors without it.
  • Enter the patient's name exactly as written on their insurance card, if available, including any special or punctuation characters such as apostrophes, hyphens (dashes), or spaces. Visit patient names for all best practices to avoid unnecessary failures.
Array item
eligibilitySearchId
String

An identifier that allows Stedi to group eligibility checks for the same patient into a unified record in the Stedi portal called an eligibility search.

This property is for use by Stedi tools only, such as Stedi's MCP server.

encounter
Object

Details about the eligibility or benefit information you are requesting for the patient.

  • If you don't specify either serviceTypeCodes or a procedureCode and productOrServiceIDQualifier, Stedi defaults to using 30 (Plan coverage and general benefits) as the only serviceTypeCodes value.
  • You can specify either a single dateOfService or a beginningDateOfService and endDateOfService. The payer defaults to using the current date in their timezone if you don't include one.
  • When checking eligibility for today, omit the dateOfService property to ensure consistent behavior across payers.
  • We recommend submitting dates up to 12 months in the past or up to the end of the current month. Payers aren't required to support dates outside these ranges. However, some payers such as the Centers for Medicare and Medicaid Services (CMS) do support requests for dates further in the future - especially the next calendar month. Check the payer's documentation to determine their specific behavior.
Show attributes
externalPatientId
StringMax length: 36

A unique identifier for the patient that Stedi uses to identify and correlate historical eligibility checks for the same individual. We recommend including this value in all requests.

informationReceiverName
ObjectDeprecated

Use the corresponding properties in the provider object instead.

Show attributes
portalPassword
StringLength: 1 - 50

The password that the provider uses to log in to the payer's portal. For payers Medicaid California, AltaMed, and Kern Family Health Care, this property is required and should be the provider's PIN. Otherwise, this is not commonly used.

portalUsername
StringLength: 1 - 50

The username that the provider uses to log in to the payer's portal. This is not commonly used.

provider
ObjectRequired

Information about the entity requesting the eligibility check. This may be an individual practitioner, a medical group, a hospital, or another type of healthcare provider.

  • You must provide the organizationName (if the entity is an organization), or firstName and lastName (if the provider is an individual).
  • You must also provide an identifier - this is typically the provider's National Provider Identifier (npi). If the provider doesn't have an NPI, you can supply an alternative, such as their taxId or ssn.
  • Don't include additional properties, such as taxId or address, unless they are specifically required or suggested by the payer.
Show attributes
submitterTransactionIdentifier
String

This property is only relevant for asynchronous batch eligibility checks.

subscriber
ObjectRequired

The primary policyholder for the insurance plan or a dependent with a unique member ID. If a dependent has a unique member ID, include their information here and leave dependents empty.

  • At a minimum, our API requires that you supply at least one of these fields in the request: memberId, dateOfBirth, or lastName. However, each payer has different requirements, so you should supply the fields necessary for each payer to identify the subscriber in their system.
  • When you provide all four of memberId, dateOfBirth, firstName, and lastName, payers are required to return a response if the member is in their database. Some payers may be able to search with less information, but this varies by payer.
  • We recommend always including the patient's member ID when possible.
  • Enter the patient's name exactly as written on their insurance card, if available, including any special or punctuation characters such as apostrophes, hyphens (dashes), or spaces. Visit patient names for all best practices to avoid unnecessary failures.
Show attributes
tradingPartnerName
StringLength: 1 - 60

The payer's name, such as Cigna or Aetna.

tradingPartnerServiceId
StringRequiredLength: 1 - 80

The payer ID. Visit the Payer Network for a complete list.

  • You can send requests using the primary payer ID, the Stedi payer ID, or any alias listed in the payer record.
  • You must include leading 0 characters - payer IDs are alphanumeric strings and must be treated as complete strings, not integers. For example, use 00540 for SISCO, not 540.

Response

application/json
benefitsInformation
Array of Objects

Information about the patient's healthcare benefits, such as coverage level (individual vs. family), coverage type (deductibles, co-pays, etc.), out of pocket maximums, and more.

Payers typically return at least the following properties: code, coverageLevelCode, serviceTypeCodes, and either benefitAmount or benefitPercent. However, the exact properties returned in this object are up to the payer's discretion.

The payer may send benefits information for service type codes (STCs) you didn't request - this is expected. The STC you send in the request tells the payer the types of benefits information you want, but they aren't required to respond with exactly the same STC(s) in the response. Receiving different STCs than you requested can also mean that the payer is ignoring the STC you sent, which is why we recommend testing payers to determine their support for specific STCs.

Visit Determine patient benefits for more information about benefit types, details about how to interpret the benefitsInformation array, and additional examples.

Array item
controlNumber
StringDeprecated

An identifier for the payer's response.

dependents
Array of Objects

Information about the patient when they are a dependent. When the patient is a dependent, this array will contain a single object with the patient's information. When the patient is a subscriber, or considered to be a subscriber because they have a unique member ID, their information is returned in the subscriber object, and this array will be empty.

When present, this object will always include the dependent's name for identification, but many payers will also return the date of birth and other identifying information.

Array item
eligibilitySearchId
String

An identifier that allows Stedi to group eligibility checks for the same patient into a unified record in the Stedi portal called an eligibility search.

This property is for use by Stedi tools only, such as Stedi's MCP server.

errors
Array of Objects

When a payer rejects your eligibility check, the response contains one or more AAA errors that specify the reasons for the rejection and any recommended follow-up actions.

Any errors that occur at the payer, provider, subscriber, or dependents levels are also included in this array, allowing you to review all errors in a central location. If there are no AAA errors, this array will be empty.

Array item
id
String

A globally unique identifier for this eligibility check across all Stedi accounts. It's formatted as ec_<uuid>. For example: ec_550e8400-e29b-41d4-a716-446655440000. You can use this ID to track this eligibility check and to construct deep links to eligibility checks in the Stedi portal.

implementationTransactionSetSyntaxError
String

The implementation transaction set error code provided in IK502 of the 999 transaction.

meta
Object

Metadata about the response. Stedi uses this data for tracking and troubleshooting.

Show attributes
payer
Object

Information about the payer providing the benefits information. The response will always include the payer's business name and an identifier, such as the payer's tax ID. Most payers also include contact information.

Show attributes
planDateInformation
Object

Contains the dates associated with the subscriber and dependents' (if applicable) insurance plan. This information is used to determine their eligibility for benefits.

  • Most fields contain a single date, but some can contain either a single date or a date range. Each field's documentation specifies its format.
  • Fields that can contain either a single date or date range include: plan, eligibility, planBegin, admission, and service.
  • The provided dates apply to every benefit within the patient's health plan unless specifically noted within a benefitsInformation[].benefitsDateInformation object.
  • If the payer sends back date(s) that are different for the subscriber and dependents, Stedi includes only the dates for the dependent in this object and omits the subscriber's date(s). Dependents can have different coverage dates than the subscriber due to qualifying life events, such as starting a new job or passing the age limit for coverage through their parent's plan.
  • Most payers return either plan or planBegin and planEnd, but the exact dates returned depend on the payer's discretion and the patient's insurance plan.
  • If the date of service is after the earliest ending plan, eligibility, planEnd, eligibilityEnd, policyEffective, or policyExpiration value, the patient likely doesn't have active coverage.
Show attributes
planInformation
Object

Additional identification for the subscriber's healthcare plan.

Show attributes
planStatus
Array of ObjectsDeprecated

Please use benefitsInformation instead.

Array item
provider
Object

Information about the entity that submitted the original eligibility check request. This may be an individual practitioner, a medical group, a hospital, or another type of healthcare provider. This object will always include at least one identifier, such as the provider's NPI, tax ID, or EIN.

Show attributes
reassociationKey
StringDeprecated
status
String

Errors Stedi encountered when generating or sending the final X12 EDI transaction to the payer. These can include validation errors and payer unavailable errors that prevent delivery.

subscriber
Object

Information about the primary policyholder for the insurance plan listed in the original eligibility check request. The response will always include either the subscriber's name or member ID for identification, but most payers will also return the subscriber's date of birth and other identifying information.

Show attributes
subscriberTraceNumbers
Array of Objects

A unique identifier for the eligibility request. It's used to trace the transaction. Stedi always generates a trace number for internal tracking, and the payer may generate one as well. Stedi returns both its internal trace number and the payer's trace number (if present) in this array.

You can't set your own trace number when submitting eligibility checks through this endpoint.

Array item
tradingPartnerServiceId
String

An ID for the payer you identified in the original eligibility check request. This value may differ from the tradingPartnerServiceId you submitted in the original request because it reflects the payer's internal concept of their ID, not necessarily the ID Stedi uses to route requests to this payer.

transactionSetAcknowledgement
String

The transaction set acknowledgment code provided in in the X12 EDI 999 response.

warnings
Array of Objects

Issues with your eligibility request that could affect the results, or information about the response. For example, warnings can help explain why the request was rejected.

Array item
x12
String

Typically this property contains the raw X12 EDI 271 Eligibility Benefit Response from the payer.

In some circumstances, this property may contain a 999 Implementation Acknowledgment instead of a 271. A 999 indicates validation errors in the X12 EDI transaction, such as improper formatting or missing or invalid values.

If the 999 is returned in this property, many of the other response properties will be empty, as they are mapped to information in the 271.

Real-Time Eligibility Check JSON
Real-Time Eligibility Check Raw X12