Integrating Your Health App With Behavioral Health EHRs

Behavioral health EHR integration usually starts the same way every other integration does: find the API, read the docs, wire it up. That's the CRM playbook, the payments playbook. It's also the playbook that stalls out fastest here, because it assumes an API exists in the first place.

‍

'TherapyNotes has zero public API. SimplePractice's own support docs say the same: no public-facing API, just a narrow 2022 Enterprise API scoped to EAP and MCO scheduling. Between them, those two platforms cover a huge share of the practices your customers already run, and neither gives you the door you're expecting to walk through. Guess wrong about which path replaces that door and you can lose a quarter before anyone notices.

‍

This piece maps all five real paths that actually work, plus exactly when the smarter move is inverting the architecture instead of chasing integration depth.

‍

How do you integrate a health app with a behavioral health EHR that has no public API?

Five real paths exist: partner or enterprise programs, Zapier-tier automation, batch exports, claims rails, or reverse-engineered adapters, each suited to a different vendor and volume. TherapyNotes and SimplePractice, the two most common platforms in this space, ship no meaningful API at all, which is why picking the right path matters more here than in most health tech integrations. When none of the five paths reach far enough, the better move is often inverting the architecture: making your own product the system of engagement with its own lightweight system of record.

‍

1. TherapyNotes and SimplePractice, the two largest behavioral health practice-management platforms, offer no meaningful public API. Any integration project built on the assumption that one exists needs a different starting point.
2. Five real paths move data without a public API: partner or enterprise programs, Zapier-tier automation, batch exports, claims rails, and reverse-engineered adapters. The right one depends on the vendor and the volume, not a one-size-fits-all default.
3. Only two categories of behavioral health data carry extra protection beyond ordinary PHI: psychotherapy notes and 42 CFR Part 2 substance use disorder records. Everything else moves under standard HIPAA rules.
4. When integration stays thin after real effort, invert the architecture. Make your own product the system of engagement, holding a lightweight system of record shaped to your actual workflow, and sync selectively wherever a real rail exists.
5. Match the trust level to the data, not just the channel. Read-only sync is the safe default, write-back needs a named field boundary, and billing codes or clinical documentation deserve a human in the loop before anything commits.

‍

Why behavioral health EHR integration is a different problem

A documented endpoint. OAuth scopes. A rate limit to respect. That's the shape developers expect walking into an integration project, whether it's a CRM or most of the software healthcare providers touch daily. Behavioral health breaks that expectation early, and teams who don't plan for it lose real time finding out.

‍

Where the "just call the API" assumption breaks

TherapyNotes has zero public API and no webhooks. Nothing to poll, nothing to subscribe to, no documented way in. SimplePractice's own support docs say almost the same thing: no public-facing API for third-party integrations, just a narrow 2022 Enterprise API scoped to EAP and MCO scheduling referrals, not general data access.

‍

TherapyNotes and SimplePractice are the two most common practice-management platforms in behavioral health, the default choice for most of the practices your customers already run on. Between the two of them, that's a huge share of the market with nothing to build against. (If you're choosing an EHR for your own practice rather than integrating with one, that's a different question, and we cover it in top EHRs for therapists.)

‍

Why behavioral health, specifically

Qualifacts and Valant both ship real, documented APIs, live and in production. Check vendor by vendor before you scope anything. TherapyNotes and SimplePractice happen to be the two names covering the most practices, and they're also the two with nothing to check against.

‍

Enterprise EHRs like Epic and Oracle Health have spent years under real ONC and FHIR certification pressure, the kind that forces interoperability whether a vendor wants it or not. The behavioral health practice-management platforms never faced that same push. That gap is exactly why mental health EHR integration looks so different from interoperability everywhere else in health tech. Nobody made TherapyNotes ship a FHIR endpoint, so it didn't.

‍

Integration in this space means partner programs, data exports, claims rails, and sometimes a reverse-engineered adapter built by a third party. Treating any of that like a documented endpoint problem is how teams burn a quarter before they've moved any real data. That's the map the rest of this piece draws out.

