Zus Health

https://docs.zushealth.com/docs/
Admin
Zus Health is a platform that aggregates, normalizes, and enriches patient health data from various...
Tokens:77,818
Snippets:312
Trust Score:8.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Example GraphQL Queries

Source: https://docs.zushealth.com/docs/graphql-api

Examples of common GraphQL queries for retrieving patient data.

```APIDOC
## GraphQL Query Examples

### Get a single Patient by FHIR ID

This query retrieves the ID, first name, and last name of a patient given their FHIR ID.

```json
query {
  Patient (id: $id) {
    id
    name {
      family
      given
    }
  }
}
```

### Get detailed Patient information by FHIR ID

This query retrieves comprehensive details about a patient, including address, contact information, and more, given their FHIR ID.

```text
query {
	Patient(id: $id) {
    address {
    	city
    	country
    	district
    	line
    	period {
        	start
        	end
    	}
    	postalCode
    	state
    	text
    	type
    	use
    }
    birthDate
    contact {
    	relationship {
        coding {
        code
       }
    }
    telecom {
        system
        use
        value
    }
    }
    deceasedBoolean
    deceasedDateTime
    gender
    id
    identifier {
    	system
    	value
    }
    maritalStatus {
    	coding {
        code
    	}
    	text
    	}
    managingOrganization {
    	reference
    	display
    	}
    name {
    	family
    	given
    	period {
        start
        end
    	}
    	prefix
    	suffix
    	text
    	use
    }
	}
}
```

### Search for Conditions associated with a UPID

This query retrieves a list of conditions associated with a given Universal Patient Identifier (UPID). It returns the condition ID and the last updated timestamp for each.

```json
query {
  ConditionList (upid: $upid) {
    id
    meta { lastUpdated }
  }
}
```
```

--------------------------------

### Paginating through Results (Example)

Source: https://docs.zushealth.com/docs/graphql-api

Example of how to paginate through a large number of results using the Connection query type with `first` and `after` parameters.

```APIDOC
#### Paginating through results

If you need to paginate through a large number of results, use the Connection query type.

```json
query {
  ConditionConnection (
    upid: $upid,
    first: 100,
    after: "",
    filter: { clinicalStatus: { anymatch: "active" } }
)
 {
    pageInfo {
      hasNextPage
    }
    edges {
      node {
        id
        meta { lastUpdated }
      }
      cursor
    }
  }
}

```

The response includes a value for the cursor. To get the next page of results, provide the after parameter using the last cursor in the last page.

```json
query MedicationRequest {
  MedicationRequestConnection(
    upid: "4ed64962-9c8f-4712-9484-db6f85174817"
    after: "f789c7f7-f706-4119-98ff-c23c578c10f1"
  ) {
    edges {
      node {
        id
        meta {
          tag {
            system
            code
          }
        }
      }
      cursor
    }
    pageInfo {
      hasNextPage
    }
  }
}

```

We currently have a partial implementation of the [GraphQL Cursor Connections Specification](https://relay.dev/graphql/connections.htm). Forward pagination (with first and after) is supported, but reverse pagination (with last and before) has not been implemented.
```

--------------------------------

### Example Practitioner User Upsert API Request Body (JSON)

Source: https://docs.zushealth.com/docs/creating-users

An example of a complete request body for the Practitioner User Upsert API. This demonstrates the full structure including FHIR Practitioner details and auth service user information, with a specific identifier system and user type.

```json
{
    "data": {
        "attributes": {
            "practitionerIdentifierSystem": "http://hospital.smarthealthit.org",
            "practitioner": {
                "resourceType": "Practitioner",
                "text": {
                    "status": "generated",
                    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">
      <p>Dr Adam Careful is a Referring Practitioner for Acme Hospital from 1-Jan 2012 to 31-Mar
        2012</p>
    </div>"
                },
                "identifier": [
                    {
                        "use": "official",
                        "system": "http://hospital.smarthealthit.org",
                        "value": "991032702992299"
                    }
                ],
                "active": true,
                "name": [
                    {
                        "family": "Flubegone",
                        "given": [
                            "Debra"
                        ],
                        "prefix": [
                            "Dr"
                        ]
                    }
                ],
                "address": [
                    {
                        "use": "home",
                        "line": [
                            "534 Erewhon St"
                        ],
                        "city": "PleasantVille",
                        "state": "Vic",
                        "postalCode": "3999"
                    }
                ],
                "qualification": [
                    {
                        "identifier": [
                            {
                                "system": "http://example.org/UniversityIdentifier",
                                "value": "12345"
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v2-0360/2.7",
                                    "code": "BS",
                                    "display": "Bachelor of Science"
                                }
                            ],
                            "text": "Bachelor of Science"
                        },
                        "period": {
                            "start": "1995"
                        },
                        "issuer": {
                            "display": "Example University"
                        }
                    }
                ]
            },
            "user": {
                "data": {
                    "type": "auth/users",
                    "attributes": {
                        "email": "debra.flubegone@primarycare.com",
                        "name": "Debra Flubegone M.D.",
                        "userType": "builder",
                        "sendPasswordResetEmail": false
                    },
                    "relationships": {
                        "auth/roles": {
                            "data": {
                                "type": "auth/roles",
                                "id": "{{RoleID}}"
                            }
                        }
                    }
                }
            }
        }
    }
}
```

