Patient Connect APIs

You can use the 1up FHIR APIs and Patient Connect APIs to connect to individual patient records and get patient consent through the patient’s health system’s patient portal. After patients have authorized sharing their data and the data is ingested in the 1up FHIR Server, you can use the Patient Connect and FHIR APIs to retrieve that patient data.

API References for Patient Connect

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. You can also use Patient Connect API endpoints to get a list of supported health plans, health systems, and token related information.

GET  https://api.1up.health/dstu2/Patient?query-param=queryvalue

Use this 1up FHIR API endpoint to get access to the Patient resource.

Parameters

Query    
query-param string The query string value.
Header    
Authorization string This endpoint receives authentication requests as an HTTP authentication header with a Bearer token.

Responses

200 
{
   "resource" : {
      "id" : "efcfce77bd6e",
      "birthDate" : "1985-08-01",
      "gender" : "male",
      "identifier" : [
         {
            "use" : "usual",
            "system" : "urn:oid:1.2.840.114350.1.13.0.1.7.5.737384.0",
            "value" : "E3967"
         },
         {
            "use" : "usual",
            "value" : "203675",
            "system" : "urn:oid:1.2.840.114350.1.13.0.1.7.5.737384.14"
         },
         {
            "system" : "https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/DSTU2",
            "value" : "Tzq4j8Zz14GtEj1vkMR1DfKeTpXPttd5-8DvjtsLBdJsB",
            "use" : "usual"
         }
      ],
      "active" : true,
      "communication" : [
         {
            "preferred" : true,
            "language" : {
               "text" : "English",
               "coding" : [
                  {
                     "system" : "urn:oid:2.16.840.1.113883.6.99",
                     "code" : "en",
                     "display" : "English"
                  }
               ]
            }
         }
      ],
      "name" : [
         {
            "use" : "official",
            "text" : "Jason Argonaut",
            "family" : [
               "Argonaut"
            ],
            "given" : [
               "Jason"
            ]
         },
         {
            "family" : [
               "Argonaut"
            ],
            "use" : "usual",
            "text" : "Jason Argonaut",
            "given" : [
               "Jason"
            ]
         }
      ],
      "deceasedBoolean" : false,
      "telecom" : [
         {
            "value" : "608-555-5555",
            "system" : "phone",
            "use" : "home"
         },
         {
            "use" : "work",
            "value" : "469-777-7777",
            "system" : "phone"
         },
         {
            "use" : "mobile",
            "value" : "123-456-7890",
            "system" : "phone"
         }
      ],
      "careProvider" : [
         {
            "display" : "Physician O. Cardiology, MD",
            "reference" : "Practitioner/2fc0240080e2"
         }
      ],
      "extension" : [
         {
            "url" : "http://hl7.org/fhir/StructureDefinition/us-core-race",
            "valueCodeableConcept" : {
               "coding" : [
                  {
                     "display" : "Asian",
                     "system" : "urn:oid:2.16.840.1.113883.5.104",
                     "code" : "2028-9"
                  }
               ],
               "text" : "Asian"
            }
         },
         {
            "valueCodeableConcept" : {
               "coding" : [
                  {
                     "system" : "urn:oid:2.16.840.1.113883.5.50",
                     "code" : "UNK",
                     "display" : "Unknown"
                  }
               ],
               "text" : "Unknown"
            },
            "url" : "http://hl7.org/fhir/StructureDefinition/us-core-ethnicity"
         },
         {
            "valueCodeableConcept" : {
               "coding" : [
                  {
                     "display" : "Male",
                     "code" : "M",
                     "system" : "http://hl7.org/fhir/v3/AdministrativeGender"
                  }
               ],
               "text" : "Male"
            },
            "url" : "http://hl7.org/fhir/StructureDefinition/us-core-birth-sex"
         }
      ],
      "meta" : {
         "versionId" : "9000000000000",
         "lastUpdated" : "2020-12-02T00:10:31.921Z"
      },
      "resourceType" : "Patient"
   },
   "fullUrl" : "https://api.1up.health/dstu2/Patient/efcfce77bd6e",
   "search" : {
      "mode" : "match"
   }
}

POST  https://api.1up.health/connect/system/clinical

Use this Patient Connect API endpoint to query the full list of supported health plans and health systems.

If you need a full-text search of providers for fields such as name, address, or clinician names, we recommend using the System Search API endpoint instead.

Parameters

Header    
  JSON object  
Body    
  JSON object  

client_id

string

API key generated for your application.

client_secret

string

API key generated for your application.

systemType

string

The type of system.

Example — Health System or Payer Patient Access

Responses

200: OK 
[
   {
      "ehr" : "eClinicalWorks",
      "id" : 11165,
      "locations" : [
         {
            "address" : {
               "city" : "New York",
               "line" : [
                  "3410-18 Broadway 2nd Fl",
                  ""
               ],
               "state" : "NY"
            },
            "name" : "139 Medical Group  "
         }
      ],
      "logo" : "https://1uphealth-assets.s3-us-west-2.amazonaws.com/systems/health-system-default.png",
      "name" : "139 Medical Group  ",
      "status" : "connection_working"
   },
   {
      "ehr" : "eClinicalWorks",
      "id" : 11167,
      "locations" : [
         {
            "address" : {
               "city" : "Suffolk",
               "line" : [
                  "171 N Main Street",
                  ""
               ],
               "state" : "VA"
            },
            "name" : "1Foot 2Foot Centre for Foot and Ankle Care"
         }
      ],
      "logo" : "https://1uphealth-assets.s3-us-west-2.amazonaws.com/systems/health-system-default.png",
      "name" : "1Foot 2Foot Centre for Foot and Ankle Care",
      "status" : "connection_working"
   },
   {
      "ehr" : "eClinicalWorks",
      "id" : 11163,
      "locations" : [
         {
            "address" : {
               "city" : "Austin",
               "line" : [
                  "8302 Minnesota Ln",
                  ""
               ],
               "state" : "TX"
            },
            "name" : "1 The Doctor Is At Your Door AUSTIN TX"
         }
      ],
      "logo" : "https://1uphealth-assets.s3-us-west-2.amazonaws.com/systems/health-system-default.png",
      "name" : "1 The Doctor Is At Your Door AUSTIN TX",
      "status" : "connection_working"
   },
]

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

