Batch Eligibility Check

Submit multiple eligibility checks for Stedi to process asynchronously

POST/eligibility-manager/batch-eligibility

You may want to periodically conduct asynchronous batch eligibility checks for your entire patient population or a subset of patients, such as those who have active care plans or who have future services scheduled. These data refreshes allow you to proactively reach out to patients when they lose or change coverage.

Call this endpoint with a JSON payload containing one or more eligibility checks. You can submit up to 1,000 individual eligibility checks within a single batch, and you can submit as many batches as you need to process.
The endpoint returns a synchronous response containing a batchId that you can use to retrieve the results of these checks later, using the Poll Batch Eligibility Checks endpoint.
Stedi translates each eligibility check included in the request to the X12 270 EDI format and sends it to the appropriate payer.

Visit Batch refresh checks for a complete how-to guide.

Start with real-time checks

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. To perform synchronous eligibility checks, use the Real-Time Eligibility Check endpoint.

Authorizations

Authorizationstringrequiredheader

A Stedi API Key for authentication.

Body

application/json

itemsarray<object>required

Each entry in this array represents a single eligibility check. You can submit up to 1,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.

Array item

items[].controlNumberstringrequired

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.

Required string length: 9

items[].dependentsarray<object>

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.
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 for all best practices to avoid unnecessary failures.

Array item

items[].dependents[].additionalIdentificationobject

Use this object when you need to provide an additional identification number for the dependent. This is rarely required for standard eligibility checks.

Show attributes

items[].dependents[].additionalIdentification.agencyClaimNumberstring

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.

Required string length: 1 - 50

items[].dependents[].additionalIdentification.contractNumberstring

The contract number for an existing contract between the payer and the provider requesting the eligibility check.

Required string length: 1 - 50

items[].dependents[].additionalIdentification.healthInsuranceClaimNumberstring

This property is never used in practice.

Required string length: 1 - 50

items[].dependents[].additionalIdentification.identificationCardSerialNumberstring

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.

Required string length: 1 - 50

items[].dependents[].additionalIdentification.insurancePolicyNumberstring

The insurance policy number.

Required string length: 1 - 50

items[].dependents[].additionalIdentification.medicalRecordIdentificationNumberstring

The medical record identification number.

Required string length: 1 - 50

items[].dependents[].additionalIdentification.memberIdentificationNumberstring

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.

Required string length: 1 - 50

items[].dependents[].additionalIdentification.patientAccountNumberstring

The patient account number.

Required string length: 1 - 50

items[].dependents[].additionalIdentification.planNetworkIdentificationNumberstring

The plan network identification number.

Required string length: 1 - 50

items[].dependents[].additionalIdentification.planNumberstring

The insurance plan number.

Required string length: 1 - 50

items[].dependents[].additionalIdentification.policyNumberstring

The insurance group or policy number.

Required string length: 1 - 50

items[].dependents[].addressobject

The dependent's address. You must include at least the address1 and city properties in this object.

Show attributes

items[].dependents[].address.address1stringrequired

The first line of the address.

Required string length: 1 - 55

items[].dependents[].address.address2string

The second line of the address.

Required string length: 1 - 55

items[].dependents[].address.citystringrequired

The city.

Required string length: 2 - 30

items[].dependents[].address.countryCodestring

The two-letter country code from Part 1 of ISO 3166.

Required string length: 2

items[].dependents[].address.countrySubDivisionCodestring

The country subdivision code from Part 2 of ISO 3166.

Required string length: 1 - 3

items[].dependents[].address.postalCodestring

The United States or Canadian postal code, excluding punctuation and blanks.

Required string length: 5 - 9

items[].dependents[].address.statestring

The US state or Canadian province code. For example, TN for Tennessee or NB for New Brunswick.

Payers may sometimes return other non-compliant values.

Possible values

NL

PE

NS

NB

QC

items[].dependents[].beginningCardIssueDatestringdeprecated

Deprecated; The date the insurance card was issued. This shape is deprecated: This property is no longer used.

Pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$

items[].dependents[].beginningPlanIssueDatestringdeprecated

Deprecated; The date the insurance plan begins. This shape is deprecated: This property is no longer used.

Pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$

items[].dependents[].birthSequenceNumberstring

The number assigned to each family member born with the same birth date, such as twins or triplets. Use to indicate the birth order when there are multiple births associated with the provided birth date.

Pattern: ^[0-9]+$
Required string length: 1 - 9

items[].dependents[].dateOfBirthstring

The dependent's date of birth (DOB). We strongly recommend including the DOB in your request. Many payers need this information to identify the patient in their system and will immediately return an error when it's not provided.

Pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$

items[].dependents[].eligibilityCategorystring

The eligibility category for the dependent.

Required string length: 1 - 50

items[].dependents[].endCardIssueDatestringdeprecated

Deprecated; The date the insurance card expires. This shape is deprecated: This property is no longer used.

Pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$

items[].dependents[].endPlanIssueDatestringdeprecated