‍

The vendor breakdown: API status of TherapyNotes, SimplePractice, Valant, Qualifacts, ICANotes, Osmind & co.

API status changes. A vendor can ship a beta API, gate an existing one behind a new partner agreement, or quietly sunset an integration program between one funding round and the next. The table below is a snapshot, verified as of July 2026, not a permanent map. Recheck the vendor's own docs before you commit engineering time to any of the seven.

‍

Each of these platforms is behavioral health practice management software at its core, handling scheduling, notes, billing, and increasingly telehealth and patient portal access. What varies, and varies a lot, is whether any of that data has a documented door in or out.

‍

‍

Verified July 2026. Confirm directly with the vendor before you scope a build.

‍

Group these seven by what's actually available, not by size or market reputation. Reputation doesn't build APIs.

‍

The vendors with no meaningful API

TherapyNotes API access is zero, and that's the complete picture: no REST endpoints, no webhooks, no bulk actions, no documented way to pull or push data. One independent review puts it more starkly: no API access of any kind. That ceiling shows up operationally too: independent analysis pegs a practical scale limit around 10-15 clinicians per practice, since nothing programmatic exists to manage growth beyond manual workflows.

‍

Billing is the exception. TherapyNotes routes claims through Claim.MD, its clearinghouse partner, handling submission to more than 2,800 payers nationwide, the one real, structured data surface a zero-API vendor still has: a claims rail, not a general integration point.

‍

The SimplePractice API story has one exception worth knowing, confirmed as recently as an April 2026 revision of its own support docs. There's no public-facing API for general integrations. The exception is a 2022 Enterprise API, scoped narrowly to EAP and MCO appointment-referral scheduling, and nothing broader has shipped in the years since.

‍

The vendors with a real API

Two names in this list ship a real, documented API, not a partner promise or a beta waitlist.

• Valant runs the Valant API under a named "EHR API Management" platform, with a Scheduling API and Inbound/Outbound Charge APIs. It's a custom REST API, not FHIR, but live and built specifically for practice-management workflows, not adapted from a generic schema.
• Qualifacts publishes the Qualifacts API across three products: CareLogic Enterprise, Credible Behavioral Health, and InSync. It also runs a live partner marketplace, with categories spanning measurement-based care and ASAM SUD assessment, among others.

‍

Qualifacts' CareLogic FHIR API, built on the HL7 data-exchange standard, is the deepest of the group, and the most gated. Access requires a BAA with Qualifacts directly, then a separate BAA with each customer agency, before any patient data moves. The API is then rate-limited to 1,000 requests per minute and 100 per second, generous for most patterns but worth knowing before a bulk sync job. Budget for the paperwork before the engineering time.

‍

The vendors in between

‍

Three vendors sit in a middle zone: some access exists, but none of it is self-serve.

• ICANotes runs a partner-request model: an intake form and a team that builds the integration on their side if your use case qualifies.
• Osmind serves a narrower niche than general talk therapy: interventional psychiatry, Spravato, TMS, ketamine, and psychedelic-adjacent medicine. API access exists but is gated rather than open. One HIPAA automation platform confirms as much indirectly, listing no pre-built Osmind connector and requiring existing API access before it will connect. Osmind does have real organizational partnerships for the niche: a DSM-5-TR measures collaboration with the American Psychiatric Association and a listed Zoom technology-partner slot.
• TheraNest, now under parent brand Ensora Health, is the least certain of the seven. Ensora runs an Echo API carrying ONC certification under federal §170.315(g)(7)-(10) criteria, tied to the Echo/EchoVantage line specifically, not confirmed to extend to TheraNest itself.

‍

Match the vendor to its actual access tier before you scope a timeline. Treating any of these three the same is how a scope estimate goes wrong.

‍

Five integration paths when there's no public API