--------------------------------

### FHIR Encounter Resource Example

Source: https://docs.zushealth.com/docs/adt-networks

This snippet demonstrates a typical FHIR Encounter resource, including patient information, service type, participant details, and diagnosis.

```json
{
    "resourceType": "Encounter",
    "identifier": [
        {
            "type": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                        "code": "VN",
                        "display": "visit number"
                    }
                ],
                "text": "visit number"
            },
            "value": "123456789"
        }
    ],
    "status": "finished",
    "class": {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
        "code": "I",
        "display": "Inpatient"
    },
    "serviceType": {
        "coding": [
            {
                "code": "285",
                "display": "General Medicine"
            }
        ],
        "text": "General Medicine"
    },
    "subject": {
      		"reference": "Patient/09c4d173-1af1-4668-a16f-401d94bb0eb5",
      		"type": "Patient",
      		"display": "John Doe"
    },
    "participant": [
        {
            "type": [
                {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
                            "code": "ATND",
                            "display": "attender"
                        }
                    ]
                }
            ],
            "individual": {
                "reference": "Practitioner/85fe2ec9-be0a-4329-ad13-6acfe0e27849",
                "type": "Practitioner",
              	"display": "Patrick Adams"
            }
        }
    ],
    "period": {
        "start": "2022-11-11T15:45:00.000Z"
    },
    "diagnosis": [
    {
        "condition": {
            "reference": "Condition/287c9d74-a7d3-9s82-90b6-h8732k73b07f",
            "type": "Condition",
            "display": "Celiac Disease"
        },
        "use": {
            "coding": [
                {
                    "system": "https://terminology.hl7.org/5.2.0/CodeSystem-v2-0052.html",
                    "code": "D",
                    "display": "Discharge"
                }
            ]
        },
        "rank": 1
    },
      {
        "condition": {
            "reference": "Condition/7616e37e-e284-4287-b32f-03dbd0f0792",
            "type": "Condition",
            "display": "Unspecified Abdominal Pain"
        },
        "use": {
            "coding": [
                {
                    "system": "https://terminology.hl7.org/5.2.0/CodeSystem-v2-0052.html",
                    "code": "A",
                    "display": "Admitting"
                }
            ]
        },
        "rank": 2
    }
],
    "location": [
        {
            "location": {
                "reference": "Location/2fb8fb58-93b6-4429-99e9-4cfaa370c22c",
                "type": "Location",
          		"display": "Community Medical Center"
            }
        }
    ]
}
```

--------------------------------

### Example API Response for Upload

Source: https://docs.zushealth.com/docs/ingesting-documents

This is an example of a successful API response when a PDF document is uploaded. It confirms the upload and provides a unique ID for the job, along with the associated patient ID and document media type.

```json
{
    "data": {
        "type": "data-transformer/upload",
        "id": "XXXXXXX3-2XXXXXf-4XXXX",
        "attributes": {
            "patientID": "cXXXXX-XXXXXX-XXXX-XXXXX",
            "documentMediaType": "application/xml"
        }
    }
}
```

--------------------------------

### GraphQL API Authentication Example

Source: https://docs.zushealth.com/docs/graphql-api

This example demonstrates how to authenticate requests to the Zus FHIR GraphQL API using a bearer token. It specifies the POST method, endpoint, authorization header, and content type required for API calls.

```plaintext
POST fqs.zusapi.com/query
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Content-Type: application/json
```

--------------------------------

### Postman Authentication Setup

Source: https://docs.zushealth.com/docs/authentication

Instructions for configuring OAuth 2.0 (Authorization Code with PKCE) in Postman to obtain an access token for the Zus API.

```APIDOC
## Postman Authentication Setup

### Description
Configure your access token in Postman for Authorization Code with PKCE (Proof Key for Code Exchange) using the values below. Because you are using PKCE, you will not need a client secret.

### Method
POST (Implicit in Postman UI)

### Endpoint
N/A (UI Configuration)

### Parameters
#### Postman OAuth 2.0 Settings
- **Grant Type** (string) - Required - Authorization Code (With PKCE)
- **Callback URL** (string) - Required - `<https://www.getpostman.com/oauth2/callback`>
- **Auth URL** (string) - Required - `<https://auth.sandbox.zusapi.com/authorize?audience=https://api.sandbox.zusapi.com`>
- **Access Token URL** (string) - Required - `<https://auth.sandbox.zusapi.com/oauth/token`>
- **Client ID** (string) - Required - `<provided by Zus, already included in Postman collection>`
- **Code Challenge Method** (string) - Required - `SHA-256`
- **Scope** (string) - Required - `openid profile email`
- **State** (string) - Required - `<create a random alphanumeric value of 8-12 characters>`
- **Client Authentication** (string) - Required - `Send client credentials in body`

