Real-Time Eligibility Check
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.
Test endpoint
When you submit specific mock requests, Stedi returns mock benefits data from the specified payer you can use for testing. You need a Stedi API key for authentication, and you must set the stedi-test header to true.
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.
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. It does not need to be globally unique. This value is returned in the response as controlNumber. |
tradingPartnerServiceId | You can find the payer ID in our list of supported payers. |
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). The NPI is a unique, 10-digit identification number assigned to healthcare providers according to HIPAA standards. |
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. |
Character restrictions and replacement
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.
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 informationReceiverName object when you need to include additional information about the provider making the request, such as their specific location.
Timeout and Concurrency
Requests to payers typically time out at 1 minute, though Stedi can keep connections open longer than that if needed.
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.
Insurance payers may take up to 60 seconds to respond to a request, so 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:
Benefit response
Visit Payer benefit response for definitions of key benefit types and information about how to interpret benefits requirements such as prior authorization and referrals.
Network status: The response provides information about the patient’s general in and out-of-network coverage. It does not confirm whether a particular provider is in or out-of-network. To determine network status, you must check directly with the payer. Note that payers may have different networks for different health plans, such as employer-sponsored plans versus Medicare.
Troubleshooting
For a list of possible errors and resolution steps, visit Errors and resolutions.
Authorizations
A Stedi API Key for authentication.
Body
MedicalEligibility
An integer used to identify the transaction. It does not need to be globally unique. This value is returned in the response as controlNumber.
9This 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.
1 - 80An object containing 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 organizationName (if the entity is an organization) or firstName and lastName (if the provider is an individual). You must also provide an identifier - this is typically the provider's National Provider ID (npi).
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 dependents empty. 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 you provide all four of memberId, dateOfBirth, firstName, and lastName, 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.
An internal ID or other value that you use to track the eligibility check within your company's business system. You can use any string value up to 50 characters.
The payer's name, such as Cigna or Aetna.
1 - 80The username that the provider uses to log in to the payer's portal. This is not commonly used.
1 - 50The password that the provider uses to log in to the payer's portal. This is not commonly used.
1 - 50Provide additional information to identify the entity making the eligibility request. For example, if a provider has multiple locations, you may need to provide the address of the specific location. This is also where you can include the Federal Taxpayers Identification Number (EIN) for providers with an NPI.
A dependent for which you want to retrieve benefits information. You can only submit one dependent per eligibility check. An individual qualifies as a dependent for eligibility checks 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. 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.
Details about the eligibility or benefit information you are requesting for the patient. If you don't specify a service date (either a single day or a range of dates), the payer defaults to using the current date in their timezone. If you don't specify either serviceTypeCodes or a procedureCode and productOrServiceIDQualifier, Stedi defaults to using 30 (Plan coverage and general benefits) as the only serviceTypeCodes value. 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. Note that payers can have different rules for future dates of service - for example, some payers may only return benefits information for dates up to the end of the current calendar month, but others may support dates further into the future.
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.
The unique identifier for the eligibility search being edited and 'retried'.
Response
Metadata about the response. Stedi uses this data for tracking and troubleshooting.
The control number you sent in the original eligibility check request.
Deprecated; do not use.
An ID for the payer you identified in the original eligibility check request. This value may differ from the tradingPartnerServiceId you submitted in the original request because it reflects the payer's internal concept of their ID, not necessarily the ID Stedi uses to route requests to this payer.
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.
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.
A unique identifier the payer may assign to the transaction. Note that Stedi doesn't support setting a subscriber trace number in the eligibility check request because there is no need to include a trace number for real-time queries.
Information about dependents listed in the original eligibility check request. Note that a dependent submitted in the request may be returned in the subscriber object. When present, this object will always include the dependent's name for identification, but many payers will also return the date of birth and other identifying information.
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.
Additional identification for the subscriber's healthcare plan.
Contains the dates associated with the subscriber's insurance plan. This information is used to determine the patient's eligibility for benefits. All dates are formatted as YYYYMMDD (for single dates) or as YYYYMMDD-YYYYMMDD (for date ranges). The provided dates apply to every every benefit within the patient's health plan unless specifically noted within a benefitsInformation.benefitsDateInformation object. Properties contain a single date unless otherwise noted. Most payers return either plan or planBegin and planEnd, but the exact dates returned depend on the payer's discretion and the patient's insurance plan.
When a payer rejects your eligibility check, the response contains one or more 'AAA' errors that specify the reasons for the rejection and any recommended follow-up actions. Learn more
Warnings indicate non-fatal issues with your eligibility check or a non-standard response from the payer.
The transaction set acknowledgment code provided in in the X12 EDI 999 response.
The implementation transaction set error code provided in IK502 of the 999 transaction.
The raw X12 EDI 271 Eligibility Benefit Response from the payer.
Deprecated; please use benefitsInformation.
Information about the subscriber or dependents' healthcare benefits, such as coverage level (individual vs. family), coverage type (deductibles, copays, etc.), out of pocket maximums, and more. Payers typically return at least the following properties: code, coverageLevelCode, serviceTypeCodes, and either benefitAmount or benefitPercent. However, the exact properties returned in this object are up to the payer's discretion. Visit Payer benefit response for more information about benefit types, details about how to interpret the response, and additional examples.
Was this page helpful?