Test Sandbox APIs
API Reference
Capability Statement
Provider Directory
Humana offers a Provider Directory service that enables current or prospective members to see which providers and pharmacies are in-network for a given Humana insurance plan. This service includes multiple FHIR APIs: InsurancePlan, PractitionerRole, Practitioner, Organization, and Location.
The InsurancePlan resource enables a user to retrieve a list of Humana’s Medicare Individual, Medicare Group, and Medicaid plans and their corresponding coverage areas and networks.
The PractitionerRole resource contains information about the providers or pharmacies in-network for a given insurance plan. The PractitionerRole responses include references to Practitioner, Organization, and Location where the user can find more contextual information about the in-network providers and where they operate.
Below, we have outlined the steps required to perform a search to retrieve the in-network providers for a specific plan and network combination.
These APIs follow the HL7 R4 FHIR specification, as well as the DaVinci PDEX Plan Net implementation guide.
Step 1
Retrieve the list of Humana plans and their associated networks from the /InsurancePlan API.
URL
Sample Request
curl -X GET \
https://fhir.humana.com/api/ \
In the response, a paginated list of all Humana’s Medicare Individual, Medicare Group, and Medicaid insurance plans will be returned. Please note, the response below is only a portion of the full response that will be returned.
Response Snippet
{
"resourceType": "Bundle",
"id": "3730e9eed5ae48e885fe829a1b4bfdc1",
"meta": {
"lastUpdated": "2021-06-30T13:14:54.8082003+00:00"
},
"type": "searchset",
"link": [
{
"relation": "next",
"url": "https://fhir.humana.com/api/InsurancePlan?ct=W3sidG9rZW4iOiIrUklEOn5hY0k1QUxwV0pPR2VRaklCQUFDQUR3PT0jUlQ6MSNUUkM6MTAjSVNWOjIjSUVPOjY1NTUxI1FDRjo3I0ZQQzpBZ2pKQkFBQUFENEFBTWtFQUFBQVBnQUF5UVFBQUFBK0FBQUVBSjZDQW9BPSIsInJhbmdlIjp7Im1pbiI6IiIsIm1heCI6IjA1QzE4MCJ9fV0="
},
{
"relation": "self",
"url": "https://fhir.humana.com/api/InsurancePlan"
}
],
"entry": [
{
"fullUrl": "https://fhir.humana.com/api/InsurancePlan/dd4054238ce86d73c95862f415e7d921fa01d025e836026c8b093faffd615182",
"resource": {
"resourceType": "InsurancePlan",
"id": "dd4054238ce86d73c95862f415e7d921fa01d025e836026c8b093faffd615182",
"meta": {
"versionId": "1",
"lastUpdated": "2021-06-25T18:47:21.535+00:00"
},
"contained": [
{
"resourceType": "Location",
"id": "a0d629afcff22ed5da780d2fe5bb44e0b74bc15c5b9073af8044cfcfd8d4b778",
"identifier": [
{
"system": "http://hl7.org/fhir/us/core/2021Jan/ValueSet-us-core-usps-state.html",
"value": "NY"
},
{
"system": "https://fhir.humana.com/documentation/glossary/County",
"value": "Bronx"
}
]
}Step 2
Select a plan and network combination the user wants to search for. For selecting a plan, reference these two fields: entry.resource.name and entry.resource.plan.identifier.value. For selecting a network, three options are available: Pharmacy, Vision, and Medical/Dental. You will find glossary links for these three options in the field entry.resource.network.identifier.system as shown below:
– https://fhir.humana.com/documentation/glossary/PharmacyNetworkId
– https://fhir.humana.com/documentation/glossary/VisionNetworkID
– https://fhir.humana.com/documentation/glossary/MedicalDentalNetworkId
Once the user has selected which type of provider they want to search for, grab the corresponding entry.resource.network.identifier.value (Example: 2450).
Response Snippet
"network": [
{
"identifier": {
"system": "https://fhir.humana.com/documentation/glossary/MedicalDentalNetworkId",
"value": "2450"
},
"display": "Medicare Employer PPO"
},
{
"identifier": {
"system": "https://fhir.humana.com/documentation/glossary/VisionNetworkID",
"value": "1021"
},
"display": "EyeMed Vision"
},
{
"identifier": {
"system": "https://fhir.humana.com/documentation/glossary/PharmacyNetworkId",
"value": "10"
},
"display": "Humana Medicare Employer Plan (Medicare Group) Network"
}
],
"plan": [
{
"identifier": [
{
"system": "https://fhir.humana.com/documentation/glossary/PlanId",
"value": "H5970-802-000-2021"
}
],
"type": {
"coding": [
{
"system": "https://fhir.humana.com/documentation/glossary/PlanType",
"code": "MA-PD"
}
]
}
}
]
}Step 3
Using the selections from step 2, formulate a search to /PractitionerRole. This search will return a bundle of resources indicating which providers or organizations are in-network for the network ID provided. Also in the response, you can see references to /Practitioner, /Organization, and /Location resources where you can find more contextual information like the provider NPI, their name, their contact information, open hours, etc. Please note providers who are no longer in-network may return with inactive statuses; please see below for an example query that returns only active PractitionerRoles.
URL
Sample Request
curl -X GET \
https://fhir.humana.com/api/PractitionerRole?_tag=https://fhir.humana.com/documentation/glossary/MedicalDentalNetworkId|2450&active=true \
Sample Response
{
"resourceType": "Bundle",
"id": "700494b9db734ec5ad083c21c879c0c1",
"meta": {
"lastUpdated": "2021-06-30T13:31:49.8488743+00:00"
},
"type": "searchset",
"link": [
{
"relation": "next",
"url": "https://fhir.humana.com/api/PractitionerRole?_tag=https://fhir.humana.com/documentation/glossary/MedicalDentalNetworkId|2450&active=true&ct=W3sidG9rZW4iOiIrUklEOn5hY0k1QUxwV0pPSFM3VWdCQUFEZ0NnPT0jUlQ6MSNUUkM6MTAjSVNWOjIjSUVPOjY1NTUxI1FDRjo3I0ZQQzpBZ2dqQlFBQWdDc0FBQ01GQUFDQUt3QUFJd1VBQUlBckFBQWFBTkV0L1A5aVFQdHRsLy9CUWY4L3NVRC9meU1BQUdEL3Y1OEEiLCJyYW5nZSI6eyJtaW4iOiIiLCJtYXgiOiIwNUMxODAifX1d"
},
{
"relation": "self",
"url": "https://fhir.humana.com/api/PractitionerRole?_tag=https://fhir.humana.com/documentation/glossary/MedicalDentalNetworkId|2450&active=true"
}
],
"entry": [
{
"fullUrl": "https://fhir.humana.com/api/PractitionerRole/d6b2613b2b4b3b56273b88b093ede32808d5738aaadebcaffb3edb46fe3548ea",
"resource": {
"resourceType": "PractitionerRole",
"id": "d6b2613b2b4b3b56273b88b093ede32808d5738aaadebcaffb3edb46fe3548ea",
"meta": {
"versionId": "1",
"lastUpdated": "2021-06-29T15:36:25.749+00:00",
"tag": [
{
"system": "https://fhir.humana.com/documentation/glossary/MedicalDentalNetworkId",
"code": "2450",
"display": "Medicare PPO"
}
]
},
"active": true,
"practitioner": {
"reference": "Practitioner/39c9d9f794af5441de83b00cff908a0113320f89cf8a2092fcf6ff29bc3c51d3"
},
"specialty": [
{
"text": "Hematology (Internal Medicine) Physician"
},
{
"text": "Medical Oncology Physician"
}
],
"location": [
{
"reference": "Location/32d7d42fae11f145fd1164223f7928176667459519d26421748f2cd31c3a777e"
}
]
},
"search": {
"mode": "match"
}
},
{
"fullUrl": "https://fhir.humana.com/api/PractitionerRole/a82ffabd35581134cd964dca38fd6830b045a8bae6939f6de2349303b08e2ed4",
"resource": {
"resourceType": "PractitionerRole",
"id": "a82ffabd35581134cd964dca38fd6830b045a8bae6939f6de2349303b08e2ed4",
"meta": {
"versionId": "1",
"lastUpdated": "2021-06-29T15:36:25.916+00:00",
"tag": [
{
"system": "https://fhir.humana.com/documentation/glossary/MedicalDentalNetworkId",
"code": "2450",
"display": "Medicare PPO"
}
]
},
"active": true,
"practitioner": {
"reference": "Practitioner/02bc7ccc3ccd050befb2f6583020d02ceb463e41d6fdc4091be61a2e542851c2"
},
"specialty": [
{
"text": "Sleep Medicine (Internal Medicine) Physician"
},
{
"text": "Pulmonary Disease Physician"
}
],
"location": [
{
"reference": "Location/9b451336fb9816a7c883905bd1060d7526f9113a09bc840fed8051859e274c53"
}
]
},
"search": {
"mode": "match"
}
},
{
"fullUrl": "https://fhir.humana.com/api/PractitionerRole/5bcd10749af768fd679bd55dcb6580baf07cfca2477ffbeaf503b250cf5e3dc5",
"resource": {
"resourceType": "PractitionerRole",
"id": "5bcd10749af768fd679bd55dcb6580baf07cfca2477ffbeaf503b250cf5e3dc5",
"meta": {
"versionId": "1",
"lastUpdated": "2021-06-29T15:36:25.968+00:00",
"tag": [
{
"system": "https://fhir.humana.com/documentation/glossary/MedicalDentalNetworkId",
"code": "2450",
"display": "Medicare PPO"
}
]
},
"active": true,
"organization": {
"reference": "Organization/900a7202b52c478a57aea3e2a7c46f341ee13e5d34f7d66d053f6d089b01e5c8"
},
"specialty": [
{
"text": "Psychiatric Hospital"
}
],
"location": [
{
"reference": "Location/e9387c7e8a562e1e4b5573039f5f4022913e24d028194ecef774518be172459a"
}
]
},
"search": {
"mode": "match"
}
},
{
"fullUrl": "https://fhir.humana.com/api/PractitionerRole/da5b232465205ba65034f56422bc4a76b7d4a0f64d4ae058cf4b3f9080d2436c",
"resource": {
"resourceType": "PractitionerRole",
"id": "da5b232465205ba65034f56422bc4a76b7d4a0f64d4ae058cf4b3f9080d2436c",
"meta": {
"versionId": "1",
"lastUpdated": "2021-06-29T15:36:26.059+00:00",
"tag": [
{
"system": "https://fhir.humana.com/documentation/glossary/MedicalDentalNetworkId",
"code": "2450",
"display": "Medicare PPO"
}
]
},
"active": true,
"organization": {
"reference": "Organization/c1a34b2da3d7cf9096447ad811895ccc46172190e6d3ae64d312d5365b6d8a7b"
},
"specialty": [
{
"text": "Family Medicine Physician (PCP)"
},
{
"text": "Internal Medicine Physician (PCP)"
}
],
"location": [
{
"reference": "Location/a1c17282e08c9ebaba38034146e7cad262f32914d527ce6d3c5c3c20dff644d5"
}
]
},
"search": {
"mode": "match"
}
},
{
"fullUrl": "https://fhir.humana.com/api/PractitionerRole/bccfae30990cf926060174c1da16b9612aaabc584000ee8dda67e9dbe1eeddf8",
"resource": {
"resourceType": "PractitionerRole",
"id": "bccfae30990cf926060174c1da16b9612aaabc584000ee8dda67e9dbe1eeddf8",
"meta": {
"versionId": "1",
"lastUpdated": "2021-06-29T15:36:26.062+00:00",
"tag": [
{
"system": "https://fhir.humana.com/documentation/glossary/MedicalDentalNetworkId",
"code": "2450",
"display": "Medicare PPO"
}
]
},
"active": true,
"organization": {
"reference": "Organization/2ec197663404104a52b75e3dd2f59f6539ac110e8dea1357c7ffba4364e699f8"
},
"specialty": [
{
"text": "General Acute Care Hospital"
}
],
"location": [
{
"reference": "Location/96cdcbde6b48e8cb139a228e48c1fe37da23c75d8e6094671a1de29762d435e5"
}
]
},
"search": {
"mode": "match"
}
},
{
"fullUrl": "https://fhir.humana.com/api/PractitionerRole/4aea786630608412637bc924548d4d57f2aadd6e62bba81d12b742df440747a7",
"resource": {
"resourceType": "PractitionerRole",
"id": "4aea786630608412637bc924548d4d57f2aadd6e62bba81d12b742df440747a7",
"meta": {
"versionId": "1",
"lastUpdated": "2021-06-29T15:36:26.084+00:00",
"tag": [
{
"system": "https://fhir.humana.com/documentation/glossary/MedicalDentalNetworkId",
"code": "2450",
"display": "Medicare PPO"
}
]
},
"active": true,
"practitioner": {
"reference": "Practitioner/f6829ead3257b51923f915fee49e5ec1e0f3832cf0ea52c30c14a211a115d123"
},
"specialty": [
{
"text": "Orthopaedic Surgery Physician"
}
],
"location": [
{
"reference": "Location/05ad027bc312247826da334252f144b7bf47ffc2f51d06055b9b8ffd43e0a810"
}
]
},
"search": {
"mode": "match"
}
},
{
"fullUrl": "https://fhir.humana.com/api/PractitionerRole/44b5a4bbaeda6f4378b377e094847acdc8f4c87274a3d6b6c76cb634ff66095a",
"resource": {
"resourceType": "PractitionerRole",
"id": "44b5a4bbaeda6f4378b377e094847acdc8f4c87274a3d6b6c76cb634ff66095a",
"meta": {
"versionId": "1",
"lastUpdated": "2021-06-29T15:36:26.097+00:00",
"tag": [
{
"system": "https://fhir.humana.com/documentation/glossary/MedicalDentalNetworkId",
"code": "2450",
"display": "Medicare PPO"
}
]
},
"active": true,
"practitioner": {
"reference": "Practitioner/834c8259fc815961137efa0f39ca4a6a3235386e7c2b5997b6095b4b2cb42f88"
},
"specialty": [
{
"text": "Neuromusculoskeletal Medicine & OMM Physician"
}
],
"location": [
{
"reference": "Location/c79ff12df843f6051aad840ce786a5b305a69b6ffbddac7df9c55730eb9740e7"
}
]
},
"search": {
"mode": "match"
}
},
{
"fullUrl": "https://fhir.humana.com/api/PractitionerRole/acad4662df67342a7768faa638308357c94c01ae11b813101e4cb6ebb2b7adf5",
"resource": {
"resourceType": "PractitionerRole",
"id": "acad4662df67342a7768faa638308357c94c01ae11b813101e4cb6ebb2b7adf5",
"meta": {
"versionId": "1",
"lastUpdated": "2021-06-29T15:36:26.111+00:00",
"tag": [
{
"system": "https://fhir.humana.com/documentation/glossary/MedicalDentalNetworkId",
"code": "2450",
"display": "Medicare PPO"
}
]
},
"active": true,
"practitioner": {
"reference": "Practitioner/5d133f1aefb726c174fd2c80a29d7c0cb65301204694c531aa7936d79a8927d1"
},
"specialty": [
{
"text": "Social Worker"
}
],
"location": [
{
"reference": "Location/cc08fd8ff76def8e194648e599b853e805b1c29d1570c1e6e002ce28102e4409"
}
]
},
"search": {
"mode": "match"
}
},
{
"fullUrl": "https://fhir.humana.com/api/PractitionerRole/c9d750752d7f5d379724b7a67c1b5a59df69c2145eed54e70c6b3634ec8af6da",
"resource": {
"resourceType": "PractitionerRole",
"id": "c9d750752d7f5d379724b7a67c1b5a59df69c2145eed54e70c6b3634ec8af6da",
"meta": {
"versionId": "1",
"lastUpdated": "2021-06-29T15:36:26.131+00:00",
"tag": [
{
"system": "https://fhir.humana.com/documentation/glossary/MedicalDentalNetworkId",
"code": "2450",
"display": "Medicare PPO"
}
]
},
"active": true,
"practitioner": {
"reference": "Practitioner/b07629a1ecd6aa0828fdbc5112342379d076e6c14d094cefde3ddb4dcf886828"
},
"specialty": [
{
"text": "Maternal & Fetal Medicine Physician"
}
],
"location": [
{
"reference": "Location/d53d679d89eb12ce52105cd9cda91eb2260d56bcb953ef519955940c1608fbb3"
}
]
},
"search": {
"mode": "match"
}
},
{
"fullUrl": "https://fhir.humana.com/api/PractitionerRole/b44407d1e2ccf2bd4b56477d48367a8c315e4fb480df249af21e35babeb01f05",
"resource": {
"resourceType": "PractitionerRole",
"id": "b44407d1e2ccf2bd4b56477d48367a8c315e4fb480df249af21e35babeb01f05",
"meta": {
"versionId": "1",
"lastUpdated": "2021-06-29T15:36:26.154+00:00",
"tag": [
{
"system": "https://fhir.humana.com/documentation/glossary/MedicalDentalNetworkId",
"code": "2450",
"display": "Medicare PPO"
}
]
},
"active": true,
"practitioner": {
"reference": "Practitioner/9906c54e4baf3707f03092c9ce038355034274d5dbd2fadd82102055f8b3d450"
},
"specialty": [
{
"text": "Obstetrics & Gynecology Physician (Specialist)"
}
],
"location": [
{
"reference": "Location/83df5ffafd90ea738de0f80043d84c312abca82e88be76e64826ff550fa12807"
}
]
},
"search": {
"mode": "match"
}
}
]
}Step 4
As you can see in the response above, there are references to other FHIR APIs (Practitioner, /Organization, and /Location where relevant). Each of the individual endpoints can be called to retrieve additional information. For example, you can use the reference to /Practitioner provided in the response above and call the Practitioner resource to retrieve information such as NPI, name, and gender.
URL
Sample Request
curl -X GET \
https://fhir.humana.com/api/Practitioner/39c9d9f794af5441de83b00cff908a0113320f89cf8a2092fcf6ff29bc3c51d3 \
Sample Response
{
"resourceType": "Practitioner",
"id": "39c9d9f794af5441de83b00cff908a0113320f89cf8a2092fcf6ff29bc3c51d3",
"meta": {
"versionId": "150",
"lastUpdated": "2021-06-28T22:24:37.028+00:00"
},
"extension": [
{
"url": "https://fhir.humana.com/documentation/glossary/DirectoryType",
"valueCodeableConcept": {
"coding": [
{
"system": "https://fhir.humana.com/documentation/glossary/DirectoryType",
"code": "MedicalDental"
}
]
}
}
],
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "1669579652"
}
],
"active": true,
"name": [
{
"use": "usual",
"text": "Dr Hyde Phyllis",
"family": "Hyde",
"given": [
"Phyllis"
],
"prefix": [
"Dr"
]
}
],
"gender": "female"
}