Use this Patient Connect 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.

ehr_patient_id

string

The unique ID assigned by the health system or EHR. Value location varies by EHR. The end user needs to successfully log in for the API to work for that individual, otherwise an error will display.

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 
{
    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 
{ 
"success": false, 
"message": "The user ID is invalid." 
}
429: Too Many Requests 
{ 
"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 
{ 
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 
{ 
"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 
{ 
"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 
{ 
"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 
{
    success : false 
message : Access to the data has expired. The user must reauthorize data access.     
}
500: Internal Server Error

 

{ "success": false, 
"message": "An error occurred while processing your request. Try to submit your request again later." 
}

GET  https://api.1up.health/connect/api/ondemand/token-status

Use this Patient Connect 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.

ehr_patient_id

string

The unique ID assigned by the health system or EHR. Value location varies by EHR. The end user needs to successfully log in for the ODI API to work for that individual, otherwise an error will display.

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 
{
     success : true,
body: {
   tokenLastRefreshedAt: 2024-08-05T12:34:56Z,
   refreshTokenExpiresAt: 2024-09-05T12:34:56Z,
}, 
}

POST  https://api.1up.health/connect/api/revoke-data-access

This Patient Connect 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.

ehr_patient_id

string

The unique ID assigned by the health system or EHR. Value location varies by EHR. The end user needs to successfully log in for the API to work for that individual, otherwise an error will display.

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 
{
    success : true,
message : Data access revoked successfully
}
400: Bad Request 
{ 
"success": false, 
"message": "The user ID is invalid." 
}
429: Too Many Requests 
{ 
"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 
{ 
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 
{ 
"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 
{ 
"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 
{ 
"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 
{
    success : false 
message : Access to the data has expired. The user must reauthorize data access.     
}
500: Internal Server Error

 

{ "success": false, 
"message": "An error occurred while processing your request. Try to submit your request again later." 
}

Use the 1up APIs for Patient Connect

1up allows users to connect data within health system (providers) electronic health records (EHR). As a developer, you can read your users' clinical health data from patients who are using your app.

Data from external health systems is a vital, missing piece that's required to improve care and reduce costs. Data from other clinics and hospitals can fill this gap.

To get OAuth client keys for the Patient Connect API, you can create an account.

Patient Connect Process Overview

  • Your app must direct users to the Patient Connect API URL to link to a specific health system.

  • Users will see the systems authentication screen and can then allow access to their data.

  • User are redirected back to your app's redirect_uri. 1up retrieves data from that system into the 1up FHIR Server.

  • Your app can query that user's resources, which are stored in FHIR® format on the 1up FHIR Server.

Get a List of Supported 1up Health Plans & Health Systems

1up supports hundreds of health plans and health systems. You can get the full list by querying the following endpoint. Results are returned in increments of 20, in alphabetical order.

To set a starting point for your query, specify an offset value in the query URL.

curl -H "Authorization: Bearer {access_token}" -X POST "https://system-search.1up.health/api/search?offset=20"

The request response includes the IDs of each health system that matches your search query. The following is an example of a single entry from a response.

[
    {
      "address" : "450 4th Ave Chula Vista CA 91910",
      "ehr" : "eClinicalWorks",
      "fhirVersion" : "FHIR STU3 3.0.1",
      "id" : 11207,
      "logo" : "https://1uphealth-assets.s3-us-west-2.amazonaws.com/systems/health-system-default.png",
      "name" : "Absolute Foot Care",
      "resourceUrl" : "https://fhir.healow.com/FHIRServer/fhir/CDJDCA"
   },
   {
      "address" : "540 2nd Ave S Saint Petersburg FL 33701",
      "ehr" : "eClinicalWorks",
      "fhirVersion" : "FHIR STU3 3.0.1",
      "id" : 11208,
      "logo" : "https://1uphealth-assets.s3-us-west-2.amazonaws.com/systems/health-system-default.png",
      "name" : "Absolute Health Internal Med and Peds Ocala FL",
      "resourceUrl" : "https://fhir.healow.com/FHIRServer/fhir/CIEABD"
   },

]

You can use the ID from the response in other requests to the FHIR Server. In this example, the IDs are 11207 and 11208.

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 programdirect users to connect their health systems must send users to the following URL.

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

https://api.1up.health/connect/system/clinical/{healthsystemid}?client_id=clientidclientidclientid&access_token=accesstokenaccesstoken

This example connects users to Michigan Medicine.

https://api.1up.health/connect/system/clinical/4894?client_id=clientidclientidclientid&access_token=accesstokenaccesstoken&fhirVersion=FHIR_VERSION

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.

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.

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

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

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.