Developers · Standards-based API
FHIR R4 API
A standards-based FHIR R4 server for each practice, conforming to US Core 6.1. Apps authorized with SMART on FHIR read and search a patient's record, or a practice's records with a backend token.
At a glance
| Status | Live in production. Read-only: create, update, patch, delete, batch and transaction are not supported. |
| Base URL | https://fhir.chartvoyant.com/r4/{practice}, one base per practice. Find each practice's exact base in the practice endpoint directory. |
| Standards | FHIR R4 (4.0.1), US Core 6.1.0, SMART App Launch 2, Bulk Data 2.0. |
| Authentication | A SMART access token: patient or clinician apps, or backend services. Discovery documents are public. |
| Format | application/fhir+json. Errors are FHIR OperationOutcome resources. |
| Cost | No fee to patients, practices or developers, and no revenue share. |
Live, with certification in progress
The FHIR and authorization hosts are live in production. ONC certification is in progress and ChartVoyant is not yet CHPL-listed. An internal security assessment has been completed with follow-up remediation ongoing; an independent external security review has not been completed. Access requires an enabled practice, a registered app and the right patient or practice authorization.
Endpoints
Relative to a practice's FHIR base.
| Path | What it does | Auth |
|---|---|---|
| GET /metadata | The CapabilityStatement: supported resources, interactions, search parameters and profiles. It is authoritative. | None |
| GET /.well-known/smart-configuration | SMART discovery: authorization endpoints, scopes and capabilities. | None |
| GET /{Type}?… | Search a supported type. A searchset Bundle; follow link[next] until it is absent. | Token |
| POST /{Type}/_search | The same search with the parameters form-encoded in the body. | Token |
| GET /{Type}/{id} | Read one resource. | Token |
| GET /Patient/{id}/$everything | A Bundle of the patient's core resources. Needs a complete-chart grant. | Token |
| GET /DocumentReference/$docref | US Core document operation: existing documents, or the current on-demand CCD (LOINC 34133-9, beta). | Token |
| GET /DocumentReference/{id}/$attachment | The original bytes of a stored document, under that document's grant. | Token |
| GET /Group, /Group/{id}/$export | Bulk export of the practice's population. See Bulk Data. | Backend token |
Supported resources and operations
Every type below supports read and search-type, each with its US Core 6.1 profile declared in the CapabilityStatement. Searches require a patient context: a patient token supplies it, and a clinician or backend token names the patient with patient (or _id for Patient).
AllergyIntoleranceCarePlanCareTeamConditionCoverageDeviceDiagnosticReportDocumentReferenceEncounterEndpointGoalImmunizationLocationMedicationMedicationDispenseMedicationRequestObservationOrganizationPatientPractitionerPractitionerRoleProcedureProvenanceQuestionnaireResponseRelatedPersonServiceRequestSpecimen
- Common search parameters.
_idand_lastUpdated, plus type-specific parameters such ascategory,code,dateandstatus. Dates take FHIR prefixes such asge,gt,leandlt. The full guide lists every parameter. - Includes.
_include=MedicationRequest:medication, and_revinclude=Provenance:targeton every type except Provenance. Included resources need their own granted scope. - Finer-grained scopes are enforced. A grant such as
patient/Observation.rs?category=…|laboratoryreturns the labs and not the vitals, on search and on read. - Group is available to backend tokens only, for Bulk Data.
- Not supported: writes of any kind,
_history, subscriptions, and document profile filters on$docref.
Example
Synthetic values throughout. Replace the placeholders with your discovered base and your token.
Discovery (no token)
GET https://fhir.chartvoyant.com/r4/your-practice/metadata Accept: application/fhir+json
Search
GET https://fhir.chartvoyant.com/r4/your-practice/Observation?patient=PATIENT_ID&category=laboratory&date=ge2026-01-01&_count=50 Authorization: Bearer ACCESS_TOKEN Accept: application/fhir+json
Response (abridged, synthetic)
{
"resourceType": "Bundle",
"type": "searchset",
"total": 1,
"entry": [{
"resource": {
"resourceType": "Observation",
"id": "EXAMPLE_ID",
"meta": { "profile": ["http://hl7.org/fhir/us/core/StructureDefinition/us-core-observation-lab"] },
"status": "final",
"category": [{ "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "laboratory" }] }],
"code": { "coding": [{ "system": "http://loinc.org", "code": "2345-7", "display": "Glucose" }] },
"subject": { "reference": "Patient/PATIENT_ID" },
"valueQuantity": { "value": 95, "unit": "mg/dL" }
},
"search": { "mode": "match" }
}]
}
Limits and errors
| Scope | Burst | Sustained |
|---|---|---|
| Per principal (token) | 300 requests / second | 9,000 requests / minute |
| Per practice | 600 requests / second | 18,000 requests / minute |
An IP budget also applies. A 429 carries Retry-After. Use paging and Bulk Data for large authorized reads. Higher limits are free on request at info@chartvoyant.com.
| Code | What to do |
|---|---|
| 401 | Supply a valid, current bearer token; reauthorize if it was revoked. |
| 403 | The request is outside the granted scope, patient, practice or enabled policy. |
| 404 | The resource or interaction is unavailable. Do not infer that another patient exists. |
| 429 | Wait for Retry-After and reduce concurrency. |
How to get access
- Read the guide
The full SMART on FHIR-4 developer guide and the public practice directory need no account, payment or agreement.
- Request registration
Email info@chartvoyant.com or use the support form with the details your app needs. Send no patient records, private keys or client secrets.
- We register and enable it
We apply the same identity and configuration checks to every developer, and register and enable a complete eligible request within five business days. If something is missing, we tell you what.
- Authorize and connect
A patient or clinician authorizes your app at sign-in. Then call the practice's FHIR base with the access token.
No fee
There is no fee to patients, practices or app developers for the standardized FHIR API, registration, testing, production access, calls or Bulk Data, and no revenue share. The API Use Agreement and profit share for the separate ChartVoyant API do not apply here.