Search and Connect to Health Systems

The following API information is included in this section:

System Search APIs

You can use the 1up System Search to locate the supported payers (health plans) and providers (health systems) in the 1up network.

1up System Search APIs are a powerful resource enabling developers to leverage each System Search API in a single query. The 1up System Search APIs search parameters are matched against the name attribute, address.line, or address.city.

Because the 1up System Search API endpoints and tools provide broader search functionality and precise results, we recommend using 1up System Search APIs instead of the individual 1up FHIR APIs.

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

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.

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.

Connect to Health System APIs

After patients authorize access to their data, you can use the access token and the 1up FHIR API to get the FHIR® resources for that patient.

Connect Users

Before you can connect users to their health systems, you must use the 1up User Management API to create a user. Application developers that want to program direct users to connect their health systems must send users to the following URL.

The following examples only apply to a production environment. They will not work in a development sandbox.

If you include the fhirVersion parameter, only valid FHIR versions supported by that system will retrieve FHIR resources.

When a user follows the link to the URL you specified, the following process occurs.

  1. 1up redirects the user to the OAuth2 authorization page for the clinical system.

  2. The user enters credentials for the health system.

    To test the process, you can use 1up's test credentials for health systems that use FHIR.

  3. 1up receives an access token for that user, and directs the user back to your app's redirect_uri (which is associated with the client_id).

  4. 1up begins collecting data in the 1up FHIR Server and makes it available to your application.

Access the Connected Data

After users have authorized sharing their data, and their clinical and claims data is sent to the 1up FHIR Server through the 1up FHIR® API, the data is stored as native FHIR® resources. Apps can get access to the clinical and claims data for a specific user by including an authorization Bearer token (access_token) for that user in the request to the 1up FHIR Server. You can modify the query from your app to select which source metrics you want to get data from.

The following are a few examples of app queries. Each query must be accompanied by the Authorization header that contains the user's authorization Bearer token.

Get Specific Patient Data

You can use the 1up FHIR API $everything query to get the full patient history or to query for specific FHIR resources.

For more information, see Get Patient Data.

OnDemand Ingest (ODI) APIs

Use the following OnDemand Ingest (ODI) APIs to query updated data, get token refresh and expiration information, and revoke token information.