The Batch Eligibility Check API from Stedi — 4 operation(s) for submitting and polling asynchronous batches of X12 270 eligibility checks.
components:
schemas:
AccessDeniedExceptionResponseContent:
description: The server response for authorization failure.
properties:
code:
description: Error classification code
type: string
message:
description: Human-readable error message
type: string
required:
- message
type: object
AdditionalIdentificationDependent:
description: Use this object when you need to provide an additional identification number for the dependent.
This is rarely required for standard eligibility checks.
properties:
agencyClaimNumber:
description: The Property and Casualty Claim Number associated with the patient. You should only submit
this value when when you are submitting an eligibility request to a property and casualty payer.
maxLength: 50
minLength: 1
type: string
contractNumber:
description: The contract number for an existing contract between the payer and the provider requesting
the eligibility check.
maxLength: 50
minLength: 1
type: string
healthInsuranceClaimNumber:
description: This property is never used in practice.
maxLength: 50
minLength: 1
type: string
identificationCardSerialNumber:
description: The identification card serial number. You can include this when the ID card has a number
in addition to the member ID number. The Identification Card Serial Number uniquely identifies the card
when multiple cards have been or will be issued to a member, such as a replacement card.
maxLength: 50
minLength: 1
type: string
insurancePolicyNumber:
description: The insurance policy number.
maxLength: 50
minLength: 1
type: string
medicalRecordIdentificationNumber:
description: The medical record identification number.
maxLength: 50
minLength: 1
type: string
memberIdentificationNumber:
description: 'Not intended for most use cases. Only set this when the property and casualty patient identifier
is a member ID that would be used in an 837 claim submission.
If the patient has their own member ID for the health plan, you should identify them in the `subscriber`
object. If the patient doesn''t have their own member ID, don''t set this property.'
maxLength: 50
minLength: 1
type: string
patientAccountNumber:
description: The patient account number.
maxLength: 50
minLength: 1
type: string
planNetworkIdentificationNumber:
description: The plan network identification number.
maxLength: 50
minLength: 1
type: string
planNumber:
description: The insurance plan number.
maxLength: 50
minLength: 1
type: string
policyNumber:
description: The insurance group or policy number.
maxLength: 50
minLength: 1
type: string
type: object
AdditionalIdentificationSubscriber:
description: 'Use this object when you need to provide an identification number other than or in addition
to the subscriber''s member ID. For example, you may provide the patient account number.
Don''t include the health insurance claim number or the medicaid recipient ID number here unless they are
different from the member ID.'
properties:
agencyClaimNumber:
description: The Property and Casualty Claim Number associated with the patient. You should only submit
this value when when you are submitting an eligibility request to a property and casualty payer.
maxLength: 50
minLength: 1
type: string
contractNumber:
description: The contract number for an existing contract between the payer and the provider requesting
the eligibility check.
maxLength: 50
minLength: 1
type: string
healthInsuranceClaimNumber:
description: The health insurance claim number.
maxLength: 50
minLength: 1
type: string
identificationCardSerialNumber:
description: The identification card serial number. You can include this when the ID card has a number
in addition to the member ID number. The Identification Card Serial Number uniquely identifies the card
when multiple cards have been or will be issued to a member, such as a replacement card.
maxLength: 50
minLength: 1
type: string
insurancePolicyNumber:
description: The insurance policy number.
maxLength: 50
minLength: 1
type: string
medicalRecordIdentificationNumber:
description: The medical record identification number.
maxLength: 50
minLength: 1
type: string
memberIdentificationNumber:
description: This property is never used in practice. Supply the subscriber's member ID in `subscriber.memberId`.
maxLength: 50
minLength: 1
type: string
patientAccountNumber:
description: The patient account number.
maxLength: 50
minLength: 1
type: string
planNetworkIdentificationNumber:
description: The plan network identification number.
maxLength: 50
minLength: 1
type: string
planNumber:
description: The insurance plan number.
maxLength: 50
minLength: 1
type: string
policyNumber:
description: The insurance group or policy number.
maxLength: 50
minLength: 1
type: string
type: object
AdditionalInformation:
properties:
description:
description: A free-form message containing additional information about the benefits in the response.
type: string
type: object
Address:
properties:
address1:
description: The first line of the address.
maxLength: 55
minLength: 1
type: string
address2:
description: The second line of the address.
maxLength: 55
minLength: 1
type: string
city:
description: The city.
maxLength: 30
minLength: 2
type: string
countryCode:
description: The two-letter country code from [Part 1 of ISO 3166](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
maxLength: 2
minLength: 2
type: string
countrySubDivisionCode:
description: The country subdivision code from [Part 2 of ISO 3166](https://en.wikipedia.org/wiki/ISO_3166-2).
maxLength: 3
minLength: 1
type: string
postalCode:
description: The United States or Canadian postal code, excluding punctuation and blanks.
maxLength: 9
minLength: 5
type: string
state:
$ref: '#/components/schemas/ResponseStateOrProvinceCode'
type: object
ApplicationModes:
description: 'The type of data in the request. This is either `production` when you send a request with a
standard API key or `test` when you send a request in test mode with a [test API key](https://www.stedi.com/docs/api-reference/index#api-key-types).
The `information` value is not currently used.
Payers may sometimes return other non-compliant values.'
enum:
- production
- test
- information
type: string
AuthOrCertIndicator:
description: 'Code indicating whether the benefit is subject to prior authorization or certification.
Payers may sometimes return other non-compliant values.'
enum:
- N
- U
- Y
type: string
BatchEligibilityChecksItem:
properties:
controlNumber:
deprecated: true
description: Stedi generates a control number for each eligibility check, so you don’t need to include
this property in your request.
maxLength: 9
minLength: 9
type: string
dependents:
description: 'A dependent for which you want to retrieve benefits information.
- You can only submit one dependent per eligibility check.
- Only include the patient''s information here 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. This includes member IDs that differ only by a suffix, such as `01`, because
the patient can still be uniquely identified.
- Most Medicaid plans don''t support dependents, with a [few exceptions](https://www.stedi.com/docs/healthcare/send-eligibility-checks#medicaid-dependents).
Sending this array to payers that don''t support dependents will either cause an error, or the payer
may ignore the information and return results for the subscriber 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.
- Enter the patient''s name exactly as written on their insurance card, if available, including any
special or punctuation characters such as apostrophes, hyphens (dashes), or spaces. Visit [patient names](https://www.stedi.com/docs/healthcare/send-eligibility-checks#patient-names)
for all best practices to avoid unnecessary failures.'
items:
$ref: '#/components/schemas/RequestDependent'
maxItems: 1
minItems: 1
type: array
eligibilitySearchId:
description: 'An identifier that allows Stedi to group eligibility checks for the same patient into a
unified record in the Stedi portal called an [eligibility search](https://www.stedi.com/docs/healthcare/eligibility-searches-view).
This property is for use by Stedi tools only, such as Stedi''s MCP server.'
type: string
encounter:
$ref: '#/components/schemas/Encounter'
externalPatientId:
description: 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.
maxLength: 36
type: string
informationReceiverName:
$ref: '#/components/schemas/InformationReceiverName'
deprecated: true
description: Use the corresponding properties in the `provider` object instead.
portalPassword:
description: The password that the provider uses to log in to the payer's portal. For payers Medicaid
California, AltaMed, and Kern Family Health Care, this property is **required** and should be the [provider's
PIN](https://www.stedi.com/docs/healthcare/eligibility-troubleshooting#portal-credentials). Otherwise,
this is not commonly used.
maxLength: 50
minLength: 1
type: string
portalUsername:
description: The username that the provider uses to log in to the payer's portal. This is not commonly
used.
maxLength: 50
minLength: 1
type: string
provider:
$ref: '#/components/schemas/Provider'
description: "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.\n - You must provide\
\ the `organizationName` (if the entity is an organization), or `firstName` and `lastName` (if the provider\
\ is an individual).\n - You must also provide an identifier - this is typically the provider's [National\
\ Provider Identifier](https://www.stedi.com/docs/healthcare/national-provider-identifier) (`npi`).\
\ If the provider doesn't have an NPI, you can supply an alternative, such as their `taxId` or `ssn`.\n\
\ - Don't include additional properties, such as `taxId` or `address`, unless they are specifically\
\ required or suggested by the payer."
submitterTransactionIdentifier:
description: A unique identifier for the eligibility check within this batch request. Stedi returns this
identifier in the response for the [Poll Batch Eligibility Checks](https://www.stedi.com/docs/healthcare/api-reference/get-healthcare-polling-eligibility)
endpoint.
type: string
subscriber:
$ref: '#/components/schemas/RequestSubscriber'
tradingPartnerName:
description: The payer's name, such as Cigna or Aetna.
maxLength: 60
minLength: 1
type: string
tradingPartnerServiceId:
description: "The payer ID. Visit the [Payer Network](https://www.stedi.com/healthcare/network) for a\
\ complete list.\n - You can send requests using the primary payer ID, the Stedi payer ID, or any alias\
\ listed in the payer record.\n - You must include leading `0` characters - payer IDs are alphanumeric\
\ strings and must be treated as complete strings, not integers. For example, use `00540` for SISCO,\
\ not `540`."
maxLength: 80
minLength: 1
type: string
required:
- provider
- submitterTransactionIdentifier
- subscriber
- tradingPartnerServiceId
type: object
BatchEligibilityChecksRequestContent:
properties:
items:
description: Each entry in this array represents a single eligibility check. You can submit up to 10,000
eligibility checks in a single request. **Warning:** If _any_ of the individual checks contain invalid
JSON data, such as missing required properties or invalid values, Stedi rejects the entire batch with
a `400` status code and returns errors to help you correct the issues.
items:
$ref: '#/components/schemas/BatchEligibilityChecksItem'
maxItems: 10000
minItems: 1
type: array
maxRetryHours:
description: The maximum number of hours that Stedi will retry eligibility checks in this batch that fail
due to [payer connectivity issues](https://www.stedi.com/docs/healthcare/eligibility-troubleshooting#payer-connectivity-issues).
Must be an integer between 8 and 24 hours. If not specified, the default is 8 hours.
maximum: 24
minimum: 8
type: integer
name:
description: The name that Stedi will use when displaying this batch on the [Eligibility check batches
page](https://portal.stedi.com/app/healthcare/checks/batch). It must be unique within your Stedi account.
If you don't specify a name, Stedi sets this property to the autogenerated `batchId` returned in the
response.
pattern: ^[a-zA-Z0-9-_]{1,100}$
type: string
required:
- items
type: object
BatchEligibilityChecksResponseContent:
properties:
batchId:
description: An identifier for this batch of eligibility checks. You can use this identifier to retrieve
the results of this batch using the [Poll Batch Eligibility Checks](https://www.stedi.com/docs/healthcare/api-reference/get-healthcare-polling-eligibility)
endpoint.
type: string
submittedAt:
description: The date and time that the batch of eligibility checks was submitted to Stedi for processing.
format: date-time
type: string
required:
- batchId
- submittedAt
type: object
BatchEligibilityPollingResponseContent:
description: Common output structure for list operations with pagination support.
properties:
items:
description: "Each eligibility check response is included as a separate item in this array. The response\
\ shape is identical to the shape of the response for the [Real-Time Eligibility Check](https://www.stedi.com/docs/healthcare/api-reference/post-healthcare-eligibility)\
\ endpoint, with the addition of two new properties that help you correlate the results with individual\
\ eligibility checks.\n - `batchId` contains the `batchId` Stedi returned from the [Batch Eligibility\
\ Check](https://www.stedi.com/docs/healthcare/api-reference/post-healthcare-batch-eligibility) endpoint\
\ when making the request.\n - `submitterTransactionIdentifier` contains the unique identifier for\
\ the eligibility check that you submitted in the request."
items:
$ref: '#/components/schemas/BatchEligibilityResultItem'
type: array
nextPageToken:
description: A Stedi-generated token that you can submit in the `pageToken` query parameter to retrieve
the next page of results. If there are no more results, this property is not included in the response.
maxLength: 1024
minLength: 1
type: string
required:
- items
type: object
BatchEligibilityResultItem:
properties:
batchId:
description: The `batchId` Stedi returned from the [Batch Eligibility Check](https://www.stedi.com/docs/healthcare/api-reference/post-healthcare-batch-eligibility)
endpoint.
type: string
batchName:
description: The name Stedi uses when displaying this batch on the [Eligibility check batches page](https://portal.stedi.com/app/healthcare/checks/batch).
If you didn't specify a name when submitting the batch, this is the same as the `batchId`.
pattern: ^[a-zA-Z0-9-_]{1,100}$
type: string
benefitsInformation:
description: "Information about the patient's healthcare benefits, such as coverage level (individual\
\ vs. family), coverage type (deductibles, co-pays, etc.), out of pocket maximums, and more. \n \n 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.\n\nThe payer may send benefits information for service type codes\
\ (STCs) you didn't request - this is expected. The STC you send in the request tells the payer the\
\ types of benefits information you want, but they aren't required to respond with exactly the same\
\ STC(s) in the response. Receiving different STCs than you requested can also mean that the payer is\
\ ignoring the STC you sent, which is why we recommend [testing payers](https://www.stedi.com/docs/healthcare/eligibility-stc-procedure-codes#test-payer-stc-support)\
\ to determine their support for specific STCs.\n\nVisit [Determine patient benefits](https://www.stedi.com/docs/healthcare/eligibility-active-coverage-benefits)\
\ for more information about benefit types, details about how to interpret the `benefitsInformation`\
\ array, and additional examples."
items:
$ref: '#/components/schemas/BenefitsInformation'
type: array
controlNumber:
deprecated: true
description: An identifier for the payer's response.
type: string
dependents:
description: "Information about the patient when they are a dependent. When the patient is a dependent,\
\ this array will contain a single object with the patient's information. When the patient is a subscriber,\
\ or considered to be a subscriber because they have a unique member ID, their information is returned\
\ in the `subscriber` object, and this array will be empty.\n\n 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."
items:
$ref: '#/components/schemas/ResponseDependent'
type: array
eligibilitySearchId:
description: 'An identifier that allows Stedi to group eligibility checks for the same patient into a
unified record in the Stedi portal called an [eligibility search](https://www.stedi.com/docs/healthcare/eligibility-searches-view).
This property is for use by Stedi tools only, such as Stedi''s MCP server.'
type: string
errors:
description: 'When a payer rejects your eligibility check, the response contains one or more [`AAA` errors](https://www.stedi.com/docs/healthcare/eligibility-troubleshooting#payer-aaa-errors)
that specify the reasons for the rejection and any recommended follow-up actions.
Any errors that occur at the `payer`, `provider`, `subscriber`, or `dependents` levels are also included
in this array, allowing you to review all errors in a central location. If there are no `AAA` errors,
this array will be empty.'
items:
$ref: '#/components/schemas/EligibilityCheckError'
type: array
id:
description: 'A globally unique identifier for this eligibility check across all Stedi accounts. It''s
formatted as `ec_<uuid>`. For example: `ec_550e8400-e29b-41d4-a716-446655440000`. You can use this ID
to track this eligibility check and to construct deep links to eligibility checks in the Stedi portal.'
type: string
implementationTransactionSetSyntaxError:
description: The implementation transaction set error code provided in `IK502` of the 999 transaction.
type: string
meta:
$ref: '#/components/schemas/EligibilityMetaDataJSON'
payer:
$ref: '#/components/schemas/Payer'
planDateInformation:
$ref: '#/components/schemas/PlanDateInformation'
planInformation:
$ref: '#/components/schemas/PlanInformation'
planStatus:
deprecated: true
description: Please use `benefitsInformation` instead.
items:
$ref: '#/components/schemas/PlanStatus'
deprecated: true
type: array
provider:
$ref: '#/components/schemas/ResponseProvider'
reassociationKey:
deprecated: true
type: string
status:
description: Errors Stedi encountered when generating or sending the final X12 EDI transaction to the
payer. These can include validation errors and payer unavailable errors that prevent delivery.
type: string
submitterTransactionIdentifier:
description: The unique identifier for the eligibility check that you submitted in the original batch
request.
type: string
subscriber:
$ref: '#/components/schemas/ResponseSubscriber'
subscriberTraceNumbers:
description: 'A unique identifier for the eligibility request. It''s used to trace the transaction. Stedi
always generates a trace number for internal tracking, and the payer may generate one as well. Stedi
returns both its internal trace number and the payer''s trace number (if present) in this array.
You can''t set your own trace number when submitting eligibility checks through this endpoint.'
items:
$ref: '#/components/schemas/SubscriberTraceNumber'
type: array
tradingPartnerServiceId:
description: 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.
type: string
transactionSetAcknowledgement:
description: The transaction set acknowledgment code provided in in the [X12 EDI 999 response](https://portal.stedi.com/app/guides/view/hipaa/implementation-acknowledgment-x231/01HRF41ES1DVGCA6X1EHSRPFXZ#properties.heading.properties.transaction_set_response_header_AK2_loop.items.properties.transaction_set_response_trailer_IK5).
type: string
warnings:
description: Issues with your eligibility request that could affect the results, or information about
the response. For example, warnings can help explain why the request was rejected.
items:
$ref: '#/components/schemas/Warning'
type: array
x12:
description: 'Typically this property contains the raw X12 EDI [271 Eligibility Benefit Response](https://portal.stedi.com/app/guides/view/hipaa/health-care-eligibility-benefit-response-x279a1/01GS66YHZPB37ABF34DBPSR213)
from the payer.
In some circumstances, this property may contain a [999 Implementation Acknowledgment](https://portal.stedi.com/app/guides/view/hipaa/implementation-acknowledgment-x231a1/01HMRQV0N8SPHG58M4ZG1CRHH0)
instead of a 271. A 999 indicates validation errors in the X12 EDI transaction, such as improper formatting
or missing or invalid values.
If the 999 is returned in this property, many of the other response properties will be empty, as they
are mapped to information in the 271.'
type: string
type: object
BatchItem:
description: A batch item representing an individual record in a batch.
properties:
additionalInfo:
$ref: '#/components/schemas/BatchItemAdditionalInfo'
description: Additional information about the eligibility check.
batchId:
description: The ID for the batch containing this eligibility check.
type: string
createdAt:
description: The date and time when the eligibility check was created.
format: date-time
type: string
index:
description: Only relevant for batches submitted through the JSON API. This is the index of the item in
the batch. It starts at 0.
type: integer
requestId:
description: 'A globally unique identifier for this eligibility check within Stedi. Stedi uses this identifier
to construct the URL for the eligibility check''s detail pages within the Stedi portal.
Don''t use this ID to correlate eligibility check requests and responses. Use the `additionalInfo.eligibility.submitterTransactionIdentifier`
property for correlation and tracking instead.'
type: string
rowNumber:
description: Only relevant for batches submitted through CSV upload. This is the row number for this eligibility
check in the CSV file. It starts at 2 because the first row of the CSV file is the header.
type: integer
state:
$ref: '#/components/schemas/BatchItemState'
description: "The current state of the eligibility check. Can be:\n - `PENDING`: Stedi hasn't begun processing\
\ the eligibility check.\n - `VALIDATED`: Stedi finished validating the eligibility check and is ready\
\ to execute it.\n - `VALIDATION_FAILED`: Stedi found errors in the eligibility check that you need\
\ to fix before processing can continue. This is typically due to malformed CSV data, missing required\
\ fields, or invalid values.\n - `STARTED`: Stedi has begun processing the eligibility check.\n -\
\ `RETRYING`: Stedi is retrying the eligibility check. Stedi retries eligibility checks that fail due\
\ to payer connectivity issues for up to 8 hours.\n - `COMPLETED`: Stedi successfully processed the\
\ eligibility check and received a response from the payer. This doesn't indicate that the payer has\
\ active coverage, only that Stedi was able to get a response.\n - `COMPLETED_WITH_ERRORS`: Stedi finished\
\ processing the eligibility check, but couldn't get a response from the payer. A common reason for\
\ failure is payer connectivity issues."
updatedAt:
description: The date and time when the eligibility check was last updated.
format: date-time
type: string
required:
- batchId
- createdAt
- state
- updatedAt
type: object
BatchItemAdditionalInfo:
description: Additional information about the batch item, based on the batch type.
oneOf:
- properties:
eligibility:
$ref: '#/components/schemas/EligibilityBatchItemInfo'
description: Additional information specific to eligibility batch items.
required:
- eligibility
title: eligibility
type: object
BatchItemState:
description: The current state of a batch item, which represents an eligibility check within a batch.
enum:
- PENDING
- VALIDATED
- VALIDATION_FAILED
- STARTED
- RETRYING
- COMPLETED
- COMPLETED_WITH_ERRORS
type: string
BatchSource:
enum:
- CSV_IMPORT
- API
type: string
BatchStatus:
description: The status of the batch.
enum:
- PENDING
- VALIDATED
- VALIDATION_FAILED
- IN_PROGRESS
- COMPLETED
- COMPLETED_WITH_ERRORS
type: string
BatchType:
description: The type of batch.
enum:
- ELIGIBILITY
type: string
BenefitRelatedEntityIdentification:
description: 'Code identifying the type of value provided in `entityIdentificationValue`. For example, `FI`
- Federal Taxpayer''s Identification Number.
Payers may sometimes return other non-compliant values.'
enum:
- '24'
- '34'
- '46'
- FA
- FI
- II
- MI
- NI
- PI
- PP
- SV
- XV
- XX
type: string
BenefitsAdditionalInformation:
description: Identifying information specific to this type of benefit.
properties:
alternativeListId:
description: The alternative list ID. This identifier allows the payer to specify a list of drugs and
its alternative drugs with the associated formulary status for the patient.
type: string
coverageListId:
description: The coverage list ID. This identifier allows the payer to specify the identifier of a list
of drugs that have coverage limitations for the associated patient.
type: string
drugFormularyNumber:
description: The drug formulary number.
type: string
familyUnitNumber:
description: The family unit number. This is returned when the payer is a pharmacy benefits manager (PBM)
and the patient has a suffix to their member ID number that is used in the NCPDP Telecom Standard Insurance
Segment, in field `303-C3` (Person Code). For all other uses, the family unit number (suffix) is considered
part of the patient's member ID number.
type: string
groupDescription:
description: Group name
type: string
groupNumber:
description: The group number for the patient's health insurance plan.
type: string
hicNumber:
description: The health insurance claim number (HICN). Note that CMS previously used the HI
# --- truncated at 32 KB (283 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stedi/refs/heads/main/openapi/stedi-batch-eligibility-check-api-openapi.yml