A TherapyNotes integration or a SimplePractice integration without a public API still has five real paths in front of it. Pick the right one for the vendor and the volume, and the project ships close to on schedule. Pick the wrong one and you find out three months in that the channel you built around can't handle real-time updates, or that a reconciliation job has been silently dropping records since week two.

‍

‍

Path 1, official partner and enterprise programs

Qualifacts runs the clearest example of a partner API program among these seven: a live marketplace with named integration categories covering measurement-based care, ASAM SUD assessment, and clinical quality reporting. Getting into a program like this isn't instant. It usually means an application and a review process, sometimes with a certification or revenue-share arrangement layered on, before your integration goes live and starts moving real patient data. Partner programs are the most sanctioned of the five paths and usually the slowest, since someone else's review calendar now sits on your critical path.

‍

Paths 2 and 3, Zapier-tier automation and batch exports

A Zapier integration is usually the first thing teams try, and for good reason: no partner agreement, no BAA negotiation, just a trigger and an action. It works fine for low-volume, non-real-time needs like syncing a calendar or firing a notification. It's also the first thing that breaks once volume climbs or the object you're syncing gets more complex than a name and a timestamp, a clinical note with structured fields, for instance.

Batch exports over CSV and SFTP are the fallback when nothing else is available. Someone on your team owns:

• a recurring file drop
• a data-mapping layer
• a reconciliation process to catch what didn't map cleanly

‍

It's slow and unglamorous work, and it holds up better than a fragile browser-automation script once the volume gets real. Heavier volume usually means introducing actual middleware or a small integration engine to own the mapping and retries, rather than a spreadsheet macro someone maintains by hand.

‍

Path 4, the claims rails

Even a vendor with zero API access usually has one real, structured data surface: the claims rail. TherapyNotes routes billing through Claim.MD, its clearinghouse partner, covering more than 2,800 payers and standard transaction sets like 837P claims, 835 remittance advice, and ERA files. That's a genuine, documented channel for encounter and billing data on a vendor that otherwise offers nothing. Scheduling and clinical documentation still need one of the other four paths to move.

‍

Comparable independent practice-management platforms show partner approval processes can add 2 to 4 weeks before development even starts, on top of whatever the integration itself takes. Treat that as a typical range for this class of work, not a quote for TherapyNotes, SimplePractice, Valant, or Qualifacts specifically.

‍

Path 5, in one line

The fifth path is unofficial, reverse-engineered access: real companies building integrations these vendors never sanctioned, filling a gap partner programs and Zapier-tier tools can't reach. It comes with its own risk calculus, covered next.

‍

Unofficial APIs and reverse-engineered adapters: what they are and what to ask

Partner programs move too slowly for some teams. Zapier-tier automation can't handle a real clinical object. A small category of companies fills exactly that gap: reverse-engineered integrations for the unofficial API layer these vendors never built, working by automating the browser or the portal itself, the same way a human user would click through it.

‍

What this category actually is

Supergood reverse-engineers authenticated browser flows and network interactions for TherapyNotes, SimplePractice, and CareLogic, the same three platforms this piece keeps coming back to. Supergood frames its own role plainly: acting on a customer's behalf, within access that customer already holds, rather than as an independent data source of its own. It also ships MCP servers for AI-agent access to TherapyNotes and CareLogic specifically, filling a gap neither vendor bothered to fill itself.

‍

Magical takes a similar approach across a wider net, automating TherapyNotes, Availity, and dozens of other EHR-payer combinations through browser automation. Its pitch is that you get the workflow without touching an API at all, since there's no API to touch on these vendors in the first place.

‍

The diligence checklist before you use one

Before you build on one of these, work through five questions:

‍

Whose terms of service is actually being tested?

The EHR's, not the adapter vendor's, and that risk sits with whoever holds the underlying account.

‍

Who holds the credentials, and how are they rotated or revoked?

Browser automation usually runs on a real login, which means a real password with real blast radius if it leaks, especially once more than one integration shares the same login.

‍

