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

Get Providers

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

Provider successfully retrieved.

1
2
3
4
5
6
7
8
9
10
11
[
    {
        "id": 4894,
        "name": "Michigan Medicine",
        "address": "1500 E Medical Center Dr",
        "fhirVersion": "FHIR R4",
        "ehr": "epic",
        "resourceUrl": "https://mcproxyprd.med.umich.edu/FHIR-PRD/api/FHIR/DSTU2",
        "logo": "https://1uphealth-assets.s3-us-west-2.amazonaws.com/systems/michigan-medicine.png",
    }
]

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.

1
2
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.

1
2
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

Example response

The following is an example response from a health system and System Search.

1
2
3
4
5
6
7
8
9
10
11
[
    {
        "id": 4894,
        "name": "Michigan Medicine",
        "address": "1500 E Medical Center Dr",
        "fhirVersion": "FHIR R4",
        "ehr": "epic",
        "resourceUrl": "https://mcproxyprd.med.umich.edu/FHIR-PRD/api/FHIR/DSTU2",
        "logo": "https://1uphealth-assets.s3-us-west-2.amazonaws.com/systems/michigan-medicine.png",
    }
]

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.

Embed the System Search tool IFrame and function for React

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.

1
<iframe ref={iframeRef} onLoad={onIframeLoad} style="border: 0px solid #fff" src="https://system-search.1up.health/search" height="500" width="100%"title="Health System Search"/>

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// 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}`);
 }
};

Embed the System Search tool IFrame and function using JavaScript

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.

1
<iframe style="border: 0px solid #fff" id=”system-search-iframe” src="https://system-search.1up.health/search" height="500" width="100%"title="Health System Search"/>

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
<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.