### Request Example
N/A (UI Configuration)

### Response
#### Success Response
Access Token (stored within Postman)

#### Response Example
N/A (Token is managed by Postman)
```

--------------------------------

### FHIR Practitioner Resource ID Example

Source: https://docs.zushealth.com/docs/setting-up-users

This snippet shows an example of a FHIR Practitioner resource ID embedded within a larger JSON structure. The ID is specifically noted as originating from a Practitioner resource upsert operation, implying its use in data management within a FHIR context. No external dependencies are noted.

```json
{
    "data": {
        "type": "fhir/practitioner",
        "id": "19c21c89-c0c4-49d6-9aa3-f88228d3a9f4" 
    }
}
```

--------------------------------

### Python Example for Token Exchange and API Request

Source: https://docs.zushealth.com/docs/user-authentication

Illustrates how to perform token exchange and make an authenticated API request using Python.

```APIDOC
## Python Example

### Description
This example demonstrates how to obtain a Zus access token by exchanging an ID token and then use that access token to make an authenticated request to a Zus API endpoint.

### Code Snippet
```python
import requests
import json

# --- Token Exchange ---
token_endpoint = "https://api.sandbox.zusapi.com/auth/token"
headers = {
    'Content-Type': 'application/json',
}
body = {
    "grant_type":               "urn:ietf:params:oauth:grant-type:token-exchange", 
    "audience":                 "https://api.sandbox.zusapi.com",
    "requested_token_type":     "urn:ietf:params:oauth:token-type:access_token",
    "subject_token":            id_token, # The token returned by your IDP at login
    "subject_token_type":       "urn:ietf:params:oauth:token-type:id_token", 
}

json_body = json.dumps(body) # Force Python to use Json format
zus_response = requests.post(token_endpoint, data=json_body, headers=headers)
try:
    access_token = zus_response.json()['access_token']
    print("Successfully obtained access token:", access_token)
except Exception as e:
    print("Error during token exchange: ", zus_response.json(), e)
    access_token = None

# --- Make a Zus API Request (if token exchange was successful) ---
if access_token:
    api_url = "https://api.sandbox.zusapi.com/fhir/Patient?_count=500&_total=accurate&_offset=0"
    api_headers = {
        'Authorization': f'Bearer {access_token}',
    }
    try:
        zus_data = requests.get(api_url, headers=api_headers)
        print("Successfully made API request. Response status:", zus_data.status_code)
        # Process zus_data.json() as needed
    except Exception as e:
        print("Error making API request: ", e)
```
```

--------------------------------

### Get Auth Roles

Source: https://docs.zushealth.com/docs/setting-up-users

Retrieve available authentication roles within the organization. This is a prerequisite step to creating a user, as it provides the RoleID required for user creation.

```APIDOC
## GET /auth/roles

### Description
Retrieves a list of authentication roles based on a filter. Used to obtain the RoleID for user creation.

### Method
GET

### Endpoint
https://api.sandbox.zusapi.com/auth/roles?filter[name]={{RoleName}}

### Query Parameters
- **filter[name]** (string) - Required - The name of the role to filter by (e.g., "Builder Admin", "Care Team User").

### Response
#### Success Response (200)
- **data** (array) - An array of role objects.
  - **id** (string) - The unique identifier for the role (RoleID).
  - **attributes** (object) - Attributes of the role.
    - **name** (string) - The name of the role.
    - **createdAt** (integer) - Timestamp of role creation.
    - **updatedAt** (integer) - Timestamp of role update.
    - **isManaged** (boolean) - Indicates if the role is managed.
    - **description** (string) - Description of the role.
    - **permissions** (array) - List of permissions associated with the role.
- **links** (object) - Links for pagination.
  - **self** (string) - Link to the current page.
  - **next** (string) - Link to the next page, if available.
```

--------------------------------

### GET /auth/users

Source: https://docs.zushealth.com/docs/authentication

Example of making a Zus request using a new access token obtained via token exchange.

```APIDOC
## GET /auth/users

### Description
An example of how to make an authenticated request to a Zus API endpoint using an access token obtained from the Token Exchange endpoint. This demonstrates how to include the bearer token in the Authorization header.

### Method
GET

### Endpoint
`https://api.sandbox.zusapi.com/auth/users`

### Parameters
#### Headers
- **Authorization** (string) - Required - `Bearer <Your_Zus_Access_Token>`

### Request Example
```bash
curl -X GET https://api.sandbox.zusapi.com/auth/users \
     -H "Authorization: Bearer <Your_Zus_Access_Token>"
```

### Response
#### Success Response (200)
- **users** (array) - A list of user objects.

