Humana Hematology Specialist Search
Using Sero to make a Provider Directory API request and searching for in-network specialists

The complete source code for this example is available at example/humana-specialist-search. Are you interested in accessing newly launched Provider Directory data? Contact [email protected]​
This example demonstrates how to use Sero to access Provider Directory APIs from health plan payers such as Humana. Using publicly accessible FHIR APIs, we are able to identify in-network specialists (a hematologist in our example) available for a given Humana plan.
If you click play ▢️ button in the Replit below, you will see the full example running. An initial request is made to find Humana Insurance Plans. Subsequent requests made to identify eligible Hematologists for a given plan.
Click the green play button for the full example to run
More information about Humana's API is available at

Sero implements an Client that can make requests to FHIR APIs. Provider Directories are a practical, real world example of life FHIR APIs in the wild. You can learn more about FHIR and Provider Directories in our How to build in health the easy way ebook.
This code walkthrough will focus primarily on humana.ts, where we start by importing Sero and querying the Humana API.

We start by importing the Client module from Sero. We're also going to be using a library called Chalk to print information about our queries.
import { Client } from ""
import chalk from "chalk";
import { Humana } from "./glossary.js"
const { log } = console;

We start by initializing the Client with the baseUrl of the FHIR API and destructuring the operations we will use (searchType and read). Then, we make a search for Humana's InsurancePlan resources. We use async and call next because Sero generates yields paginated results for searches through an iterator and a generator function.
const { searchType, read } = Client("")
const planSearch = await searchType("InsurancePlan").next()
We identify an eligible plan, and find its network details - specifically searching for the medical/dental network identifier associated with the plan. We'll use this in step 2.
const insurancePlan = planSearch.value?.entry?.find((bundleEntry) => {
return bundleEntry.resource?.resourceType == "InsurancePlan"
})?.resource as fhir4.InsurancePlan
const { name, plan, network } = insurancePlan;
const { value: planId } = network?.find(n => {
return n.identifier?.system == Humana.MedicalDentalNetwork
})?.identifier as fhir4.Identifier

Now, we need to search for Hematology specialists (or any other kind we want) who have available coverage under the plan network we identified in step 1. We do this by forming a query against PractitionerRole, which is a FHIR Resource that defines specializations.
The first step here is to define our query. Sero's searchType operation accepts a object as a second argument and automatically URI encodes the values to generate the API request. We're using quotes around the "speciality:text" key because : cannot be used in a symbol.
const hematologyQuery = {
"specialty:text": "Hematology",
_tag: `${Humana.MedicalDentalNetwork}|${planId}`,
active: true
Then, we make the query. Again, we call next() to return the first page of results. From the results, we try to find an eligible Practitioner (Hematologist).
const specialistSearch = await searchType("PractitionerRole", hematologyQuery).next()
const specialistRole = specialistSearch.value?.entry?.find((bundleEntry) => {
return bundleEntry.resource?.resourceType == "PractitionerRole" && bundleEntry.resource.practitioner
})?.resource as fhir4.PractitionerRole

If we were able to identify a Practitioner in step 2, we can make a query to retrieve their individual information including NPI:
const { practitioner } = specialistRole;
if (!practitioner?.reference) throw new Error("No practitioner matched that search")
let readPractitioner = await read(practitioner.reference) as fhir4.Practitioner
Finally, we use chalk to log our queries and the final result to console.
Copy link
On this page