Search and Connect to Health Systems

The following API information is included in this section:

• System Search APIs

• Connect to Health System APIs

• OnDemand Ingest (ODI) APIs

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.

Post Providers

POST   https://system-search.1up.health/api/search

You can use this API endpoint to search for providers supported by 1up. 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

201: Ok

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",     } ]

400: Bad Request

If the one-up user_id is invalid. 1 2 3 4 5 {  "success": false,  "message": "The user ID is invalid."  }

Get Zip Codes

GET  https://system-search.1up.health/api/systems/ :zipCode

You can use this API endpoint to query Zip Codes in all the Health Systems supported by 1up. You can use the query Search parameter.

Parameters

Query
query	string	String matches on US zip codes in 5 digits (e.g. 12345), or 5-4 digits (e.g. 12345-6789).
offset	number	Offset indicates the starting point within the result set.
system_type	string	Indicates the type of system: HealthSystem, or PayerPatientAccess

Header
Authorization	string	Authentication token to verify who is accessing the system.

Responses

200

Zip Codes successfully retrieved. 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 [     {     "systems": [         {             "id": 1288,             "name": "Humana (demo)",             "resourceUrl": "https://fhir.humana.com/sandbox/api",             "logo": "humana.png",             "fhirVersions": [                 "FHIR R4 4.0.1"             ],             "primaryFhirVersion": "FHIR R4 4.0.1",             "ehr": null,             "locations": [                 {                     "name": "Humana (demo)",                     "address": {                         "line": [                             "500 West Main Street"                         ],                         "city": "Louisville",                         "postalCode": "40202",                         "state": "KY"                     }                 }             ]         }     ] } ]

Get Admins - All-Systems

GET  https://system-search.1up.health/api/all-systems

You can use this API endpoint to query Health Systems supported by 1up. 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, or PayerPatientAccess

Header
Authorization	string	Authentication token to verify who is accessing the system.

Responses

200

Health System successfully retrieved. 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 [       {"systems": [         {             "id": 3467,             "name": "Cascade Comprehensive Care" ,             "resourceUrl": "https://api.cascadecompfhir.com/r4",             "logo": null,             "fhirVersions": [                 "DSTU2",                 "FHIR R4"             ],             "primaryFhirVersion": "FHIR R4",             "ehr": "epic",             "locations": [                 {                     "name": "Cascade Comprehensive Care",                     "address": {                         "line": ["123 main st", "some other stuff"],                         "city": Seattle,                         "postalCode": "98103",                         "state": WA                     }                 }             ]         }, ... ] } ]

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/R4",
        "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.

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.

Embed the System Search tool IFrame and function for React

This code in this implementation example includes the onLoad listener in the IFrame.

1. 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"/>

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

1. 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"/>

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

Example of the embedded System Search tool

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.

Troubleshooting the System Search IFrame

