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.

​

Transaction enrollment

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

​

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

The information you provide to the payer in an eligibility check can vary, depending on the circumstances. You can review a list of all possible request fields in the documentation for the JSON Eligibility Check endpoint.

However, each eligibility check must include the following information in the request body:

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"
  }
}

​

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.

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.

​

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. It also includes the patientId, which is a unique identifier Stedi uses to identify and correlate historical eligibility checks for the same individual.

Visit Determine patient benefits for details about how you can use the eligibility response to determine a patient’s coverage status and benefits.

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": "AHS",
      "patientId": "UAA111222333",
      "encounter": {
        "serviceTypeCodes": ["MH"]
      },
      "provider": {
        "organizationName": "ACME Health Services",
        "npi": "1999999984" 
      },
      "subscriber": {
        "dateOfBirth": "19000101",
        "firstName": "Jane",
        "lastName": "Doe",
        "memberId": "1234567890"
      }
   }'

​

Test with mock requests

When you submit specific mock requests to the JSON Eligibility Check endpoint, Stedi returns mock benefits data from the specified payer you can use for testing. Visit Send mock requests for a complete list of mock requests you can send.

You can also manually submit mock requests in the Stedi portal by enabling Test mode. Visit Test mode for more details.

​

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.

​

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:

1. The patient is listed as a dependent on the subscriber’s insurance plan.
2. 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 in the subscriber object 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:

• benefitsInformation.benefitsAdditionalInformation.hicNumber
• planInformation.hicNumber

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.

​

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

Dental

​

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.

​

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:

1. Send a request with just STC 30 for general medical benefits or 35 for general dental benefits.
2. 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).
3. Send a request with multiple STCs.
4. 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.

​

Recommended retry strategy

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.