Real-time eligibility checks

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. We recommend always starting with real-time checks when integrating with a new payer. This approach allows you to quickly test and refine your pipeline through fast feedback loops. Once you’re comfortable with real-time checks, you may also want to start sending asynchronous batch checks to perform periodic refreshes for all or a subset of patients. You can send real-time eligibility checks to payers manually through the Stedi portal or programmatically through the API. The synchronous response includes the patient’s complete benefits information, such as coverage status, co-pays, and deductibles.

Eligibility checks verify coverage with a specific payer. If you don’t know the payer, you can perform an insurance discovery check instead to find a patient’s coverage using their demographic data.

Transaction enrollment

Some payers require transaction enrollment before you can start sending them eligibility checks. The Payer Network specifies which payers require enrollment.

Testing

The best way to test real-time eligibility checks is through mock requests.

Mock requests

When you submit specific mock requests, Stedi returns mock benefits data from the specified payer. You can submit mock requests through the:

JSON endpoint: Visit Eligibility mock requests for a complete list.
Stedi portal: Visit Test mode to learn how to enable Test mode in your account and manually submit mock requests.

Don’t send fake data

Some payers, particularly CMS (HETS), prohibit sending test eligibility checks for fake patients or providers to their production systems. Payers may block your access if you send these types of test transactions. You can send as many mock requests to Stedi as you need, but if you need to send test data to payers in production, you must contact Stedi support to coordinate with the payer and obtain approval. For example, some payers require that you use specific test credentials.

Manual submission

Manual eligibility checks can be useful for testing and for situations when you need to do a one-time eligibility check. Go to the Create manual eligibility check page in the Stedi portal to submit manual eligibility checks and review the full JSON response. You can also sort and filter a more user-friendly response organized by coverage type and level.

API submission

Call one of the following endpoints to send real-time 270/271 eligibility checks to payers:

Eligibility Check to send requests in JSON
Eligibility Check Raw X12 to send requests in X12 EDI

Stedi automatically applies various repairs to help your requests meet X12 HIPAA specifications, resulting in fewer payer rejections.

Headers

You must include the following Stedi-specific headers in your API request:

Authorization: Generate an API key to use for authentication.
Content-Type: Set to application/json.

curl --request POST \
  --url https://healthcare.us.stedi.com/2024-04-01/change/medicalnetwork/eligibility/v3 \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \

Body - JSON

The information you provide to the payer in an eligibility check can vary, depending on the circumstances. We recommend starting with a basic eligibility request.

Basic eligibility request

Each eligibility check must include at least the following information in the request body:

Information	Description
`controlNumber`	An integer used to identify the transaction. This is a requirement for the X12 EDI 270 transaction that Stedi will generate and send to the payer. It doesn’t need to be globally unique - you can use the same number for every request.
`tradingPartnerServiceId`	This is 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. If you don’t know the payer, try submitting an insurance discovery check instead.
`provider` object, name and identifier	You must include the provider’s name - either the `firstName` and `lastName` of a specific provider within a practice or the `organizationName`. You must include an identifier. Most often this is the National Provider Identifier (NPI).
`subscriber` and/or `dependents` objects	The `dependents` object is optional - refer to the scenarios when the patient qualifies as a dependent. 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 all four of `memberId`, `dateOfBirth`, `firstName`, and `lastName` are provided, 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. Learn more about patient information.
`encounter` object, service dates	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.
`encounter` object, service or procedure codes	Specify `serviceTypeCodes` and/or a `procedureCode` and `productOrServiceIDQualifier` to request specific types of benefits information. We recommend including no more than one service type code in each request. If you don’t include any service type code or procedure code information, Stedi defaults to using `30` (Plan coverage and general benefits) as the only `serviceTypeCodes` value. Learn more about checking eligibility for specific services.

The following example shows the bare minimum request body for an eligibility check. Because the dateOfService is not specified, the payer will use the current date in their timezone (default) to retrieve benefits information.

{
  "controlNumber": "123456789",
  "tradingPartnerServiceId": "AHS",
  "encounter": {
    "serviceTypeCodes": ["78"]
  },
  "provider": {
    "organizationName": "ACME Health Services",
    "npi": "1999999984"
  },
  "subscriber": {
    "dateOfBirth": "19000101",
    "firstName": "Jane",
    "lastName": "Doe",
    "memberId": "1234567890"
  }
}

Conditional requirements

Note that objects marked as required are required for all requests, while others are conditionally required depending on the circumstances. When you include a conditionally required object, you must include all of its required properties. For example, you must always include the provider object in your request, but you only need to include the dependents object when you need to request benefits information for a dependent on the subscriber’s insurance plan.

