Request and Response
The Eligibility request helps find:
- Types of procedures covered by an insurance policy
- Extent or percentage up to which, the insurance covers the medical procedures under a policy
- Amount for which patients will be financially responsible
- Patient responsibility details, such as co-payments, coinsurance, and deductibles
- More about many other plan membership features
```json
curl --request POST \
--url https://sandbox-apigw.optum.com/medicalnetwork/eligibility/v3/ \
--header 'Authorization: Bearer eyJraWQiOiIxIiwidHlwIjoiSldUIi...' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"controlNumber":"123456789", //required
"tradingPartnerServiceId": "serviceId",
"provider":
{
"organizationName": "provider_name",
"npi": "0123456789",
"serviceProviderNumber": "54321",
"providerCode": "AD",
"referenceIdentification": "54321g"
},
"subscriber": { //required
"memberId": "0000000000",
"firstName": "johnOne",
"lastName": "doeOne",
"gender": "M",
"dateOfBirth": "18800102",
"ssn": "000000000",
"idCard": "card123"
},
"dependents": [ //required
{
"firstName":"janeOne",
"lastName":"doeOne",
"gender":"F",
"dateOfBirth":"18160421",
"groupNumber": "0000000000"
}
],
"encounter": { //required
"beginningDateOfService": "20100101",
"endDateOfService": "20100102",
"serviceTypeCodes": [
"98"
]
}
}
```
The preceding example lists a serviceTypeCode of 98, indicating that the Eligibility request is inquiring about the patient's insurance benefit covering a visit to a physician's office. Some payers will support a number of specific service type codes to drill down into benefits coverage; some will not, and will support only a verification of core medical insurance coverage. Those requests and responses will show a value of 30 in those cases.
In most cases, Eligibility is a straightforward insurance membership query. As shown here, the core request information consists of several JSON objects of the provider and subscriber/dependents information, the date(s) of the medical encounter and the provider services rendered during the encounter. The amount of information depends on the information the provider needs to submit as the initiating request for the Eligibility transaction.
NOTE
If you submit an Eligibility request with a
serviceTypeCodeother than 30 to a payer that does not support other more-specific code values for this information, you will receive a generic response equaling the standard one of 30, describing whether or not the patient has active coverage.
```json
curl --request POST \
--url https://sandbox-apigw.optum.com/medicalnetwork/eligibility/v3/ \
--header 'Authorization: Bearer eyJraWQiOiIxIiwidHlwIjoiSldUIi...' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"controlNumber":"123456789",
"tradingPartnerServiceId": "serviceId",
"provider": {
"organizationName": "provider_name",
"npi": "0123456789"
},
"subscriber": {
"firstName": "johnOne",
"lastName": "doeOne",
"dateOfBirth": "18800102",
"memberId": "0000000000"
},
"encounter": {
"dateOfService": "20100101",
"serviceTypeCodes": [
"30"
]
}
```
Many encounters involve only a policy subscriber, so the request can omit dependent information. In the preceding example, the subscriber information illustrates its use as a search object, providing the minimum mandated amount of information needed for a subscriber match. Other search options are available but success rate will vary as per payer.
Compare the preceding example to a longer request body containing several optional data fields as illustrated here.
```json
curl --request POST \
--url https://sandbox-apigw.optum.com/medicalnetwork/eligibility/v3/ \
--header 'Authorization: Bearer eyJraWQiOiIxIiwidHlwIjoiSldUIi...' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"controlNumber":"123456789",
"tradingPartnerServiceId": "serviceId",
"provider":{
"organizationName": " happy_doctors_group", //provider name
"npi": "0123456789",
"serviceProviderNumber": "54321",
"providerCode": "AD",
"referenceIdentification": "54321g"
},
"subscriber": {
"memberId": "0000000000",
"firstName": "johnOne",
"lastName": "doeOne",
"gender": "M",
"dateOfBirth": "18800102",
"ssn": "555443333",
"idCard": "card123"
},
"dependents": [
{
"firstName":"janeOne",
"lastName":"doeone",
"gender":"F",
"dateOfBirth":"18160421",
"groupNumber": "1111111111"
}
],
"encounter": {
"beginningDateOfService": "20100101",
"endDateOfService": "20100102",
"serviceTypeCodes": [
"30"
]
}
```
The preceding request body more closely resembles a first-time encounter when a significant amount of information is needed for intake of a subscriber.
Response example
The Eligibility response provides the complete status of the requested patient's medical insurance. It can provide details of medical coverage for dozens of medical specialties, or it can simply confirm that the patient has current medical insurance (or otherwise). This information is provided:
- where you can expect to find it
- what the medical benefits look like
- how the Eligibility response describes medical benefits for medical services
You may receive lengthy responses to our Medical Network APIs, due to the many data points that a payer or trading partner provides in the query response. It reflects the needs to inform the provider about the various financial components of the patient's insurance coverage — existence of copays and co-insurance payments; deductible amounts; possible dependents information; coverage levels, and much more. In many cases you will see a much larger body of information in the Eligibility response, depending on the level of detail supported by the payer.
{
"meta": {
"senderId": "APIM_Marketplace_SBX_Native_ExrHHlUnWaTxwjVs",
"applicationMode": "sandbox",
"traceId": "2b8983bf-6298-4e18-1274-0d653803337a"
},
"controlNumber": "123456789",
"reassociationKey": "123456789",
"tradingPartnerServiceId": "serviceId",
"provider": {
"providerName": "provider_name",
"entityIdentifier": "Provider",
"entityType": "Non-Person Entity",
"npi": "0123456789"
},
"subscriber": {
"firstName": "johnOne",
"lastName": "doeOne",
"gender": "M",
"entityIdentifier": "Insured or Subscriber",
"entityType": "Person",
"dateOfBirth": "18800102",
"ssn": "111111111"
},
"subscriberTraceNumbers": [
{
"traceTypeCode": "1",
"traceType": "Current Transaction Trace Numbers",
"referenceIdentification": "123456789",
"originatingCompanyIdentifier": "9EMDEON999"
}
],
"payer": {
"entityIdentifier": "Payer",
"entityType": "Non-Person Entity",
"name": "Unknown",
"payorIdentification": "serviceId"
},
"planInformation": {
"socialSecurityNumber": "111111111"
},
"planDateInformation": {
"plan": "20160818-20160818"
},
"planStatus": [
{
"statusCode": "1",
"status": "Active Coverage",
"planDetails": "QMB",
"serviceTypeCode": [
"30"
],
"serviceTypeCodes": [
"30"
]
}
],
"benefitsInformation": [
{
"code": "1",
"name": "Active Coverage",
"coverageLevelCode": "IND",
"coverageLevel": "Individual",
"serviceTypeCodes": [
"30"
],
"serviceTypes": [
"Health Benefit Plan Coverage"
],
"insuranceTypeCode": "QM",
"insuranceType": "Qualified Medicare Beneficiary",
"planCoverage": "QMB",
"benefitsDateInformation": {
"benefit": "20160818-20160818"
}
},
{
"code": "R",
"name": "Other or Additional Payor",
"coverageLevelCode": "IND",
"coverageLevel": "Individual",
"serviceTypeCodes": [
"30"
],
"serviceTypes": [
"Health Benefit Plan Coverage"
],
"insuranceTypeCode": "MA",
"insuranceType": "Medicare Part A",
"planCoverage": "MEDICARE PART A",
"benefitsDateInformation": {
"plan": "20160818-20160818"
}
},
{
"code": "R",
"name": "Other or Additional Payor",
"coverageLevelCode": "IND",
"coverageLevel": "Individual",
"serviceTypeCodes": [
"30"
],
"serviceTypes": [
"Health Benefit Plan Coverage"
],
"insuranceTypeCode": "MB",
"insuranceType": "Medicare Part B",
"planCoverage": "MEDICARE PART B",
"benefitsDateInformation": {
"plan": "20160818-20160818"
}
}
],
"x12": "ISA*00* *01*SomePwd *ZZ*EMDEON *ZZ*TPG00000 *250923*0425*^*00501*123456789*0*T*:~GS*HB*MTEXE*LLX1210001*20131015*2219*123456789*X*005010X279A1~ST*271*946380841*005010X279A1~BHT*0022*11*2b8983bf-6298-4e18-1274-0d653803337a*20250923*0425~HL*1**20*1~NM1*PR*2*Unknown*****PI*serviceId~HL*2*1*21*1~NM1*1P*2*provider_name*****XX*0123456789~HL*3*2*22*0~TRN*1*123456789*9EMDEON999*~NM1*IL*1*doeOne*johnOne***~REF*SY*111111111~DMG*D8*18800102*M~DTP*291*RD8*20160818-20160818~EB*1*IND*30*QM*QMB~DTP*292*RD8*20160818-20160818~EB*R*IND*30*MA*MEDICARE PART A~DTP*291*RD8*20160818-20160818~EB*R*IND*30*MB*MEDICARE PART B~DTP*291*RD8*20160818-20160818~SE*19*946380841~GE*1*123456789~IEA*1*123456789~"
}
NOTE
Check the Eligibility API Mappings document in the Attachments tab for a complete Eligibility EDI loop and segment mappings to the JSON fields in the Eligibility 270 requests and 271 responses.
Updated 1 day ago