System Search
You can use 1upHealth‘s System Search to locate the supported payers (health plans) and providers (health systems) in the 1upHealth network.
1upHealth’s System Search API is a powerful resource that enables developers to leverage each System Search API in a single query. The System Search API search parameters match against the name
attribute, address.line
, or address.city
.
Because the System Search endpoint and tool provide broader search functionality and precise results, we recommend using System Search instead of the individual 1up FHIR APIs.
System Search API Endpoint
![Closed](../../../Skins/Default/Stylesheets/Images/transparent.gif)
GET https://system-search.1up.health/api/search
You can use this endpoint to search for providers supported by 1upHealth. You can use the query Search parameter.
Parameters
Query | ||
---|---|---|
query |
string |
String matches on name, address.line, or address.city. |
offset |
number |
Offset indicates the starting point within the result set. |
system_type |
string |
Indicates the type of system: HealthSystem, Payer2Payer, or PayerPatientAccess |
Header | ||
---|---|---|
Authorization |
string |
Authentication token to verify who is accessing the system. |
Responses
200 |
Use the System Search API
You can use the System Search API to create a custom search interface that patients can use to identify their providers. You can also use it to retrieve results returned by the System Search tool.
Before you use the System Search API, make sure that you have the access token to use for authorization. The access token (access_token
) is generated from your client_id
and client_secret
for the application.
For more information about access tokens, see Authentication & Authorization APIs.
To use the System Search API, run the following query with the search term appended to the URL as a query parameter. Make sure to add your access_token
to the header as a Bearer token.
You can include alphanumeric characters and the '
character in your query parameters. Other special characters are not allowed.
curl -X POST "https://system-search.1up.health/api/search?query={SEARCH-TERM}" \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"
Each search query returns 20 rows at a time, in alphabetical order, with the offset
value as the starting point. To get another page of search results, you can set the offset value to a multiple of 20. For example, to get the second page of results, include &offset=20
after the search term, as shown in the following example query.
curl -X POST "https://system-search.1up.health/api/search?query={SEARCH-TERM}&offset=20" \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"
After you run this query, the query response returns a list of payers, health systems, clinics, hospitals, or doctors for the searched term with the 1upHealth system ID. You can use this ID to direct a user to a patient portal (using the same access token) to initiate the log in process.
Use System Search
To search for health systems and providers, run the following cURL
command.
curl -H "Authorization: Bearer {access_token}" -X POST "https://system-search.1up.health/api/search?query=epic&offset=20" | json_pp
![Closed](../../../Skins/Default/Stylesheets/Images/transparent.gif)
The following is an example response from a health system and System Search.
Embed the System Search Tool
If you don't want to build a search tool for your application using the 1up System Search API, you can use the 1up System Search IFrame to embed the System Search tool inside your application.
Implementations Before August 2024
The August 2024 release included a security upgrade for the System Search tool IFrame.
To get these security enhancements, you must complete the following steps to embed the System Search tool IFrame again, and add the supporting function to your application. We recommend that you update your implementation as soon as possible. Your current instance of the System Search tool will continue to function normally until you can complete the IFrame implementation upgrade, but it won’t include the new security measures.
To embed the System Search tool IFrame in your application, you must add the System Search IFrame HTML element and function to your application. The purpose of the function is to protect any sensitive data that is sent when the IFrame loads, such as your access token, by sending it through the JavaScript postMessage API. To do this, you must include the src
(source) and onLoad
parameters in the IFrame HTML element. The src
parameter specifies the URL of the content that’s displayed in the IFrame. The onLoad
parameter specifies the function that’s called when the IFrame loads, and is required to be able to load the content securely with your access token.
The following sets of instructions include example code for the System Search IFrame HTML element and the System Search onIframeLoad
function. One set is for React implementations and one is for JavaScript implementations. These examples are base code that you can customize for your specific implementation and front-end framework.
Before You Begin
Make sure that you have your access_token
(which is generated using the client_id
and client_secret
for the application). You must include your access_token
value in the System Search function.
For information about access tokens, see the Authentication & Authorization APIs.
![Closed](../../../Skins/Default/Stylesheets/Images/transparent.gif)
This code in this implementation example includes the onLoad
listener in the IFrame.
-
On the page in your application that will host the System Search tool, insert this IFrame code.
-
Add the System Search function to your application.
Make sure to replace the
{placeholder text}
in this function with the correct values for your implementation.// Instantiate channel and iframeRef variable
const messageChannelRef = useRef();
const iframeRef = useRef();
const onIframeLoad = () => {
// Initialize the message channel when the IFrame loads.
messageChannelRef.current = new window.MessageChannel();
const targetWindow = iframeRef.current.contentWindow;
const targetOrigin = new URL(iframeRef.current.src).origin;
// Send the MessageChannel port to the IFrame. This enables communication with the IFrame.
targetWindow.postMessage('', targetOrigin, [messageChannelRef.current.port2]);
// Get the secure data, including your access token, to send to the IFrame. You must specify the access_token value as a string.
const secureDataPacket = {
jwt: {access_token},// The access_token value must be a string.
};
// Send the data as a message through postMessage API, otherwise throw an error (recommended)
try {
messageChannelRef.current.port1.postMessage(secureDataPacket);
} catch (e) {
console.error(`Error encountered sending secure data to IFrame: ${e}`);
}
};
![Closed](../../../Skins/Default/Stylesheets/Images/transparent.gif)
This code in this implementation example includes the onLoad
listener in the JavaScript function.
-
On the page in your application that will host the System Search tool, insert this IFrame code inside the HTML <body> tag.
-
On the same page, insert this System Search function script inside your <head> tag.
Make sure to replace the
{placeholder text}
in this function with the correct values for your implementation.If you’re inserting the System Search IFrame in an HTML page, insert this function as a script on the same page that you inserted the IFrame code.
<script>
document.addEventListener('DOMContentLoaded', () => {
// Get a reference to the IFrame element before it finishes loading
const iframe = document.querySelector('#system-search-iframe');
let messageChannel;
// Add the onload listener for the IFrame element
iframe.onload = () => {
// Initialize the message channel when the IFrame loads
messageChannel = new window.MessageChannel();
messageChannel.port1.onmessage = handleMessageChannelEvent;
const targetWindow = iframe.contentWindow;
const targetOrigin = new URL(iframe.src).origin;
// Send the MessageChannel port to the IFrame. This enables communication with the IFrame.
targetWindow.postMessage('', targetOrigin, [messageChannel.port2]);
// Get the secure data, including your access token, to send to the IFrame. You must specify the access_token value as a string.
const secureDataPacket = {
jwt: { access_token },
};
// Send the data as a message through postMessage API, otherwise throw an error (recommended)
try {
messageChannel.port1.postMessage(secureDataPacket);
} catch (e) {
console.error(`Error encountered sending secure data to IFrame: ${e}`);
}
};
});
</script>
After a user selects a health system, clinic, hospital, or doctor, the user is directed to a log in page using the same access_token
.