Searching resources
Requirements
FHIR resources are the core of the Flexpa Patient Access APIs. Patients authorize your app to access their resources via Flexpa Link. At the end of that flow you'll have:
- An access token that allows you to make further requests and is required for all requests to Flexpa API
- A patient ID that is used to query FHIR Resources directly related to the patient.
You can retrieve the patient ID by either:
After the authorization, you can make HTTP requests to Flexpa API using the access token and patient ID to search for and find different resources belonging to a particular patient.
Searching for resources
Searches on Flexpa API follow the RESTful style of the FHIR specification by submitting a GET HTTP request to the base URL of the resource with parameters to define the exact search criteria to filter the response.
The most common search type you will want to make is to search for resources belonging to a particular patient. To do this, you can use the $PATIENT_ID wildcard parameter. Flexpa swaps this out for the real patient ID before we send the request to the right FHIR API.
Examples of other searches you may want to make include:
- Searching for ExplanationOfBenefits by status to pull specifically denied claims
- Searching for ExplanationOfBenefits by claim type to pull only pharmacy claims
- Searching for MedicationRequests by date range to pull only the most recent prescriptions
Searches may not be available for some of the resources that a server supports! Some resources may only be accessed directly via a read using a specific resource ID. For example, some servers do not allow for searching across all Practitioners as they expect you to pull the specific Practitioners referenced from patient-specific resources such as ExplanationOfBenefits. You can inspect the CapabilityStatement for a particular server to see what resources are available and what search parameters are supported.
Example search request
Here's an example of searching for a specific patient's coverage:
ACCESS_TOKEN=... # replace with the access token you obtained at the end of the Flexpa Link flow
curl "https://api.flexpa.com/fhir/Coverage?patient=$PATIENT_ID" \
-H "Authorization: $ACCESS_TOKEN"
Response type
The return type of querying the coverage endpoint is a searchset
bundle. Technically, a searchset bundle may contain different types of resources
(e.g., EOB, Patient) in the entry field. When iterating through entry it is best practice to inspect each resourceType field
to ensure you are dealing with the expected resource.
Example search response
In a successful response to the Coverage example above where results are found, you'll receive a Bundle like this:
If no results are found, you'll receive a Bundle with an empty entry field.
If a server is unable to execute a search request, it may either return an error for the request or return success with an outcome containing details of the error
Search parameters
The FHIR specification defines a set of general parameters that can be used to search for resources. These parameters are defined in the FHIR Search specification.
There are also resource-specific search parameters that are defined in individual resource definitions. For instance, the ExplanationOfBenefit resource defines a set of parameters that can be used to search for EOBs, such as status or provider.
In order to understand the search parameters available for a particular resource, you can inspect the CapabilityStatement for that insurer. Read more about CapabilityStatements here.
Please note: A FHIR request without any parameters is treated as a search operation. Some servers may not support this and will return an error. It is best practice to always include at least one search parameter. Most commonly this will be the patient ID.
If a search returns a large number of results based on the included parameters, it's very common for servers to paginate the response and offer a set count of resources in each Bundle, with links to the next and previous pages.
The link field in the Bundle contains the links to the next and previous pages. The link field is an array of objects, each with a relation and url field. The relation field will be either next or previous depending on which page you are on. The url field will be the URL to the next or previous page.
The links are opaque to the client, have no dictated structure, and only the server understands them. The client must use the server-supplied links in order to traverse the pages.
Read more about paging as defined in the FHIR standard here and Flexpa's support for pagination here.
Referenced resources
Many resources returned by a search will contain references to other resources. For instance, an ExplanationOfBenefit may contain a reference to a Patient, a Coverage, and a Practitioner. When you receive a resource with a reference, you can use the reference to make a request to the referenced resource.
For resources that have many references, the number of subsequent API requests needed to pull all referenced content may be quite high. As a result, when supported, it's common to use the _include parameter to include the referenced resources in the response. This is especially useful when you want to display a list of resources and their related resources in a single request.
Read more about the FHIR definition of the _include parameter here.
Example search request with _include
ACCESS_TOKEN=... # replace with the access token you obtained at the end of the Flexpa Link flow
curl "https://api.flexpa.com/fhir/Coverage?patient=$PATIENT_ID&_include=*" \
-H "Authorization: $ACCESS_TOKEN"
Contained resources
When searching, you may encounter resources where the referenced resource is actually contained in the API response and not a separate external reference.
For instance, rather than point to an external Organization resource, a Coverage resource may contain the Organization that is the insurer for that coverage. When you receive a resource with a contained resource, you can access the contained resource by using the resourceType and id fields.
Example contained resource
{
"resourceType" : "Coverage",
"contained": [
{
"resourceType" : "Organization",
"id" : "o1",
"name" : "Cigna Insurance"
}],
"insurer" : {
"reference" : "#o1"
}
}
Next steps