Developers · Standards-based API

SMART write

NewTurned on per practice and app

An approved SMART app sends new information to a patient's chart through the FHIR API: a reading, a survey score, an allergy, a health concern, a medicine the patient takes, a vaccine, a document, or answers to the practice's questionnaire. Nothing an app sends becomes part of the chart until a clinician accepts it. Write interactions are not part of the certified read API.

POSThttps://fhir.chartvoyant.com/r4/{practice}/{Type}docs below

Status

StatusDeployed in production on October 29, 2026, and turned on per practice and per app. A practice's /metadata lists create and update only for the types that practice and an app allow, and discovery lists write scopes once ChartVoyant's submission service is on. The general CapabilityStatement at https://chartvoyant.com/api/v1/fhir/metadata shows every type an office may opt in to.
Three switchesAll three must be on: ChartVoyant's service switch for submissions; the practice's own setting, "Allow connected apps to send information to charts", which a practice administrator controls; and writing turned on for your app at that practice, for the types the practice approves. Turning any of them off stops new writes at once, checked on every request.
ConsentThe person approving your app sees "Add information to your health record", with one box per type. Write boxes start unchecked.
TokensAn access token that carries a write scope lasts 300 seconds. Read-only tokens keep their 3,600 seconds.
Rate30 writes per minute for each app at each practice. Past that, 429 with Retry-After: 60.
EndpointThe practice's FHIR base, https://fhir.chartvoyant.com/r4/{practice}, with POST /{Type} and PUT /{Type}/{id}.

Scopes

Create and update use SMART App Launch v2 scopes. The context is patient, user, or system. The permission is .c to create, .u to update, or .cu for both.