Deprecated; The date the insurance plan ends. This shape is deprecated: This property is no longer used.

Pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$

items[].dependents[].firstNamestring

The dependent's first name.

Required string length: 1 - 35

items[].dependents[].genderstring

Code indicating the dependent's gender.

Possible values

M

F

items[].dependents[].groupNumberstring

The group number for the dependent's insurance plan.

Required string length: 1 - 50

items[].dependents[].healthCareCodeInformationarray<object>

Information about the dependent's health care diagnosis. You can include up to eight entries in this array.

The first array entry must have diagnosisTypeCode set to ABK. All subsequent entries must have diagnosisTypeCode set to ABF.

Array item

items[].dependents[].healthCareCodeInformation[].diagnosisCodestringrequired

The diagnosis code. Omit the decimal points in diagnosis codes - the decimal point is assumed.

Pattern: ^[A-Za-z0-9]+$
Required string length: 1 - 30

items[].dependents[].healthCareCodeInformation[].diagnosisTypeCodestringrequired

The type of diagnosis code you are providing. You can set to BK - International Classification of Diseases Clinical Modification (ICD-9-CM) Principal Diagnosis, ABK - International Classification of Diseases Clinical Modification (ICD-10-CM) Principal Diagnosis, BF- International Classification of Diseases Clinical Modification (ICD-9-CM) Diagnosis, or ABF- International Classification of Diseases Clinical Modification (ICD-10-CM) Diagnosis.

Note that ICD-9 codes are deprecated and should no longer be used in eligibility checks.

Possible values

BK

ABK

BF

ABF

items[].dependents[].idCardstring

The dependent's insurance card number.

Required string length: 1 - 50

items[].dependents[].idCardIssueDatestringdeprecated

Deprecated; The date the identification card was issued. This shape is deprecated: This property is no longer used.

Pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$

items[].dependents[].individualRelationshipCodestring

The dependent's relationship to the subscriber. You can set this to 01 - Spouse, 19 - Child, 34 - Other Adult.

Possible values

01

19

34

items[].dependents[].issueNumberstring

The issue number for the dependent's insurance policy.

Required string length: 1 - 50

items[].dependents[].lastNamestring

The dependent's last name. Don't include the dependent's name suffix, such as Jr. or III. Use the designated suffix property instead.

Required string length: 1 - 60

items[].dependents[].memberIdstringdeprecated

This shape is deprecated: This property is no longer used.

Pattern: ^[A-Za-z0-9- ]+$
Required string length: 2 - 80

items[].dependents[].middleNamestring

The dependent's middle name or middle initial.

Required string length: 1 - 25

items[].dependents[].planIssueDatestringdeprecated

This shape is deprecated: This property is no longer used.

Pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$

items[].dependents[].providerCodestring

Use this for providers that are not requesting the eligibility check - the requestor is specified in the provider object. For example, if you are a hospital making an eligibility request, this is where you would specify information about a referring provider's role.

You can use one of the following: AD - Admitting, AT - Attending, BI - Billing, CO - Consulting, CV - Covering, H - Hospital, HH - Home Health Care, LA - Laboratory, OT - Other Physician, P1 - Pharmacist, P2 - Pharmacy, PC - Primary Care Physician, PE- Performing, R- Rural Health Clinic, RF - Referring, SB - Submitting, SK - Skilled Nursing Facility, SU - Supervising

Possible values

AD

AT

BI

CO

CV

items[].dependents[].providerIdentifierstring

The provider identifier you specified in the referenceIdentificationQualifier property. For example, the provider's National Provider ID or Federal Taxpayer Identification number. If you set the referenceIdentificationQualifier to PXC, then this property should contain the provider's taxonomy code.

Pattern: ^[A-Za-z0-9]+$
Required string length: 1 - 50

items[].dependents[].referenceIdentificationQualifierstring

The type of providerIdentifier you are using. Use for providers that are not requesting the eligibility check, such as the referring provider.

Set to HPI when the National Provider ID is mandated for use.
Set to PXC if you're identifying a type of specialty associated with services provided to the dependent.

Otherwise, you can set to the following: 9K - Servicer, D3 - National Council for Prescription Drug Programs Pharmacy Number, EI - Employer's Identification Number, HPI - Centers for Medicare and Medicaid Services National Provider Identifier, PXC - Health Care Provider Taxonomy Code, SY - Social Security Number, TJ - Federal Taxpayer's Identification Number

Possible values

9K

D3

EI

HPI

PXC

items[].dependents[].ssnstring

The dependent's social security number. Don't use this for Federally-administered programs, such as Medicare.

Pattern: ^\d{9}$

items[].dependents[].suffixstring

The dependent's name suffix, such as Sr. or III. Only include the dependent's personal name suffix - don't include professional or academic titles, such as M.D. or MBA.

Required string length: 1 - 10

items[].eligibilitySearchIdstring

An identifier that allows Stedi to group eligibility checks for the same patient into a unified record within Eligibility Manager called an eligibility search.

