Developers · Interoperability
FHIR write to other systems
ChartVoyant as a FHIR R4 client. A clinician at a practice sends a patient's final observations, such as vital signs, to a FHIR server the practice has registered: another clinic's EHR, a hospital, a health information exchange or a registry. This page is for the team that runs that server.
At a glance
| Status | Deployed in production on October 29, 2026, in synthetic mode: a practice can register a destination and exercise it against ChartVoyant's own test servers. Real-data sending is turned on per destination in a later ChartVoyant release, after an executed agreement for that destination and independent security testing of this path. |
| Direction | ChartVoyant writes to your server. It reads only your CapabilityStatement and, to find the patient, a Patient search by identifier. |
| Standards | FHIR R4 and SMART Backend Services, with ChartVoyant as the client. |
| Authentication | client_credentials with a private_key_jwt assertion signed RS384 that expires within five minutes. ChartVoyant makes a key pair for each destination, keeps the private key encrypted, and publishes only the public key at a JWKS address you register, of the form https://chartvoyant.com/api/v1/interop/jwks/{key}.json. |
| Resources | Observation only. Each create carries ChartVoyant's identifier, so a resend finds the same resource. Conditional create, update with If-Match, and batch or transaction Bundles are used only where both your CapabilityStatement and the destination's profile allow them. |
| Network | HTTPS only. Redirects are refused, and so is any host that resolves to an internal or cloud metadata address. |
| Patients | ChartVoyant never creates a Patient on your server. A send needs a patient link a person has confirmed. |
What runs today, and what comes next
Destinations, matching, the send pipeline and the disclosure rules run in production, in synthetic mode against ChartVoyant's own test servers. Sending to your server, with real patient data, comes per destination in a later release, once its agreement is executed and independent security testing covers this path. The steps below describe how a send works then.
How a send works
- The practice registers your server
Your FHIR base, your token endpoint, the system scopes to request, and the reason for sending: treatment by a provider with an NPI, or the patient's written authorization. The destination is created disabled, and ChartVoyant generates its signing key.
- ChartVoyant reads your CapabilityStatement
Every hour once your server can be reached: the FHIR version, batch and transaction support, and conditional create. A destination moves to testing only after a check in the last day.
- A clinician links the patient
See Patient matching. Without a confirmed link, nothing is sent.
- A clinician previews and sends
The preview lists the patient's final and amended observations. Anything that must not leave is withheld, and the preview says only "Some items were withheld", with no reason and no count.
- Each item is tracked
A temporary failure (HTTP 408, 425, 429, a 5xx, or a network error) is retried after 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours and 12 hours, at most eight tries within 48 hours. Other refusals and conflicts are marked failed at once. ChartVoyant keeps a hash of what it sent, not the body, and the practice can list everything sent for a patient.
Patient matching
- Search, then confirm by hand. ChartVoyant searches Patient by identifier. One certain match becomes a proposal that a person confirms. Several become candidates a person chooses from. None stops.
- Saved links are checked again. When a clinician returns to a saved link, ChartVoyant re-reads that Patient from your server and compares family name and birth date. A mismatch revokes the link, and nothing more is sent on it.
- No Patient create. There is no path that creates a patient on your server, and no setting that adds one.
What your server sees
Synthetic placeholders throughout. The scope is the one the practice set for your destination, limited to the writes its profile allows.
Token request
POST YOUR_TOKEN_ENDPOINT Content-Type: application/x-www-form-urlencoded grant_type=client_credentials &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer &client_assertion=SIGNED_JWT &scope=system%2FObservation.c
Create an observation (where conditional create is allowed)
POST YOUR_FHIR_BASE/Observation
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/fhir+json
If-None-Exist: identifier=urn:chartvoyant:send:PRACTICE_ID|observations:OBSERVATION_ID
{
"resourceType": "Observation",
"status": "final",
"code": { "coding": [{ "code": "8867-4", "system": "http://loinc.org" }] },
"identifier": [{ "system": "urn:chartvoyant:send:PRACTICE_ID", "value": "observations:OBSERVATION_ID" }],
"subject": { "reference": "Patient/YOUR_PATIENT_ID" },
"effectiveDateTime": "2026-10-28T15:00:00.000Z",
"valueQuantity": { "value": 72, "unit": "/min" }
}
The identifier is stable, so a resend finds the same resource instead of making a second one. A later amendment is a PUT to the id you returned, with If-Match on the version you returned. Notes and ChartVoyant's own metadata stay off the wire.
What is sent, and what never is
| Rule | Detail |
|---|---|
| Sent | Final and amended observations that the practice itself recorded. |
| Never sent | Anything that came from outside the practice (HL7 results, app submissions, faxes, imported records), anything an AI produced, and records a clinician marked sensitive: substance use disorder records under 42 CFR Part 2, psychotherapy, behavioral health and reproductive health. There is no override. |
| Stops the send | A missing provider NPI for a treatment destination, a missing patient link, a restriction or opt-out the patient asked for, or a written authorization that is missing, expired or revoked. The clinician sees one plain sentence. |
| Refused purposes | Payment and health care operations. |
How to get connected
- Tell us about your server
Email info@chartvoyant.com with your organization, the practice that wants to send to you, your FHIR base and token endpoint, whether you support
Patient/$match, and a technical contact. Send no patient data. - Sign the agreement
An executed agreement for the destination, plus a business associate agreement when an intermediary such as an HIE sits in the path. Agreements carry an expiry; when one lapses, the destination stops.
- Register our public key
Register ChartVoyant as a backend client using the JWKS address we give you, with the scopes you will allow.
- Test, then go live
Synthetic sends go to a ChartVoyant test server. ChartVoyant sends to your server once real-data sending is turned on for your destination, after the agreement is executed and independent security testing covers this path. We confirm what your server needs before the first send, so it works the first time.