Body - X12 EDI

When sending real-time eligibility checks through the raw X12 endpoint you must send a payload in 270 X12 EDI format. The information you send can vary, depending on the circumstances. We recommend starting with a basic eligibility request.

Basic eligibility request

In addition to the required fields in the header and trailer, each eligibility check must include at least the following information:

Information	Description
`BHT03` (Submitter Transaction Identifier)	This identifier must be 1-50 characters long and different from the value you choose for `ST02`. We also strongly recommend using a unique value. Learn more
`Loop 2100A` (Information Source)	This loop contains the payer’s information. Notably, you must include the payer’s name (`NM103`) and identifier (`NM109`). The payer’s identifier must be a payer ID or payer ID alias listed in the Payer Network. For example, you could use `60054`, `HPQRS`, `AETNA`, or any other listed payer ID alias for Aetna.
`Loop 2000B` (Information Receiver)	This loop contains information about the provider requesting the benefits information. You must include the provider’s name (`NM103`) and an identifier (`NM109`). Most often this is the National Provider Identifier (NPI).
`Loop 2000C` (Subscriber) and `Loop 2000D` (Dependent)	`Loop 2000D` is optional - refer to the scenarios when the patient qualifies as a dependent. At a minimum, you must supply at least one of these fields in the appropriate loop to identify the patient: `NM109` (member ID), `DMG02` (birth date), or `NM103` (last name). However, each payer has different requirements, so you should supply the fields necessary for each payer to identify the patient in their system. When all four of member ID, first name, last name, and date of birth are provided, 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. Learn more about patient information.
`Loop 2110C` or `Loop 2100D DTP` (Eligibility/Benefit Date)	You can specify either a single date of service or a range of service dates. 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 from the request 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.
`Loop 2110C` or `Loop 2100D EQ` (Eligibility or Benefit Inquiry)	You must specify a service type code and/or a procedure code and qualifier to request specific types of benefits information. We recommend including no more than one service type code in each request. Learn more about checking eligibility for specific services.

BHT03

The BHT03 (Submitter Transaction Identifier) element is required when submitting real-time eligibility checks in X12 EDI. The identifier you choose must be:

An alphanumeric string from 1-50 characters long.
Different from the value you choose for ST02 (Transaction Set Control Number).

We also strongly recommend using a unique value. This approach makes it easier for Stedi to troubleshoot eligibility checks in your account. The payer returns the identifier in the BHT03 element of the 271 eligibility response, and Stedi returns it in the meta.traceId JSON property. If you don’t include BHT03 in the request, Stedi returns a 200 with the status property set to ERROR and the implementationTransactionSetSyntaxError property set to 5. The response also includes a negative 999 Implementation Acknowledgment in the x12 property.

Example error response due to missing BHT03

{
  "controlNumber": "138549672",
  "tradingPartnerServiceId": "STEDI",
  "errors": [
    {
      "description": "The payer or clearinghouse rejected the request with validation errors. The original edi response is returned in the x12 field, please contact Stedi Support if you need further help."
    }
  ],
  "status": "ERROR",
  "transactionSetAcknowledgement": "R",
  "implementationTransactionSetSyntaxError": "5",
  "x12": "ISA*00*          *00*          *ZZ*STEDI          *01*117151744      *250523*1304*^*00501*000000000*0*P*:~GS*FA*STEDI*117151744*20250523*1304*000000000*X*005010X231A1~ST*999*0001*005010X231A1~AK1*HS*9872*005010X279A1~AK2*270*0001*005010X279A1~IK3*BHT*2**8~IK4*3*127*2~CTX*SITUATIONAL TRIGGER*BHT*2**3~IK5*R*5~AK9*R*1*1*0~SE*9*0001~GE*1*000000000~IEA*1*000000000~"
}

Character restrictions

Only use the X12 Basic and Extended character sets in request data. Using characters outside these sets may cause validation and HTTP 400 errors.

Basic character set

Extended character set

In addition, the following characters are reserved for delimiters in the final X12 EDI transaction to the payer: ~, *, :, and ^. X12 doesn’t support using escape sequences to represent delimiters or special characters. Stedi returns a 400 error if you use these restricted characters improperly.

JSON endpoint: Don’t include delimiter characters anywhere in your request data.
Raw X12 endpoint: You can use these characters as delimiters, but not in the body of the request data.

Autocorrection for backticks

