Request Body Parameters
Understanding the JSON code for the Eligibility request.
The Eligibility request body consists of a set of JSON objects that contain the key parameters to verify a patient’s medical coverage. These blocks of information define the contents of your Eligibility query to the clearinghouse.
NOTE
The JSON attributes in our APIs use snake-case, with the first letter of the attribute in lower case as in
tradingPartnerServiceId(the Payer ID; this will vary based on the payer you want to connect to). Our APIs are case-sensitive and your JSON request body must observe this convention.
Eligibility object
The JSON attributes with leading elements of the request body:
```json
POST ${api_basepath} HTTP/1.1
Host: ${apigee_host}
Authorization: Bearer <Your-Access-Token>
Content-Type: application/json
{
"controlNumber":"123456789",
"tradingPartnerServiceId": "UHC",
"provider":
},
```
| Request Body Element | Description |
|---|---|
ControlNumber | Required A single arbitrary value that the requestor defines in the initial Eligibility API transaction request by a random number generator. All parties to the Eligibility transaction refer to this number to ensure accurate responses and completion of the exchange. The controlNumber must be defined as a nine-digit unsigned numeric value. |
TradingPartnerServiceId | Required Payer ID; you can use the payer’s ConnectCenter real-time Payer ID value as the tradingPartnerServiceId. |
ProviderType | Optional Partner type requested to verify patient eligibility. |
Provider object
The Provider object describes the medical service provider submitting the Eligibility request.
```json
"Provider": {
"organizationName": "provider_name",
"npi": "0123456789",
"serviceProviderNumber": "54321",
"providerCode": "AD",
"referenceIdentification": "54321g"
},
```
| Request Body Element | Description |
|---|---|
OrganizationName | Required Business name of the provider. The required value to identify the entity submitting the transaction; providers submitting directly can use firstName and lastName instead of this field. |
Npi | Required National Provider ID number for the submitting provider. Some form of identification for the provider is required for any Eligibility transaction; npi is the most common. |
ServiceProviderNumber | Optional Service Provider ID number. |
ProviderCode | Optional Clearinghouse-assigned Provider Code. This two-digit code identifies the medical provider type, such as Admitting (AD), Billing (BI), and so on. To see the complete code list, use the PDF search term Provider Code in the X12 270/271 Implementation Guide. |
ReferenceIdentification | Optional Healthcare Provider Taxonomy code value. |
Subscriber object
```json
"subscriber": {
"memberId": "0000000000",
"firstName": "johnOne",
"lastName": "doeOne",
"gender": "M",
"dateOfBirth": "18800102",
"ssn": "000000000",
"idCard": "card123"
},
```
| Request Body Element | Description |
|---|---|
Subscriber | Required Medical insurance subscriber. The object contains several identity and demographic data fields identifying the insurance policyholder, including memberId, firstName, lastName, dateOfBirth, gender, ssn, and idCard(the subscriber’s insurance plan card number). |
Dependents object
```json
"dependents": [
{
"firstName":"janeOne",
"lastName":"doeOne",
"gender":"F",
"dateOfBirth":"18160421",
"groupNumber": "0000000000"
}
],
```
| Request Body Element | Description |
|---|---|
Dependents | Required An array of one or more records describing one or more dependents of the subscriber who are on the insurance policy. The encounter for the Eligibility request may involve the subscriber or a dependent. If a dependent is not involved in the encounter, you can omit the dependent information from the request. This content is Situational for that reason. The dependent object is subordinate to the subscriber. In some cases, the person listed as a Dependent for insurance purposes may need to be listed as the Subscriber. |
Encounter object
The Encounter object describes the beginning and end dates of the medical services associated with the Eligibility request. It also contains the Situational serviceTypeCodes field.
The object itself is required in your request but you can define it based on whether the medical encounter is a single occasion on a single date or if it spans a longer period of time.
```json
"encounter": {
"beginningDateOfService": "20100101",
"endDateOfService": "20100102",
"serviceTypeCodes": [
"98"
]
}
```
| Request Body Element | Description |
|---|---|
DateOfService | Date of provider service to the subscriber. Required if the encounter spans only a single visit on a single day, otherwise, use beginningDateOfService and endDateOfService to delineate the time span for the medical services. |
ServiceTypeCodes | Required (Situational) request eligibility for service types using the optional serviceTypeCodes object.If you do not specify a service type, make the request for general benefit coverage information. Some trading partners may not support service type inquiries. |
ProcedureId | Required (Situational) specify the procedureId values from a standard list of IDs that the proposed procedure is associated with. The most common is the Healthcare Common Procedure Coding System (HCPCS), which defines reference codes for items and services provided in the delivery of healthcare. Providers will likely have a smaller set of well-understood procedure IDs associated with their practice. |
Using search options to optimize queries
A search option is a set of related fields that will yield a successful Eligibility response from a payer if there is a member match.
Trading partners typically require a combination of specific fields to ensure retrieval of requested records. You can tailor your Eligibility requests to use different sets of fields depending on the application.
In some cases, search options allow you to get a successful response even without a piece of information like the memberId. A common name-based search option can include the firstName, lastName, and dateOfBirth of the member in question.
If you always have the memberId, we suggest sending a request containing the memberId, firstName, lastName, and dateOfBirth fields.
Updated about 2 months ago