Batch eligibility checks

Batch eligibility checks are a great option as your volume grows. Stedi handles complexity like queuing and retries according to established best practices, so you don't have to build this logic yourself. We recommend using batch checks for bulk workflows that aren't time sensitive, including:

Monthly or weekly coverage refreshes
Upcoming appointments
Sets of thousands or millions of checks that can run in the background

However, batch checks have a longer feedback cycle than real-time checks because you don't receive the payer's response immediately. That's why we strongly recommend starting with real-time checks when integrating with a new payer or working with eligibility checks for the first time. This approach allows you to ensure that your pipeline is working smoothly before you begin staging batch checks.

You can submit batch checks manually by uploading CSV files to the Stedi portal or programmatically through the API. Each batch can contain up to 1,000 eligibility checks.

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

To upload a CSV file with batch eligibility checks, go to the Eligibility check batches page in the Stedi portal and click + New CSV batch.

CSV upload

You can download a template CSV file with all of the supported properties.

Each row in the file corresponds to one batch eligibility check. You can submit up to 1,000 checks per CSV file.
CSV batch checks support a subset of the properties available in the API. The available properties cover the vast majority of use cases. Contact Stedi support if you need to include additional properties.

Once you upload the CSV file, click Verify file so Stedi can validate the data in each eligibility check. You can fix any validation errors and re-upload the CSV file as many times as needed.

When the file is error-free, you'll be able to click Execute batch to send the eligibility checks to Stedi. Stedi processes the checks asynchronously, implementing best practices to avoid payer throttling.

Batch status

The batch status changes to In progress while Stedi is processing the batch. The status changes to Completed when Stedi has sent all checks in the batch to payers and received responses. A completed batch may contain both successful and failed eligibility checks.

You can retrieve the results of each check in the batch through the Stedi portal or API.

API submission

You can use Stedi's Batch Eligibility Check API to submit up to 1,000 eligibility checks in a single request. Stedi processes these eligibility checks asynchronously, implementing best practices to avoid payer throttling.

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://manager.us.stedi.com/2024-04-01/eligibility-manager/batch-eligibility \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \

Request data