This property is for use by Stedi tools only, such as Stedi's MCP server.

items[].encounterobject

Details about the eligibility or benefit information you are requesting for the patient.

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.
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.

Show attributes

items[].encounter.beginningDateOfServicestring

The beginning date of service. If you include this value, you must also include the endDateOfService.

Pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$

items[].encounter.dateOfServicestring

The date of service. You can use this value to specify a single occasion, such as a doctor's visit. 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.

Pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$

items[].encounter.diagnosisCodePointerarray<string>

Diagnosis code pointers in order of importance to the service. These pointers are an index to the ICD-10 codes you included in the subscriber.healthCareCodeInformation or dependents.healthCareCodeInformation object arrays. The pointer values can be from 1 - 8 (integer numbers). If you are including diagnosis codes, you must set at least one pointer here for the primary diagnosis. Then, you can add up to three additional pointers (up to four in total). Don't put ICD-10 codes here.

items[].encounter.endDateOfServicestring

The end date of service. If you include this value, you must also include the beginningDateOfService.

Pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$

items[].encounter.industryCodestring

The type of facility where the service was provided. You can set this to one of the place of service codes.

Possible values

01

02

03

04

05

items[].encounter.medicalProceduresarray<object>

Use only when you need to send multiple procedure codes in a single request. Otherwise, use the encounter.procedureCode and encounter.productOrServiceIDQualifier properties.

Array item

items[].encounter.medicalProcedures[].diagnosisCodePointerarray<string>

The diagnosis code pointer.

items[].encounter.medicalProcedures[].procedureCodestringrequired

The procedure code.

Required string length: 1 - 48

items[].encounter.medicalProcedures[].procedureModifiersarray<string>

Procedure modifiers that provide additional information related to the service.

items[].encounter.medicalProcedures[].productOrServiceIDQualifierstringrequired

Code identifying the type/source of the procedureCode. You can set this to AD - American Dental Association Codes, CJ - Current Procedural Terminology (CPT) Codes, HC - Health Care Financing Administration Common Procedural Coding System (HCPCS) Codes, ID - International Classification of Diseases, 9th Revision, Clinical Modification (ICD-9-CM) - Procedure, IV - Home Infusion EDI Coalition (HIEC) Product/Service Code, N4 - National Drug Code in 5-4-2 Format, or ZZ - Mutually Defined.

Possible values

AD

CJ

HC

ID

IV

items[].encounter.priorAuthorizationOrReferralNumberstring

The prior authorization or referral number for a particular benefit or procedure.

items[].encounter.procedureCodestring

The procedure code.

Required string length: 1 - 48

items[].encounter.procedureModifiersarray<string>

The procedure modifier that provides additional information related to the performance of the service.

items[].encounter.productOrServiceIDQualifierstring

Possible values

AD

CJ

HC

ID

IV

items[].encounter.referenceIdentificationQualifierstring

The type of information you provided in the priorAuthorizationOrReferralNumber property. You can set this to 9F - Referral Number or G1 - Prior Authorization Number.

Possible values

9F

G1

items[].encounter.serviceTypeCodesarray<string>

One or more codes classifying the type of services for which you want to receive benefits information.

If you don't specify a service type code or a procedureCode and productOrServiceIDQualifier, Stedi defaults to using 30 - Health Benefit Plan Coverage. Visit Service Type Codes for a complete list.

Not all payers support all service type codes, and not all payers support multiple service type codes in the same request. We recommend including one service type code per request unless you're sure the payer supports multiple.

Payers aren't required to respond with exactly the same STC(s) in the response, so you may receive benefits information for STCs you didn't request. However, receiving different STCs can mean that the payer is ignoring the STC you sent, which is why we recommend testing payers to determine their support for specific STCs.

items[].externalPatientIdstring

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.

Maximum length: 36

items[].informationReceiverNameobjectdeprecated

Use the corresponding properties in the provider object instead.

Show attributes

items[].informationReceiverName.addressobjectdeprecated

Show attributes

items[].informationReceiverName.address.address1stringrequired

The first line of the address.

Required string length: 1 - 55

items[].informationReceiverName.address.address2string

The second line of the address.

Required string length: 1 - 55

items[].informationReceiverName.address.citystringrequired

The city.

Required string length: 2 - 30

items[].informationReceiverName.address.countryCodestring

The two-letter country code from Part 1 of ISO 3166.

Required string length: 2

items[].informationReceiverName.address.countrySubDivisionCodestring

The country subdivision code from Part 2 of ISO 3166.

Required string length: 1 - 3

items[].informationReceiverName.address.postalCodestring

The United States or Canadian postal code, excluding punctuation and blanks.

Required string length: 5 - 9

items[].informationReceiverName.address.statestring

The US state or Canadian province code. For example, TN for Tennessee or NB for New Brunswick.

Payers may sometimes return other non-compliant values.

Possible values

NL

PE

NS

NB

QC

