Zushooks deliver inbound HTTPS callbacks when patient data is created or updated in the Zus FHIR Store - ADT events, medication pickups, lab results, and status changes - filtered by JQ criteria and authenticated with basic auth or OAuth client credentials.
openapi: 3.0.1
info:
title: Zus Health API
description: >-
FHIR R4 (v4.0.1) REST API for the Zus Health shared health-data platform.
Provides access to Patient resources, the Zus Aggregated Profile (ZAP) via
Patient History jobs, general FHIR resources, document ingestion and
retrieval through DocumentReference and Binary, and OAuth2 token issuance.
All requests are authenticated with an OAuth2 Bearer access token. Endpoints
and behavior are derived from the public Zus documentation at
https://docs.zushealth.com; production hostnames use api.zusapi.com and the
sandbox uses api.sandbox.zusapi.com / auth.sandbox.zusapi.com.
termsOfService: https://zushealth.com
contact:
name: Zus Health
url: https://docs.zushealth.com
version: '1.0'
servers:
- url: https://api.zusapi.com
description: Production
- url: https://api.sandbox.zusapi.com
description: Sandbox
security:
- bearerAuth: []
tags:
- name: Auth
description: OAuth2 token issuance and exchange.
- name: Patient
description: FHIR R4 Patient resources.
- name: FHIR
description: General FHIR R4 resources.
- name: Patient History
description: Jobs that retrieve external data into the Zus Aggregated Profile.
- name: Documents
description: DocumentReference and Binary resources.
paths:
/oauth/token:
servers:
- url: https://auth.zusapi.com
description: Production auth
- url: https://auth.sandbox.zusapi.com
description: Sandbox auth
post:
operationId: createToken
tags:
- Auth
summary: Issue or exchange an OAuth2 access token.
description: >-
Exchange credentials for a Zus access token. Supports the
authorization_code (with PKCE) grant and the RFC 8693 token-exchange
grant (grant_type urn:ietf:params:oauth:grant-type:token-exchange) for
exchanging a third-party IdP ID token. Access tokens are valid for one
hour (expires_in 3600). The token endpoint is rate limited to 200
requests per hour per App Client.
security: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/TokenRequest'
responses:
'200':
description: Access token issued.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
'401':
description: Invalid credentials.
/fhir/Patient:
get:
operationId: searchPatients
tags:
- Patient
summary: Search Patient resources.
description: >-
Search FHIR R4 Patient resources. Supports search parameters including
identifier, name, and the Zus universal patient identifier (upid).
Returns a FHIR searchset Bundle. Default page size is 10 and can be
expanded up to 500.
parameters:
- name: identifier
in: query
schema:
type: string
description: Token search on a Patient identifier (system|value).
- name: name
in: query
schema:
type: string
- name: upid
in: query
schema:
type: string
description: Zus universal patient identifier.
- name: _count
in: query
schema:
type: integer
default: 10
maximum: 500
responses:
'200':
description: A FHIR searchset Bundle.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Bundle'
post:
operationId: createPatient
tags:
- Patient
summary: Create a Patient resource.
description: >-
Create a FHIR R4 Patient. Setting Patient.active to true is the primary
signal of an active treatment relationship and authorizes access to the
patient's aggregated third-party data. Zus interprets a NULL value for
Patient.active as false.
requestBody:
required: true
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Patient'
responses:
'201':
description: Patient created.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Patient'
/fhir/Patient/{id}:
get:
operationId: readPatient
tags:
- Patient
summary: Read a Patient by id.
parameters:
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
description: The requested Patient resource.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Patient'
'404':
description: Patient not found.
put:
operationId: updatePatient
tags:
- Patient
summary: Replace a Patient by id.
description: >-
Replace an existing Patient. Version-aware writes are supported via the
Zus-If-Match header.
parameters:
- $ref: '#/components/parameters/ResourceId'
- name: Zus-If-Match
in: header
schema:
type: string
description: Version-aware write precondition.
requestBody:
required: true
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Patient'
responses:
'200':
description: Patient updated.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Patient'
/fhir/{resourceType}:
get:
operationId: searchResources
tags:
- FHIR
summary: Search resources of a given FHIR R4 type.
description: >-
Search any supported FHIR R4 resource type (140+ types including
Observation, Condition, Encounter, MedicationStatement, Procedure,
DiagnosticReport, DocumentReference, and Binary). Returns a searchset
Bundle.
parameters:
- name: resourceType
in: path
required: true
schema:
type: string
example: Observation
- name: patient
in: query
schema:
type: string
- name: _count
in: query
schema:
type: integer
default: 10
maximum: 500
responses:
'200':
description: A FHIR searchset Bundle.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Bundle'
post:
operationId: createResource
tags:
- FHIR
summary: Create a resource of a given FHIR R4 type.
parameters:
- name: resourceType
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Resource'
responses:
'201':
description: Resource created.
/fhir/{resourceType}/{id}:
get:
operationId: readResource
tags:
- FHIR
summary: Read a resource by type and id.
parameters:
- name: resourceType
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
description: The requested resource.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Resource'
'404':
description: Resource not found.
delete:
operationId: deleteResource
tags:
- FHIR
summary: Delete a resource by type and id.
parameters:
- name: resourceType
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
description: Resource deleted.
/fhir:
post:
operationId: submitBundle
tags:
- FHIR
summary: Submit a FHIR transaction or batch Bundle.
description: >-
Submit a FHIR R4 transaction or batch Bundle (up to 100 entries).
Supports conditional create, update, and delete by identifier.
requestBody:
required: true
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Bundle'
responses:
'200':
description: A transaction-response or batch-response Bundle.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Bundle'
/patient-history/jobs:
post:
operationId: createPatientHistoryJob
tags:
- Patient History
summary: Create a Patient History job.
description: >-
Submit a Patient History job to retrieve a patient's clinical data from
Zus network partners into the FHIR Store, populating the Zus Aggregated
Profile (ZAP). Submitting a Patient History request sets Patient.active
to true for the patient.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatientHistoryJobRequest'
responses:
'201':
description: Job created.
content:
application/json:
schema:
$ref: '#/components/schemas/PatientHistoryJob'
get:
operationId: listPatientHistoryJobs
tags:
- Patient History
summary: List Patient History jobs.
responses:
'200':
description: A list of Patient History jobs.
/patient-history/jobs/{jobId}:
get:
operationId: getPatientHistoryJob
tags:
- Patient History
summary: Retrieve a Patient History job.
parameters:
- name: jobId
in: path
required: true
schema:
type: string
responses:
'200':
description: The requested Patient History job.
content:
application/json:
schema:
$ref: '#/components/schemas/PatientHistoryJob'
/fhir/DocumentReference/{id}:
get:
operationId: readDocumentReference
tags:
- Documents
summary: Read a DocumentReference by id.
description: >-
Retrieve a FHIR R4 DocumentReference. Narrative content (text.div) is
treated as opaque and is not validated.
parameters:
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
description: The requested DocumentReference.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Resource'
/fhir/Binary/{id}:
get:
operationId: readBinary
tags:
- Documents
summary: Read a Binary resource by id.
description: >-
Retrieve a FHIR R4 Binary resource. The base64-encoded Binary.data
payload is stored as submitted and is not run through instance
validation.
parameters:
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
description: The requested Binary resource.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Resource'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
OAuth2 Bearer access token obtained from the Zus token endpoint
(auth.zusapi.com/oauth/token). Sent as Authorization: Bearer
<ACCESS_TOKEN>.
parameters:
ResourceId:
name: id
in: path
required: true
schema:
type: string
description: The logical id of the resource.
schemas:
TokenRequest:
type: object
required:
- grant_type
properties:
grant_type:
type: string
description: >-
authorization_code or
urn:ietf:params:oauth:grant-type:token-exchange.
client_id:
type: string
code:
type: string
code_verifier:
type: string
redirect_uri:
type: string
subject_token:
type: string
description: Third-party IdP ID token (token-exchange grant).
subject_token_type:
type: string
scope:
type: string
example: openid profile email
TokenResponse:
type: object
properties:
access_token:
type: string
token_type:
type: string
example: Bearer
expires_in:
type: integer
example: 3600
scope:
type: string
PatientHistoryJobRequest:
type: object
properties:
patient:
type: object
description: Reference to the FHIR Patient the job is run for.
practitioner:
type: object
description: Reference to the requesting Practitioner.
config:
type: object
description: Job configuration options.
PatientHistoryJob:
type: object
properties:
id:
type: string
status:
type: string
example: running
patient:
type: object
Resource:
type: object
description: A generic FHIR R4 resource.
properties:
resourceType:
type: string
id:
type: string
additionalProperties: true
Patient:
type: object
properties:
resourceType:
type: string
example: Patient
id:
type: string
active:
type: boolean
description: >-
Primary signal of an active treatment relationship. Zus interprets
NULL as false.
identifier:
type: array
items:
type: object
name:
type: array
items:
type: object
gender:
type: string
description: administrative-gender; value set strictly enforced.
birthDate:
type: string
format: date
additionalProperties: true
Bundle:
type: object
properties:
resourceType:
type: string
example: Bundle
type:
type: string
example: searchset
total:
type: integer
entry:
type: array
items:
type: object
additionalProperties: true