{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["json-schema"]},"type":"markdown"},"seo":{"title":"Clinic Integration Guide","llmstxt":{"hide":true}},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"clinic-integration-guide","__idx":0},"children":["Clinic Integration Guide"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"introduction","__idx":1},"children":["Introduction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide is for clinics who are interested in retrieving clinic or patient data programmatically from Tidepool Data Platform. That can be done in two ways:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["EHR integrations with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.hl7.org"},"children":["Health Level Seven (HL7)"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://hl7.org/fhir/"},"children":["Fast Healthcare Interoperability Resources (FIHR)"]}," through middleware partners ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redoxengine.com/"},"children":["Redox"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.xealth.com/"},"children":["Xealth"]},". This feature is part of our ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.tidepool.org/providers/tidepoolplus"},"children":["Tidepool+ offering"]}," that requires a paid subscription."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Tidepool Data Platform exposes a rich set of REST APIs that may be used to directly interact with Tidepool data model. These are the same APIs that are used by Tidepool's own applications."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you are interested in EHR integration, please contact ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:sales@tidepool.org"},"children":["Tidepool Sales team"]},". This guide focuses on the latter use-case."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The intended audience for this guide are information technology teams or software developers who may be asked to evaluate and implement the direct API integration. For brevity, this guide assumes you are experienced with common web technologies such as OpenID Connect, OAuth2 and REST APIs."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"clinic-data-model","__idx":2},"children":["Clinic Data Model"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before diving into sample use-cases, let's walk through an overview of how clinics, clinicians, patients and patient data is structured in Tidepool Data Platform."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are 3 basic data types in the clinic data model: ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["clinics"]},", ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["members"]},", and ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["patients"]},"."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Clinic"]},": represents a healthcare organization, such as a clinic or hospital."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Member"]},": staff member of one or more clinics. Each member has a role that is specific to each clinic:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Administrator: member with administrator privileges, i.e. change clinic settings, add or remove clinicians or administrators, and so on. Every clinic has at least one administrator."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Clinician: member without administrator privileges."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Patient"]},": person with diabetes who is a patient of one or more clinics. They can be further sub-divided into two categories:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Custodial Patient"]},": a patient who was created by the clinic, and has not accessed their patient account outside of that clinic."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Claimed Patient"]},": a patient who either created their own account and shared it with a clinic, or accepted an invitation from a clinic to claim a custodial patient account created by that clinic."]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both members and patients may be part of multiple clinics. That is, there exists a one-to-many relationship between them and clinics."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here is a simple diagram to illustrate this data model. ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Dr Seastar"]}," manages her ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Seastar Endocrinology"]}," clinic with 2 other members and 3 patients."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart TB\n clinic1(Seastar Endocrinology)\n subgraph Members\n member1(Dr Sally Seastar)\n member2(Carla Espinosa, RN)\n member3(Morgan Tookers, NP)\n end\n subgraph Patients\n patient1(James Jellyfish)\n patient2(Kacey Kelp)\n patient3(Ava Abalone)\n end\n\n member1 == administrator of ===> clinic1\n member2 ===> clinic1\n member3 ===> clinic1\n patient1 ==> clinic1\n patient2 ==> clinic1\n patient3 ==> clinic1\n","diagramHtml":"

Patients

Members

administrator of

Seastar Endocrinology

Dr Sally Seastar

Carla Espinosa, RN

Morgan Tookers, NP

James Jellyfish

Kacey Kelp

Ava Abalone

","diagramHtmlDark":"

Patients

Members

administrator of

Seastar Endocrinology

Dr Sally Seastar

Carla Espinosa, RN

Morgan Tookers, NP

James Jellyfish

Kacey Kelp

Ava Abalone

"},"children":["flowchart TB\n clinic1(Seastar Endocrinology)\n subgraph Members\n member1(Dr Sally Seastar)\n member2(Carla Espinosa, RN)\n member3(Morgan Tookers, NP)\n end\n subgraph Patients\n patient1(James Jellyfish)\n patient2(Kacey Kelp)\n patient3(Ava Abalone)\n end\n\n member1 == administrator of ===> clinic1\n member2 ===> clinic1\n member3 ===> clinic1\n patient1 ==> clinic1\n patient2 ==> clinic1\n patient3 ==> clinic1\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here is somewhat more complicated sample diagram. ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Dr Seuss"]}," manages his own ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Whoville Health System"]},", but occasionally helps out his friend ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Dr Seastar"]}," at the ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Seastar Endocrinology"]},". He has administrator role in his own clinic, and only normal clinician role in ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Seastar Endocrinology"]},". One of his patients, ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Harold Haddock"]},", is also a patient of ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Seastar Endocrinology"]},"."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart TB\n clinic1(Seastar Endocrinology)\n clinic2(Whoville Health System)\n subgraph Members\n member1(Dr Sally Seastar)\n member2(Carla Espinosa, RN)\n member3(Morgan Tookers, NP)\n member4(Dr Seuss)\n member5(Cindy Lou Who, NP)\n end\n subgraph Patients1 [Patients of Dr Seastar]\n patient1(James Jellyfish)\n patient2(Kacey Kelp)\n patient3(Ava Abalone)\n end\n subgraph Patients2 [Patients of Dr Seuss]\n patient4(Harold Haddock)\n patient5(D'andre Dolphin)\n end\n\n member1 == administrator of ===> clinic1\n member2 ===> clinic1\n member3 ===> clinic1\n member4 == administrator of ===> clinic2\n member4 ===> clinic1\n member5 ===> clinic2\n patient1 ==> clinic1\n patient2 ==> clinic1\n patient3 ==> clinic1\n patient4 ==> clinic2\n patient5 ==> clinic2\n patient4 ==> clinic1\n","diagramHtml":"

Patients of Dr Seuss

Patients of Dr Seastar

Members

administrator of

administrator of

Seastar Endocrinology

Whoville Health System

Dr Sally Seastar

Carla Espinosa, RN

Morgan Tookers, NP

Dr Seuss

Cindy Lou Who, NP

James Jellyfish

Kacey Kelp

Ava Abalone

Harold Haddock

D'andre Dolphin

","diagramHtmlDark":"

Patients of Dr Seuss

Patients of Dr Seastar

Members

administrator of

administrator of

Seastar Endocrinology

Whoville Health System

Dr Sally Seastar

Carla Espinosa, RN

Morgan Tookers, NP

Dr Seuss

Cindy Lou Who, NP

James Jellyfish

Kacey Kelp

Ava Abalone

Harold Haddock

D'andre Dolphin

"},"children":["flowchart TB\n clinic1(Seastar Endocrinology)\n clinic2(Whoville Health System)\n subgraph Members\n member1(Dr Sally Seastar)\n member2(Carla Espinosa, RN)\n member3(Morgan Tookers, NP)\n member4(Dr Seuss)\n member5(Cindy Lou Who, NP)\n end\n subgraph Patients1 [Patients of Dr Seastar]\n patient1(James Jellyfish)\n patient2(Kacey Kelp)\n patient3(Ava Abalone)\n end\n subgraph Patients2 [Patients of Dr Seuss]\n patient4(Harold Haddock)\n patient5(D'andre Dolphin)\n end\n\n member1 == administrator of ===> clinic1\n member2 ===> clinic1\n member3 ===> clinic1\n member4 == administrator of ===> clinic2\n member4 ===> clinic1\n member5 ===> clinic2\n patient1 ==> clinic1\n patient2 ==> clinic1\n patient3 ==> clinic1\n patient4 ==> clinic2\n patient5 ==> clinic2\n patient4 ==> clinic1\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication","__idx":3},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All Tidepool Data Platform APIs require a valid access token. The process to acquire an access token is described in greater detail in a separate ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/authentication"},"children":["authentication guide"]},". Note that depending on the origin of the access token, they may be fairly short-lived: you will need to refresh the token once it expires."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You login to your user account which in turn may be member of any number of clinics. Your membership in those clinics grants you access to the clinic data, and any patients of each clinic."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-use-cases","__idx":4},"children":["Common Use Cases"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"identify-current-user","__idx":5},"children":["Identify Current User"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Many API calls require your Tidepool user ID as part of the URL. This is ether a 10-digit hexadecimal number (legacy) or an UUID (new) that uniquely identifies the user within Tidepool. It is an immutable value that never changes even if your email address changes. You can retrieve it along with the rest of your user account metadata with this API:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -X GET -H \"X-Tidepool-Session-Token: {access_token}\" \"https://app.tidepool.org/auth/user\"\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You will need the user ID (the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userid"]}," field) of the account:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"emailVerified\": true,\n \"emails\": [\n \"demo+drseastar@tidepool.org\"\n ],\n \"roles\": [\n \"clinician\",\n \"default-roles-tidepool\"\n ],\n \"termsAccepted\": \"2017-04-25T22:34:30+00:00\",\n \"userid\": \"cbd70cabd8\",\n \"username\": \"demo+drseastar@tidepool.org\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"enumerate-clinics","__idx":6},"children":["Enumerate Clinics"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As mentioned above, a member can belong to any number of clinics. You can enumerate the list of clinics. By default, this API returns the first 10 clinics. If the clinic list is longer, you'll need to use the optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offset"]}," and/or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]}," parameters."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -X GET -H \"X-Tidepool-Session-Token: {access_token}\" \"https://app.tidepool.org/v1/clinicians/{userId}/clinics?offset={start}&limit={limit}\"\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You will need the clinic ID (the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," field) for a given clinic to fetch more data about that clinic's members or patients."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"[\n {\n \"clinic\": {\n \"address\": \"123 Milly Mole Lane\",\n \"canMigrate\": false,\n \"city\": \"Palo Alto\",\n \"clinicType\": \"provider_practice\",\n \"country\": \"US\",\n \"createdTime\": \"2024-11-29T13:28:58.561Z\",\n \"id\": \"6749c19a2169780db2894303\",\n \"name\": \"Seastar Pediatric Endocrinology\",\n \"postalCode\": \"94301\",\n \"preferredBgUnits\": \"mg/dL\",\n \"shareCode\": \"JDZY-KS2F-AR8T\",\n \"state\": \"CA\",\n \"tier\": \"tier0100\",\n \"tierDescription\": \"Free\",\n \"updatedTime\": \"2024-11-29T15:00:26.913Z\",\n \"website\": \"\"\n },\n \"clinician\": {\n \"createdTime\": \"2024-11-29T14:55:28.498Z\",\n \"email\": \"demo+drseastar@tidepool.org\",\n \"id\": \"cbd70cabd8\",\n \"name\": \"Sally Seastar\",\n \"roles\": [\n \"CLINIC_ADMIN\"\n ],\n \"updatedTime\": \"2024-11-29T14:59:22.027Z\"\n }\n },\n {\n \"clinic\": {\n \"address\": \"123 Milly Mole Lane\",\n \"canMigrate\": false,\n \"city\": \"Blacksburg\",\n \"clinicSize\": \"250-499\",\n \"clinicType\": \"provider_practice\",\n \"country\": \"US\",\n \"createdTime\": \"2022-01-06T17:54:03Z\",\n \"id\": \"61d72cbb4faea5d2c9b608c2\",\n \"name\": \"Seastar Endocrinology\",\n \"patientTags\": [\n {\n \"id\": \"635c1d0b776e61e410de6346\",\n \"name\": \"Pregnant\"\n },\n {\n \"id\": \"635c1d1a8ddfbdd65bb73f14\",\n \"name\": \"CGM Start\"\n },\n {\n \"id\": \"635c1d388ddfbdd65bb73f15\",\n \"name\": \"Type 2\"\n },\n {\n \"id\": \"635c1e64776e61e410de634b\",\n \"name\": \"Type 1\"\n },\n {\n \"id\": \"63865e2f776e61e410de78c1\",\n \"name\": \"College\"\n },\n {\n \"id\": \"638fa5048ddfbdd65bb758aa\",\n \"name\": \"Extra Care\"\n },\n {\n \"id\": \"640b40127623a9bf2d179d85\",\n \"name\": \"Dr Seastar\"\n },\n {\n \"id\": \"640b40177623a9bf2d179d86\",\n \"name\": \"Dr Quinn\"\n },\n {\n \"id\": \"640b40387623a9bf2d179d87\",\n \"name\": \"Dr Seuss\"\n },\n ],\n \"postalCode\": \"24061\",\n \"preferredBgUnits\": \"mg/dL\",\n \"shareCode\": \"A45F-F8JJ-CS6S\",\n \"state\": \"VA\",\n \"suppressedNotifications\": {},\n \"tier\": \"tier0300\",\n \"tierDescription\": \"Premium\",\n \"updatedTime\": \"2025-02-18T21:03:49.923Z\",\n \"website\": \"https://tidepool.org\"\n },\n \"clinician\": {\n \"createdTime\": \"2022-01-06T17:54:03.242Z\",\n \"email\": \"demo+drseastar@tidepool.org\",\n \"id\": \"cbd70cabd8\",\n \"name\": \"Dr. Sally Seastar\",\n \"roles\": [\n \"CLINIC_ADMIN\"\n ],\n \"updatedTime\": \"2022-01-06T17:54:03.242Z\"\n }\n }\n]\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"enumerate-clinic-staff-members","__idx":7},"children":["Enumerate Clinic Staff Members"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have a clinic ID, you can fetch the list of members (administrators, clinicians) of that clinic:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -X GET -H \"X-Tidepool-Session-Token: {access_token}\" \"https://app.tidepool.org/v1/clinics/{clinicId}?offset={start}&limit={limit}\"\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"[\n {\n \"createdTime\": \"2023-05-04T13:17:43.862Z\",\n \"email\": \"demo+yertle@tidepool.org\",\n \"id\": \"674703f4-eb4b-407f-9120-8564ae2b652b\",\n \"name\": \"Yertle Turtle\",\n \"roles\": [\n \"CLINIC_MEMBER\"\n ],\n \"updatedTime\": \"2023-05-04T13:19:58.604Z\"\n },\n {\n \"createdTime\": \"2022-02-14T19:26:37.144Z\",\n \"email\": \"demo+drseastar@tidepool.org\",\n \"id\": \"cbd70cabd8\",\n \"name\": \"Sally Seastar\",\n \"roles\": [\n \"CLINIC_ADMIN\"\n ],\n \"updatedTime\": \"2022-02-14T19:26:47.983Z\"\n },\n {\n \"createdTime\": \"2022-02-14T19:23:11.861Z\",\n \"email\": \"demo+drseuss@tidepool.org\",\n \"id\": \"eaeebec366\",\n \"name\": \"Dr. Seuss\",\n \"roles\": [\n \"CLINIC_ADMIN\"\n ],\n \"updatedTime\": \"2022-02-14T19:23:11.861Z\"\n }\n]\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"enumerate-patients","__idx":8},"children":["Enumerate Patients"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can enumerate the patient list of a clinic. This API also allows you to sort the resulting list by many different fields. The API reference documentation contains full details of all allowed parameter values."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -X GET -H \"X-Tidepool-Session-Token: {access_token}\" \"https://app.tidepool.org/v1/clinics/{clinicId}/patients?offset={start}&limit={limit}\"\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The resulting patient list may be quite large due to the inclusion of summary data fields for each patient (depends on the clinic's tier). You'll need the patient user ID (the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," field) to fetch data for that patient, or make changes to their patient record."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"data\": [\n {\n \"birthDate\": \"1984-08-24\",\n \"createdTime\": \"2022-06-15T18:59:55.773Z\",\n \"dataSources\": null,\n \"email\": \"demo+james@tidepool.org\",\n \"fullName\": \"James Jellyfish\",\n \"id\": \"d02b85e6b3\",\n \"mrn\": \"12345\",\n \"permissions\": {\n \"note\": {},\n \"upload\": {},\n \"view\": {}\n },\n \"reviews\": [],\n \"summary\": {\n \"bgmStats\": {\n \"config\": {\n \"highGlucoseThreshold\": 10,\n \"lowGlucoseThreshold\": 3.9,\n \"schemaVersion\": 4,\n \"veryHighGlucoseThreshold\": 13.9,\n \"veryLowGlucoseThreshold\": 3\n },\n \"dates\": {\n \"firstData\": \"2024-12-11T15:00:00Z\",\n \"hasFirstData\": true,\n \"hasLastData\": true,\n \"hasLastUploadDate\": true,\n \"hasOutdatedSince\": false,\n \"lastData\": \"2025-02-09T14:41:08Z\",\n \"lastUpdatedDate\": \"2025-02-11T17:26:59.49Z\",\n \"lastUpdatedReason\": [\n \"LEGACY_DATA_ADDED\"\n ],\n \"lastUploadDate\": \"2025-02-11T17:25:13.555Z\"\n },\n \"offsetPeriods\": {\n \"14d\": {\n \"averageDailyRecords\": 0.7142857142857143,\n \"averageDailyRecordsDelta\": 0.6428571428571429,\n \"averageGlucoseMmol\": 9.902534416025231,\n \"averageGlucoseMmolDelta\": 6.738608061129277,\n \"hasAverageDailyRecords\": true,\n \"hasAverageGlucoseMmol\": true,\n \"hasTimeInAnyHighPercent\": true,\n \"hasTimeInAnyHighRecords\": true,\n \"hasTimeInAnyLowPercent\": true,\n \"hasTimeInAnyLowRecords\": true,\n \"hasTimeInExtremeHighPercent\": true,\n \"hasTimeInExtremeHighRecords\": true,\n \"hasTimeInHighPercent\": true,\n \"hasTimeInHighRecords\": true,\n \"hasTimeInLowPercent\": true,\n \"hasTimeInLowRecords\": true,\n \"hasTimeInTargetPercent\": true,\n \"hasTimeInTargetRecords\": true,\n \"hasTimeInVeryHighPercent\": true,\n \"hasTimeInVeryHighRecords\": true,\n \"hasTimeInVeryLowPercent\": true,\n \"hasTimeInVeryLowRecords\": true,\n \"hasTotalRecords\": true,\n \"timeInAnyHighPercent\": 0.2,\n \"timeInAnyHighPercentDelta\": 0.2,\n \"timeInAnyHighRecords\": 2,\n \"timeInAnyHighRecordsDelta\": 2,\n \"timeInAnyLowPercent\": 0,\n \"timeInAnyLowPercentDelta\": -1,\n \"timeInAnyLowRecords\": 0,\n \"timeInAnyLowRecordsDelta\": -1,\n \"timeInExtremeHighPercent\": 0,\n \"timeInExtremeHighPercentDelta\": -0,\n \"timeInExtremeHighRecords\": 0,\n \"timeInExtremeHighRecordsDelta\": 0,\n \"timeInHighPercent\": 0.2,\n \"timeInHighPercentDelta\": 0.2,\n \"timeInHighRecords\": 2,\n \"timeInHighRecordsDelta\": 2,\n \"timeInLowPercent\": 0,\n \"timeInLowPercentDelta\": -1,\n \"timeInLowRecords\": 0,\n \"timeInLowRecordsDelta\": -1,\n \"timeInTargetPercent\": 0.8,\n \"timeInTargetPercentDelta\": 0.8,\n \"timeInTargetRecords\": 8,\n \"timeInTargetRecordsDelta\": 8,\n \"timeInVeryHighPercent\": 0,\n \"timeInVeryHighPercentDelta\": -0,\n \"timeInVeryHighRecords\": 0,\n \"timeInVeryHighRecordsDelta\": 0,\n \"timeInVeryLowPercent\": 0,\n \"timeInVeryLowPercentDelta\": -0,\n \"timeInVeryLowRecords\": 0,\n \"timeInVeryLowRecordsDelta\": 0,\n \"totalRecords\": 10,\n \"totalRecordsDelta\": 9\n },\n \"1d\": {\n // omitted for brevity\n },\n \"30d\": {\n // omitted for brevity\n },\n \"7d\": {\n // omitted for brevity\n }\n },\n \"periods\": {\n \"14d\": {\n // omitted for brevity\n },\n \"1d\": {\n // omitted for brevity\n },\n \"30d\": {\n // omitted for brevity\n },\n \"7d\": {\n // omitted for brevity\n }\n },\n \"totalHours\": 1440\n },\n \"cgmStats\": {\n \"config\": {\n \"highGlucoseThreshold\": 10,\n \"lowGlucoseThreshold\": 3.9,\n \"schemaVersion\": 4,\n \"veryHighGlucoseThreshold\": 13.9,\n \"veryLowGlucoseThreshold\": 3\n },\n \"dates\": {\n \"firstData\": \"2024-12-13T18:00:00Z\",\n \"hasFirstData\": true,\n \"hasLastData\": true,\n \"hasLastUploadDate\": true,\n \"hasOutdatedSince\": false,\n \"lastData\": \"2025-02-11T17:21:15Z\",\n \"lastUpdatedDate\": \"2025-02-11T17:27:27.308Z\",\n \"lastUpdatedReason\": [\n \"LEGACY_DATA_ADDED\",\n \"LEGACY_UPLOAD_COMPLETED\"\n ],\n \"lastUploadDate\": \"2025-02-11T17:26:20.073Z\"\n },\n \"offsetPeriods\": {\n \"14d\": {\n // omitted for brevity\n },\n \"1d\": {\n // omitted for brevity\n },\n \"30d\": {\n // omitted for brevity\n },\n \"7d\": {\n // omitted for brevity\n }\n },\n \"periods\": {\n \"14d\": {\n // omitted for brevity\n },\n \"1d\": {\n // omitted for brevity\n },\n \"30d\": {\n // omitted for brevity\n },\n \"7d\": {\n // omitted for brevity\n }\n },\n \"totalHours\": 1440\n }\n },\n \"tags\": null,\n \"targetDevices\": [\n \"onetouchverioiq\",\n \"tandem\"\n ],\n \"updatedTime\": \"2024-01-10T13:17:39.198Z\"\n },\n {\n \"birthDate\": \"1993-04-19\",\n \"createdTime\": \"2023-04-13T17:18:46.768Z\",\n \"dataSources\": null,\n \"email\": \"demo+jessica@tidepool.org\",\n \"fullName\": \"Jessica Jellyfish\",\n \"id\": \"7d7c8c54-640d-4316-a713-0690851af67e\",\n \"mrn\": \"44951\",\n \"permissions\": {\n \"custodian\": {},\n \"note\": {},\n \"upload\": {},\n \"view\": {}\n },\n \"reviews\": [],\n \"summary\": {\n \"bgmStats\": {\n \"config\": {\n \"highGlucoseThreshold\": 10,\n \"lowGlucoseThreshold\": 3.9,\n \"schemaVersion\": 4,\n \"veryHighGlucoseThreshold\": 13.9,\n \"veryLowGlucoseThreshold\": 3\n },\n \"dates\": {\n \"firstData\": \"2023-08-21T20:00:00Z\",\n \"hasFirstData\": true,\n \"hasLastData\": true,\n \"hasLastUploadDate\": true,\n \"hasOutdatedSince\": false,\n \"lastData\": \"2023-10-19T13:43:05Z\",\n \"lastUpdatedDate\": \"2024-07-19T07:23:27.301Z\",\n \"lastUpdatedReason\": [\n \"SCHEMA_MIGRATION\"\n ],\n \"lastUploadDate\": \"2023-10-23T14:28:08.107Z\"\n },\n \"offsetPeriods\": {\n \"14d\": {\n // omitted for brevity\n },\n \"1d\": {\n // omitted for brevity\n },\n \"30d\": {\n // omitted for brevity\n },\n \"7d\": {\n // omitted for brevity\n }\n },\n \"periods\": {\n \"14d\": {\n // omitted for brevity\n },\n \"1d\": {\n // omitted for brevity\n },\n \"30d\": {\n // omitted for brevity\n },\n \"7d\": {\n // omitted for brevity\n }\n },\n \"totalHours\": 1410\n }\n },\n \"tags\": null,\n \"targetDevices\": [\n \"onetouchverioiq\"\n ],\n \"updatedTime\": \"2023-10-23T14:18:15.829Z\"\n },\n ],\n \"meta\": {\n \"count\": 2\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"search-for-a-patient","__idx":9},"children":["Search for a Patient"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API for searching for patients is the same as for enumerating patients, with the addition of a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]}," parameter. It allows you to search the patient list for a match with a fuzzy search term that matches names, emails, or medical record numbers (MRNs)."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -X GET -H \"X-Tidepool-Session-Token: {access_token}\" \"https://app.tidepool.org/v1/clinics/{clinicId}/patients?offset={start}&limit={limit}&search={search_term}\"\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The resulting patient list has the same format as the previous example, omitted here for brevity."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"fetch-patient-record","__idx":10},"children":["Fetch Patient Record"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you know the user ID of a patient, you can fetch their patient record directly."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -X GET -H \"X-Tidepool-Session-Token: {access_token}\" \"https://app.tidepool.org/v1/clinics/{clinicId}/patients/{patientUserId}\"\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The resulting patient record has the same format as one element of the data array in the previous examples, omitted here for brevity."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"fetch-patient-data","__idx":11},"children":["Fetch Patient Data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can fetch the individual diabetes data points for any given patient by invoking the data API. The start and end dates are ISO8601 formatted dates, and the data type list is a comma-separated list of data types you want to fetch. The full list of data types can be found in:"]},{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"$ref":"../reference/data/models/datatype.v1.yaml"},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"$ref":"#/components/schemas/datatype.v1"},"datatype.v1":{"title":"Tidepool Data Type","description":"Data type","type":"string","enum":["alert","basal","bloodKetone","bolus","cbg","cgmSettings","controllerSettings","controllerStatus","deviceEvent","deviceStatus","dosingDecision","food","insulin","physicalActivity","pumpSettings","pumpStatus","reportedState","smbg","upload","water","wizard"],"example":"upload","x-tags":["Data"]}}}},"schemaResolvedErrors":[]},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -X GET -H \"X-Tidepool-Session-Token: {access_token}\" \"https://app.tidepool.org/data/{userId}?startDate={startDate}&endDate={endDate}&type={dataTypesList}\"\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is only a short example of the response. The API reference documentation contains full details of each data type."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"[\n {\n \"_deduplicator\": {\n \"hash\": \"/4YSyroSK6Qa/nrvaBV7OZyAhoAPpGcnfHCyZD40mco=\"\n },\n \"deviceId\": \"Tidepool Testing Meter\",\n \"id\": \"4aedcd3b5c3a2569bbd71e5c7905766c\",\n \"revision\": 1,\n \"time\": \"2023-02-27T14:45:32Z\",\n \"type\": \"smbg\",\n \"units\": \"mmol/L\",\n \"uploadId\": \"704de0e907136fc152cde36c495b06f4\",\n \"value\": 12.49991\n },\n {\n \"_deduplicator\": {\n \"hash\": \"aWfjiZE4Nmt7Mtk8N3Matkd3qJecRjiwvzPHiTQx/eY=\"\n },\n \"deviceId\": \"Tidepool Testing Meter\",\n \"id\": \"a43183fafd474677015acb7a0f3ca07e\",\n \"revision\": 1,\n \"time\": \"2023-02-27T09:18:32Z\",\n \"type\": \"smbg\",\n \"units\": \"mmol/L\",\n \"uploadId\": \"704de0e907136fc152cde36c495b06f4\",\n \"value\": 14.32278\n },\n {\n \"_deduplicator\": {\n \"hash\": \"t52k0mUvH+02WsrG80K3rHImlhx16ViWFgdbeKFqucQ=\"\n },\n \"deviceId\": \"Tidepool Testing Meter\",\n \"id\": \"7a3f16e5d073b21e0cf5ab6198910967\",\n \"revision\": 1,\n \"time\": \"2023-02-27T04:50:32Z\",\n \"type\": \"smbg\",\n \"units\": \"mmol/L\",\n \"uploadId\": \"704de0e907136fc152cde36c495b06f4\",\n \"value\": 15.9436\n },\n]\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"update-patient-record","__idx":12},"children":["Update Patient Record"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can update a patient record by making a PUT request (rather than a GET) on the patient. Note however:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Only some fields such as name, birth date, email, or MRN may be updated. Others are read-only."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The update may fail if the field values violate validation rules."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -X PUT -H \"X-Tidepool-Session-Token: {access_token}\" -H \"Content-Type: application/json\" -d '{patient_record}' \"https://app.tidepool.org/v1/clinics/{clinicId}/patients/{patientUserId}\"\n","lang":"shell"},"children":[]}]},"headings":[{"value":"Clinic Integration Guide","id":"clinic-integration-guide","depth":1},{"value":"Introduction","id":"introduction","depth":2},{"value":"Clinic Data Model","id":"clinic-data-model","depth":3},{"value":"Authentication","id":"authentication","depth":2},{"value":"Common Use Cases","id":"common-use-cases","depth":2},{"value":"Identify Current User","id":"identify-current-user","depth":3},{"value":"Enumerate Clinics","id":"enumerate-clinics","depth":3},{"value":"Enumerate Clinic Staff Members","id":"enumerate-clinic-staff-members","depth":3},{"value":"Enumerate Patients","id":"enumerate-patients","depth":3},{"value":"Search for a Patient","id":"search-for-a-patient","depth":3},{"value":"Fetch Patient Record","id":"fetch-patient-record","depth":3},{"value":"Fetch Patient Data","id":"fetch-patient-data","depth":3},{"value":"Update Patient Record","id":"update-patient-record","depth":3}],"frontmatter":{"seo":{"title":"Clinic Integration Guide"}},"lastModified":"2025-07-25T15:19:47.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/clinic-integration","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}