#### Response Example
```json
{
  "users": [
    {
      "id": "user-123",
      "email": "user@example.com"
    }
  ]
}
```
```

--------------------------------

### Encounter Lens Resource Example (JSON)

Source: https://docs.zushealth.com/docs/encounter-lens

This is a JSON representation of a mocked Encounter Lens resource. It demonstrates the structure and fields, including standard FHIR elements and Zus-specific extensions. It highlights how `aggregatedFrom` extensions are used to link to other Encounter resources.

```json
{
 "resourceType": "Encounter",
 "id": "7bdd-47fa-accf-6e1f2b855555",


 "class": {
   "system": "https://terminology.hl7.org/2.1.0/ValueSet-v3-ActEncounterCode.html",
   "code": "AMB",
   "display": "ambulatory"
 },
 "status": "finished",
 "subject": {
   "reference": "Patient/8804-4728-95cf-3ab4af655555",
   "type": "Patient"
 },
 "diagnosis": [
   {
     "condition": {
       "reference": "Condition/6a10-4cd0-b377-d2aa13555555"
     }
   }
 ],
 "extension": [
   {
     "extension": [
       {
         "url": "https://zusapi.com/lens/extension/aggregatedFrom",
         "valueReference": {
           "reference": "Encounter/da3f-4b69-9b15-9e3099655555",
           "type": "Encounter"
         }
       },
       {
         "url": "https://zusapi.com/lens/extension/aggregatedFrom",
         "valueReference": {
           "reference": "Encounter/0b43-414e-a925-58b9d1a55555",
           "type": "Encounter"
         }
       },
       {
         "url": "https://zusapi.com/lens/extension/aggregatedFrom",
         "valueReference": {
           "reference": "Encounter/7d22-40e5-a453-5d3a7d055555",
           "type": "Encounter"
         }
       }
     ],
     "url": "https://zusapi.com/lens/extension/aggregatedFrom"
   },
   {
     "url": "https://zusapi.com/lens/id",
     "valueString": "8326-c94e-4fd4-aabe-4fa744655555"
   },
   {
     "url": "https://zusapi.com/fhir/identifier/universal-id",
     "valueString": "7fb1-40ff-8e63-b3f4e0355555"
   }
 ],
 "identifier": [
   {
     "system": "urn:oid:1.2.840.114350.1.13.280.2.7.3.698084.8",
     "value": "1484343255"
   },
   {
     "system": "urn:oid:1.2.840.114350.1.13.280.2.7.3.698084.8",
     "value": "1484345497"
   },
   {
     "system": "urn:oid:1.2.840.114350.1.13.280.2.7.3.698084.8",
     "value": "1484616178"
   }
 ],
 "location": [
   {
     "location": {
       "reference": "Location/5073-74ae-4d80-877d-5c628e055555"
     }
   },
   {
     "location": {
       "reference": "Location/deb-9491-46dc-91f6-46deace55555"
     }
   }
 ],
 "meta": {
   "extension": [
     {
       "url": "https://zusapi.com/stream",
       "valueString": "zus"
     },
     {
       "url": "https://zusapi.com/created-at",
       "valueInstant": "2024-06-25T20:10:17.143+00:00"
     }
   ],
   "versionId": "1",
   "lastUpdated": "2024-06-25T20:10:16.545+00:00",
   "tag": [
     {
       "system": "https://zusapi.com/summary",
       "code": "Common"
     },
     {
       "system": "https://zusapi.com/accesscontrol/owner",
       "code": "builder/bb0b-4543-8489-262fcbf55555"
     }
   ]
 },
 "participant": [
   {
     "individual": {
       "reference": "Practitioner/7-fbf9-44ec-bc65-3b1becf55555"
     }
   },
   {
     "individual": {
       "reference": "Practitioner/ddfe-4be4-8442-1587a1e55555"
     }
   }
 ],
 "period": {
   "start": "2023-11-20T09:51:00-05:00",
   "end": "2023-11-21T16:57:00-05:00"
 }
}
```

--------------------------------

### API Call to Query Patients by UPID

Source: https://docs.zushealth.com/docs/how-the-zap-works

This is an example of an API call to retrieve all patient resources that share a specific Universal Patient Identifier (UPID). It uses a GET request to the FHIR endpoint, filtering by the 'upid' parameter. This is a common method for developers to access aggregated patient data.

```http
https://api.zusapi.com/fhir/Patient?upid={{UPID}}
```

--------------------------------

### Retrieve Users in Auth Service (Zus)

Source: https://docs.zushealth.com/docs/cross-builder-grants

These examples show how to retrieve user information using the Zus Auth Service. You can fetch all users across accessible Builders or filter users by a specific `BuilderID`. Retrieving a list of accessible Builders is also demonstrated.

```http
GET https://api.sandbox.zusapi.com/auth/users
```

```http
GET https://api.sandbox.zusapi.com/auth/users?filter[builderId]={{BuilderID}}
```

```http
GET https://api.sandbox.zusapi.com/auth/builders
```

--------------------------------

### Viewing Generated Resources in FHIRPlace

Source: https://docs.zushealth.com/docs/ingesting-documents

Instructions on how to filter by patient UPID in FHIRplace, navigate to the Binary resource type, and view associated Binary documents. It also guides users to the Provenance History tab to see resources created from submitted documents.

```APIDOC
## Viewing Generated Resources in FHIRPlace

