OpenEMR API Integration Guide: FHIR, REST and HL7 (2026)
CTO & Co-Founder
CTO & Co-Founder at Nirmitee.io. Architects healthcare integrations across FHIR, SMART on FHIR, ABDM and NHCX, writing from production experience taking hospital software from sandbox to go-live.

OpenEMR is a free, open source electronic health record and practice management system, released under the GNU GPL. Its API is open source under GPL 3. The newest release is 8.5.0, published on Oct 27, 2026. OpenEMR 8 holds ONC certification, number 15.05.05.3115.OPEN.02.01.1.260130, dated Jan 30, 2026.
This guide is for a buyer or product lead who has to connect a product to OpenEMR, and for the engineer who will build it. You get who grants access, every route, the endpoints you can read and write, and the published limits, with real requests and responses from a clean OpenEMR 8.5.0 install. Where OpenEMR publishes nothing, we say so and list what to ask before you commit. Last checked Nov 18, 2026.
OpenEMR API at a glance
| Question | Short answer |
|---|---|
| Who grants access? | The practice or host that runs the OpenEMR server. Its admin turns the APIs on and enables each app. There is no vendor to apply to. |
| Who signs? | OpenEMR publishes no contract or signing step for API access. Any business associate agreement is between you and the practice or its host. |
| Are there public documents? | Yes. API guides in the GitHub repo, a Swagger file with 225 operations, and Swagger UI on every install. |
| Which routes exist? | FHIR R4 with SMART on FHIR and bulk export, a Standard REST API, an experimental patient portal API, HL7 v2 for labs and public health, C-CDA on demand, Direct messaging and X12 billing. |
| What does it cost? | No fee for the software or the API. ONC-certified Direct messaging through EMR Direct costs about $300 setup plus about $150 per provider per year. |
| How long does it take? | OpenEMR publishes no build or approval time for provider and system apps. Patient apps are approved at once in the default mode. |
| What is the biggest limit? | No FHIR DELETE, no Subscription and no webhooks, so you poll for changes. No rate limit or page size is published. |
What can you build with the OpenEMR API?
Nine use cases follow. Each points to a row in the read and write tables in section 6. OpenEMR publishes no build times, so this guide gives no build estimate. Build complexity is our own rating.
1. Launch a clinical app inside the OpenEMR chart
- Who it is for: clinical decision support, care gap and specialty workflow companies.
- The value: a clinician opens your app from the patient chart, already signed in and on the right patient.
- Build complexity: medium.
- How well it works: well. OpenEMR supports SMART App Launch v2.2.0 and the EHR launch grant. An enabled app shows in the Patient Summary "SMART Enabled Apps" widget. When no patient is selected, the flow makes the user pick one. See rows F1 to F6.
2. Give patients their records in a consumer app
- Who it is for: patient engagement, personal health record and caregiver apps.
- The value: patients connect your app to their practice and see their own data.
- Build complexity: low to medium.
- How well it works: well. In the default Automatic mode, patient standalone apps that use only
patient/*scopes are approved at once. The docs point patient apps to FHIR withpatient/*scopes over the experimental portal API. See rows F1 to F6.
3. Export a population for analytics or value-based care
- Who it is for: analytics, quality reporting and value-based care companies.
- The value: you pull all patients, or one provider's panel, in one job and refresh it with
_since. - Build complexity: medium.
- How well it works: well for system-to-system loads. Bulk export runs at system, Patient and Group level, returns NDJSON, and uses client credentials with JWKS. A Group exists for each practitioner, holding the patients who have that practitioner as primary care provider. See row F8.
4. Write vitals from a remote monitoring device
- Who it is for: remote patient monitoring and connected device companies.
- The value: readings land in the chart without retyping.
- Build complexity: medium.
- How well it works: works, with a shape to respect. FHIR Observation accepts create and update. A vital sign must reference an Encounter, because OpenEMR stores vitals as an encounter form. Reading back returns the whole vitals form, so one heart rate came back as 15 Observations. See rows F3 and F4.
5. Register patients from an intake or scheduling front end
- Who it is for: digital front door, intake form and booking companies.
- The value: new patients are created in OpenEMR without front desk typing.
- Build complexity: low to medium.
- How well it works: well. Both the Standard API and FHIR create patients, and FHIR search finds a patient made through either. FHIR Appointment supports create but not update, and the Standard API creates and deletes appointments. See rows F3, S1 and S4.
6. Send lab orders and receive results
- Who it is for: reference labs, lab networks and lab connectivity vendors.
- The value: orders leave the chart electronically and results file back to the patient.
- Build complexity: medium to high.
- How well it works: well, over HL7 v2. Orders go out as HL7 v2.3 ORM^O01. Results come in as ORU^R01, and the code handles 2.3 and 2.5 forms. Transport is set per lab, with download and SFTP in the code. See row H1 and H2.
7. Report immunizations to a state registry
- Who it is for: public health connectivity vendors and practices that report.
- The value: shots given in the clinic reach the registry.
- Build complexity: medium.
- How well it works: well for outbound reporting. OpenEMR builds HL7 v2.5.1 VXU^V04 messages. FHIR Immunization also supports read, create and update. See row H3 and F3.
8. Pull a care summary for a referral or transition
- Who it is for: referral management, care coordination and HIE connection vendors.
- The value: a receiving provider gets a standard summary of the patient.
- Build complexity: low to medium.
- How well it works: well.
POST /fhir/DocumentReference/$docrefreturns a Continuity of Care Document for a patient and a date range. Referrals are read-only over FHIR, and the Standard API saves them as transactions. It cannot close a referral. See rows F7 and S6.
9. Feed billing or claims software
- Who it is for: revenue cycle and clearinghouse companies.
- The value: coverage and encounter data reach the billing system.
- Build complexity: medium.
- How well it works: works through several routes. FHIR Coverage supports read, create and update. OpenEMR's own billing supports X12 5010, and a ClaimRev clearinghouse module exists for claims and eligibility. See rows F3, S5 and H5.
The nine OpenEMR use cases compared
| Use case | Who it is for | Build complexity (our rating) | Rows |
|---|---|---|---|
| 1. Launch a clinical app inside the chart | Decision support and specialty workflow companies | Medium | F1 to F6 |
| 2. Give patients their records in a consumer app | Patient engagement and PHR apps | Low to medium | F1 to F6 |
| 3. Export a population for analytics | Analytics and value-based care companies | Medium | F8 |
| 4. Write vitals from a monitoring device | Remote monitoring and device companies | Medium | F3, F4 |
| 5. Register patients from intake or scheduling | Front door, intake and booking companies | Low to medium | F3, S1, S4 |
| 6. Send lab orders and receive results | Labs and lab connectivity vendors | Medium to high | H1, H2 |
| 7. Report immunizations to a registry | Public health vendors and practices | Medium | H3, F3 |
| 8. Pull a care summary for a referral | Referral and care coordination vendors | Low to medium | F7, S6 |
| 9. Feed billing or claims software | Revenue cycle and clearinghouse companies | Medium | F3, S5, H5 |
How do you get access to the OpenEMR API?
The practice or host that runs the OpenEMR server grants access. Its admin turns the APIs on and enables your app.
The three API switches
An admin turns each API on under Administration, Config, Connectors.
| Switch | Base path | Status |
|---|---|---|
| Enable OpenEMR Standard REST API | /apis/{site}/api | Supported |
| Enable OpenEMR Standard FHIR REST API | /apis/{site}/fhir | Supported |
| Enable OpenEMR Patient Portal REST API | /apis/{site}/portal | Marked EXPERIMENTAL |
TLS is required for all OAuth2 calls, and the Site Address must be set for OAuth2 and FHIR. On a clean 8.5.0 install all three switches and the password grant are off.
The steps
- The admin turns on the APIs and sets the Site Address.
- You register the app. Use OAuth2 dynamic client registration at
POST /oauth2/{site}/registration. SMART apps can also use the web form at/interface/smart/register-app.php. Registration needs no login. - The admin enables the app under Administration, System, API Clients. Until then, token requests fail with
invalid_client. - The user or patient signs in and consents. You get a token with the grant your app uses.
Which apps need a person to approve them
In Automatic mode, the default, patient standalone apps that use only patient/* scopes are approved at once. Provider and system apps need manual approval. In Manual mode every app needs admin approval. The docs say Manual mode needs monitoring so patient apps are approved within 48 hours under the Cures Act.
Patients get Portal API credentials only when their clinician generates them from the demographics screen.
Grants and scopes
OpenEMR supports authorization code (with PKCE for public apps), EHR launch, standalone launch, client credentials with JWKS, refresh token, and the password grant. The password grant is off by default, has no consent screen and gives no refresh token for the patient role. In 8.5.0 it is an admin-only grant. A self-registered app that asks for it is stored with only authorization_code|refresh_token. An admin turns it on per client in Administration, System, API Clients, with allow password grant.
Scopes start with openid plus api:oemr for the Standard API or api:fhir for FHIR, then resource scopes. SMART v2 .cruds syntax and the older .read and .write both work.
What OpenEMR does not publish about access
OpenEMR publishes no contract, data use terms or signing step for API access.
Ask the practice or its host:
- Which OpenEMR version and site name do you run?
- Which approval mode is set, and who enables provider and system apps?
- Who signs the business associate agreement with us?
- Is the password grant allowed, and for which users?
What does OpenEMR API access give you?
Access gives you a client on one OpenEMR server, with the scopes the admin allows. There is no vendor sandbox or production split. Test and production are whatever installs you or the practice run.
Environments you can use
| Environment | What it is | Watch out for |
|---|---|---|
| Public demos | Daily builds at eleven.openemr.io (PHP 8.5), seven.openemr.io (PHP 8.4) and one.openemr.io (PHP 8.3). Add /a/openemr for the copy with demo data. | They reset daily at 8:30 UTC, and the reset takes about 30 to 120 minutes. eleven.openemr.io showed API version 8.6.0, which is unreleased code. |
| Your own install | Any OpenEMR release you run, for example in Docker. | Self-signed certificates need curl -k. |
| The practice's server | The production install, with its own site name. | Your app must be enabled on it separately. |
Demo logins are admin / pass. With demo data there are also physician, clinician, accountant and receptionist users, with the password the same as the user name. Portal logins are Phil1 / phil and Susan2 / susan.
Every install has Swagger UI at /swagger/. A client used from Swagger must set the redirect URI <base>/swagger/oauth2-redirect.html.
Standards the FHIR API states
OpenEMR states FHIR R4 (4.0.1), US Core 8.0, SMART App Launch v2.2.0, Bulk Data v2.0.0 and USCDI v5, in both master and 8.5.0. The admin can cap the advertised US Core version at 3.1, 7.0 or 8.0.
Discovery without a token
The CapabilityStatement at /fhir/metadata needs no token. On a clean 8.5.0 install it answered with fhirVersion 4.0.1 and 35 resource types. The SMART discovery document is at /fhir/.well-known/smart-configuration.
Certification
The OpenEMR 8 certificate covers 170.315 (b)(1), (b)(10), (b)(11), (g)(2) to (g)(7), (g)(9), (g)(10) and (h)(1). A certified install must set SHA512 hashing, audit log encryption and the FHIR REST API on. OpenEMR 7.0 certification was retired on Feb 27, 2026.
The OpenEMR Foundation publishes the FHIR base URLs of certified installs, as a table and as a FHIR Bundle. On Nov 18, 2026 it listed 6 production and 3 test endpoints. A practice joins the list by emailing the Foundation with the subject "ONC registration", its organization name, location, NPI and FHIR endpoint. The Foundation posts it within 10 days.
What are the ways to integrate with OpenEMR?
OpenEMR offers FHIR R4, a Standard REST API, an experimental portal API, HL7 v2 for labs and public health, C-CDA on demand, Direct messaging and X12 billing.
| Route | What OpenEMR documents | Fits when |
|---|---|---|
| FHIR R4 API | https://{host}/apis/{site}/fhir, US Core 8.0, SMART on FHIR. | You want a standard API that also works with other EHRs. |
| Bulk FHIR export | $export at system, Patient and Group level, NDJSON output, client credentials with JWKS. | You load many patients on a schedule. |
| Standard REST API | https://{host}/apis/{site}/api, OpenEMR's own JSON. | You need a write FHIR does not offer, such as a delete or a referral. |
| Patient Portal API | https://{host}/apis/{site}/portal, EXPERIMENTAL, read-only Patient, Encounter and Appointment. | Rarely. The docs say to use FHIR with patient/* scopes instead. |
| C-CDA on demand | POST /fhir/DocumentReference/$docref returns a CCD. | You need a standard care summary document. |
| HL7 v2 | Lab orders, lab results, immunization reporting and syndromic surveillance. | You connect a lab or a public health agency. |
| Direct messaging | Send and receive records. ONC certification needs the EMR Direct phimail service. | You exchange records with other providers by secure email. |
| X12 billing | Integrated billing on X12 5010, and a ClaimRev clearinghouse module. | Claims and eligibility run through OpenEMR's own billing. |
HL7 v2 messages in the 8.5.0 code
| Message | Direction | Version | Used for |
|---|---|---|---|
| ORM^O01 | Out | 2.3 | Lab orders |
| ORU^R01 | In | 2.3 and 2.5 forms | Lab results |
| VXU^V04 | Out | 2.5.1 | Immunization reporting |
| ADT^A01 | Out | 2.5.1 | Syndromic surveillance |
No document describes a general inbound HL7 v2 ADT or scheduling (SIU) interface.
Multisite installs put the site name in every path, as in /apis/{site}/fhir/Patient and /oauth2/{site}/. Most installs use default.
Want a second opinion on the route before you start? See our EHR integration service.
What can you read and write with the OpenEMR API?
FHIR reads and searches 35 resource types and writes 23 of them. The Standard API adds writes FHIR lacks. The Swagger file lists 225 operations: 135 GET, 44 POST, 37 PUT and 9 DELETE, the same in 8.5.0 and master.
FHIR R4 endpoints
| Row | Method and path | What it does |
|---|---|---|
| F1 | GET /fhir/metadata | CapabilityStatement, no token needed. |
| F2 | GET /fhir/.well-known/smart-configuration | SMART discovery. |
| F3 | GET, POST /fhir/{type} and PUT /fhir/{type}/{uuid} | Read, search, create and update. Create and update work on AllergyIntolerance, CarePlan, CareTeam, Condition, Coverage, Device, Encounter, Goal, Immunization, Medication, MedicationRequest, Observation, Organization, Patient, Person, Practitioner, PractitionerRole, Questionnaire, QuestionnaireResponse, RelatedPerson, ServiceRequest and Task. |
| F4 | GET /fhir/{type} and GET /fhir/{type}/{uuid} only | Read and search on Binary, DiagnosticReport, DocumentReference, Group, Location, Media, MedicationDispense, OperationDefinition, Procedure, Provenance, Specimen and ValueSet. |
| F5 | POST /fhir/Appointment | Create an appointment. There is no PUT. |
| F6 | GET /fhir/Observation?category= | Observations by category, including laboratory, vital signs, social history, SDOH and survey. Granular scopes can filter by category. |
| F7 | POST /fhir/DocumentReference/$docref | A CCD for a patient, start and end. Scopes DocumentReference.$docref, DocumentReference.read and Binary.read. |
| F8 | GET /fhir/$export, GET /fhir/Patient/$export, GET /fhir/Group/{id}/$export | Bulk export with _type and _since. Status at GET /fhir/$bulkdata-status, cancel with DELETE. |
FHIR accepts and returns application/fhir+json, application/json and application/fhir+xml. The capability statement on a clean 8.5.0 install lists the same 23 writable types, with Appointment as create only.
Standard REST API endpoints
All paths sit under /apis/{site}/api.
| Row | Area | Methods |
|---|---|---|
| S1 | Patient | POST /patient, PUT /patient/{puuid}, plus reads |
| S2 | Encounter, SOAP note and vitals | Create and update |
| S3 | Allergy, medical problem, medication, surgery, dental issue | Create, update and delete |
| S4 | Appointment | POST and DELETE |
| S5 | Insurance and insurance company | POST and PUT |
| S6 | Referral transaction /patient/{pid}/transaction | POST and PUT |
| S7 | Document, message, prescription | Document POST. Message POST, PUT, DELETE. Prescription POST, DELETE |
| S8 | Facility and practitioner | POST and PUT |
| S9 | Lists, users, employers, immunizations, procedures, drugs, insurance types, version | Read only |
Standard API responses wrap the data as {"validationErrors":[], "internalErrors":[], "data": ...}.
HL7 and other rows
| Row | Function | Direction |
|---|---|---|
| H1 | Lab order, HL7 v2.3 ORM^O01 | Out |
| H2 | Lab result, HL7 v2 ORU^R01 | In |
| H3 | Immunization report, HL7 v2.5.1 VXU^V04 | Out |
| H4 | Syndromic surveillance, HL7 v2.5.1 ADT^A01 | Out |
| H5 | Claims on X12 5010, ClaimRev module | Out |
What is not possible with the OpenEMR API?
You cannot delete over FHIR, you cannot subscribe to changes, and several clinical resources are read-only over FHIR. Most gaps have a workaround in the Standard API or in polling.
| Gap | What OpenEMR shows | Usual workaround |
|---|---|---|
| No FHIR DELETE | The only FHIR DELETE cancels a bulk export. | Use a Standard API delete where one exists, such as allergies or appointments. |
| No change notifications | No FHIR Subscription and no webhooks. | Poll searches, or run bulk export with _since. |
| Read-only FHIR resources | No FHIR write for DiagnosticReport, Procedure, DocumentReference (except $docref), Binary, Media, Specimen, MedicationDispense, Location, Provenance, Group and ValueSet. | Send lab results as HL7 v2 ORU^R01. Use the Standard API document endpoint for files. |
| No FHIR appointment update | Appointment has POST but no PUT. | Delete and create through the Standard API. |
| Referrals over FHIR | Read-only. POST and PUT /fhir/ServiceRequest write a procedure order. (Master docs.) | Save referrals with /api/patient/{pid}/transaction. |
| Closing a referral | The Standard API does not write the Reply Date. | Close it in the OpenEMR screen. |
| General inbound HL7 ADT or SIU | Not documented. | Use FHIR Patient and Appointment writes. |
| Password grant for U2F-only users | Users enrolled only in U2F cannot get a token this way. | Use the authorization code grant. |
What are the OpenEMR API limits?
OpenEMR publishes token lifetimes but no rate limit and no page size. The deployment checklist leaves rate limiting to the host.
| Limit | Value | Source |
|---|---|---|
| Access token, authorization code and EHR launch | expires_in: 3600 (1 hour) in the docs' examples | Docs. Measured as 3600 on 8.5.0 with the password grant. |
| Client credentials token | 60 seconds, no refresh token | Docs |
| JWT assertion for client credentials | exp at most 5 minutes after iat | Docs |
| Refresh token | Only when offline_access is requested | Docs |
| Refresh token lifetime | Not published | Ask the host |
| Rate limits | Not published. The checklist says only "Rate limiting configured". | Ask the host |
Maximum _count for FHIR search | Not published. _count=10 appears in an example only. | Test on the target server |
| Failed password-grant logins | Count toward the standard lockout counters | Docs |
| Demo data | Gone at the 8:30 UTC daily reset | Wiki |
Because client credentials tokens last 60 seconds, plan for a bulk export job to request a fresh token for each step.
How much does OpenEMR API integration cost?
The software and the API are free. The costs you meet are hosting, support and the services certification names.
| Item | Cost | Source |
|---|---|---|
| OpenEMR and its API | No fee, GPL licensed | OpenEMR wiki |
| EMR Direct phimail, needed for ONC-certified Direct messaging | About $300 setup plus about $150 per provider per year | OpenEMR wiki |
| EMR Direct Interoperability Engine 2017 and AccessGUDID v2, listed as additional software in certification | Not published | OpenEMR wiki |
| Hosting, for example AWS Express Plus | Not published in the Foundation's post | Ask, or read the AWS Marketplace listing |
| Professional support | Varies by vendor. See below. | Vendor pages |
The Foundation's Professional Support page listed 21 vendors in three tiers on Nov 18, 2026. It says entries met "a strict set of criteria" and contribute financially. It does not say it reviews their work. Two vendors state prices or times for their own service:
- Tarevo states ongoing support at $2,500 to $3,000 a month and "Go-live in 45 days".
- AcuMedSoft states it can "Set up your OpenEMR in less than 24 hrs".
Both lines are the vendor's own statement about its service.
How long does an OpenEMR API integration take?
OpenEMR publishes two waits and no build time.
| Step | Time | Source |
|---|---|---|
| Patient app approval, Automatic mode | At once, for patient/* scopes only | Docs |
| Patient app approval, Manual mode | Within 48 hours, under the Cures Act note in the docs | Docs |
| Provider and system app approval | Set by each practice's admin. Not published. | Ask the practice |
| Listing in the certified endpoint directory | Within 10 days of the email to the Foundation | Wiki |
| Build, test and go-live | Not published by OpenEMR | Only vendor statements, see section 9 |
The release pace also sets your test work. 2026 has had seven releases so far: 8.0.0.2 (18 Mar), 8.0.0.3 (25 Mar), 8.2.0 (8 Jul), 8.3.0 (18 Aug), 8.4.0 (13 Sep), 8.4.1 (20 Sep) and 8.5.0 (27 Oct).
How do you build an OpenEMR API integration, step by step?
Turn on the API, register, get the app enabled, get a token, then read and write. Every request and response below comes from a clean OpenEMR 8.5.0 install with MariaDB 11.4 and test data only. Secrets and tokens are removed.
Step 1. Check the server without a token
curl -k https://localhost:9300/apis/default/fhir/metadata
The answer is a CapabilityStatement with "fhirVersion": "4.0.1", software name OpenEMR and 35 resource types.
Step 2. Register the app
POST https://localhost:9300/oauth2/default/registration
Content-Type: application/json
{
"application_type": "private",
"redirect_uris": ["https://localhost/cb"],
"client_name": "poc",
"grant_types": ["password", "authorization_code", "refresh_token"],
"token_endpoint_auth_method": "client_secret_post",
"scope": "openid offline_access api:oemr api:fhir user/Patient.read user/Patient.write user/patient.read user/patient.write user/Observation.read user/Observation.write"
}
The response, with the secret and the registration token removed:
{
"client_id": "<client id>",
"client_secret": "<removed>",
"registration_access_token": "<removed>",
"registration_client_uri": "https://localhost:9300/oauth2/default/client/<id>",
"client_secret_expires_at": 0,
"client_role": "user",
"application_type": "private",
"client_name": "poc",
"token_endpoint_auth_method": "client_secret_post",
"grant_types": ["authorization_code", "refresh_token"],
"dsi_type": "none"
}
The app asked for password, and the server dropped it. In 8.5.0 the password grant is admin-only.
Step 3. Try a token before the admin enables the app
POST https://localhost:9300/oauth2/default/token
grant_type=password&client_id=<client id>&client_secret=<secret>
&user_role=users&username=<user>&password=<password>&scope=<scopes>
{"error":"invalid_client","error_description":"Client authentication failed","message":"Client authentication failed"}
A new app is stored disabled (is_enabled=0). The admin enables it in Administration, System, API Clients. For the password grant, the admin also opens Administration, System, API Clients, edits the client and chooses allow password grant. Until then the call fails with "Grant type password is not registered for this client." Since 8.5.0, confidential clients on the password grant must send client_secret, or get 401 invalid_client.
Step 4. Get the token
After the admin step the same call returns a Bearer token with "expires_in": 3600 and a refresh token. The granted scope came back as:
openid offline_access user/Patient.read user/Patient.write user/patient.read user/patient.write user/Observation.read user/Observation.write
api:oemr and api:fhir are missing from the granted list, yet Standard API and FHIR calls both worked.
For production apps, use the authorization code grant with PKCE for public apps, or client credentials with JWKS for system jobs.
Step 5. Create a patient with the Standard API
POST /apis/default/api/patient
Authorization: Bearer <token>
Content-Type: application/json
{"title":"Mr","fname":"Test","lname":"Poc","DOB":"1980-01-15","sex":"Male",
"street":"1 Main St","postal_code":"10001","city":"New York","state":"NY",
"country_code":"US","phone_contact":"555-0100"}
HTTP 201
{"validationErrors":[],"internalErrors":[],"data":{"pid":1,"uuid":"a341063d-b473-423a-b041-0b6ec47c20de"},"links":[]}
GET /apis/default/fhir/Patient?family=Poc then returned total: 1.
Step 6. Create a patient with FHIR
Without name.use:
POST /apis/default/fhir/Patient
Content-Type: application/fhir+json
{"resourceType":"Patient","name":[{"family":"Fhirpoc","given":["Ann"]}],"gender":"female","birthDate":"1990-02-02"}
HTTP 400
{"validationErrors":{"fname":{"NotEmpty::EMPTY_VALUE":"First Name must not be empty"},"lname":{"NotEmpty::EMPTY_VALUE":"Last Name must not be empty"}}}
With "use":"official" on the name, the same body returns:
HTTP 201
{"pid":2,"uuid":"a341063e-0e32-45f0-8589-20336130c0a3"}
The 201 body is OpenEMR's own {pid, uuid}. It holds no FHIR Patient resource.
Step 7. Write a vital sign
A vital sign needs an Encounter first. Encounter create needs the user/Encounter.write scope, and without it the call returns HTTP 401 {"error":"An error occurred","message":"Unauthorized","code":0}. With the scope, POST /fhir/Encounter returns HTTP 201 with OpenEMR's internal encounter row (eid, euuid, pid and about 40 other fields).
Then the Observation. With no code:
HTTP 400
{"validationErrors":{"code":"Observation.code is required (FHIR R4 1..1)"}}
A vital sign with no encounter:
HTTP 400
{"validationErrors":{"encounter":"Observation.encounter must reference an Encounter; vitals are stored as an encounter form"}}
With a code and an encounter, a heart rate (LOINC 8867-4, 72 /min) returns:
HTTP 201
{"uuid":"a3410673-78a6-4ac4-a047-b5835808638b"}
Reading vital signs back for the patient returned 15 Observations: the whole vitals form, with 14 carrying no value.
Step 8. Keep in step
There are no webhooks, so schedule polling or a bulk export with _since. For bulk export, the job uses client credentials with JWKS, starts with GET /fhir/$export or a Group export, and checks GET /fhir/$bulkdata-status.
Which OpenEMR API quirks should you know?
Twelve details from the docs and from a clean 8.5.0 install can change a design or a test plan.
A new app is disabled, and the error hides it
Registration succeeds without a login, but the app is stored disabled. The first token call returns invalid_client / Client authentication failed, which reads like a wrong secret.
The password grant is silently dropped at registration
In 8.5.0 a self-registered app can ask for password, and OpenEMR stores only authorization_code|refresh_token. The token call then fails with "Grant type password is not registered for this client."
Confidential clients must send the secret on the password grant
Before 8.5.0 a client could leave the secret out. In 8.5.0 a request without it gets 401 invalid_client.
The granted scope list leaves out api:oemr and api:fhir
The token response did not list them, yet both APIs answered. Do not use the granted list alone to decide which API to call.
FHIR Patient create needs name.use
A name with no use fails with "First Name must not be empty" and "Last Name must not be empty". "use":"official" fixes it.
FHIR writes return OpenEMR's own shapes
Patient create returns {pid, uuid}, and Encounter create returns the internal encounter row. To get FHIR resources, read the resource back.
Vitals live inside an encounter form
A vital Observation must reference an Encounter. One reading comes back as the whole form, 15 Observations with 14 empty. Filter on a value before you show or compare.
IDs differ by endpoint
Standard API paths mix numeric ids ({pid}, {eid}) and UUIDs ({puuid}, {euuid}), for example /api/patient/{pid}/medication and /api/patient/{puuid}/allergy.
US Core versions conflict
The docs say US Core 3.1, 7.0 and 8.0 have profiles that conflict in some resources. That is why the admin can cap the advertised version. Check the cap on each server.
Referral writes fail quietly
On the Standard API, an NPI that matches no user is not an error, and on PUT the old recipient stays. PUT skips empty values, "0" included, so it cannot clear a field. A referral save succeeds even when making its FHIR Task fails, and the failure is only logged. (Master docs.)
Old docs still rank
Google's second open-emr.org FHIR result on Nov 18, 2026 was the "FHIR API Documentation for 7.0.2" page from 2024. The wiki Features page still says US Core 4.0.0, while the API docs say US Core 8.0. Read the docs at the tag of the release you target. On 7.0.3, FHIR wrote only Patient, Practitioner and Organization (plus DocumentReference create), and POST /fhir/Observation returned 404.
The 8.5.0 container does not wait for its database
If the database is not ready, the 8.5.0 container exits with "unable to connect to database as root". 7.0.3 waited. Make your Docker setup wait for a healthy database.
What should you check before you sign an OpenEMR integration?
Check the version, the certificate, security, consent and support with the practice or host. Then put the questions at the end of this section to them in writing.
Version and certificate
The certificate says "Version 8". No page states which 8.x minor releases are in scope. The OpenEMR site calls 8.2.0 "the current, ONC-certified production release" in a Jul 21, 2026 post. The public demo at eleven.openemr.io runs unreleased 8.6.0 code. Test against the exact release the practice runs.
Security
TLS is required for OAuth2. A certified install sets SHA512 hashing and audit log encryption. The password grant has no consent screen and is off by default. Keep it off for production. Rate limiting is left to the host.
Consent
Patient apps see a consent screen in the authorization code flow. The password grant skips it. In Manual mode, patient apps must be approved within 48 hours, per the docs' Cures Act note.
Testing
Use your own install of the target release for writes, because the public demos reset daily. Use Swagger at /swagger/ to try calls. Test both FHIR and Standard API writes, since the responses differ in shape.
Support
OpenEMR is community run. Paid support comes from the vendors on the Foundation's Professional Support page.
Questions to ask the practice or host before you sign
- Which OpenEMR release and site name do you run, and when do you plan to upgrade?
- Is the FHIR API on, and which US Core version is advertised?
- Which approval mode is set, and who enables our app?
- Do you allow the password grant or client credentials for our use?
- Who signs the business associate agreement with us?
- What rate limit does your host set?
- What refresh token lifetime is configured?
- Is your install on the Foundation's certified endpoint list?
- Which lab and registry interfaces already run on HL7 v2?
- Who supports the server if our calls start failing?
Ask the Foundation which 8.x releases the certificate covers.
Ready to plan your OpenEMR API integration?
Planning an OpenEMR API integration? We scope the route, the access steps and the build with you. Start at our EHR integration service.
Ready to scale?
Talk to our healthcare engineering team about building, integrating, and shipping faster.
Frequently Asked Questions
Does OpenEMR have an API?
Is the OpenEMR API free?
How do I get OpenEMR API access?
Does OpenEMR support FHIR?
Can I write data to OpenEMR over FHIR?
What is the OpenEMR REST API?
Does OpenEMR support HL7 v2?
Does OpenEMR send webhooks?
Is there an OpenEMR sandbox?
Why does my first OpenEMR token request fail with invalid_client?
What are the OpenEMR API rate limits?


