Patient Connect APIs

You can use the 1up FHIR API and 1up Connect API 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 Reference 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 the 1up Connect API endpoint to get a list of supported health plans and health systems.

Get Patient

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

Patient 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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
{
   "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 Supported Health Plans & Health Systems

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

Use the 1up 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 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

Response example

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
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
[
   {
      "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"
   },
]

Use the 1up APIs for Patient Connect

1upHealth 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 1upHealth API, you can create an account.

Patient Connect Process Overview

Your app must direct users to the 1upHealth 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. 1upHealth 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 Health Plans & Health Systems

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

Get a list of health systems

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.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
[
    {
      "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 programmatically direct users to connect their health systems must send users to the following URL.

Connect users to health systems

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

Example request

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.

1upHealth 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.
1upHealth 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).
1upHealth 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/dstu2/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 1upHealth FHIR API $everything query to get the full patient history or to query for specific FHIR resources.

For more information, see Get Patient Data.