items[].informationReceiverName.contactNumberstringdeprecated

Required string length: 1 - 50

items[].informationReceiverName.contractNumberstringdeprecated

Required string length: 1 - 50

items[].informationReceiverName.devicePinNumberstringdeprecated

Required string length: 1 - 50

items[].informationReceiverName.facilityIdNumberstringdeprecated

Required string length: 1 - 50

items[].informationReceiverName.facilityNetworkIdNumberstringdeprecated

Required string length: 1 - 50

items[].informationReceiverName.federalTaxpayerIdentificationNumberstringdeprecated

Required string length: 1 - 50

items[].informationReceiverName.informationReceiverAdditionalIdentifierStatestringdeprecated

Required string length: 1 - 80

items[].informationReceiverName.medicaidProviderNumberstringdeprecated

The provider's Medicaid provider number.

Required string length: 1 - 50

items[].informationReceiverName.medicareProviderNumberstringdeprecated

Required string length: 1 - 50

items[].informationReceiverName.nationalProviderIdentifierstringdeprecated

Required string length: 1 - 50

items[].informationReceiverName.priorIdentifierNumberstringdeprecated

Required string length: 1 - 50

items[].informationReceiverName.providerPlanNetworkIdNumberstringdeprecated

Required string length: 1 - 50

items[].informationReceiverName.socialSecurityNumberstringdeprecated

Required string length: 1 - 50

items[].informationReceiverName.stateLicenceNumberstringdeprecated

Required string length: 1 - 50

items[].informationReceiverName.submitterIdNumberstringdeprecated

Required string length: 1 - 50

items[].portalPasswordstring

The password that the provider uses to log in to the payer's portal. This is not commonly used.

Required string length: 1 - 50

items[].portalUsernamestring

The username that the provider uses to log in to the payer's portal. This is not commonly used.

Required string length: 1 - 50

items[].providerobjectrequired

An 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).

Show attributes

items[].provider.addressobject

The address of the provider requesting the information. Only include when specifically instructed by a payer, such as when the provider has multiple locations and you need to identify the specific location making the request. You must include at least the address1 and city properties in this object.

Show attributes

items[].provider.address.address1stringrequired

The first line of the address.

Required string length: 1 - 55

items[].provider.address.address2string

The second line of the address.

Required string length: 1 - 55

items[].provider.address.citystringrequired

The city.

Required string length: 2 - 30

items[].provider.address.countryCodestring

The two-letter country code from Part 1 of ISO 3166.

Required string length: 2

items[].provider.address.countrySubDivisionCodestring

The country subdivision code from Part 2 of ISO 3166.

Required string length: 1 - 3

items[].provider.address.postalCodestring

The United States or Canadian postal code, excluding punctuation and blanks.

Required string length: 5 - 9

items[].provider.address.statestring

The US state or Canadian province code. For example, TN for Tennessee or NB for New Brunswick.

Payers may sometimes return other non-compliant values.

Possible values

NL

PE

NS

NB

QC

items[].provider.contactNumberstringdeprecated

The provider's contract number. Only include when required by a payer. This shape is deprecated: Use contractNumber instead.

Required string length: 1 - 50

items[].provider.contractNumberstring

The provider's contract number. Only include when required by a payer.

Required string length: 1 - 50

items[].provider.devicePinNumberstring

The provider's electronic device pin number. Only include when required by a payer.

Required string length: 1 - 50

items[].provider.employersIdstringdeprecated

Deprecated; The submitter's Employer's Identification Number (EIN). Only use when an employer is checking the eligibility and benefits of their employees. This shape is deprecated: This property is no longer used.

Required string length: 2 - 80

items[].provider.facilityIdNumberstring

The ID number for the provider's facility. Only include when required by a payer.

Required string length: 1 - 50

items[].provider.facilityNetworkIdNumberstring

The provider's facility network identification number. Only include when required by a payer.

Required string length: 1 - 50

items[].provider.firstNamestring

The provider's first name. This property is required if the provider is an individual.

Required string length: 1 - 35

items[].provider.informationReceiverAdditionalIdentifierStatestring

The two-character state ID of the state that assigned the stateLicenseNumber. Only include when required by a payer.

Required string length: 1 - 80

items[].provider.lastNamestring

The provider's last name. This property is required if the provider is an individual.

Required string length: 1 - 60

items[].provider.medicaidProviderNumberstring

The provider's Medicaid provider number. Only include when required by a payer.

Required string length: 1 - 50

items[].provider.medicareProviderNumberstring

The provider's Medicare provider number. Only include when required by a payer.

Required string length: 1 - 50

items[].provider.npistring

The provider's National Provider Identifier (NPI). This identifier is required for all healthcare providers who are eligible to receive an NPI. Some non-traditional providers such as transportation services, durable medical equipment (DME) suppliers, or alternative medicine practitioners are not eligible to receive an NPI. If the provider doesn't have an NPI, requests with alternate IDs are virtually never supported. In the rare circumstance that a payer has instructed you to use an alternate ID, the payer will typically require you to supply either their taxId or ssn instead.

