The speech model is rarely the bottleneck in clinical transcription workflows. The critical path runs through data pipeline engineering: audio ingestion, FHIR (Fast Healthcare Interoperability Resources)resource mapping, and resilient writes to EHR (Electronic Health Record) systems that enforce strict rate limits and validation rules.
This guide covers the architectural plumbing: how to ingest audio, transcribe it with Solaria-3, map the payload to FHIR resources, and write it to Epic and athenahealth with the resilience patterns that production clinical environments require.
The role of FHIR in EHR data normalization
FHIR is a standard framework for exchanging electronic health records using JSON-based RESTful APIs. FHIR R4's DocumentReference and Observation resources provide a reusable schema that works across Epic and athenahealth, letting you build the integration once and adapt it at the edges.
Our API returns structured JSON with word-level timestamps, speaker labels, named entities, and summaries from our audio intelligence features that feed your FHIR mapping layer directly.
Data exchange: FHIR vs. HL7 v2
HL7 v2 (Health Level Seven Version 2) is the dominant legacy messaging standard for clinical data exchange. It's pipe-delimited, socket-based, and still running in most production clinical environments. FHIR is JSON-based, RESTful, and resource-oriented, making it the correct target for any AI pipeline consuming speech data.
The complexity appears at the integration boundary. Health systems running legacy HL7 v2 infrastructure require middleware (InterSystems IRIS, AWS HealthLake, Rhapsody, or Cloverleaf) to convert v2 ADT and ORU messages to FHIR resources before your pipeline can read or write them. HL7 v2 parsing adds friction to clinical AI pipelines, particularly for OBX segment mapping where observation values carrying transcription text must be parsed into discrete fields. FHIR eliminates that parsing surface for new integrations and pushes the conversion cost to a one-time middleware configuration.
Structuring STT output for EHR systems
Our payload structures data before it reaches your FHIR mapping layer. Named entity recognition, available through our audio intelligence suite, identifies entities from transcript text. Combined with custom vocabulary configuration, NER can be tuned to flag clinical terms such as medications and symptoms, though out-of-the-box extraction targets general entity types rather than clinical-specific categories. The Audio-to-LLM pipeline generates condensed summaries from the transcript, which is useful as a starting point for clinical documentation, though the output reflects general summarization rather than a clinically tuned model. Speaker labels from speaker diarization (async-only, powered by pyannoteAI's Precision-2 model) distinguish between speakers, so you can infer clinician vs. patient turns downstream before data enters the EHR.
Securing EHR data flows via FHIR
Epic and athenahealth use SMART on FHIR, an OAuth 2.0 profile with scopes controlling write access and patient context.
Our security posture covers the audio infrastructure layer: SOC 2 Type II, ISO 27001, HIPAA, GDPR, and HDS (Hébergeur de Données de Santé) support, which qualifies clinical call center and medical dictation use cases under French and EU health data law. Deployment runs on dedicated cloud clusters in EU and US regions.
Designing robust Epic EHR data pipelines
Epic integrations typically take longer and cost more than other major EHR platforms, as reflected in the nine-to-eighteen-month timeline for complex write integrations. Total project costs for full bidirectional pipelines routinely reach six figures or more depending on scope, vendor program fees, and security review requirements.
Epic program enrollment vs. direct FHIR trade-offs
Epic replaced App Orchard with three distinct programs: Connection Hub (the developer listing directory, ~$500/year), Showroom (the customer-facing marketplace where health systems browse apps), and Vendor Services (the paid program that gates access to Epic's proprietary APIs and sandboxes, ~$1,900/year per independent sources. Verify directly with Epic before budgeting). Enrollment in Vendor Services is required to access proprietary Epic APIs. Connection Hub listing alone does not grant that access. Direct FHIR uses Epic's public FHIR R4 endpoints without marketplace enrollment.
| Factor |
Epic program enrollment (Connection Hub / Vendor Services) |
Direct FHIR endpoints |
| Cost |
Two separate fees apply. Connection Hub listing: ~$500/year (marketplace directory only). Epic Vendor Services developer membership: ~$1,900/year per independent sources (FierceHealthcare, Folio3, Saga IT). This is the fee that gates access to proprietary Epic APIs and sandboxes. Verify both figures directly with Epic before budgeting. Full bidirectional write integrations routinely reach six figures or more depending on scope. |
No program fees |
| Review timeline |
8-16 weeks for the Connection Hub listing review itself. Full Epic integration projects (development through production go-live) typically run nine to eighteen months separately |
Per health system security review |
| API access |
Proprietary Epic APIs and FHIR R4 via Vendor Services enrollment |
Standard FHIR R4 only |
| Marketplace listing |
Yes |
Not applicable. Direct endpoint access bypasses the Connection Hub listing program entirely |
| Vendor lock-in |
Mixed. Proprietary Epic APIs create platform dependency. FHIR R4 endpoints via Vendor Services are portable across EHR vendors |
Low. Standard FHIR R4 endpoints are portable across EHR vendors by design. Implementation-level differences in auth flows, endpoint URLs, and per-health-system validation rules create minor switching friction |
For most teams, direct FHIR is the faster path to a working integration. The 8–16 week Connection Hub listing review and program costs are only justified once a health system customer explicitly requires marketplace listing or access to Epic's proprietary API surface. A signed letter of intent from a health system that runs Epic is a practical lever worth securing early. It gives you a named customer commitment to reference in vendor enrollment paperwork and can drive that health system's internal governance process, which is often the slowest variable in the integration timeline.
Structuring transcription data for FHIR
Epic ingests clinical notes through the DocumentReference resource. The status field is required per the FHIR R4 specification. Common fields include type, subject (patient reference), content (attachment), and context (encounter link). The transcript goes into content.attachment.data as base64-encoded text.
```json
{
"resourceType": "DocumentReference",
"status": "current",
"type": {
"coding": [{"system": "http://loinc.org", "code": "11506-3", "display": "Progress note"}]
},
"subject": {"reference": "Patient/example-patient-id"},
"content": [{
"attachment": {
"contentType": "application/json",
"data": "<base64-encoded-transcript-json>"
}
}],
"context": {"encounter": [{"reference": "Encounter/example-encounter-id"}]}
}
```
For clinical entities extracted via NER, map medications to MedicationRequest and diagnoses to Condition, each linked to the same Encounter reference. For summaries from the Audio-to-LLM pipeline, use ClinicalImpression.
EHR encounter and patient state sync
As a pre-write best practice, query Epic's Encounter and Patient resources to verify patient identity and confirm the encounter context before committing a transcript. Writing to a closed encounter is a known integration edge case: Epic's DocumentReference.Create operation accepts both open and closed encounters at the FHIR layer, so the write succeeds without error, but the resulting note may surface in an unexpected chart location, making it harder for clinicians to locate or cosign. One recommended design pattern for this race condition: if the encounter closes while transcription is in flight, hold the payload in your queue rather than committing the write immediately, and surface a conflict alert to the clinician. This gives the responsible party an opportunity to reopen the encounter or redirect the note before it lands in an unexpected chart location.
Epic does not expose a native outbound webhook system via its public FHIR API. Where the Epic instance supports it, use a FHIR Subscription resource (R4) to receive event notifications. Availability is instance-specific and must be confirmed with the health system's integration team. Otherwise, poll Encounter.status on a fixed interval during active sessions as the reliable fallback.
Sandbox testing for speech integrations
Register through Epic's FHIR sandbox to access a test environment for your integration. Register your app with the exact FHIR scopes you intend to request in production, then simulate high-concurrency DocumentReference POST requests to surface rate-limit429 responses and latency degradation. As a general benchmark, flag operations that consistently exceed your integration's established baseline latency under realistic concurrency. The threshold will vary by health system, but sustained outliers under load are a reliable signal of rate-limit pressure or EHR validation overhead before those issues reach production.
Before wiring up the SDK, npx skills add gladiaio/skills gives Cursor or Claude Code accurate context on our transcription API, reducing hallucinated parameters during implementation.
Integrating speech data into athenahealth EHRs
Athenahealth's Developer Portal was built for external developers, making the integration timeline and cost generally shorter than Epic. Marketplace approval alone typically runs six to twelve weeks, with full write integrations ranging six to twenty-four weeks depending on scope. Project costs vary significantly by scope. athenahealth is generally positioned at the lower end of major EHR platforms for integration cost, though verify current figures with your system integrator before budgeting. The portal exposes both a mature proprietary REST API and FHIR R4 endpoints, and the choice between them shapes portability.
Integration path: API vs FHIR endpoints
The proprietary REST API exposes over 800 endpoints covering a broad range of EHR functionality and is well-documented through the athenahealth Developer Portal, but it creates vendor lock-in that becomes a liability if you later need to support Epic or Oracle Health. FHIR endpoints are standardized and reusable across EHR vendors, but coverage is narrower, particularly for administrative and billing workflows that remain proprietary REST-only.
Use FHIR endpoints for core clinical note writes to preserve portability across EHR vendors, and fall back to the proprietary REST API for scheduling, billing, and practice administration workflows.
FHIR resource mapping for clinical notes
Athenahealth maps clinical notes to DocumentReference, with content derived from athenahealth's internal document store. Consult the athenahealth DocumentReference implementation guide for the authoritative list of required fields, as field-level requirements are instance- and workflow-specific and subject to change across API versions. Solaria-3's structured JSON output (full transcript, speaker metadata, and NER-extracted entities) provides the source data for your FHIR mapping layer. You will need to align that payload to athenahealth's field requirements by consulting the athenahealth DocumentReference implementation guide, as the field-level mapping is implementation-specific rather than a pre-built correspondence between the two systems.
Solaria-3 is our most accurate model for real-world, noisy, and accented business audio, ranking #1 on Switchboard in English and core European languages with 6.4% WER (Word Error Rate) on Earnings22 financial calls (the only model under 7%).
Configuring OAuth 2.0 for athenahealth
Athenahealth supports three grant types: 2-legged client credentials for background system-to-system access, 3-legged authorization code for user-facing workflows, and SMART on FHIR launch for embedded EHR apps. For a server-side transcription pipeline writing notes in the background, the client credentials flow is correct. Exchange your client_id and client_secret for an access token at the token endpoint, include the token as a Bearer header on all FHIR requests, and implement token refresh before expiry. athenahealth's token lifespan is 60 minutes per the platform's authentication documentation.
```python
import requests
token_response = requests.post(
"https://api.platform.athenahealth.com/oauth2/v1/token",
data={
"grant_type": "client_credentials",
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET,
"scope": "user/DocumentReference.write"
}
)
access_token = token_response.json()["access_token"]
```
Store client secrets in a secrets manager (AWS Secrets Manager, HashiCorp Vault) and rotate on a schedule, not only on suspected compromise.
Handling FHIR endpoint rate limits
athenahealth enforces rate limits communicated during the partner onboarding process. When you receive a 429 Too Many Requests, implement exponential backoff: start with a short delay, then increase exponentially with random jitter to avoid thundering herd problems.
For high-volume clinical pipelines, a recommended pattern is to buffer writes through a message queue (RabbitMQ or AWS SQS) rather than issuing individual FHIR POSTs per transcript. FHIR's own batch and transaction model acknowledges the overhead of multiple HTTP round trips, and a queue consumer lets you absorb that overhead asynchronously. Accept the completed transcript payload, return 202 Accepted immediately, and let the consumer handle the EHR write at a rate that respects daily and burst limits, keeping the application responsive during peak clinical hours when multiple clinicians are completing notes simultaneously.
Mapping transcription payloads to FHIR schemas
A transcript payload from our API contains more than text: it includes word-level timestamps, speaker IDs, confidence scores, and extracted entities. The FHIR schema must preserve this metadata or you lose the clinical audit trail.
Mapping transcripts to FHIR resources
| Transcription element |
FHIR resource |
Field |
| Full transcript text |
DocumentReference |
content.attachment.data (base64) |
| Clinical summary |
ClinicalImpression |
summary |
| Extracted entities (medications, diagnoses) |
MedicationRequest, Condition |
Per resource spec |
| Discrete observations (vitals, symptoms) |
Observation |
value[x] |
Named entity recognition extracts the clinical entities and the Audio-to-LLM pipeline generates the summary, so your FHIR mapping layer consumes structured JSON rather than parsing free text.
Storing diarization data in FHIR
Speaker diarization is powered by pyannoteAI's Precision-2 model and is available in async workflows only, as detailed in our diarization documentation. FHIR's DocumentReference has no native speaker-turn field, so the recommended pattern is to embed speaker metadata in a structured JSON object within content.attachment.data, including speaker ID, inferred role (clinician or patient), and timestamp range for each turn, with content.attachment.contentType set to text/plain for plain transcripts, or to application/json when embedding structured speaker metadata. application/json is a valid MIME type under the FHIR spec but is not explicitly defined in US Core examples for this pattern, so validate against your FHIR server's conformance statement before using it in production. The alternative, mapping distinct speaker turns to separate Observation resources linked to the same Encounter, creates resource sprawl at scale and complicates queries.
Use FHIR Extensions to add a custom speaker-role annotation to the attachment when your FHIR server supports it, following the pattern used in clinical NLP pipelines for provenance metadata.
Handling transcription time offsets
Word-level timestamps from our API map to Observation.effectiveDateTime for extracted clinical statements, with millisecond precision in ISO 8601 format. For the full transcript, store word-level offsets as a custom extension within the DocumentReference resource per the US Core clinical notes specification. Include confidence scores alongside timestamps so downstream review tools can flag low-confidence words for clinician verification before the note is cosigned.
Choosing data models for FHIR integration
DocumentReference: Use for unstructured or semi-structured full-text clinical notes and any structured JSON embedding speaker metadata.Observation: Use for discrete, queryable data points extracted from the transcript, such as blood pressure readings, reported symptoms, or extracted lab values.ClinicalImpression: Use for AI-generated clinical summaries and overall assessments produced by the Audio-to-LLM pipeline.
FHIR integration: best practices to follow
Writing to an EHR is a high-stakes operation. A network timeout that triggers a duplicate write produces duplicate clinical notes in a patient's chart, which is a patient safety issue, not just a data integrity issue.
Choosing between sync and async writes
Synchronous writes block your application's UI and propagate EHR downtime directly to the clinician's session. FHIR write operations incur measurable latency from EHR database validation, security checks, and audit logging. The exact range varies by health system and load, but it is reliably enough to block UI threads, making async writes the correct pattern for clinical transcription. Accept the transcript, return immediately, and let a background worker handle the EHR write.
Idempotency patterns for EHR integration
Use FHIR's Conditional Create mechanism with the If-None-Exist header to prevent duplicate resources. Compute an idempotency key by hashing the transcript payload (encounter ID plus audio file hash plus timestamp), store it locally before sending the FHIR request, and include it in the search parameter of If-None-Exist. If the server returns 200 OK (resource already exists) rather than 201 Created, treat the write as a no-op. AWS HealthLake documents the ETag-based optimistic concurrency pattern for cases where you need to update an existing resource without overwriting concurrent edits.
Managing failed FHIR write attempts
Classify errors before deciding on a retry strategy:
- Transient (retry with backoff):
429 Too Many Requests, 503 Service Unavailable, 504 Gateway Timeout - Permanent (route to Dead Letter Queue):
400 Bad Request, 403 Forbidden, 422 Unprocessable Entity
Messages that fail transiently should retry for up to one hour using exponential backoff. Permanent failures route to a DLQ with the full request and response body logged, flagged for integration engineer review, and available for manual replay once the underlying issue (schema validation failure, stale token, misconfigured scope) is resolved.
Strategies for partial FHIR writes
When a transcript write succeeds but the associated ClinicalImpression or extracted entity write fails, you have a partially-written clinical record. Prevent this with FHIR transaction bundles, which are atomic: either all entries succeed or none do. Structure the bundle to include the DocumentReference, all Observation resources for extracted entities, and the ClinicalImpression in a single transaction type bundle. If any entry fails validation, the server rolls back the entire transaction and returns a single error response.
Scaling transcription for clinical workflows
Handling PHI in EHR integrations
Encrypt all audio and transcript data at rest using AES-256 and in transit using TLS 1.3. Our optional PII redaction feature can mask entities like patient names and phone numbers in the transcript output, but it is not enabled by default and must be explicitly configured in the API request.
On our Growth and Enterprise plans, customer data is never used for model training, which limits one path by which PHI could otherwise surface in a shared model, while the Starter plan can use data for training by default. Any clinical deployment handling Protected Health Information requires Growth or Enterprise, as documented in our compliance hub. One financial services team using our API for high-volume call transcription noted the accuracy and compliance story directly:
"Gladia provides a highly accurate real-time speech-to-text solution for high volumes of support and service calls. Latency is low and accuracy high, even for numericals. We've appreciated the quality of support across pre-processing, post-processing, and model optimization." - Verified user on G2
Our HDS support (Hébergeur de Données de Santé) covers cloud-hosted EU infrastructure and meets France's mandatory HDS requirements for hosting personal health data, a framework overseen by the Agence du Numérique en Santé and aligned with French and EU health data law.
Implementing FHIR audit logging
Map every transcription write event to a FHIR AuditEvent resource capturing: who initiated the transcription (practitioner reference), what was written (DocumentReference ID), when the write occurred (ISO 8601 timestamp), and the source system. Store these logs in a write-once-read-many system (AWS CloudWatch with object lock, or equivalent) and retain them per your jurisdiction's minimum retention period, as covered in our call recording compliance guide.
Observability for EHR transcription flows
Track four metrics in production: transcription latency (Gladia API response time), FHIR write success rate (target above 99.5%), rate-limit consumption (percentage of daily quota used per hour), and transcription accuracy in production on a sampled subset of clinical audio. Use Datadog or Prometheus to alert on anomalies, particularly a sudden spike in FHIR write failures (indicating an EHR authentication or schema issue). Our public status page provides real-time API uptime data to distinguish our infrastructure issues from your EHR connectivity issues.
Authentication requirements by facility
Individual hospitals layer facility-specific security controls on top of standard OAuth 2.0. Common additions include IP whitelisting (your egress IPs must be pre-registered with hospital IT), mutual TLS requiring a client certificate alongside the OAuth token, and site-to-site VPN for facilities with on-premises Epic instances. Design your authentication module with pluggable facility adapters: a standard OAuth 2.0 path, an OAuth-plus-mTLS path, and an OAuth-plus-VPN path selectable at provisioning. Validate certificate expiry in pre-flight checks so a certificate rotation at the hospital does not silently break clinical note writes overnight.
The EHR authentication adapter is where facility-specific complexity concentrates. Keeping it separate from your transcription and FHIR mapping logic lets you swap adapters per health system without touching the speech layer. Our SDK is straightforward to wire up.
Start with €50 in free credits to have your integration in staging in less than a day. Test Gladia on your own multilingual audio to see how it handles language detection, accent-heavy speech, and code-switching.
FAQs
Does Gladia support HDS-hosting for European health data?
Yes, we do support HDS (Hébergeur de Données de Santé), which qualifies our cloud-hosted EU infrastructure for clinical workflows under French and EU health data law, as governed by the Agence du Numérique en Santé.
Can we deploy Gladia on-premises or in an air-gapped environment?
No, we do not support on-premises or air-gapped hosting on any plan, and deployment is limited to dedicated cloud clusters in our EU and US regions.
Does Gladia use patient audio to train its models?
On Growth and Enterprise plans, customer data is never used for model training by default and no opt-out is required. On the Starter plan, data can be used for training, so clinical PHI deployments require Growth or Enterprise.
Is speaker diarization available in real-time clinical workflows?
No, speaker diarization (powered by pyannoteAI's Precision-2 model) is available only in asynchronous workflows. For real-time use cases, handle speaker attribution in post-processing for higher accuracy.
What are the rate limits for athenahealth's FHIR endpoints?
Athenahealth does not publish environment-specific rate limit figures. Your actual limits, for both the Preview and Production environments, are confirmed during partner onboarding and may vary by agreement. The API X-RateLimit-Remaining and X-RateLimit-Reset returns HTTP 429 when limits are exceeded. Implement exponential backoff with jitter as described in the rate limit section above.
What FHIR resource should we use for transcribed clinical notes?
Use DocumentReference for full-text clinical notes and structured transcript JSON, Observation for discrete extracted data points like symptoms or vitals, and ClinicalImpression for AI-generated clinical summaries. FHIR transaction bundles let you write all three atomically in a single request.
How should we handle version conflicts when writing to the EHR?
Use FHIR's optimistic locking: include the ETag header from the current resource version in your update request as an If-Match header. If a clinician edits the note between your read and write, the server returns 412 Precondition Failed, so retrieve the latest version, merge changes, and retry with the updated ETag.
Key terms glossary
FHIR (Fast Healthcare Interoperability Resources): A standard framework for exchanging electronic health records using JSON-based RESTful APIs, maintained by HL7 International.
HDS (Hébergeur de Données de Santé): France's mandatory security certification for organizations hosting personal health and patient data, overseen by the Agence du Numérique en Santé and aligned with French and EU health data law.
HL7 v2 (Health Level Seven Version 2): The dominant legacy standard for clinical data exchange, using pipe-delimited message segments (ADT, ORU, OBX) transmitted over socket-based connections. Predates RESTful APIs and remains the most widely deployed interface protocol in production health systems.
Diarization: The process of partitioning an audio stream into segments by speaker identity, producing labeled turns that distinguish between speakers. Clinician vs. patient role can then be inferred downstream from those labels.
SMART on FHIR: An OAuth 2.0 profile that provides standardized, scope-based authorization for applications integrating with EHR systems.
DocumentReference: A FHIR R4 resource used to index and deliver clinical documents, such as transcribed notes, within an EHR, linking content to a specific patient and encounter.
Transaction bundle: A FHIR mechanism for grouping multiple resource writes into a single atomic operation, where all entries succeed or none are committed.
Conditional Create: A FHIR HTTP pattern using the If-None-Exist header to prevent duplicate resource creation when a matching resource already exists on the server.
