Stedi home page
Docs

Real-Time Eligibility Check (270/271) JSON

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

POST/eligibility-check

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. The required information can vary depending on the circumstances, but we recommend starting with a basic eligibility request.
  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.

Test your integration with eligibility mock requests.

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
dependent
Object

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 information 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.
Show attributes
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.

encounter
Object

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

  • You can optionally include service type codes (STCs) or procedure codes to request benefits for specific services.
  • You can specify either a single service date or a date range using dates.service. The payer defaults to using the current date in their timezone if you don't include one.
  • When checking eligibility for today, omit the service date 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.

payerId
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.
payerName
StringLength: 1 - 120

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

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 provider's name as either a person (with name.person) or an organization (with name.organization).
  • 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 tin or ssn.
  • Don't include additional properties, such as tin or address, unless they are specifically required or suggested by the payer.
Show attributes
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 dependent empty.

  • At a minimum, our API requires that you supply at least one of these fields in the request: memberId, dateOfBirth, or name.person.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, name.person.firstName, and name.person.lastName, payers must 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

Response

application/json
dependent
Object

Information about the dependent from the eligibility check request. Note that the payer may return the dependent in the subscriber object instead. When present, this object will always include the dependent's name for identification, but many payers also include the date of birth and other identifying information. Some payers truncate names to fit their own technical limits, so the payer may not return the dependent's full legal name.

Show attributes
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

AAA rejection errors from the payer. AAA errors specify the reasons for the rejection and any recommended follow-up actions.

Array item
id
StringRequired

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.

meta
Object

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

Show attributes
payer
ObjectRequired

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
payerId
String

The primary payer ID from the Stedi Payer Network. This ID is consistent across eligibility and claims systems and matches the payer ID printed on the member's ID card. You can use it as the payerId in subsequent eligibility check requests.

plans
Array of Objects

The patient's insurance plans, grouped by plan name. Each plan contains the benefits that apply to the patient.

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
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. Some payers truncate names to fit their own technical limits, so the payer may not return the subscriber's full legal name.

Show attributes
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
StringRequired

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 this property contains a 999, many of the other response properties will be empty, as Stedi populates them with information from the 271.

Delete Document
Real-Time Eligibility Check JSON - Legacy