Pattern: ^\d{10}$

items[].provider.organizationNamestring

The provider's business name. This property is required if the provider is not an individual.

Required string length: 1 - 60

items[].provider.payorIdstring

Only used for payer-to-payer transactions, which are not currently supported. Do not use.

Required string length: 2 - 80

items[].provider.pharmacyProcessorNumberstring

The provider's pharmacy processor number. Only include when specifically instructed by a payer - for example, when the provider doesn't have an NPI. This use case is very rarely supported, and is typically when the provider is a non-medical provider, such as a social worker, home health aide, or transportation service.

Required string length: 2 - 80

items[].provider.priorIdentifierNumberstring

The provider's prior identifier number. Only include when required by a payer.

Required string length: 1 - 50

items[].provider.providerCodestring

Communicate the provider's role in the type of benefits specified in the request. Visit Eligibility code lists for a complete list. Only include when required by a payer.

Possible values

AD

AT

BI

CO

CV

items[].provider.providerPlanNetworkIdNumberstring

The provider's plan network identification number. Only include when required by a payer.

Required string length: 1 - 50

items[].provider.providerTypestring

Identify the type of provider.

Possible values

payer

third-party administrator

employer

hospital

facility

items[].provider.referenceIdentificationstring

The provider's Taxonomy Code. Only used when the provider's taxonomy code is relevant to the eligibility/benefit inquiry. For example, an institutional provider such as a hospital may need to use a taxonomy code to specify a specific unit or department.

items[].provider.serviceProviderNumberstring

The provider's service provider number. Only include when specifically instructed by a payer - for example, when the provider doesn't have an NPI. This use case is very rarely supported, and is typically when the provider is a non-medical provider, such as a social worker, home health aide, or transportation service.

Required string length: 2 - 80

items[].provider.servicesPlanIDstringdeprecated

Required string length: 2 - 80

items[].provider.ssnstring

The provider's Social Security Number (SSN). - Only include when specifically instructed by a payer - for example, if the provider doesn't have an NPI. This use case is very rarely supported, and is typically when the provider is a non-medical provider, such as a social worker, home health aide, or transportation service. - If the payer has instructed you to send an EIN but the provider operates using their SSN, use provider.taxId instead of this field. - Don't use this for Federally-administered programs, such as Medicare.

Pattern: ^\d{9}$

items[].provider.stateLicenceNumberstring

The provider's state license number. If you include this information, you must also include the informationReceiverAdditionalIdentifierState. Only include when required by a payer.

Required string length: 1 - 50

items[].provider.submitterIdNumberstring

The provider's submitter identification number. Only include when required by a payer.

Required string length: 1 - 50

items[].provider.taxIdstring

The provider's Federal Taxpayer Identification Number. This is typically the provider's EIN (Employer Identification Number), but the provider's SSN may be used if the provider does not have an EIN. Only include if required by the payer.

Pattern: ^\d{9}$

items[].submitterTransactionIdentifierstringrequired

A unique identifier for the eligibility check within this batch request. Stedi returns this identifier in the response for the Poll Batch Eligibility Checks endpoint.

items[].subscriberobjectrequired

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.
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 for all best practices to avoid unnecessary failures.

Show attributes

items[].subscriber.additionalIdentificationobject

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.

Show attributes

items[].subscriber.additionalIdentification.agencyClaimNumberstring

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.

Required string length: 1 - 50

items[].subscriber.additionalIdentification.contractNumberstring

The contract number for an existing contract between the payer and the provider requesting the eligibility check.

Required string length: 1 - 50

items[].subscriber.additionalIdentification.healthInsuranceClaimNumberstring

The health insurance claim number.

Required string length: 1 - 50

items[].subscriber.additionalIdentification.identificationCardSerialNumberstring

Required string length: 1 - 50

items[].subscriber.additionalIdentification.insurancePolicyNumberstring

The insurance policy number.

Required string length: 1 - 50

items[].subscriber.additionalIdentification.medicalRecordIdentificationNumberstring

The medical record identification number.

Required string length: 1 - 50

items[].subscriber.additionalIdentification.memberIdentificationNumberstring

This property is never used in practice. Supply the subscriber's member ID in subscriber.memberId.

Required string length: 1 - 50

items[].subscriber.additionalIdentification.patientAccountNumberstring

The patient account number.

Required string length: 1 - 50

items[].subscriber.additionalIdentification.planNetworkIdentificationNumberstring

The plan network identification number.

Required string length: 1 - 50

items[].subscriber.additionalIdentification.planNumberstring

The insurance plan number.

Required string length: 1 - 50

items[].subscriber.additionalIdentification.policyNumberstring

The insurance group or policy number.

Required string length: 1 - 50

items[].subscriber.addressobject

The subscriber's address. You must include at least the address1 and city properties in this object.

Show attributes

items[].subscriber.address.address1stringrequired