Does the BAA chain cover this vendor specifically?

A BAA with the EHR doesn't automatically extend to a company reverse-engineering its way in from outside.

‍

What happens operationally when the target UI changes?

Sanctioned APIs version and deprecate on a schedule. Browser automation breaks the day a vendor redesigns a page, with no changelog to warn you.

‍

Has the practice consented to this kind of access?

The account owner knowing what's connected to it isn't optional, whatever the vendor's terms say about who's allowed to automate what.

‍

This is a per-vendor, per-practice decision, not a category-wide verdict. Run the checklist before you write the first line of integration code. The BAA question alone deserves a closer look, since behavioral health data carries protections most PHI doesn't get, and that's exactly where the next section picks up.

‍

The compliance layer: psychotherapy notes, 42 CFR Part 2, and BAAs across the chain

Two categories of behavioral health data get extra protection beyond ordinary PHI: psychotherapy notes and 42 CFR Part 2 substance use disorder records. That's the whole list. Everything else, diagnosis, treatment plans, progress notes, medication records, moves under the same HIPAA rules as any other medical record.

‍

What's actually extra-protected, and what isn't

Psychotherapy notes have a precise, narrow legal definition under 45 CFR 164.501: notes on the content of a counseling session, kept separate from the rest of the medical record through what EHR systems typically implement as note locking. The regulation is explicit about what doesn't count, which is exactly where teams over-restrict. Excluded from the psychotherapy-notes category:

• Medication management
• Session start and stop times
• Treatment modalities and frequency
• Test results
• Summaries of diagnosis, functional status, treatment plan, symptoms, prognosis, and progress

‍

All of that is regular PHI, accessible under the same rules that govern any other medical record. Lock it down like a psychotherapy note and your integration can't deliver data the law never actually restricted.

‍

What changed with 42 CFR Part 2

42 CFR Part 2 covers the second protected category: substance use disorder treatment records. HHS finalized a rule on February 8, 2024, implementing CARES Act Section 3221 and aligning Part 2 much more closely with HIPAA than the old regime's redisclosure-notice requirement.

‍

The compliance deadline, February 16, 2026, has already passed. OCR opened a civil enforcement program for Part 2 confidentiality three days earlier, on February 13.

‍

The practical changes matter for integration work specifically. A single consent now covers future SUD-record use and disclosure across treatment, payment, and healthcare operations, replacing the old requirement to re-consent for every new use. And the rule creates a new SUD-notes category with protection analogous to psychotherapy notes, a second narrow carve-out alongside the one covered above. Consent management gets meaningfully simpler as a result.

‍

The BAA chain across every hop

One business associate agreement doesn't cover the whole chain. Qualifacts' CareLogic FHIR API is the clearest example among the vendors in this piece: the developer executes a BAA directly with Qualifacts, then a separate BAA with each customer agency whose data the integration touches. Skip either one and PHI moves through an otherwise-compliant API unprotected.

‍

‍

The same logic extends to middleware and the unofficial adapters above: every hop touching PHI needs its own agreement, audit logs, and accountability for who's allowed to connect. Information blocking rules add pressure to share more data; the BAA requirement underneath it stays just as strict. Our mental health EHR requirements piece goes deeper on structuring that chain end to end.

‍

Behavioral health interoperability is live, unsettled territory at the federal level, not a solved problem. Quinn Bastian (VA) and Dr. Susy Postal (IHS) have both spoken publicly on how much work behavioral health interoperability still needs, even after the Part 2 changes. HIPAA compliance elsewhere in the stack stays the baseline; this is the layer specific to behavioral health data.

‍

Inverting the architecture: when your app should be the system of engagement

Every path covered so far assumes you're still trying to integrate deeper with a vendor that has a real API, a partner slot, or a claims rail. Sometimes the better move is changing what your own product depends on, instead of pushing for a deeper connection that may never arrive.

‍

The trap of chasing deeper integration

