Epic’s public FHIR sandbox is where most developers make their first real calls to Epic. It is free, documented and full of synthetic patients, but first-time users still lose days to registration settings, authentication errors and confusion about what the sandbox can and cannot prove. This guide walks through the sandbox step by step and explains how to move from sandbox success to real health system deployments. For production Epic work, see our Epic integration services. Need help getting started? Request a free developer onboarding session.
What the Epic FHIR Sandbox Offers
Epic provides public developer resources where you can register apps, browse FHIR documentation and test against a sandbox populated with synthetic data. It is the right place to learn Epic’s FHIR behavior before any customer conversation, and it costs nothing to start using.
Public FHIR endpoints
The sandbox exposes Epic FHIR endpoints for R4 and older versions, hosted on Epic’s own servers. You call these endpoints with standard FHIR requests. Each endpoint’s metadata document describes supported resources and the authorization server, which your app needs for authentication.
Synthetic test patients
Epic publishes test patients with realistic records, including conditions, medications, results and encounters. Use these to test reads, searches and display logic. Because the data is synthetic, you can experiment freely without HIPAA concerns or approvals from any health system.
App registration and client IDs
You register apps through Epic’s developer site, choosing app type, user audience and FHIR scopes. Registration provides client IDs for non-production and production use. Settings chosen at registration affect what your app can request, so review them carefully before building.
Documentation and tooling
Epic documents each supported FHIR resource, search parameters and specific behaviors, plus authentication patterns. Read resource pages closely, because Epic’s implementation sometimes differs from the base FHIR specification in supported searches, required parameters or returned elements. Bookmark the pages for every resource you use.
Choosing the Right App Type
Your first decision is which kind of app you are building, because it determines authentication flow, scopes and user experience. Getting this right early avoids rebuilding authentication later and ensures your sandbox testing reflects how the app will actually run in production.
Patient-facing apps
Apps used by patients authenticate with patient credentials and request patient scopes. In the sandbox, you log in as test patients to simulate this flow. These apps typically support patient access use cases such as personal health records or care management tools.
Clinician-facing SMART apps
Clinician apps usually launch from within Epic with patient and user context. The sandbox supports testing launch flows, though full in-workflow testing requires a customer environment. Our guide on building your first SMART on FHIR app covers these launch patterns.
Backend services
Backend apps run without a user, such as data pipelines or population services. They authenticate using signed JSON Web Tokens with registered public keys. This pattern needs careful key management, and production use requires customer approval of exactly which data the service may access.
Why the choice matters
Each app type uses different scopes, tokens and approvals. Switching later means re-registration, new testing and possibly redesigned user flows. Decide based on who uses the app and how, then confirm with a target health system that they support that pattern.
Step-by-Step: First Calls in the Sandbox
These steps take most developers from registration to working FHIR requests. Following them in order avoids the most common errors, especially around authentication and scopes, which cause the majority of first-week frustration when teams start building against Epic.
Step 1: Register your app
Create an account on Epic’s developer site, register your app, select the audience and choose the minimum FHIR scopes you need. Record your client IDs and redirect URIs. Allow time for registration changes to become active before testing new settings.
Step 2: Discover endpoints
Request the sandbox metadata document to confirm the FHIR base URL, supported resources and authorization endpoints. Build your app to read these values dynamically rather than hard-coding them, because each health system will have its own endpoints in production. Cache values carefully and refresh periodically.
Step 3: Implement authentication
Implement the OAuth 2.0 flow for your app type, using SMART authorization for user-facing apps or signed JWTs for backend services. Test token expiry and refresh. Most early failures come from mismatched redirect URIs, scopes or key configurations. Compare every setting against your registration record.
Step 4: Read and search resources
Start with simple reads, such as Patient, then add searches for Observation, Condition and MedicationRequest. Handle paging through Bundles and missing elements gracefully. Log full requests and responses during development to diagnose errors quickly and accurately. Start small, then expand coverage gradually.
Step 5: Test edge cases
Test expired tokens, denied scopes, empty results, large result sets and unexpected values. Synthetic patients rarely include every scenario, so add your own test cases where possible. Robust error handling now prevents painful failures during customer pilots later. Document each scenario and its expected result.
What the Sandbox Cannot Prove
Sandbox success is an important milestone, but it does not guarantee production readiness. Real health systems differ in configuration, data and policies. Knowing the sandbox’s limits helps teams plan the next stage realistically instead of assuming launch is only weeks away.
Customer-specific configuration
Each health system decides which resources, scopes and write capabilities to enable for your app. Features working in the sandbox may be unavailable at a customer. Confirm capabilities with each target organization before promising features in sales or contracts. Track differences in a configuration log.
Real data variety
Production data is messier than synthetic data, with missing values, unusual codes and historical inconsistencies. Apps must handle this gracefully. Plan time for testing with customer test environments, which reflect local data patterns more closely than public sandbox patients. Ask customers which data issues are common.
Performance and rate limits
The sandbox does not reflect production volumes, network conditions or rate limits. Load testing and performance tuning must happen later with customer guidance. Design efficient queries now, requesting only needed data, to reduce surprises when real usage begins. Cache reference data where policies allow.
Approval and security reviews
Health systems review security, privacy and workflow impact before enabling apps. These reviews can take longer than development. Prepare documentation on data flows, encryption, logging and support early, so reviews move quickly once a customer is ready. Assign one owner to manage each review.
Moving From Sandbox to Production
After sandbox testing, the path to production runs through Epic programs and individual health system approvals. Understanding this path early prevents the common mistake of finishing development and then discovering months of access and approval work still ahead.
Choose the right Epic program
Depending on your business model, you may continue with public developer resources or join Vendor Services for broader access and support. Our Epic Vendor Services vs open.epic comparison explains the differences and helps you choose. The right choice depends on your product, customers and support needs.
Secure a pilot customer
A committed health system partner is essential for production. They activate your app, configure scopes and provide test environments. Choose a pilot customer whose workflows match your product well, and agree on clear success criteria for the pilot. Share progress with them regularly.
Test in customer environments
Customer test environments reveal configuration, data and workflow differences the sandbox cannot. Run full scenarios with real users where possible. Track issues carefully and fix them before production, because first impressions shape whether the customer expands usage. Involve customer analysts in every test cycle.
Plan for many customers
Each new health system requires activation, configuration and testing. Design your app to read endpoints and capabilities dynamically, and document a repeatable onboarding process. Efficient onboarding becomes a major competitive advantage as your customer base grows. Measure onboarding time for each new customer.
How Taction Helps Developers Working With Epic
Taction has delivered 200+ healthcare projects, including SMART on FHIR apps and Epic integrations. We help development teams move from sandbox experiments to production deployments, covering authentication, data handling, approvals and multi-customer onboarding.
Free developer onboarding session
Share your app concept and current progress. We review app type, scopes, authentication and architecture, then outline the path from sandbox to production. You leave with clear next steps and fewer surprises. Book your free session. We also flag approval risks you can address early.
SMART on FHIR app development
We build patient, clinician and backend apps that work across Epic organizations. Our SMART on FHIR app development tutorial shows the engineering approach we apply to client projects every day. We design every app for portability, so new health system customers need configuration rather than redevelopment.
FHIR readiness assessment
Not sure whether your product is ready for health system review? Our FHIR readiness assessment helps teams evaluate architecture, security and data handling before customer conversations, highlighting gaps worth fixing early. Teams that address these gaps before customer reviews usually move through approvals faster and with fewer surprises.
FHIR developers on demand
Need extra capacity to reach production faster? Hire FHIR API developers who know Epic’s FHIR behavior, authentication patterns and approval processes. They integrate with your team and document everything for long-term ownership. Engagements scale with your roadmap, from a first pilot to many health system customers.
Frequently Asked Questions
These answers address common questions developers ask about Epic’s FHIR sandbox. Because Epic programs and customer requirements evolve, an onboarding session focused on your specific app gives the most current and reliable guidance.
Is the Epic FHIR sandbox free?
Yes. Epic provides public developer resources and a FHIR sandbox at no cost, allowing developers to register apps and test against synthetic patients. Broader access and support programs may involve fees, depending on your business model and needs. Start with the public sandbox first.
What data is in the Epic sandbox?
The sandbox contains synthetic test patients with realistic records, including demographics, conditions, medications, results and encounters. No real patient data is included, so developers can test freely without HIPAA concerns or health system approvals during early development. Add your own scenarios for edge cases.
Why does authentication fail in the sandbox?
Common causes include mismatched redirect URIs, incorrect scopes, registration changes not yet active, expired tokens or misconfigured keys for backend services. Check your registration settings against your app configuration, and log full authorization requests and responses. Most issues trace back to registration mismatches.
Does sandbox success mean my app works with every Epic customer?
No. Each health system configures resources, scopes and write capabilities differently, and real data is messier. Test in customer environments, confirm capabilities with each organization and handle missing features gracefully before production launch. Treat the sandbox as a learning environment, not proof that features will work everywhere.
How do I move from sandbox to production?
Choose the right Epic developer program, secure a pilot health system, complete their security and workflow reviews, and test in their environments. The health system then activates your app in production. Plan approval time alongside development for realistic timelines. A pilot customer makes this easier.