The first line of the address.

Required string length: 1 - 55

items[].subscriber.address.address2string

The second line of the address.

Required string length: 1 - 55

items[].subscriber.address.citystringrequired

The city.

Required string length: 2 - 30

items[].subscriber.address.countryCodestring

The two-letter country code from Part 1 of ISO 3166.

Required string length: 2

items[].subscriber.address.countrySubDivisionCodestring

The country subdivision code from Part 2 of ISO 3166.

Required string length: 1 - 3

items[].subscriber.address.postalCodestring

The United States or Canadian postal code, excluding punctuation and blanks.

Required string length: 5 - 9

items[].subscriber.address.statestring

The US state or Canadian province code. For example, TN for Tennessee or NB for New Brunswick.

Payers may sometimes return other non-compliant values.

Possible values

NL

PE

NS

NB

QC

items[].subscriber.beginningCardIssueDatestringdeprecated

Deprecated; The date the subscriber's identification card was issued. This shape is deprecated: This property is no longer used.

Pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$

items[].subscriber.beginningPlanIssueDatestringdeprecated

Deprecated; The date the subscriber's insurance plan was issued. This shape is deprecated: This property is no longer used.

Pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$

items[].subscriber.birthSequenceNumberstring

Pattern: ^[0-9]$
Required string length: 1 - 9

items[].subscriber.caseNumberstring

The case number associated with the subscriber.

Pattern: ^[A-Za-z0-9]+$
Required string length: 1 - 50

items[].subscriber.coverageLevelCodestring

This property is no longer used.

items[].subscriber.dateOfBirthstring

The subscriber's date of birth.

Pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$

items[].subscriber.endCardIssueDatestringdeprecated

Deprecated; The date the subscriber's identification card expires. This shape is deprecated: This property is no longer used.

Pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$

items[].subscriber.endPlanIssueDatestringdeprecated

Deprecated; The date the subscriber's insurance plan ended. This shape is deprecated: This property is no longer used.

Pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$

items[].subscriber.firstNamestring

The patient's first name.

Required string length: 1 - 35

items[].subscriber.genderstring

Code indicating the subscriber's gender.

Possible values

M

F

items[].subscriber.groupNumberstring

The group number associated with the subscriber's insurance policy.

Required string length: 1 - 50

items[].subscriber.healthCareCodeInformationarray<object>

Information about the subscriber's health care diagnosis. You can include up to eight entries in this array.

The first array entry must have diagnosisTypeCode set to ABK. All subsequent entries must have diagnosisTypeCode set to ABF.

Array item

items[].subscriber.healthCareCodeInformation[].diagnosisCodestringrequired

The diagnosis code. Omit the decimal points in diagnosis codes - the decimal point is assumed.

Pattern: ^[A-Za-z0-9]+$
Required string length: 1 - 30

items[].subscriber.healthCareCodeInformation[].diagnosisTypeCodestringrequired

Note that ICD-9 codes are deprecated and should no longer be used in eligibility checks.

Possible values

BK

ABK

BF

ABF

items[].subscriber.idCardstring

The subscriber's identification card number. Include this property when this number is different than the subscriber's member ID. This is common in Medicaid.

Required string length: 1 - 50

items[].subscriber.idCardIssueDatestringdeprecated

Deprecated; The date the subscriber's identification card was issued. This shape is deprecated: This property is no longer used.

Pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$

items[].subscriber.lastNamestring

The subscriber's last name. Don't include the subscriber's name suffix, such as Jr. or III. Use the designated suffix property instead.

Required string length: 1 - 60

items[].subscriber.medicaidRecipientIdentificationNumberstring

The Medicaid Recipient Identification Number. You can provide this number to identify the subscriber when it is the primary number the payer knows a member by (such as for Medicare or Medicaid). Do not supply this value unless it is different from the memberId.

Pattern: ^[A-Za-z0-9]+$
Required string length: 1 - 50

items[].subscriber.memberIdstring

The member ID for the subscriber's insurance policy.

Pattern: ^[A-Za-z0-9- ]+$
Required string length: 2 - 80

items[].subscriber.middleNamestring

The patient's middle name or middle initial.

Required string length: 1 - 25

items[].subscriber.planIssueDatestringdeprecated

Deprecated; The date the subscriber's insurance plan was issued. This shape is deprecated: This property is no longer used.

Pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$

items[].subscriber.providerCodestring

This property is required when the providerIdentifier and referenceIdentificationQualifier properties are populated.

You can use one of the following: AD - Admitting, AT - Attending, BI - Billing, CO - Consulting, CV - Covering, H - Hospital, HH - Home Health Care, LA - Laboratory, OT - Other Physician, P1 - Pharmacist, P2 - Pharmacy, PC - Primary Care Physician, PE - Performing, R - Rural Health Clinic, RF - Referring, SB - Submitting, SK - Skilled Nursing Facility, SU - Supervising

Possible values

AD

AT

BI

CO

CV