On slower networks or devices with limited resources, it is possible for the IFrame to fully load and render before React finishes hydrating the page on the client side (the IFrame host). If that happens, React will not have attached the onLoad handler yet — meaning, it never gets called at all. This is a known React quirk (see Events before Client Side Hydration · Issue #15446 · facebook/react ).

To fix this, 1up forces the component to wait to render the IFrame until after React hydration is complete. This is done by setting a shouldRenderIframe flag in a useEffect which only runs once the client-side React is ready. That guarantees the onLoad handler will be in place when the IFrame is created, ensuring it fires reliably.

Example IFrame flag

This example demonstrates setting the shouldRenderIframe flag .

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
33
const [shouldRenderIframe, setShouldRenderIframe] = useState(false);

// This will run on 'component did mount' - only once the UI loads does this run
useEffect(() => {
    setShouldRenderIframe(true);
}, []);

// In your JSX:
{shouldRenderIframe ?
  <iframe
        ref={iFrameRef}
        onLoad={onIframeLoad}
        className="container"
        style={{ height: '760px' }}
        src="YOUR_IFRAME_URL"
        title="Health System Search"
    /> :
  <div
    className="container"
    style={{ height: '760px' }}
  >
    <div
      className="spinner-border"
            style={{
                position: 'absolute',
                top: '50%',
                left: '50%',
                marginTop: '-20px',
                marginLeft: '-16px',
                zIndex: 10000,
    }} />
  </div>
}

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.

Connect users to health systems

Make sure to include the user's access token and your applications client ID as parameters.

https://system-search.1up.health/api/clinical/{healthsystemid}

Path Parameter	JSON object	Description
system_id (required)	string	The ID of the FHIR system that the client wants to connect to.
system_name	string	The name of the system that the client wants to connect to.
Headers
authorization (required)	string	Bearer token for user authentication, sent as Bearer <token>.
x-client-id (optional)	string	The client ID associated with the request. If not present, this can be retrieved from cookies.

Cookies
auth_token (optional)	string	Token for user authentication (alternative to the Authorization header).
client_id (optional)	string	The client ID (alternative to the x-client-id header).

Query Parameters
fhirVersion (optional)	string	Specifies the FHIR version for the system. Valid values depend on the supported FHIR versions configured in the system ('dstu2', 'stu3', 'r4').
sendRedirectUrlAsResponse (optional)	string	When set to true, the response includes the authorization URL instead of redirecting the client.

Outputs

200:OK

If the system responds successfully and the sendRedirectUrlAsResponse query parameter is true, the API responds with a JSON payload: 1 2 3 4 5 {   "system_id": "<systemId>",   "system_name": "<systemName>",   "authorization_url": "<connectApiResponse>" } If sendRedirectUrlAsResponse is not true, the API redirects the client to the authorization URL (connectApiResponse).

Example request

This example connects users to Michigan Medicine.

https://system-search.1up.health/api/clinical/4894?sendRedirectUrlAsResponse=true

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.

Query new clinical data

To run a query for a specific user, you can use that user's access_token.

You can run a query to get new clinical data using the same access token, or a new access token if the original token expired.

1
2
curl -X GET https://api.1up.health/r4/Patient \
  -H "Authorization: Bearer accesstokenaccesstoken"

List observations

1
2
curl -X GET https://api.1up.health/version/Observation
  -H "Authorization: Bearer accesstokenaccesstoken"

Query by measured metric

You can run a query to get a user’s conditions for a specific resource code.

We use LOINC codes to identify measurements, such as steps (66334-4).

1
2
curl -X GET https://api.1up.health/version/Observation?code=29308-4
  -H "Authorization: Bearer accesstokenaccesstoken"

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.

Post OnDemand Ingest

POST  https://api.1up.health/on-demand-ingest

Use this API endpoint to query updated data from their health systems and remove the timely burden of having to re-authenticate to the health system each time they want new data ingested into the third party application they are using. This API works with 1up's Refresh Token service (see REST API Endpoint Reference).

Parameters

Header
	JSON object

Body
	JSON object
oneup_user_id	string	1up is typically mapped to the patient or member who is logging in. When the patient is first authorized, the patient resource is retrieved using the Get Patient Data API.
system_id	string	1up ID for a provider or payee. To obtain the system id, use the Patient Connect Audit Events along with the user_id, client_id, and client secret.
fhir_version	string	The FHIR version supported by the payee or provider (case sensitive).To obtain the fhir_version, use the Patient Connect Audit Events along with the user_id, client_id, and client secret.

Responses

200: OK

ODI initiates data ingest successfully. 1 2 3 4 5 6 7 8 {     success : true, message : The call to the On-Demand Ingest API was successful. The data refresh process was initiated. body: {    refreshTokenExpiresOn: 2024-08-05T12:34:56Z },  }

400: Bad Request

If the one-up user_id is invalid. 1 2 3 4 5 {  "success": false,  "message": "The user ID is invalid."  }

429: Too Many Requests

If a user exceeds the rate limit (300 requests/hour for a client-id). 1 2 3 4 5 {  "success": false,  "message": "You have sent more requests in the last hour than allowed. Wait until the start of the next hour and try your request again."  }

400: Bad Request

If the request payload has a missing attribute or has an undefined value. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 {  success: false,  message: "The request payload is invalid and has the following errors", errors: [ {  field: "attribute_name",  error: "The ${attribute_name} is required."  },  {  field: "another_attribute",  error: "The ${attribute_name} value is required."  }                 ]  }

400: Bad Request

If the combination of system_id and fhir_version is invalid or not supported by 1up. 1 2 3 4 5 {  "success": false,  "message": "The system ID and FHIR version you specified are invalid or are not a supported combination. Review the values that you specified to verify that they are correct and submit your request again."  }

400: Bad Request

If the system id is not supported for On Demand Ingest yet. 1 2 3 4 5 {  "success": false,  "message": "The system ID that you specified is not supported for On-Demand Ingest. Review the supported system IDs and submit your request again with a valid system ID."  }

400: Bad Request

If a user has never logged in before. (They must log in at least once for ODI to work) . 1 2 3 4 5 {  "success": false,  "message": "The user ID you specified has not logged in to the system. Make sure the user has logged in to the system and then submit your request again."  }

403: Forbiddent

If system access token/refresh token has expired or is invalid 1 2 3 4 5 {     success : false  message : Access to the data has expired. The user must reauthorize data access.      }

500: Internal Server Error

If there’s an error while processing the request   1 2 3 4 { "success": false,  "message": "An error occurred while processing your request. Try to submit your request again later."  }

Get Token Status

GET  https://api.1up.health/on-demand-ingest/token-status

Use this API endpoint to get token refresh and expiration information. This API works with 1up's Refresh Token service (see REST API Endpoint Reference).

Parameters

Header
	JSON object

Body
	JSON object
oneup_user_id	string	1up is typically mapped to the patient or member who is logging in. When the patient is first authorized, the patient resource is retrieved using the Get Patient Data API.
fhir_version	string	The FHIR version supported by the payee or provider (case sensitive).To obtain the fhir_version, use the Patient Connect Audit Events along with the user_id, client_id, and client secret.

Responses

200:OK

Token initiates data successfully. 1 2 3 4 5 6 7 8 {      success : true, body: {    tokenLastRefreshedAt: 2024-08-05T12:34:56Z,    refreshTokenExpiresAt: 2024-09-05T12:34:56Z, },  }

Post Revoke Data Access

POST  https://api.1up.health/on-demand-ingest/revoke-data-access

This API endpoint provides the ability to delete token information so that a patient’s data will not be refreshed automatically in the future unless they go through the login flow and opt in again. This API works with 1up's Refresh Token service (see REST API Endpoint Reference).

Parameters

Header
	JSON object

Body
	JSON object
oneup_user_id	string	1up is typically mapped to the patient or member who is logging in. When the patient is first authorized, the patient resource is retrieved using the Get Patient Data API.
system_id	string	1up ID for a provider or payee. To obtain the system id, use the Patient Connect Audit Events along with the user_id, client_id, and client secret.
fhir_version	string	The FHIR version supported by the payee or provider (case sensitive).To obtain the fhir_version, use the Patient Connect Audit Events along with the user_id, client_id, and client secret.

Responses

201: Created

Data access revoked successfully. 1 2 3 4 5 6 {     success : true, message : Data access revoked successfully }

400: Bad Request

If the one-up user_id is invalid. 1 2 3 4 5 {  "success": false,  "message": "The user ID is invalid."  }

429: Too Many Requests

If a user exceeds the rate limit (300 requests/hour for a client-id). 1 2 3 4 5 {  "success": false,  "message": "You have sent more requests in the last hour than allowed. Wait until the start of the next hour and try your request again."  }

400: Bad Request

If the request payload has a missing attribute or has an undefined value. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 {  success: false,  message: "The request payload is invalid and has the following errors", errors: [ {  field: "attribute_name",  error: "The ${attribute_name} is required."  },  {  field: "another_attribute",  error: "The ${attribute_name} value is required."  }                 ]  }

400: Bad Request

If the combination of system_id and fhir_version is invalid or not supported by 1up. 1 2 3 4 5 {  "success": false,  "message": "The system ID and FHIR version you specified are invalid or are not a supported combination. Review the values that you specified to verify that they are correct and submit your request again."  }

400: Bad Request

If the system id is not supported for On Demand Ingest yet. 1 2 3 4 5 {  "success": false,  "message": "The system ID that you specified is not supported for On-Demand Ingest. Review the supported system IDs and submit your request again with a valid system ID."  }

400: Bad Request

If a user has never logged in before. (They must log in at least once for ODI to work) . 1 2 3 4 5 {  "success": false,  "message": "The user ID you specified has not logged in to the system. Make sure the user has logged in to the system and then submit your request again."  }

403: Forbiddent

If system access token/refresh token has expired or is invalid 1 2 3 4 5 {     success : false  message : Access to the data has expired. The user must reauthorize data access.      }

500: Internal Server Error

If there’s an error while processing the request   1 2 3 4 { "success": false,  "message": "An error occurred while processing your request. Try to submit your request again later."  }

ODI API Token Refresh Troubleshooting

Epic and individual provider systems operate as separate entities, each responsible for its own token implementation. Provider/ Health Systems will need to ensure OAuth2 implementation steps have been fully completed, specifically ensuring that Oauth2 is enabled for the Introspect endpoint.

Note to App Developers: If you are receiving the following 400 error message when hitting the ODI endpoint, and you can confirm the user has logged into the system previously, there may be some additional steps needed from the Provider Systems to complete token refresh support.

The user ID you specified has not logged in to the system. Make sure the user has logged in to the system and then submit your request again.