Authentication

All requests to FQS require authentication.

FQS supports the same HTTP Authorization token used througout Zus APIs. Queries are made using a POST request and a bearer token. See Authenticating for API Access for instructions on obtaining a bearer token.

POST /fqs/query HTTP/1.1
Host: api.zusapi.com/fqs/query
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Content-Type: application/json

Using HTTP 2:

POST /fqs/query HTTP/2
Host: api.zusapi.com/fqs/query
authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
content-type: application/json

Find a patient

Find the FHIR resource iD of a Patient record, and make the following query in Postman (link TBD):

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

Data you are authorized to see

FQS is a read-only service. You are permitted to view data in the Zus platform that was either created directly by your organization, or is part of the Common Patient Record for a patient that your organization has a treatment relationship with.

To view data that created by your organization, perform builder-scoped searches. To view data in the Common Patient Record, perform patient-scoped searches.

Get a single resource by FHIR ID

query {
  Patient (id: $id) {
    id
    name { family given }
    // any other fields you want
  }
}

A more detailed example

query {
Patient(id: "0098df9f-e41f-4ded-8fa3-bf9190a0db1d") {
    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 Patients with a UPID

The List query type allows you to retrieve the first n results. The first 10 results are returned by default.

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

A more detailed example

{
PatientList(upid: "0468241e-220c-4fa8-bed2-15343430b27d") {
    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
    }
}
}

Paginating through results

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

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

A more detailed example

query MedicationRequest {
  MedicationRequestConnection(
    upid: "4ed64962-9c8f-4712-9484-db6f85174817"
    first: 100
  ) {
    edges {
      node {
        resourceType
        contained {
          resource {
            ... on Medication {
              id
              resourceType
              code {
                coding {
                  extension {
                    url
                    valueString
                  }
                  system
                  code
                  display
                  userSelected
                }
              }
            }
            ... on Organization {
              id
              resourceType
              _organization__name: name
            }
            ... on Practitioner {
              id
              resourceType
              _practitioner__name: name {
                family
                given
                prefix
                suffix
              }
            }
          }
        }
        meta {
          id
          versionId
          lastUpdated
          source
          profile
          security {
            system
            code
          }
          tag {
            system
            code
          }
        }
        implicitRules
        authoredOn
        language
        text {
          id
          div
        }
        identifier {
          id
          type {
            coding {
              system
              code
              display
            }
          }
          system
          value
          period {
            start
            end
          }
        }
        category {
          coding {
            system
            code
            display
          }
        }
        medicationCodeableConcept {
          coding {
            extension {
              url
              valueString
            }
            system
            code
            display
            userSelected
          }
          text
        }
        subject {
          id
          reference
          type
          identifier {
            id
            type {
              coding {
                system
                code
                display
              }
            }
            system
            value
            period {
              start
              end
            }
          }
          display
        }
      }
      cursor
    }
    pageInfo {
      hasNextPage
    }
  }
}

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

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. Forward pagination (with first and after) is supported, but reverse pagination (with last and before) has not been implemented.

Query scopes

For HTTP requests, the POST body is passed as a JSON string:

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

<queryContent> is a GraphQL query string:

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.

Single resource

query [<name>] {
  <resourceType> (id: $id) {
    // FHIR fields
  }
}

• <resourceType> is the FHIR resource type
• $id (required) is the FHIR resource ID

Single resoure history

History queries return all versions of a single resource. Versions are sorted in ascending order.

query [<name>] {
  <resourceType>History (id: $id) {
    // FHIR fields
  }
}

• <resourceType> is the FHIR resource type
• $id (required) is the FHIR resource ID

Patient-scoped queries

List queries

query [<name>] {
  <resourceType>List (upid: $upid) {
    // FHIR fields
  }
}

• <resourceType> is the FHIR resource type
• $upid (required) is the patient UPID

Connection queries

query [<name>] {
  <resourceType>Connection (upid: $upid, [<pagination>], [<sort>], [<filter>]) {
    pageInfo {
      hasNextPage
    }
    edges {
      node {
        // FHIR fields
      }
      cursor
    }
  }
}

• <resourceType> is the FHIR resource type
• $upid (required) is the patient UPID
• <pagination> (optional) can be any/all of the pagination parameters. See below for pagination parameter documentation.
• <sort> (optional) is a field to sort by. See details below.
• <filter> (optional) is an object of fields to filter by. See detials below.

Builder-scoped queries

Under construction

Filtering

Connection queries support a filter argument to filter returned results. The filter argument has the following form:

{
    <searchTerm>: { <predicate>: <value> }
}

Valid values for <searchTerm> depend on the resource type. All resource types support a <searchTerm> of tag and ids. To look up what filter parameters are supported by each resource type, look for <resourceType>FilterParams under the list of types.

Predicates

Valid values for <predicate> and <value> depends on the search term type.

All types

Date

String

StringSet

Sorting

Connection queries support a sort argument to sort returned results. The sort argument has the following form:

{
    <sortTerm>: <direction>
}

<direction> is either "ASC" for ascending or "DESC" for descending.

Only one sort parameter may be specified at a time. All resource types can be sorted by lastUpdated. To look up what sort parameters are supported by each resource type, look for <resourceType>SortParams under the list of types.

Pagination

Valid pagination parameters:

• first: Page size to return
• after: Return results after the specified cursor

References and contained resources

FHIR resources often contain a reference to another resource of a different type. To get fields from the referenced resource, use GraphQL fragments.

Example of getting a Patient's managingOrganization

query Patient {
  Patient (id: "0a9f397d-1255-4f28-8f58-7ca0e6509e5b") {
    id
    meta {
        lastUpdated
        versionId
        tag {
            system
            code
        }
    }
    extension {
        url
        valueString
    }
    managingOrganization {
      resource {
        ... on Organization {
            id
            name
        }
      }
    }
  }
}

FHIR resoure types

Resoruces in the designated record set (DRS)

The designated record set (DRS) covers the records that individuals have a right to request under the HIPAA Privacy Rule

Zus has mapped record types in the DRS to the following resources in the FHIR standard:

• Account
• AllergyIntolerance
• Appointment
• AppointmentResponse
• BodyStructure
• CarePlan
• CareTeam
• ClinicalImpression
• Composition
• Condition
• Consent
• Coverage
• CoverageEligibilityRequest
• CoverageEligibilityResponse
• DetectedIssue
• Device
• DeviceRequest
• DiagnosticReport
• DocumentManifest
• DocumentReference
• Encounter
• EpisodeOfCare
• FamilyMemberHistory
• Flag
• Goal
• ImagingStudy
• Immunization
• ImmunizationEvaluation
• ImmunizationRecommendation
• MeasureReport
• Media
• MedicationAdministration
• MedicationDispense
• MedicationRequest
• MedicationStatement
• MolecularSequence
• NutritionOrder
• Observation
• Patient
• Person
• Procedure
• Provenance
• RelatedPerson
• RiskAssessment
• ServiceRequest
• Specimen
• SupplyDelivery
• SupplyRequest
• VisionPrescription

FHIR resource types in the DRS can be queried using patient-scoped queries.

Foundational resources

Foundational resource types are FHIR resource types that represent entities in the health system. These records by themselves are not PHI, but are referenced by PHI as they are involved in patient treatment. Zus considers the following FHIR resource types to be Foundational:

• Location
• Medication
• Organization
• Practitioner
• PractitionerRole

Superclusters (UPIDs with over 1000 resources for a single resource type) have poor query performance

Don't request fields than you don't need. Response latency is correlated with response size, and requesting too many fields increases the size of the response.

If you're trying to compute statistics, you should probably use the data lake/warehouse

How is FQS related to GraphQL with FHIR?

The GraphQL schema on FQS was based on the draft GraphQL on FHIR spec, but we have chosen to diverge on several points:

• The query scopes for patient-centric and builder-centric queries are unique to Zus
• We do not suppress empty elements (the GraphQL documentation is ambiguous about this and it has caused confusion in the FHIR community)
• Pagination follows the GraphQL Cursor Connection spec rather than the Connection examples in the FHIR spec
• Instead of supporting FHIR search parameters, FQS search parameters are curated. We are using the Dgraph database syntax as inspiration for allowing richer combinations of filter parameters
• FQS supports fragment expansion of contained resources (but the client has to know in advance what resource type they want). The FHIR GraphQL spec expressly does not support _contained
• FQS supports sorting but the FHIR GraphQL spec does not mention it

How data gets in FQS

There are a number of ways data gets in the Zus ecosystem:

• Direct writes via API
• Third party data from patient history jobs
• Data arriving from third party subscriptions
• Derived data (Lenses) generated automatically by Zus

FQS is eventually consistent for all data input sources. Direct writes from input APIs typically arrive in FQS within a second. Derived data is typically updated within seconds. Data from patient history jobs arrive between a few minutes and 24 hours, depending on the data source. Data from third party subscriptions typically arrive in FQS within seconds from when it is received by Zus.