items[].subscriber.providerIdentifierstring

The provider identifier you specified in the referenceIdentificationQualifier property. It is required if you set the referenceIdentificationQualifier. For example, this property could contain the provider's National Provider ID or Federal Taxpayer Identification number.

If you set the referenceIdentificationQualifier to PXC, then this property should contain the provider's taxonomy code.

Pattern: ^[A-Za-z0-9]+$
Required string length: 1 - 50

items[].subscriber.referenceIdentificationQualifierstring

Use this for providers that are not requesting the eligibility check. This is the type of providerIdentifier you are providing.

Set to HPI when the National Provider ID is mandated for use.
Set to PXC if you're identifying a type of specialty associated with services provided to the subscriber.

Otherwise, you can set to the following: 9K - Servicer, D3 - National Council for Prescription Drug Programs Pharmacy Number, EI - Employer's Identification Number, HPI - Centers for Medicare and Medicaid Services National Provider Identifier, PXC - Health Care Provider Taxonomy Code, SY - Social Security Number, TJ` - Federal Taxpayer's Identification Number

Possible values

9K

D3

EI

HPI

PXC

items[].subscriber.spendDownAmountstring

Identify the dollar amount the subscriber will apply toward their spend down amount, if required. For some Medicaid programs, individuals must pay a certain amount towards their healthcare cost (spend down) before coverage starts.

Required string length: 1 - 15

items[].subscriber.spendDownTotalBilledAmountstring

The subscriber's spend down total billed amount.

Required string length: 1 - 15

items[].subscriber.ssnstring

The subscriber's Social Security Number (SSN). Many commercial and government payers ignore this property due to concerns about member privacy. However, some Medicaid programs support alternative searches using the patient's Social Security Number, instead of the member ID.

Pattern: ^\d{9}$

items[].subscriber.suffixstring

The name suffix, such as Jr., Sr., or III. Only include the subscriber's personal name suffix - don't include professional or academic titles, such as M.D. or MBA.

Required string length: 1 - 10

items[].tradingPartnerNamestring

The payer's name, such as Cigna or Aetna.

Required string length: 1 - 80

items[].tradingPartnerServiceIdstringrequired

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.

Required string length: 1 - 80

namestring

The name that Stedi will use when displaying this batch on the Eligibility check batches page. 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}$

Response

application/json

BatchEligibilityChecks 200 response

batchIdstringrequired

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 endpoint.

submittedAtstringrequired

The date and time that the batch of eligibility checks was submitted to Stedi for processing.

Format: date-time

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": [
      {
        "controlNumber": "000022222",
        "encounter": {
          "serviceTypeCodes": [
            "MH"
          ]
        },
        "provider": {
          "npi": "1234567891",
          "organizationName": "ACME Health Services"
        },
        "submitterTransactionIdentifier": "ABC123456789",
        "subscriber": {
          "dateOfBirth": "19000101",
          "firstName": "Jane",
          "lastName": "Doe",
          "memberId": "1234567890"
        },
        "tradingPartnerServiceId": "AHS"
      },
      {
        "controlNumber": "333344444",
        "encounter": {
          "serviceTypeCodes": [
            "78"
          ]
        },
        "provider": {
          "npi": "1234567891",
          "organizationName": "ACME Health Services"
        },
        "submitterTransactionIdentifier": "DEF123456799",
        "subscriber": {
          "dateOfBirth": "19001021",
          "firstName": "John",
          "lastName": "Doe",
          "memberId": "1234567892"
        },
        "tradingPartnerServiceId": "AHS"
      }
    ],
    "name": "march-2024-eligibility-batch"
  }'

const body = JSON.stringify({
  "items": [
    {
      "controlNumber": "000022222",
      "encounter": {
        "serviceTypeCodes": [
          "MH"
        ]
      },
      "provider": {
        "npi": "1234567891",
        "organizationName": "ACME Health Services"
      },
      "submitterTransactionIdentifier": "ABC123456789",
      "subscriber": {
        "dateOfBirth": "19000101",
        "firstName": "Jane",
        "lastName": "Doe",
        "memberId": "1234567890"
      },
      "tradingPartnerServiceId": "AHS"
    },
    {
      "controlNumber": "333344444",
      "encounter": {
        "serviceTypeCodes": [
          "78"
        ]
      },
      "provider": {
        "npi": "1234567891",
        "organizationName": "ACME Health Services"
      },
      "submitterTransactionIdentifier": "DEF123456799",
      "subscriber": {
        "dateOfBirth": "19001021",
        "firstName": "John",
        "lastName": "Doe",
        "memberId": "1234567892"
      },
      "tradingPartnerServiceId": "AHS"
    }
  ],
  "name": "march-2024-eligibility-batch"
})

fetch("https://manager.us.stedi.com/2024-04-01/eligibility-manager/batch-eligibility", {
  headers: {
    "Authorization": "<api_key>"
  },
  body
})

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
  "strings"
)