To view generated resources in FHIRPlace:

1. Set FHIRplace to filter on your patient's UPID.
2. Navigate to the **Binary** resource type in the left-hand pane.
3. View the Binary documents associated with the patient and select the binary corresponding to the submitted document (likely the most recent).
4. To view the resources created from your submitted document, navigate to the **Provenance History** tab.

If the FHIR data you expect does not appear, contact the Support team.
```

--------------------------------

### Query Patient Encounter Summary Lens Resources

Source: https://docs.zushealth.com/docs/encounter-lens

This example demonstrates how to query for a patient's Encounter Summary Lens resources using FHIR. It filters by the 'Common' tag and a patient's universal ID.

```fhir
{{fhir_url}}/Encounter?_tag=<https://zusapi.com/summary|Common&patient.identifier=https://zusapi.com/fhir/identifier/universal-id|{{universal_patient_id}}>
```

--------------------------------

### Get Authentication Roles

Source: https://docs.zushealth.com/docs/creating-users

Retrieve available authentication roles within the organization. This is a prerequisite step to assigning a role when creating a new user.

```APIDOC
## GET /auth/roles

### Description
Retrieves a list of available authentication roles. This endpoint is used to find the RoleID required for creating a new user.

### Method
GET

### Endpoint
`https://api.sandbox.zusapi.com/auth/roles`

### Parameters
#### Query Parameters
- **filter[name]** (string) - Required - Filters roles by name (e.g., 'Builder Admin', 'Care Team User').

### Response
#### Success Response (200)
- **data** (array) - An array of role objects.
  - **type** (string) - The type of the role resource.
  - **id** (string) - The unique identifier for the role.
  - **attributes** (object) - Attributes of the role.
    - **createdAt** (integer) - Timestamp of role creation.
    - **description** (string) - Description of the role.
    - **isManaged** (boolean) - Indicates if the role is managed by the system.
    - **name** (string) - The name of the role.
    - **permissions** (array) - List of permissions associated with the role.
    - **updatedAt** (integer) - Timestamp of last role update.
- **links** (object) - Pagination links.
  - **next** (string) - Link to the next page of results.
  - **self** (string) - Link to the current page of results.

#### Response Example
```json
{
    "data": [
        {
            "type": "auth/roles",
            "id": "<UUID>", 
            "attributes": {
                "createdAt": 1638828368,
                "description": "",
                "isManaged": true,
                "name": "Care Team User",
                "permissions": [
                    ....
                ],
                "updatedAt": 1655996421
            }
        }
    ],
    "links": {
        "next": "https://api.sandbox.zusapi.com/auth/roles?filter[name]=Care%20Team%20User&page[count]=50&page[offset]=50",
        "self": "https://api.sandbox.zusapi.com/auth/roles?filter[name]=Care%20Team%20User&page[count]=50&page[offset]=0"
    }
}
```
```

--------------------------------

### Example Raw Codeable Concept JSON

Source: https://docs.zushealth.com/docs/data-enrichment

This JSON snippet demonstrates the structure of a raw codeable concept before any Zus enrichment, showing a single coding entry with a system and code.

```json
{
  "code": {
    "coding": [
      {
        "system": "urn:oid:2.16.840.1.113883.6.104",
        "code": "401.9",
        "display": "- HTN 401.9"
      }
    ]
  }
}
```

--------------------------------

### FHIR EpisodeOfCare Resource Example

Source: https://docs.zushealth.com/docs/transition-of-care-lens

This snippet demonstrates a minimal FHIR EpisodeOfCare resource. It includes the resource type and a status field. This can be used as a template for creating new EpisodeOfCare resources within the Zus Health platform.

```json
{
    "resourceType": "EpisodeOfCare",
    "status": "finished"
}
```

--------------------------------

### API Call to View Condition with Enrichments

Source: https://docs.zushealth.com/docs/data-enrichment

This example shows a standard GET API request to a FHIR server to retrieve a Condition resource, including any associated enrichments applied by Zus.

```http
GET {{fhir_url}}/Condition?_id=[unique condition id]
```

--------------------------------

### Python Zus API Request Example

Source: https://docs.zushealth.com/docs/user-authentication

This Python code snippet shows how to make an authenticated GET request to the Zus API after obtaining an access token. It includes the access token in the Authorization header.

```python
import requests

api_url = "https://api.sandbox.zusapi.com/fhir/Patient?_count=500&_total=accurate&_offset=0"
headers = {
    'Authorization': f'Bearer {access_token}',
}
zus_data = requests.get(api_url, headers=headers)

```

--------------------------------

### GraphQL Query Syntax Overview

Source: https://docs.zushealth.com/docs/graphql-api

This section outlines the general syntax for constructing GraphQL queries, including the structure of the POST body and query content.

```APIDOC
## GraphQL Query Syntax Overview