Some teams read everything in this piece so far and still keep pushing on the same door: one more reverse-engineered workaround, one more follow-up email to a partner-program contact who stopped replying three weeks ago. The instinct makes sense: you've already sunk real time into the relationship.

‍

The EHR isn't going to open up more than it structurally can. TherapyNotes and SimplePractice aren't withholding an API they secretly have ready to ship. No amount of persistence changes what these platforms actually offer, and the teams that keep pushing past that point are usually the ones burning the quarter this piece opened with.

‍

Make your app the system of engagement

‍

The practice's EHR doesn't have to be the system of record for your product. Your app can hold its own purpose-built clinical record, shaped to your actual workflow instead of bent to fit someone else's schema, with things like:

• a structured field for your specific intake question
• a status enum matching your actual care pathway
• a relationship model connecting client to provider your way

‍

None of it has to look like a TherapyNotes export.

‍

Custom data models make that possible: you define the entities, fields, and relationships your product actually needs, not whatever a vendor twelve states away happened to ship. That's a meaningful shift in your tech stack, not a cosmetic one. The system of record for your product's own workflow moves from someone else's platform to yours. We cover the build side of this in launching an EHR system without coding.

‍

Sync selectively, don't go dark

Inverting the architecture doesn't mean cutting the EHR out of the picture. Your product becomes the system of engagement, the place where the patient and the provider actually spend their time, while the EHR keeps doing what it was built for on the billing and compliance side. Sync selectively wherever a real rail exists: the claims data from Section 4, a partner API where one's available, an export job where that's the only door. Treat the practice's EHR as an external system your product exchanges specific data with, on your own schedule, rather than a dependency your core workflow waits on. A mental health app built this way still needs the clinical judgment and safety features that come with the territory, covered in our broader guide to building a mental health app.

‍

This is a legitimate architecture decision, not a consolation prize. Teams across this space converge on it out of necessity, after real effort on the other four paths, because integrating with a behavioral health EHR that structurally can't go deeper stops being worth the calendar time it costs.

‍

Integration patterns that work: read-only sync, selective write-back, human-in-the-loop

Section 4 covered which of the five channels to use. This section covers a different question: once data is moving, how much do you trust what's coming through it? Any of the five paths from Section 4 can run read-only, write-back, or with a human checking every write. The channel and the trust level are two separate decisions, and conflating them is how teams end up writing directly to a clinical record through a channel that was never built to carry that kind of risk. Read vs write access is the axis this section is actually about.

‍

Read-only sync

Read-only sync is the safest default. Pull patient demographics, appointment data, and clinical notes in for dashboards and reference, and never push anything back. A bad read is cheap to fix: correct it on your side, resync, done. Nothing about the source system changes because of a mistake on yours, which is exactly why most first integrations start here, with an appointments sync or a demographics feed, before anyone touches a write.

‍

Selective write-back

Selective write-back is worth more and costs more. You're no longer just pulling data, you're pushing specific updates into a system a practice depends on for its own daily operations. Name the boundary precisely before you write a single line of code: exactly which fields your integration is allowed to touch, and nothing beyond that list.

‍

Bidirectional sync sounds appealing in a planning meeting and gets messy in production the moment two systems both think they own the same field. Pick one system as the source of truth per field, even inside a nominally bidirectional setup.

‍

Human-in-the-loop

Human-in-the-loop is the right default for anything touching billing codes or clinical documentation. An automated write error in a CPT code produces a rejected claim. An automated write error in a clinical note produces a wrong record that's expensive to trace back and worse to explain in an audit. A person reviewing the write before it commits catches both, at the cost of speed you're trading away on purpose.

‍

What about Epic, Oracle Health, and the big EHRs in behavioral health?

Some readers' customers are CCBHCs or larger health systems running Epic or Oracle Health, not TherapyNotes or SimplePractice practices. That's a genuinely different project: sandbox setup, per-site app review, FHIR and SMART on FHIR instead of the paths covered here. Epic's own App Orchard and Showroom approval process typically takes anywhere from several weeks to several months depending on scope, closer to an enterprise timeline than anything in this piece, and Oracle Health runs a comparable review process of its own. Our EHR integration guide covers that project in full.