Stedi automatically replaces backticks (`), also known as backquotes or grave accents, with an apostrophe (') in subscriber and dependents first and last names. These corrections prevent errors when submitting your request. Stedi returns a message in the response’s warnings array when it makes this replacement.

Sample request and response

The following request and response examples show a basic eligibility check for a patient named Jane Doe. The request uses the MH service type code to check for mental health benefits. The response shape is the same for requests made through both the JSON and X12 EDI endpoints, and it contains the patient’s benefits information. Visit Determine patient benefits for detailed explanations of how to determine the patient’s active coverage, financial responsibility, whether referrals and authorizations are required, and more.

curl --request POST \
  --url https://healthcare.us.stedi.com/2024-04-01/change/medicalnetwork/eligibility/v3 \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
      "controlNumber": "123456789",
      "tradingPartnerServiceId": "ABDCE",
      "encounter": {
        "serviceTypeCodes": ["MH"]
      },
      "provider": {
        "organizationName": "ACME Health Services",
        "npi": "1999999984"
      },
      "subscriber": {
        "dateOfBirth": "19000101",
        "firstName": "Jane",
        "lastName": "Doe",
        "memberId": "1234567890"
      }
   }'

Retries

Implementing the right retry strategy for eligibility check failures saves a lot of time and money. At a minimum, we strongly recommend automatically retrying every request that fails due to payer connectivity issues. Automatic retries resolve a significant portion of these types of failures without manual intervention. Visit Retry strategy for details.

Timeout

Insurance payers may take up to 60 seconds to respond to a request, but Stedi holds real-time eligibility check requests open for up to 120 seconds before timing out. During this period, Stedi attempts multiple retries to payers in an effort to complete your request. Canceling and retrying requests before Stedi’s automatic retry period ends may create multiple ongoing requests to payers and increase your concurrency usage.

Request hedging

When eligibility responses are taking too long, you can use request hedging to try to get results faster. To implement request hedging, send a second request at some internal duration cutoff (for example, 30 seconds) without cancelling the first request. Then, you can use whichever result comes back first. If one of the requests fails, you can wait for the second request to see if it’s successful.

Concurrency limit

Our real-time eligibility check endpoint has rate limiting on a per-account basis. This limit is based on concurrent requests, not requests per second. The default rate limit is 5 concurrent requests; if you need a higher limit, reach out to Support. Your transactions per second (and thus your concurrency limit) will vary based on the payer response time. If you reach the maximum concurrency limit, Stedi rejects additional requests with a 429 HTTP code until one of your previous requests is completed. Rejected requests have the following error message:

{
  "message": "The request can't be submitted because the sender's submission has been throttled: CUSTOMER_LIMIT",
  "code": "TOO_MANY_REQUESTS"
}

Asynchronous batch eligibility checks don’t count toward your Stedi account concurrency budget. This allows you to stage thousands of batch requests while continuing to send real-time requests.

Avoid payer throttling

Payers expect to receive requests at a “human scale”, such as a member entering insurance information into a website or presenting their insurance card at a doctor’s office. They may throttle high volumes of requests for the same provider (NPI ID) at once. This throttling can occur even when you are within Stedi’s concurrency limit. Real-time requests during normal operations are unlikely to experience throttling. However, we recommend spacing out requests during testing and periodic “refresh” checks, such as verifying active insurance. Avoid hitting payers with the same NPI ID more than 1-2 times every 15 seconds. You can also use Stedi’s Batch Eligibility Check API to submit up to 500 eligibility checks in a single request. Stedi processes these eligibility checks asynchronously, implementing best practices to avoid payer throttling.

Recommended API clients

You may want to use an API client to make testing and debugging easier. We don’t recommend using Postman for requests containing Protected Health Information (PHI) because Postman defaults to storing request history - including full request payloads - on its cloud servers. You can’t turn this feature off without impractical workarounds. Visit API clients for a list of recommended clients you can use instead.

Patient information

All payers are required to be able to search for patients using the following “bare minimum” subsets of information. They will return benefits information as long as they can find a unique match for the patient within their system. For a subscriber:

Member ID, first name, last name, date of birth
Member ID, last name, date of birth
Member ID, first name, last name

For a dependent:

Subscriber member ID (in the subscriber object), first name, last name, date of birth
Subscriber member ID, last name, date of birth
Subscriber member ID, first name, last name

Of course, not all of this patient information is always available. For example, a patient may forget their ID card. In these instances, some payers may still be able to search with even less information, such as the patient’s first name, last name, and date of birth. Contact us if you have questions about alternative search options for a particular payer.

Dependents

The patient qualifies as a dependent for eligibility checks when:

The patient is listed as a dependent on the subscriber’s insurance plan.
The payer cannot uniquely identify the patient through information outside the subscriber’s policy.

For example, if the dependent has their own member ID number in the payer’s database, you must identify them as a subscriber instead.

Patient names

Note the following information and best practices when entering patient names:

Enter the name exactly as written on the patient’s insurance ID card (if available), including any special or punctuation characters such as apostrophes, hyphens (dashes), or spaces. If the patient’s insurance ID card isn’t available, enter the name exactly as written on a government-issued ID card. If a government ID card isn’t available, enter the name exactly as given by the patient.
Don’t include a name prefix, title, rank, honorific, or academic degree in any property. These include Mrs., Dr., Hon., and PhD.
Don’t include a suffix or generation such as Jr. or III in the firstName or lastName property. Put it in the separate suffix property instead. Payers are supposed to automatically parse suffixes out of the last name, but Stedi can’t guarantee that all payers will do this correctly.
You can populate a middle name (or names) or initial in the middleName property, but most payers ignore it when searching for the patient.
Case doesn’t matter. For example, JANE is equivalent to Jane.

The following are supported for patient names:

Compound last and first names separated by spaces or hyphens such as Jean‐Claude or Smith Jones
Apostrophized or elided names such as O’Connor or D’Amore
Numbers like 3, however this typically indicates a data entry error

Some payers may have more specific requirements or restrictions that we don’t cover in our docs. If you’re receiving errors for a specific payer, we recommend consulting that payer’s documentation for eligibility checks for additional guidance.

MBI for CMS checks

A Medicare Beneficiary Identifier (MBI) is a unique, randomly-generated identifier assigned to individuals enrolled in Medicare. You must include the patient’s MBI in every eligibility check to the Centers for Medicare and Medicaid Services (payer ID: CMS). Some payers return the patient’s MBI in one of the following properties of the standard eligibility response:

If the value in either of these properties matches the format specified in the Medicare Beneficiary Identifier documentation, the number is likely an MBI, and we recommend sending a follow-up eligibility check to CMS for additional benefits data. You’re most likely to receive an MBI in eligibility check responses from commercial Medicare Advantage plans, but they can also be present in responses from Medicaid plans for dual-eligible patients. When you don’t know a patient’s MBI, you can use Stedi’s eligibility check APIs to perform an MBI lookup using their Social Security Number instead. Stedi returns a complete benefits response from CMS with the patient’s MBI in the subscriber object for future reference. Visit Medicare Beneficiary Identifier (MBI) lookup for complete details.

Don’t submit eligibility checks for Medicare Advantage plans to CMS (HETS) - you should submit them to the actual Medicare Advantage plan payer instead.

Checking eligibility for specific services

You may need to determine whether a patient’s insurance covers particular medical or dental services, such as chiropractic or hospice care. You can request specific types of benefits information from the payer by including either a procedureCode and productOrServiceIDQualifier or a serviceTypeCodes value in the encounter object. In practice:

Most medical payers don’t support procedure codes (CPT/HCPCS/CDT), so you will almost always need to submit a service type code (STC) in your eligibility check.
Many (but not all) dental payers support procedure codes. To check general dental eligibility, we recommend always using STC 35 instead of a CDT code. To check eligibility for specific services, try the relevant CDT code first. If the payer’s response doesn’t include it, try a more general inquiry for the STC mapped to that CDT code.

Mapping procedure codes

It can be hard to map procedure codes to the right STC. For example, if a provider offers medical nutrition therapy and bills using CPT code 97802, should they use service type code 1 - Medical Care, 3 - Consultation, MH - Mental Health, or another option? Unfortunately, there’s no standardized mapping between procedure codes and STCs. In fact, payers themselves often don’t have an explicit mapping for their own health plans. Their eligibility check systems aren’t necessarily directly integrated with their claims processing systems, so when you ask them which STC to use, they may not always be able to provide a good answer. Figuring out the best service type codes to use requires some trial and error, and you’ll need to maintain an internal document that contains the mappings for the health plans you most frequently bill. Here’s our recommended approach:

Review the payers’ documentation for eligibility checks. Some payers provide a list of STCs they support and their mappings to procedure codes.
If you can’t find the information in the payer’s documentation, contact the payer directly or reach out to Stedi support, and we’ll contact the payer for you.
For dental payers that don’t support specific CDT codes, you can use either of these sources to map CDT codes to service type codes: the NDEDIC’s Companion to ASC X12 270/271 or Table 6 in the American Dental Association’s Technical Report No. 1102. You can either purchase a copy of these documents or contact Stedi support for recommendations about specific mappings.
If none of the above methods work, you can ask a medical coder with AAPC certification for guidance. Their familiarity with billable codes will help them make good recommendations about service type code mappings.

Common mappings

We recommend testing the following procedure code to STC mappings with your payers: Medical

Procedure	Description	STCs to try
`90867`	Transcranial magnetic stimulation	`MH`, `A4`
`96130`	Psychological testing evaluation	`MH`, `A4`
`96375`	IV push	`92`
`96493`	Chemotherapy, IV push	`82`, `92`
`96494`	Chemotherapy, additional infusion	`82`, `92`
`97802`	Medical nutrition therapy	`1`, `98`, `MH`
`97803`	Medical nutrition follow-up	`1`, `98`, `MH`
`99214`	Psychiatry visits	`MH`, `A4`
`E1399`	Durable medical equipment, miscellaneous	`11`, `12`, `18`

Dental

Procedure	Description	STCs to try
`D4210`	Gingivectomy or gingivoplasty	`25`
`D4381`	Local delivery of antimicrobial agent	`25`
`D5110`	Complete maxillary (upper) denture	`39`

Service Type Codes

You can include the following service type codes in the encounter object to request specific benefits information from the payer. Not all payers support all service type codes, however all payers are required to return benefits information for 30(Plan coverage and general benefits). The word physician in service type codes refers to any healthcare provider, including physician assistants, nurse practitioners, and other types of healthcare professionals. This list is specific to X12 version 005010, the mandated version for eligibility checks. It differs from the current X12 Service Type Codes list, which applies to X12 versions later than 005010. Payers shouldn’t accept or send service type codes not explicitly listed in version 005010.

Service Type Codes

Choosing STCs

STC support varies by payer:

Some only respond to the first STC.
Some ignore the STCs and always return a default response for STC 30 (Health Benefit Plan Coverage).
Some don’t support multiple STCs in a single request.
Some support multiple STCs, but only a limited number per request.

Figuring out which STCs to send for the best results requires some trial and error with each payer. We recommend testing each payer individually using the following process:

Send a request with just STC 30 for general medical benefits or 35 for general dental benefits.
Submit a test request with the specific STC that best matches the benefit type you want to check. For example, to check fertility benefits, you might send an initial request with STC 83 (Infertility).
Send a request with multiple STCs.
Compare the responses. If they change based on the STC or the number of STCs, the payer likely supports them. If not, they may be ignoring or only partially supporting STCs.

Payers & enrollment

Eligibility & benefits

Claims processing

Administrative

Real-time eligibility checks

Transaction enrollment

Testing

Mock requests

Don’t send fake data

Manual submission

API submission

Headers

Body - JSON

Basic eligibility request

Conditional requirements

Body - X12 EDI

Basic eligibility request

BHT03

Character restrictions

Autocorrection for backticks

Sample request and response

Retries

Timeout

Request hedging

Concurrency limit

Avoid payer throttling

Recommended API clients

Patient information

Dependents

Patient names

MBI for CMS checks

Checking eligibility for specific services

Mapping procedure codes

Common mappings

Service Type Codes

Choosing STCs

Payers & enrollment

Eligibility & benefits

Claims processing

Administrative

​Transaction enrollment

​Testing

​Mock requests

​Don’t send fake data

​Manual submission

​API submission

​Headers

​Body - JSON

​Basic eligibility request

​Conditional requirements

​Body - X12 EDI

​Basic eligibility request

​BHT03

​Character restrictions

​Autocorrection for backticks

​Sample request and response

​Retries

​Timeout

​Request hedging

​Concurrency limit

​Avoid payer throttling

​Recommended API clients

​Patient information

​Dependents

​Patient names

​MBI for CMS checks

​Checking eligibility for specific services

​Mapping procedure codes

​Common mappings

​Service Type Codes

​Choosing STCs

Transaction enrollment

Testing

Mock requests

Don’t send fake data

Manual submission

API submission

Headers

Body - JSON

Basic eligibility request

Conditional requirements

Body - X12 EDI

Basic eligibility request

BHT03

Character restrictions

Autocorrection for backticks

Sample request and response

Retries

Timeout

Request hedging

Concurrency limit

Avoid payer throttling

Recommended API clients

Patient information

Dependents

Patient names

MBI for CMS checks

Checking eligibility for specific services

Mapping procedure codes

Common mappings

Service Type Codes

Choosing STCs