RequestResult
patient/Observation.cuThe patient app may send or update an Observation, after the person checks that box.
patient/Observation.c?category=…|vital-signsThe same, fenced to one category. A body outside the fence is 403. Category fences work on Observation and Condition.
user/Condition.cA clinician app may send a new health concern for a chart in the practice.
system/Immunization.cuA backend client may send or update an immunization the practice has allowed.
SMART v1 .write or .*Refused.
Delete, including the letter dRefused. The app cannot delete information.
A wildcard type, such as patient/*.cRefused. Name each type.
AppointmentRefused. Appointment is not a writable type.

The office and the app both have to allow the type, and the service has to allow submissions. A scope a token does not carry is 403, even when the app is registered for it.

Writable types

TypeAcceptedWhen a clinician accepts it
ObservationCategory vital-signs or survey, with a LOINC code. Vital signs carry UCUM units; blood pressure is one observation with systolic and diastolic components in mm[Hg]. Laboratory, imaging and social-history are refused; labs arrive through HL7.A chart observation.
AllergyIntoleranceA coded allergy. Verification status is set to unconfirmed on intake.An unconfirmed allergy until a clinician confirms it.
ConditionCategory problem-list-item or health-concern, coded in SNOMED CT or ICD-10-CM. encounter-diagnosis is refused.An unconfirmed problem or health concern.
MedicationStatementAn RxNorm-coded medicine the patient says they take. Write only: it is not a read type.A patient-reported medicine, never a prescription.
ImmunizationA CVX-coded vaccine.Immunization history. It is not sent to a state registry.
DocumentReferenceAn inline attachment (content.attachment.data) of PDF, PNG, JPEG or plain text, up to 5 MiB. A URL is refused and never fetched. A PDF that carries script is refused and not stored.A file with the chart's documents.
QuestionnaireResponseAnswers to a questionnaire the practice publishes.Answers on the intake record, marked as from an app. They are not scored and do not change demographics.

Every other type is refused for writing, including Patient, Encounter, MedicationRequest, DiagnosticReport, Procedure, CarePlan, Goal, Provenance and Appointment.

Review before the chart

A successful create stores a submission. It does not change the chart. A clinician accepts it (correcting a reading's value first if needed) or rejects it with a reason, or the sender withdraws it. Nothing reads a pending submission to make a decision: no alert, rule, AI summary or order.

Until it is accepted, other apps do not see it in search, $everything, Bulk Data, C-CDA, or a complete EHI export. Once accepted, it appears in all of them, and the FHIR id your app received keeps working. A rejected submission reads as entered-in-error to the app that sent it and to the patient.

The patient, and a person who is a proxy for that patient, can see every status in the portal: waiting, accepted, not added, and withdrawn. A proxy for a different patient sees none. A patient's records request lists their submissions with the same status words.

Pending submissions are labelled "Sent by the app name. Waiting for your care team to review."

If-Match and If-None-Exist

Create is POST {base}/{Type} with Content-Type: application/fhir+json. Conditional create uses If-None-Exist and only the identifier parameter. One existing match returns that resource. More than one match is 412.

Update is PUT {base}/{Type}/{id} and requires If-Match: W/"n". A missing header is 428. A stale version is 412. Conditional update is not supported.

Only the app that sent a pending submission can update it. Updating an accepted resource proposes a new submission. The chart row stays as it is until a clinician reviews the proposal. Delete, PATCH, history, batch and transaction are not supported.

Errors

Errors are an OperationOutcome. The diagnostics text does not include the submitted record.

HTTPWhen
400Malformed JSON, wrong resourceType, or an id mismatch on PUT.
401No token, or the token is invalid.
403Scope, compartment, office switch, app switch, or a category outside the scope's fence.
404Unknown id, or not visible to this client.
405Unsupported interaction, including delete.
409Business conflict, such as updating a withdrawn submission.
412Stale If-Match, or an ambiguous conditional create.
413Body or attachment too large.
415Not application/fhir+json.
422Profile or terminology validation failed.
428Missing If-Match on update.
429Rate limited. The response includes Retry-After.

Unverified tag

A submission carries meta.tag with system https://chartvoyant.com/fhir/CodeSystem/data-status and code app-submitted-unverified. That tag means a clinician has not accepted it yet. Do not treat a tagged resource as chart fact.

Every write is recorded with a Provenance that names your app as the transmitter, and an accepted item adds the reviewing clinician as the verifier. Each write is also recorded in the practice's audit trail in the same transaction; if that record cannot be written, the write fails and nothing is stored.

Full access, and what is not offered

Full access. A practice administrator can give one app every write scope this server implements in a single step, after an authenticator code and typing the app's name. It adds no read scopes and grants nothing to a SMART v1 registration. A user or system app needs an executed agreement with an expiry on file, and a patient app needs a recorded security review. Turning it off revokes the app's tokens at that practice. It must be confirmed again every 12 months, and it is capped at 500 writes a day. It has its own service switch, separate from the one for submissions.

Filing without review. Not offered. Every submission waits for a clinician, including from a practice's own apps.

Example

Synthetic only. This is not a real patient and not a real reading.

POST https://fhir.chartvoyant.com/r4/example-practice/Observation
Authorization: Bearer {access_token}
Content-Type: application/fhir+json
If-None-Exist: identifier=https://synthetic.example/hr|hr-1

{
  "resourceType": "Observation",
  "status": "final",
  "category": [{ "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "vital-signs" }] }],
  "code": { "coding": [{ "system": "http://loinc.org", "code": "8867-4", "display": "Heart rate" }] },
  "subject": { "reference": "Patient/00000000-0000-4000-8000-0000000000b1" },
  "effectiveDateTime": "2026-10-28T15:00:00Z",
  "valueQuantity": { "value": 72, "unit": "beats/minute", "system": "http://unitsofmeasure.org", "code": "/min" },
  "identifier": [{ "system": "https://synthetic.example/hr", "value": "hr-1" }]
}

A create that is stored returns 201, a Location, and ETag: W/"1". The chart does not yet contain that heart rate. A later update sends If-Match: W/"1".

This is not part of the certified read API.