‍

Cost and timeline of behavioral health EHR integrations

A behavioral health EHR integration costs a fraction of an Epic-style project and moves in weeks, not the four to nine months enterprise timelines often take. Weeks is still real time, mostly on the vendor's side of the process, and it belongs in a launch plan from day one.

‍

Where the time actually goes

Partner-approval processes for comparable independent practice-management platforms can add 2 to 4 weeks before development even starts. That's calendar time spent waiting on someone else's review queue. Your own engineering time doesn't start burning until that queue clears. It's a fraction of the four-to-nine-month range an enterprise EHR project like Epic or Oracle Health typically runs, covered in the section above, but it's still real time to plan around rather than assume away. Once approval clears, the development process itself, the part your team actually controls, tends to move quickly by comparison.

‍

Where the money actually goes

Three cost drivers show up across comparable integration projects:

‍

Treat these as a typical range for this class of integration, not a quote for TherapyNotes, SimplePractice, Valant, or Qualifacts specifically. Maintenance covers the ongoing cost of a vendor's platform changing underneath you: a UI redesign that breaks a reverse-engineered adapter, a version bump on a partner API, a new field in an export you now have to handle.

‍

Budget both timelines into the launch plan before you commit to a date with anyone above you. The vendor-side clock starts the day you submit a partner application. Your own engineering clock starts later, once that approval clears, and a launch date that ignores the gap between the two is a launch date you'll miss.

‍

Common mistakes that sink behavioral health EHR integration projects

Most integration projects in this space stall or die on operational failures: a vendor relationship nobody actively managed, a timeline built on hope instead of the actual approval process. The technical work in Sections 4 through 8 is rarely the part that sinks a project.

1. Treating partner-program approval as a finished integration. Getting accepted into a partner program is the start of scoping, not the finish line. Real integration work, the actual data mapping, testing, and edge cases, begins after approval, and celebrating the acceptance email as if the project shipped leads straight to a slipped timeline.
2. Skipping a test against the practice's actual account. Plan tier and configuration vary practice to practice, sometimes significantly, right down to which features are even enabled. A timeline built against generic vendor documentation instead of the specific account you'll actually integrate with is a guess dressed up as a plan.
3. Underestimating the practice admin's bandwidth. The person who needs to grant access or sign enrollment paperwork isn't your employee, and this project isn't their priority. Expect the request to sit in their inbox for a while. That's normal, and building slack into the timeline for it beats being surprised by it.
4. Building before the BAA chain and consent scoping are settled. Writing integration code before every agreement in the chain is signed means retrofitting compliance under time pressure later, the worst possible way to handle a BAA or a consent-scoping question. Settle the paperwork first, then write the code that depends on it.

‍

How Specode can help

Building your own lightweight system of record, the pattern from the section above, is real engineering work without the right foundation underneath it. With that foundation, it's mostly a modeling exercise: deciding what your product's record should actually contain.

‍

Specode's custom data models let you define exactly that: the entities, fields, relationships, and permissions your product's clinical record actually needs, not a generic schema borrowed from someone else's EHR. Composable healthcare skills, covering things like patient intake, provider profiles, and scheduling, layer onto that foundation and encode healthcare domain knowledge a PM or compliance consultant would otherwise have to supply by hand.

‍

None of that has to wait on a separate compliance build-out. Backend hosting comes with a BAA included on the Pro plan, no separate hosting account or negotiation required, and audit logging for PHI and ePHI surfaces is a capability Specode can plan and implement directly into the surfaces that need it.

‍

Start by scoping what your product's own record actually needs to hold: the fields, the relationships, the permissions. That's the foundation behind reliable EHR integration for mental health apps, a record of your own, built to your actual workflow, that stays useful no matter how deep any single vendor connection goes.