Sharing Data on Patient Outreach
Your organization may have a cohort of patients attributed to you that you are reaching out to to engage and enroll in your programs. Even if you haven't had a full clinical encounter with the patient yet, it is still useful for other members of these patients' care teams to know that they have been attributed to you, and that you are reaching out to engage them for a given condition. We recommend using the following USCDI v1 data elements as a reference when supplying this information:
- Assessment and Plan of Treatment: Represents a health professional’s conclusions and working assumptions that will guide treatment of the patient.
- Care Team Member: The specific person(s) who participate or are expected to participate in the care team.
- Goals: An expressed desired health state to be achieved by a subject of care (or family/group)
over a period of time or at a specific point of time. - Problems: Information about a condition, diagnosis, or other event, situation, issue, or clinical
concept that is documented. To be documented using SNOMED if at all possible. - Although not included in USCDI v1, Referral data can also provide helpful documentation of your relationship with a patient
This guide shows you how to represent and write that data to Zus.
What data to supply
We recommend that you supply the following information:
📆 Records of planned outreach to attributed patients
🗒️ Notes from outreach calls that you conduct with the patient
🤝 Members of your organization that are part of a patient's care team (either through an attribution relationship, referral relationship, or a pre-existing visit)
Mechanics of contributing data
Our FHIR APIs allow you to write data to Zus. You can simplify your API calls by using two important elements of the FHIR toolkit
- Bundles allow you to submit multiple resources in one API call
- Conditional writes allow you to reference resources that might already exist in Zus and safely create them if they don't exist. E.g., "check if a Practitioner with this NPI already exists and create them if they don't."
Useful notes:
- To create a bundle, POST to
https://api.sandbox.zusapi.com/fhir/ - When setting up
fullURLUUIDs, remember:- You need a unique UUID for each resource in the bundle, but you can reuse UUIDs across different bundles
- The UUIDs need to be structurally valid, but can be completely arbitrary; the Zus system will replace them with real generated IDs
- Conditional writes
- Specify the request method you want to use
- Use a POST if you want to link to existing resources without updating them, using the
ifNoneExistfield in the bundle'srequestto provide the identifier to match. - Use a PUT if you want your request to update existing resources with new information, using a
identifierquery param to provide the identifier to match.
- Use a POST if you want to link to existing resources without updating them, using the
- 👉 Remember:
- Make sure the identifier you use in the
ifNoneExistparameter or theidentifiersearch parameter matches the identifier in the resource itself. - If the resource does not exist, it will get created with only the information you supply in the API call. If you expect that this request might write Patients or Practitioners for the first time, make sure the stub has sufficient identifying information.
- Make sure the identifier you use in the
- If there are multiple copies of a resource with the same identifier belonging to your organization, your conditional write will fail. If you expect that to be a regular occurrence, we recommend just using a standard (not conditional) POST or PUT.
- Specify the request method you want to use
Starter bundles
Steal and modify these bundles to start syncing data.
📆 Planned outreach
Use this bundle to indicate that you have an outreach call planned to a patient.
- Resources needed
- Patient that you are planning to call
- Care plan containing the details of the scheduled call
- Practitioner that will be making the call
- Condition about which you are calling the patient
- Goal of your engagement with patient (recommended, but not required)
- Key fields
- Capture the planned phone call in the
CarePlan.activityarray, populating information about the timing and nature of the call inactivity.detail
- Capture the planned phone call in the
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000001",
"request": {
"method": "POST",
"url": "Patient",
"ifNoneExist": "identifier=https://zusapi.com/demo/mrn|MRN-BZ-1234"
},
"resource": {
"resourceType": "Patient",
"identifier": [
{
"system": "https://zusapi.com/demo/mrn",
"value": "MRN-BZ-1234"
}
],
"name": [
{
"family": "Zhang",
"given": [
"Bruno"
]
}
]
}
},
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000002",
"request": {
"method": "POST",
"url": "Practitioner",
"ifNoneExist": "identifier=http://hl7.org/fhir/sid/us-npi|3333333333"
},
"resource": {
"resourceType": "Practitioner",
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "3333333333"
}
],
"name": [
{
"family": "Marshall",
"given": [
"Dana"
]
}
]
}
},
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000005",
"request": {
"method": "POST",
"url": "Condition",
"ifNoneExist": "identifier=https://zusapi.com/demo/problem-id|2424"
},
"resource": {
"resourceType": "Condition",
"subject": {
"reference": "urn:uuid:00000000-0000-0000-0000-000000000001"
},
"identifier": [
{
"system": "https://zusapi.com/demo/problem-id",
"value": "2424"
}
],
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "73211009",
"display": "Diabetes mellitus (disorder)"
}
]
},
"category": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/condition-category",
"code": "problem-list-item",
"display": "Problem List Item"
}
]
}
]
}
},
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000006",
"request": {
"method": "POST",
"url": "Goal",
"ifNoneExist": "identifier=https://zusapi.com/demo/goal-id|1111"
},
"resource": {
"resourceType": "Goal",
"identifier": [
{
"system": "https://zusapi.com/demo/goal-id",
"value": "1111"
}
],
"lifecycleStatus": "proposed",
"description": {
"text": "Bring diabetes under control using nutrition therapy"
},
"subject": {
"reference": "urn:uuid:00000000-0000-0000-0000-000000000001"
},
"target": [
{
"dueDate": "2025-12-05"
}
]
}
},
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000004",
"request": {
"method": "PUT",
"url": "CarePlan?identifier=https://zusapi.com/demo/careplan-id|1414"
},
"resource": {
"resourceType": "CarePlan",
"status": "active",
"intent": "plan",
"subject": {
"reference": "urn:uuid:00000000-0000-0000-0000-000000000001"
},
"identifier": [
{
"system": "https://zusapi.com/demo/careplan-id",
"value": "1414"
}
],
"period": {
"start": "2025-01-01"
},
"goal": [
{
"reference": "urn:uuid:00000000-0000-0000-0000-000000000006"
}
],
"category": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/care-plan-category",
"code": "assess-plan",
"display": "Assessment and Plan of Treatment"
}
]
}
],
"addresses": [
{
"reference": "urn:uuid:00000000-0000-0000-0000-000000000005"
}
],
"activity": [
{
"detail": {
"status": "scheduled",
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "185317003",
"display": "Telephone encounter"
}
]
},
"description": "Initial outreach call to newly attributed patient to inform them about Celery Health diabetes management benefits available through their health plan.",
"scheduledPeriod": {
"start": "2025-07-06T09:00:00Z",
"end": "2025-07-06T10:00:00Z"
},
"performer": [
{
"reference": "urn:uuid:00000000-0000-0000-0000-000000000002"
}
]
}
}
]
}
}
]
}
🗒️ Notes from outreach call
After you speak to a patient, use this bundle to record the outcome of the conversation
- Resources needed
- Patient that was called
- Practitioner that conducted the call
- Encounter detailing when the call occurred, and through what medium (virtual)
- DocumentReference capturing notes from the conversation
- Key fields
- Represent the call as a Encounter resource, using the
Encounter.classandEncounter.typefields to denote that it is a virtual telephone encounter - Capture Base64-encoded notes in the
DocumentReference.content.attachment.data - Use
DocumentReference.contextto link it to the associated Encounter - 🖐️ Make sure
DocumentReference.categoryis set toclinical-note
- Represent the call as a Encounter resource, using the
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000001",
"request": {
"method": "POST",
"url": "Patient",
"ifNoneExist": "identifier=https://zusapi.com/demo/mrn|MRN-BZ-test"
},
"resource": {
"resourceType": "Patient",
"identifier": [
{
"system": "https://zusapi.com/demo/mrn",
"value": "MRN-BZ-test"
}
],
"name": [
{
"family": "Zhang",
"given": [
"Bruno"
]
}
]
}
},
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000002",
"request": {
"method": "POST",
"url": "Practitioner",
"ifNoneExist": "identifier=http://hl7.org/fhir/sid/us-npi|3333333333"
},
"resource": {
"resourceType": "Practitioner",
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "2223333333"
}
],
"name": [
{
"family": "Marshall",
"given": [
"Dana"
]
}
],
"qualification": [
{
"code": {
"coding": [
{
"code": "163WC1500X",
"display": "Registered Nurse, Community Care",
"system": "http://nucc.org/provider-taxonomy"
}
]
}
}
]
}
},
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000003",
"request": {
"method": "POST",
"url": "Encounter"
},
"resource": {
"resourceType": "Encounter",
"status": "finished",
"class": {
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "VR",
"display": "virtual"
},
"type": [
{
"coding": [
{
"system": "http://snomed.info/sct",
"code": "386472008",
"display": "Telephone encounter"
}
],
"text": "Telephone Encounter with Dana"
}
],
"subject": {
"reference": "urn:uuid:00000000-0000-0000-0000-000000000001"
},
"participant": [
{
"individual": {
"reference": "urn:uuid:00000000-0000-0000-0000-000000000002"
}
}
],
"period": {
"start": "2024-07-05T09:00:00Z",
"end": "2024-07-05T09:30:00Z"
}
}
},
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000004",
"request": {
"method": "POST",
"url": "DocumentReference"
},
"resource": {
"resourceType": "DocumentReference",
"status": "current",
"docStatus": "final",
"type": {
"coding": [
{
"system": "http://loinc.org",
"code": "34133-9",
"display": "Summary of episode note"
}
],
"text": "Telephone Encounter Note"
},
"subject": {
"reference": "urn:uuid:00000000-0000-0000-0000-000000000001"
},
"date": "2024-03-05T09:00:00Z",
"author": [
{
"reference": "urn:uuid:00000000-0000-0000-0000-000000000002"
}
],
"content": [
{
"attachment": {
"contentType": "text/plain",
"data": "VGhpcyBpcyBhIHNhbXBsZSBjYWxsIG5vdGUuIERpc2N1c3NlZCBkaWFiZXRlcyBtYW5hZ2VtZW50IHdpdGggdGhlIHBhdGllbnQsIGluY2x1ZGluZyBzZXJ2aWNlcyB0aGF0IHRoZSBwcm9ncmFtIGNvdWxkIG9mZmVyIHRoZW0uIFBhdGllbnQgd2FudGVkIGhlbHAgd2l0aCBtZWRpY2F0aW9uIG1hbmFnZW1lbnQgYW5kIG1lZGljYXRpb24gYWRoZXJlbmNlLCBpbmNsdWRpbmcgcmVkdWNpbmcgdGhlIGNvc3Qgb2YgdGhlaXIgcHJlc2NyaXB0aW9ucy4="
}
}
],
"category": [
{
"coding": [
{
"system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
"code": "clinical-note"
}
]
}
],
"context": {
"encounter": [
{
"reference": "urn:uuid:00000000-0000-0000-0000-000000000003"
}
]
}
}
}
]
}
🤝 Attribution relationships
Use this bundle to indicate that practitioners within your org are part of a patient's care team.
- Resources needed
- Patient who has been attributed or referred to your org
- Practitioner(s) treating this patient
- CareTeam resource wrapper to describe relationships between the Patient and Practitioners
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000001",
"request": {
"method": "POST",
"url": "Patient",
"ifNoneExist": "identifier=https://zusapi.com/demo/test|MRN-BZ-test"
},
"resource": {
"resourceType": "Patient",
"identifier": [
{
"system": "https://zusapi.com/demo/test",
"value": "MRN-BZ-test"
}
],
"name": [
{
"family": "Zhang",
"given": [
"Bruno"
]
}
]
}
},
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000002",
"request": {
"method": "POST",
"url": "Practitioner",
"ifNoneExist": "identifier=http://hl7.org/fhir/sid/us-npi|3333333333"
},
"resource": {
"resourceType": "Practitioner",
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "3333333333"
}
]
}
},
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000004",
"request": {
"method": "POST",
"url": "Practitioner",
"ifNoneExist": "identifier=http://hl7.org/fhir/sid/us-npi|2222222222"
},
"resource": {
"resourceType": "Practitioner",
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "2222222222"
}
]
}
},
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000003",
"request": {
"method": "POST",
"url": "CareTeam"
},
"resource": {
"resourceType": "CareTeam",
"subject": {
"reference": "urn:uuid:00000000-0000-0000-0000-000000000001"
},
"participant": [
{
"role": [
{
"coding": [
{
"system": "http://snomed.info/sct",
"code": "446050000",
"display": "Primary care provider"
}
]
}
],
"member": {
"reference": "urn:uuid:00000000-0000-0000-0000-000000000002"
}
},
{
"role": [
{
"coding": [
{
"system": "http://snomed.info/sct",
"code": "224540001",
"display": "Community Nurse"
}
]
}
],
"member": {
"reference": "urn:uuid:00000000-0000-0000-0000-000000000004"
}
}
]
}
}
]
}
⬅️ Referral
Although referral data is not part of USCDI v1 and therefore not required for sharing, it can be a helpful record of your relationship with a patient.
- Resources needed
- Patient referred to your org
- Practitioner who referred the patient to you
- Organization resource representing your practice or provider group
- ServiceRequest resource encapsulating the referral itself
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000001",
"request": {
"method": "POST",
"url": "Patient",
"ifNoneExist": "identifier=https://zusapi.com/demo/mrn|MRN-BZ-1234"
},
"resource": {
"resourceType": "Patient",
"id": "00000000-0000-0000-0000-000000000001",
"identifier": [
{
"system": "https://zusapi.com/demo/mrn",
"value": "MRN-BZ-1234"
}
],
"name": [
{
"use": "official",
"family": "Zhang",
"given": [
"Bruno"
]
}
]
}
},
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000002",
"request": {
"method": "POST",
"url": "Practitioner",
"ifNoneExist": "identifier=http://hl7.org/fhir/sid/us-npi|4444444444"
},
"resource": {
"resourceType": "Practitioner",
"id": "00000000-0000-0000-0000-000000000002",
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "4444444444"
}
],
"name": [
{
"use": "official",
"family": "Smith",
"given": [
"Jane"
]
}
]
}
},
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000003",
"request": {
"method": "POST",
"url": "Organization",
"ifNoneExist": "identifier=https://zusapi.com/demo/oid|345678"
},
"resource": {
"resourceType": "Organization",
"id": "00000000-0000-0000-0000-000000000003",
"identifier": [
{
"system": "https://zusapi.com/demo/oid",
"value": "345678"
}
],
"name": "Diabetes Management Practice"
}
},
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000004",
"request": {
"method": "POST",
"url": "ServiceRequest",
"ifNoneExist": "identifier=https://zusapi.com/demo/referralid|567890"
},
"resource": {
"resourceType": "ServiceRequest",
"id": "00000000-0000-0000-0000-000000000004",
"identifier": [
{
"system": "https://zusapi.com/demo/referralid",
"value": "567890"
}
],
"status": "active",
"intent": "order",
"category": [
{
"coding": [
{
"system": "http://snomed.info/sct",
"code": "409063005",
"display": "Counseling"
}
]
}
],
"priority": "routine",
"subject": {
"reference": "urn:uuid:00000000-0000-0000-0000-000000000001",
"display": "Bruno Zhang"
},
"authoredOn": "2024-07-29T12:00:00Z",
"requester": {
"reference": "urn:uuid:00000000-0000-0000-0000-000000000002",
"display": "Dr. Jane Smith"
},
"performer": [
{
"reference": "urn:uuid:00000000-0000-0000-0000-000000000003",
"display": "Diabetes Management Practice"
}
],
"reasonCode": [
{
"coding": [
{
"system": "http://snomed.info/sct",
"code": "44054006",
"display": "Diabetes mellitus type 2"
}
],
"text": "Referral for diabetes management"
}
],
"note": [
{
"text": "Patient has been diagnosed with type 2 diabetes and requires specialized management."
}
]
}
}
]
}
Updated 26 days ago