Skip to main content
Most of the API serves our synced copy of the practice’s data. It is fast, but a note signed or a file uploaded a few minutes ago may not be there yet. The /v4/ehr endpoints read live from the practice’s EHR instead, the same way on ModMed (EMA) and EZDerm. They are read-only: nothing you read here is saved to our copy, and nothing here changes the synced endpoints.

​
Patient reads

All patient routes live under GET /v4/ehr/patients/{patientId}/…. patientId is our pat_ id (find a patient the EHR knows but we have not synced yet with POST /v4/patients/match).

​
id and ref

Every item in a list carries two identifiers:
  • id — our id (apt_, nte_, pol_, …) when our synced copy already has the record, otherwise null.
  • ref — an opaque token that always works for the sub-routes above. It is tied to this patient: a ref from one patient’s chart returns 404 on another patient’s route.
Sub-routes accept either. Store id when you want to join with synced data; pass ref back to read further.

​
Other reads

​
Responses

Every JSON read returns the usual envelope with a meta block:
  • completeness is lower_bound when the EHR’s list was cut short; what you got is real, but there may be more.
  • actingAs is user when the read ran on the signed-in user’s own EHR login (send X-Session-Token), otherwise system.

​
Slow reads: 202

A JSON read that takes longer than 8 seconds answers 202 Accepted with a Location header (/v4/ehr/reads/{readId}) and Retry-After. Poll that URL: it answers 202 while the read is running and the full response once it is done. Results are kept for 10 minutes and only your app, organization and signed-in user can read them. If the read was interrupted (for example by a deploy) the poll answers 502 ehr_unavailable: start the read again. EZDerm practice logins are slow (one request every 2 seconds), so expect 202 on EZDerm unless you send X-Session-Token. File routes (final-pdf, documents/{ref}/content, consents/{consentRef}/pdf) never answer 202: they stream the bytes within 55 seconds and answer 413 above 25 MB.

​
Capabilities

Not every EHR offers every read. Unsupported reads answer 501 capability_unsupported before any call to the EHR; read GET /v4/ehr/capabilities once and hide those features instead of calling them. Today EZDerm does not offer lab-results, consent PDFs or merge-history. Each instance also reports connected: whether the practice’s own connection to that EHR is live. When it is false (the connection is paused or signed out), reads without X-Session-Token answer 503 ehr_unavailable; a signed-in user’s own EHR login may still read.

​
Limits

Live reads draw from your app’s share of the practice’s EHR rate. Over it, reads answer 429 with Retry-After. Facility-limited API keys cannot use /v4/ehr.