func main() {
  url := "https://manager.us.stedi.com/2024-04-01/eligibility-manager/batch-eligibility"
  body := strings.NewReader(`{
    "items": [
      {
        "controlNumber": "000022222",
        "encounter": {
          "serviceTypeCodes": [
            "MH"
          ]
        },
        "provider": {
          "npi": "1234567891",
          "organizationName": "ACME Health Services"
        },
        "submitterTransactionIdentifier": "ABC123456789",
        "subscriber": {
          "dateOfBirth": "19000101",
          "firstName": "Jane",
          "lastName": "Doe",
          "memberId": "1234567890"
        },
        "tradingPartnerServiceId": "AHS"
      },
      {
        "controlNumber": "333344444",
        "encounter": {
          "serviceTypeCodes": [
            "78"
          ]
        },
        "provider": {
          "npi": "1234567891",
          "organizationName": "ACME Health Services"
        },
        "submitterTransactionIdentifier": "DEF123456799",
        "subscriber": {
          "dateOfBirth": "19001021",
          "firstName": "John",
          "lastName": "Doe",
          "memberId": "1234567892"
        },
        "tradingPartnerServiceId": "AHS"
      }
    ],
    "name": "march-2024-eligibility-batch"
  }`)
  req, _ := http.NewRequest("POST", url, body)
  req.Header.Add("Authorization", "<api_key>")
  req.Header.Add("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import requests

url = "https://manager.us.stedi.com/2024-04-01/eligibility-manager/batch-eligibility"
body = {
  "items": [
    {
      "controlNumber": "000022222",
      "encounter": {
        "serviceTypeCodes": [
          "MH"
        ]
      },
      "provider": {
        "npi": "1234567891",
        "organizationName": "ACME Health Services"
      },
      "submitterTransactionIdentifier": "ABC123456789",
      "subscriber": {
        "dateOfBirth": "19000101",
        "firstName": "Jane",
        "lastName": "Doe",
        "memberId": "1234567890"
      },
      "tradingPartnerServiceId": "AHS"
    },
    {
      "controlNumber": "333344444",
      "encounter": {
        "serviceTypeCodes": [
          "78"
        ]
      },
      "provider": {
        "npi": "1234567891",
        "organizationName": "ACME Health Services"
      },
      "submitterTransactionIdentifier": "DEF123456799",
      "subscriber": {
        "dateOfBirth": "19001021",
        "firstName": "John",
        "lastName": "Doe",
        "memberId": "1234567892"
      },
      "tradingPartnerServiceId": "AHS"
    }
  ],
  "name": "march-2024-eligibility-batch"
}
response = requests.request("POST", url, json = body, headers = {
  "Authorization": "<api_key>",
  "Content-Type": "application/json"
})

print(response.text)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.time.Duration;
import java.net.http.HttpRequest.BodyPublishers;

var body = BodyPublishers.ofString("""{
  "items": [
    {
      "controlNumber": "000022222",
      "encounter": {
        "serviceTypeCodes": [
          "MH"
        ]
      },
      "provider": {
        "npi": "1234567891",
        "organizationName": "ACME Health Services"
      },
      "submitterTransactionIdentifier": "ABC123456789",
      "subscriber": {
        "dateOfBirth": "19000101",
        "firstName": "Jane",
        "lastName": "Doe",
        "memberId": "1234567890"
      },
      "tradingPartnerServiceId": "AHS"
    },
    {
      "controlNumber": "333344444",
      "encounter": {
        "serviceTypeCodes": [
          "78"
        ]
      },
      "provider": {
        "npi": "1234567891",
        "organizationName": "ACME Health Services"
      },
      "submitterTransactionIdentifier": "DEF123456799",
      "subscriber": {
        "dateOfBirth": "19001021",
        "firstName": "John",
        "lastName": "Doe",
        "memberId": "1234567892"
      },
      "tradingPartnerServiceId": "AHS"
    }
  ],
  "name": "march-2024-eligibility-batch"
}""");
HttpClient client = HttpClient.newBuilder()
  .connectTimeout(Duration.ofSeconds(10))
  .build();

HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
  .uri(URI.create("https://manager.us.stedi.com/2024-04-01/eligibility-manager/batch-eligibility"))
  .header("Content-Type", "application/json")
  .header("Authorization", "<api_key>")
  .POST(body)
  .build();

try {
  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());
  System.out.println("Status code: " + response.statusCode());
  System.out.println("Response body: " + response.body());
} catch (Exception e) {
  e.printStackTrace();
}

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

{
  "fieldList": [
    {
      "message": "string",
      "path": "string"
    }
  ],
  "message": "string"
}

{
  "code": "string",
  "message": "string"
}

{
  "code": "string",
  "message": "string"
}

{
  "code": "string",
  "message": "string"
}

{
  "code": "string",
  "message": "string"
}

{
  "code": "string",
  "message": "string"
}

Batch Eligibility Check

Start with real-time checks

Authorizations

Body

Response

Batch eligibility checks