The POST body is passed as a JSON string:

```json
{
    "query": "<queryContent>",
    "variables": {
        "variable1": "value1"
    }
}
```

`<queryContent>` is a GraphQL query string:

```graphql
query <queryName> {
    <queryType> (<parameters) {
        <fields>
    }
}
```

- `<queryName>` is optional and allows you to identify your query.
- `<queryType>` is one of the types below.
- `<parameters>` varies by query type. There is always a required scope parameter (id or upid), and Connection query types support optional pagination, filter, and sort parameters.
- `<fields>` varies by query type. See the documentation below for where to request specific FHIR fields.
```

--------------------------------

### Step 4: Make an API Call with the Access Token

Source: https://docs.zushealth.com/docs/creating-app-clients

Demonstrates how to make an authenticated API call using the access token obtained in Step 3. This involves including the token in the `Authorization` header.

```APIDOC
## GET /auth/app-clients/{YOUR_APPCLIENT_UUID}

### Description
Retrieves details of a specific app client using its UUID. Requires an `Authorization` header with a valid access token.

### Method
GET

### Endpoint
`https://api.sandbox.zusapi.com/auth/app-clients/<YOUR_APPCLIENT_UUID>`

### Parameters
#### Path Parameters
- **YOUR_APPCLIENT_UUID** (string) - Required - The UUID of the app client to retrieve.

### Request Headers
- **Accept** (string) - Required - Set to `application/vnd.api+json`.
- **Authorization** (string) - Required - Set to `Bearer <YOUR_ACCESS_TOKEN>`, where `<YOUR_ACCESS_TOKEN>` is the token obtained in Step 3.

### Request Example
```curl
curl --request GET \
     --url https://api.sandbox.zusapi.com/auth/app-clients/<YOUR_APPCLIENT_UUID>\
     --header 'Accept: application/vnd.api+json' \
     --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'
```

### Response
#### Success Response (200)
- **data** (object) - Contains the app client details.
  - **data.id** (string) - The UUID of the app client.
  - **data.type** (string) - The type of the resource, `auth/app-clients`.
  - **data.attributes** (object) - Attributes of the app client.
    - **data.attributes.clientId** (string) - The client ID.
    - **data.attributes.createdAt** (integer) - Timestamp of creation.
    - **data.attributes.name** (string) - The name of the app client.
    - **data.attributes.type** (string) - The type of the app client.
    - **data.attributes.updatedAt** (integer) - Timestamp of last update.
    - **data.attributes.userType** (string) - The user type.
  - **data.relationships.auth/roles.data.id** (string) - The ID of the associated role.

### Response Example
```json
{
  "data": {
    "type": "auth/app-clients",
    "id": "YOUR_APPCLIENT_UUID",
    "attributes": {
      "clientId": "YOUR_APPCLIENT_ID (for authentication)",
      "createdAt": 1651254340,
      "name": "YOUR_APPCLIENT_NAME",
      "type": "machine_to_machine",
      "updatedAt": 1651254340,
      "userType": "builder"
    },
    "relationships": {
      "auth/roles": {
        "data": {
          "type": "auth/roles",
          "id": "ROLE_UUID"
        }
      }
    }
  }
}
```
```

--------------------------------

### Make Authenticated API Call - Zus API

Source: https://docs.zushealth.com/docs/creating-app-clients

This cURL example shows how to make an authenticated GET request to the Zus API after obtaining an access token. The 'Authorization' header must include the 'Bearer' token. This is used to access specific resources, such as retrieving details of an app client using its UUID.

```curl
curl --request GET \
     --url https://api.sandbox.zusapi.com/auth/app-clients/<YOUR_APPCLIENT_UUID>\
     --header 'Accept: application/vnd.api+json' \
     --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'
```

```json
{
  "data": {
    "type": "auth/app-clients",
    "id": "YOUR_APPCLIENT_UUID",
    "attributes": {
      "clientId": "YOUR_APPCLIENT_ID (for authentication)",
      "createdAt": 1651254340,
      "name": "YOUR_APPCLIENT_NAME",
      "type": "machine_to_machine",
      "updatedAt": 1651254340,
      "userType": "builder"
    },
    "relationships": {
      "auth/roles": {
        "data": {
          "type": "auth/roles",
          "id": "ROLE_UUID"
        }
      }
    }
  }
}
```

--------------------------------

### Constraints and Best Practices

Source: https://docs.zushealth.com/docs/graphql-api

Outlines rate limits, performance considerations, consistency guarantees, and best practices for efficient API usage.

```APIDOC
## Constraints and Best Practices

### Description
This section details the constraints and recommended best practices for using the Zushealth GraphQL API to ensure optimal performance and avoid issues.

### Method
N/A (General guidelines)

