Real-Time Eligibility Check (270/271) JSON

This endpoint sends real-time eligibility checks to payers. Visit Check eligibility for a full how-to guide.

• Call this endpoint with a JSON payload.
• Stedi translates your request to the X12 270 EDI format and sends it to the payer.
• 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.

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.

Test endpoint with mock requests

When you submit specific mock requests, Stedi returns mock benefits data from the specified payer you can use for testing. Mock requests are free for testing purposes and won’t incur any charges in your Stedi account. Visit Send mock requests for additional 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.

Basic eligibility check

The content of your eligibility request depends on your use case and the payer’s requirements. However, a basic eligibility check includes 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	You can find the payer ID in our list of supported payers. If you don’t know the payer, try submitting an insurance discovery check instead.
provider object, name	You must include the provider’s name - either the firstName and lastName of a specific provider within a practice or the organizationName.
provider object, identifier	You must include an identifier. Most often this is the National Provider Identifier (NPI).
subscriber and/or dependents objects	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. We recommend submitting dates up to 12 months in the past or up to the end of the current month. Dates outside of these ranges are likely to be rejected by many payers, since they may have archived older data and they cannot guarantee eligibility for future months.
encounter object, service or procedure codes	Specify serviceTypeCodes and/or a procedureCode and productOrServiceIDQualifier to request specific types of benefits information. We don’t know which payers support multiple service type codes, so we recommend including no more than one in each request. If you do not include any of these fields, Stedi defaults to using 30 (Plan coverage and general benefits) as the only serviceTypeCodes value. Learn more about checking eligibility for specific services.

MBI lookup for CMS: You must include the patient’s Medicare Beneficiary Identifier (MBI) in every eligibility check to the Centers for Medicare and Medicaid Services (Payer ID: CMS). If the patient doesn’t know their MBI, you can perform an MBI lookup using their Social Security Number instead. Learn more

Character restrictions

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.

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

The X12 Basic character set includes uppercase letters, digits, space, and some special characters. Lowercase letters and special language characters like ñ are not included.

The following special characters are included:

Extended character set

The Extended character set includes the characters listed in Basic, plus lowercase letters and additional special characters, such as @.

The following additional special characters are included:

Autocorrection

Stedi automatically replaces backticks (`), also known as backquotes or grave accents, with a single quote (') in subscriber and dependents first and last names. This autocorrection prevents errors when submitting your request to payers and intermediary clearinghouses. Stedi returns a message in the response’s warnings array when it makes this replacement.

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.

Benefit response

Visit Determine patient benefits for detailed explanations and examples of how to use the benefit response to determine the patient’s active coverage, financial responsibility, requirements such as referrals or authorizations, and more.

Network status: The response typically doesn’t confirm whether a particular provider is in- or out-of-network for the patient’s health plan. The most reliable way to confirm network status is by checking with the payer or provider directly. Learn more

Our documentation lists all enums officially allowed in the payer benefit response. Some payers return non-compliant values, which Stedi passes through as is.

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",
  "eligibilitySearchId": "019249c7-e176-76b0-a46a-3aef1a519bc4"
}

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.

Troubleshooting

For a list of possible errors and resolution steps, visit Errors and resolutions.

Authorizations

Authorization · string · header · required

A Stedi API Key for authentication.

Headers

stedi-test · boolean · deprecated

Please create a test API key to submit requests in test mode.

Body

application/json

Response

200

application/json

EligibilityCheck 200 response

The response is of type object.