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.

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 |
400: Bad Request |

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 |
![]()
|

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 |
![]()
|
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

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.

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}`);
}
};

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

Make sure to include the user's access token and your applications client ID as parameters.
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 |
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 |
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 |
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.
-
1up redirects the user to the OAuth2 authorization page for the clinical system.
-
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.
-
1up receives an access token for that user, and directs the user back to your app's
redirect_uri
(which is associated with theclient_id
). -
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.

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 |
400: Bad Request |
429: Too Many Requests |
400: Bad Request |
400: Bad Request |
400: Bad Request |
400: Bad Request |
403: Forbiddent |
500: Internal Server Error |

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 |

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 |
400: Bad Request |
429: Too Many Requests |
400: Bad Request |
400: Bad Request |
400: Bad Request |
400: Bad Request |
403: Forbiddent |
500: Internal Server Error |