### Endpoint
N/A (General guidelines)

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Constraints
- **Rate Limits**: The GraphQL API adheres to rate limits defined in the [Zus FAQs](https://docs.zushealth.com/docs/faqs#is-the-zus-api-rate-limited).
- **Superclusters**: UPIDs with over 1000 resources of a single type may lead to poor query performance.
- **Consistency**: The GraphQL API does not guarantee immediate read-your-write consistency; there might be a delay before data is available for subsequent read operations.

### Best Practices
- **Field Selection**: Only request fields that are necessary for your use case to minimize response size and latency.
- **Bulk Operations**: For statistics computation or bulk data exports, consider using [Data Marts](https://docs.zushealth.com/docs/data-marts) instead of direct API queries.
```

--------------------------------

### Create User

Source: https://docs.zushealth.com/docs/setting-up-users

Create a new user within your organization. This endpoint requires the RoleID obtained from the '/auth/roles' endpoint and optionally accepts a PractitionerID and clientId for redirection upon password reset.

```APIDOC
## POST /auth/users

### Description
Creates a new user in the Auth Service with specified attributes and role.

### Method
POST

### Endpoint
https://api.sandbox.zusapi.com/auth/users

### Parameters
#### Request Body
- **data** (object) - Required - The user data object.
  - **type** (string) - Required - Must be "auth/users".
  - **attributes** (object) - Required - Attributes of the user.
    - **email** (string) - Required - The user's email address. Must match the identity provider's email for SSO.
    - **name** (string) - Required - The username.
    - **userType** (string) - Required - The type of user (e.g., "builder").
    - **clientId** (string) - Optional - A client ID for redirecting the user upon password reset.
    - **sendPasswordResetEmail** (boolean) - Optional - Whether to send a password reset email (defaults to true).
  - **relationships** (object) - Required - Relationships for the user.
    - **auth/roles** (object) - Required - The role associated with the user.
      - **data** (object) - Required.
        - **type** (string) - Required - Must be "auth/roles".
        - **id** (string) - Required - The RoleID obtained from the '/auth/roles' endpoint.
    - **fhir/practitioner** (object) - Optional - The FHIR Practitioner resource to link.
      - **data** (object) - Optional.
        - **type** (string) - Optional - Must be "fhir/practitioner".
        - **id** (string) - Optional - The OptionalPractitionerID obtained from the '/fhir/Practitioner' endpoint.

### Request Example
```json
{
    "data": {
        "type": "auth/users",
        "attributes": {
            "email": "{{Email}}",
            "name": "{{Username}}",
            "userType": "builder",
            "clientId": "PuzaR6b4U1l2wMC3qciU1qUJI2fOxJLw", 
            "sendPasswordResetEmail": true
        },
        "relationships": {
            "auth/roles": {
                "data": {
                    "type": "auth/roles",
                    "id": "{{RoleID}}"
                }
            },
            "fhir/practitioner": {
                "data": {
                    "type": "fhir/practitioner", 
                    "id": "{{OptionalPractitionerID}}"
                }
            }
        }
    }
}
```

### Response
#### Success Response (200)
Details of the created user, including their ID and attributes.
```

--------------------------------

### FHIR DiagnosticReport Resource Example

Source: https://docs.zushealth.com/docs/lab-networks

An example of a FHIR DiagnosticReport resource, detailing a lipid panel test. This resource includes codes for the test, patient information, effective date, issuance date, performer, and references to individual Observation resources for each test result.

```json
{
    "resourceType": "DiagnosticReport",
    "id": "6c03ccbb-9ce2-4c36-9172-68067047a4fbVERSION1",
    
    "code": {
        "coding": [
            {
                "code": "2600000334",
                "display": "CHOLESTEROL, TOTAL"
            },
            {
                "system": "http://www.ama-assn.org/go/cpt",
                "code": "80061"
            }
        ]
    },
    "subject": {
        "reference": "Patient/28b2fb19-7625-47f4-9fe2-6075eb0262a3",
        "type": "Patient"
    },
    "effectiveDateTime": "2022-11-11",
    "issued": "2022-11-23T05:36:00.000Z",
    "performer": [
        {
            "reference": "Practitioner/b0386767-c02b-4512-919f-9fff9843e599",
            "type": "Practitioner"
        }
    ],
    "result": [
        {
            "reference": "Observation/60ccfa37-aa1e-4b39-bfe7-2dbd91d16fdc",
            "type": "Observation"
        },
        {
            "reference": "Observation/fc6f58b6-b073-4036-98c8-e8914e26321e",
            "type": "Observation"
        },
        {
            "reference": "Observation/75cf31ae-d245-4660-8cf4-87e0d376302e",
            "type": "Observation"
        }
    ]
}

```

--------------------------------

### Get Role ID for App Client - Zus API

Source: https://docs.zushealth.com/docs/creating-app-clients

This snippet demonstrates how to retrieve the ID of a role (e.g., 'Builder Admin' or 'Care Team User') required for creating an App Client. It involves a GET request to the Zus API's auth/roles endpoint. The 'id' from the response is crucial for the subsequent App Client creation step.

```json
{
    "data": {
        "type": "auth/roles",
        "id": "<RoleID>",
        "attributes": {
            "createdAt": timestamp,
            "description": "<description>",
            "isManaged": true,
            "name": "<RoleName>",
            "permissions": [
              #permissions listed here
            ],
            "updatedAt": timestamp
        }
    }
}
```

--------------------------------

### Create Practitioner Resource

Source: https://docs.zushealth.com/docs/setting-up-users

Optionally create a FHIR Practitioner resource for clinical users. This resource can be linked to the user's identity and used for associating with FHIR Care Teams and PractitionerRoles. A practitioner_id will be returned upon successful creation.

```APIDOC
## POST /fhir/Practitioner

### Description
Creates a FHIR Practitioner resource.

### Method
POST

### Endpoint
https://api.sandbox.zusapi.com/fhir/Practitioner

### Request Body
- **resourceType** (string) - Required - Must be "Practitioner".
- **active** (boolean) - Required - Indicates if the practitioner is active.
- **name** (array) - Required - An array of name objects for the practitioner.
  - **family** (string) - Required - The family name.
  - **given** (array) - Required - An array of given names.
    - (string) - The given name.

### Request Example
```json
{
    "resourceType": "Practitioner",
    "active": true,
    "name": [
                {
                    "family": "{{FamilyName}}",
                    "given": [
                        "{{GivenName}}"
                        ]
                }
            ]
}
```

### Response
#### Success Response (200)
- **practitioner_id** (string) - The ID of the created Practitioner resource.
```

--------------------------------

### GET /auth/roles

Source: https://docs.zushealth.com/docs/authentication

Retrieve the ID for a given role name, used when creating users for token exchange.

```APIDOC
## GET /auth/roles

### Description
Retrieves the ID for a given role name. This is used to configure users for token exchange, specifically for setting the `RoleID` for care team users.

### Method
GET

### Endpoint
`https://api.sandbox.zusapi.com/auth/roles`

### Parameters
#### Query Parameters
- **filter[name]** (string) - Required - The name of the role to filter by (e.g., `Care Team User`).

### Request Example
```bash
curl -X GET "https://api.sandbox.zusapi.com/auth/roles?filter[name]=Care Team User"
```

### Response
#### Success Response (200)
- **roles** (array) - An array of role objects matching the filter.
  - **id** (string) - The unique identifier for the role.
  - **name** (string) - The name of the role.

#### Response Example
```json
{
  "roles": [
    {
      "id": "some-role-id",
      "name": "Care Team User"
    }
  ]
}
```
```

--------------------------------

### GET /auth/users

Source: https://docs.zushealth.com/docs/user-authentication

Retrieves a list of users. This endpoint requires an authenticated request using a Zus access token.

```APIDOC
## GET /auth/users

### Description
Retrieves a list of users. This endpoint is an example of a Zus API call that requires an authenticated request using a Zus access token obtained via token exchange.

### Method
GET

### Endpoint
https://api.sandbox.zusapi.com/auth/users

#### Headers
- **Authorization** (string) - Required - `Bearer <Your Zus access token>`
```

--------------------------------

### Step 1: Specify a Role for the App Client

Source: https://docs.zushealth.com/docs/creating-app-clients

Specify the role for your App Client. Recommended role for Machine-to-Machine clients is `Builder Admin`. This step retrieves the role ID needed for client creation.

```APIDOC
## GET /auth/roles

### Description
Retrieves available roles and their details. Used to specify a role for the App Client.

### Method
GET

### Endpoint
`https://api.sandbox.zusapi.com/auth/roles`

### Query Parameters
- **filter[name]** (string) - Required - Filters roles by name. Use `Builder Admin` or `Care Team User`.

### Response
#### Success Response (200)
- **data** (object) - Contains role information.
  - **data.id** (string) - The ID of the specified role, to be used in the next step.
  - **data.attributes** (object) - Attributes of the role.
    - **data.attributes.name** (string) - The name of the role.
    - **data.attributes.description** (string) - Description of the role.
    - **data.attributes.permissions** (array) - List of permissions associated with the role.

### Response Example
```json
{
    "data": {
        "type": "auth/roles",
        "id": "<RoleID>",
        "attributes": {
            "createdAt": "timestamp",
            "description": "<description>",
            "isManaged": true,
            "name": "<RoleName>",
            "permissions": [
              
            ],
            "updatedAt": "timestamp"
        }
    }
}
```
```

--------------------------------

### GET /auth/roles

Source: https://docs.zushealth.com/docs/user-authentication

Retrieves a list of available roles. This can be used to find the RoleID for specific roles like 'Care Team User'.

```APIDOC
## GET /auth/roles

### Description
Retrieves a list of available roles, which can be filtered by name to obtain a specific RoleID.

### Method
GET

### Endpoint
https://api.sandbox.zusapi.com/auth/roles

#### Query Parameters
- **filter[name]** (string) - Optional - Filters roles by their name. Example: `filter[name]=Care Team User`
```
Tokens:
Raw