The information you provide to the payer in an eligibility check can vary, depending on the circumstances. However, each batch eligibility check must include at least the following information:

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.
`submitterTransactionIdentifier`	A unique identifier for the eligibility check within the batch. Stedi returns this identifier in the response for the Poll Batch Eligibility Checks endpoint so you can correlate eligibility responses with the original eligibility check.
`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 STCs and procedure codes.

Patient information

Batch checks should follow the same best practices as real-time eligibility checks when entering patient information. Visit Real-time eligibility checks for guidance on:

Which patient identifiers to use for best results
How to know if a patient qualifies as a dependent
How to enter patient names for best results

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.

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.

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.

Don't include the following characters in your request data: ~, *, : and ^. They are reserved for delimiters in the resulting X12 EDI transaction, and X12 doesn't support using escape sequences to represent delimiters or special characters. Stedi returns a 400 error if you include these restricted characters in your request.

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 example demonstrates how to submit a batch of eligibility checks in the items array, where each item represents an individual eligibility check. Stedi returns a batchId that you can use to retrieve the results of these checks later.

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://manager.us.stedi.com/2024-04-01/eligibility-manager/batch-eligibility \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "submitterTransactionIdentifier": "ABC123456789",
      "controlNumber": "000022222",
      "tradingPartnerServiceId": "AHS",
      "encounter": {
        "serviceTypeCodes": [
          "MH"
        ]
      },
      "provider": {
        "organizationName": "ACME Health Services",
        "npi": "1999999984"
      },
      "subscriber": {
        "dateOfBirth": "19000101",
        "firstName": "Jane",
        "lastName": "Doe",
        "memberId": "1234567890"
      }
    },
    {
      "submitterTransactionIdentifier": "DEF123456799",
      "controlNumber": "333344444",
      "tradingPartnerServiceId": "AHS",
      "encounter": {
        "serviceTypeCodes": [
          "78"
        ]
      },
      "provider": {
        "organizationName": "ACME Health Services",
        "npi": "1999999984"
      },
      "subscriber": {
        "dateOfBirth": "19001021",
        "firstName": "John",
        "lastName": "Doe",
        "memberId": "1234567892"
      }
    }
  ]
}'

{
  "batchId": "01928d19-df25-76c0-8d51-f5351260fa05",
  "submittedAt": "2023-11-07T05:31:56Z"
}

Concurrency limit

Asynchronous batch checks don’t count toward your Stedi account concurrency limit for real-time checks.

There are no limits on the number of batches you can run in parallel.

Automatic retries

Stedi retries checks that fail due to payer connectivity issues for up to 8 hours. Therefore, it can take up to 8 hours for all checks in a batch to return results.

Retrieve batch results

After you've submitted a batch of eligibility checks, you can review and retrieve the results through the Stedi portal or API.

Stedi portal

You can review the progress of batch eligibility checks submitted manually through CSV files and programmatically through the API on the Eligibility check batches page.

Click the batch name to view its details, including the status of each check in the batch. You can also download the original CSV input, if the batch was submitted as a CSV file.

On the batch details page, you can click any eligibility check to review it in Eligibility Manager, including the full request and response payload. You'll also be able to edit the request details for failed eligibility checks and resubmit them to the payer.

Polling endpoint

You can use the Poll Batch Eligibility Checks endpoint to retrieve the results from batch checks submitted through both the Stedi portal and API.

Polling strategy

The response only includes completed checks. As a result, a single polling attempt may not retrieve responses for all checks within the batch. Most batches complete in 15–30 minutes. However, it can take up to 8 hours for all checks in a batch to return results.

You can start polling immediately. After the initial poll, use exponential backoff with jitter. Start at 2 minutes and approximately double the wait between polls, up to 8 hours. For example, you might use something similar to the following formula (all values in seconds):

wait_time = (0 if attempt == 0 else min(120 * 2**(attempt - 1), 8*60*60)) + random(0, 30)

In this formula:

Immediate first poll: if attempt == 0 then wait time is 0.
Start at 2 minutes: On attempt == 1, base wait is 120 seconds (2 minutes).
Exponential backoff: Doubles each time: 2, 4, 8, 16, ... minutes.
Cap at 8 hours: min(..., 86060) ensures it never exceeds 480 minutes.
Jitter: Adds a random delay between 0 and 30 seconds.

Track completed checks

The polling endpoint only returns completed checks, and Stedi retries checks that fail due to payer connectivity issues for up to 8 hours. You'll need to track the status of pending checks in your own system to determine when to stop polling.

We recommend doing this by either:

Comparing the total number of checks you sent in the batch with the number of completed checks returned by the polling endpoint.
Matching the submitterTransactionIdentifier of each request to the submitterTransactionIdentifier in each response to ensure every check has been processed.

Filter results

You can filter the polling results using the following query parameters:

batchId: Retrieve results for a specific batch of eligibility checks. You can find this value in the synchronous response from the Batch Eligibility Check endpoint.
startDateTime: Retrieve results for checks submitted after a specific date and time (in ISO 8601 format).

The following example example retrieves the results for batch checks submitted after 2025-12-31T00:00:00Z:

curl --request GET \
  --url https://manager.us.stedi.com/2024-04-01/eligibility-manager/polling/batch-eligibility?startDateTime=2025-12-31T00:00:00Z \
  --header 'Authorization: <api-key>'

Costs

The costs for running a batch eligibility check – manually or using the API – are the same as running the equivalent number of real-time eligibility checks.

For example, if you run a batch with 500 checks, it will cost the same as running 500 real-time eligibility checks.

Minimize waste

We recommend the following to optimize batch eligibility checks:

Periodically purge or archive records for inactive patients. It's a waste to perform eligibility checks on patients who have died or who haven't scheduled an encounter for several years.
Remove or deactivate patients that are no longer eligible. The payer indicates ineligibility by setting benefitsInformation.code = “6” (Inactive) in the response.

Monitor for potential coverage loss

When you receive the results of your batch eligibility checks, look for patients who have coverage that may be at risk.

Check for benefitsInformation.code = “5”, which stands for Active - Pending investigation, or a response containing a benefitsDateInformation.premiumPaidToDateEnd before the current date. Some payers may still show active coverage while the subscriber is behind on premium payments.

You may want to conduct additional checks on these patients because they have an elevated risk of losing coverage soon.

Batch eligibility checks

Basic character set

Extended character set

On this page