How EHR and EMR API integration works with TouchpointHQ
Behavioral health outcome data is only useful if it lands where clinicians already work. TouchpointHQ exposes a REST API and FHIR-shaped resources so assessment results, severity bands, quality-measure numerators and alert events can be written back into your EHR, your data warehouse or your payer reporting pipeline. This page covers the integration patterns we support, the resources and endpoints involved, what a project timeline realistically looks like, and how the same data becomes HEDIS-ready output.
Four integration patterns, from fastest to deepest
Most organizations do not need a full bidirectional interface on day one. The fastest path to value is usually to run assessments in TouchpointHQ and push results into the chart, then add inbound patient sync once the outbound flow is trusted. Every pattern below is available with the same API credentials; the difference is how much of your EHR project queue it consumes.
| Pattern | Direction | What moves | Typical setup |
|---|---|---|---|
| REST API | Bidirectional | Patients, assessment sends, responses, scores, alerts, quality-measure rollups | Days — an API key and your own client code |
| Webhooks | Outbound (event-driven) | Assessment completed, threshold crossed, crisis item endorsed, delivery failed | Hours — register an HTTPS endpoint and verify the signature |
| FHIR-shaped resources | Outbound | QuestionnaireResponse, Observation, Patient, Encounter references | Weeks — mapping review with your interface team |
| Scheduled file exchange | Bidirectional | Roster in, results and score history out (CSV over SFTP) | Days — the fallback when API access is restricted |
The resources an integration actually touches
An outcome-measurement interface is narrower than a full clinical interface. You need to identify the patient, know which instrument was administered, carry the answers and the total score, and attach the result to the right encounter or episode. That is four resources, not forty.
| TouchpointHQ object | FHIR R4 resource | Carries | Notes |
|---|---|---|---|
| Patient | Patient | MRN or external ID, name, date of birth, contact email | We key on your external ID so the MRN stays the system of record |
| Assessment form | Questionnaire | Instrument code (PHQ-9, GAD-7, PCL-5, AUDIT-C), item text, response options | Instrument codes are stable and safe to map once |
| Assessment response | QuestionnaireResponse | Item-level answers, completion timestamp, administration mode | Includes partially completed responses with a status flag |
| Score and severity | Observation | Total score, severity band, change from baseline, LOINC code where one exists | Most charts want the Observation, not the item detail |
| Visit context | Encounter (reference only) | Encounter ID supplied by you on send or on roster sync | Optional, but it is what makes measure attribution clean |
| Clinical alert | Flag / webhook event | Tier, triggering item or threshold, timestamp, acknowledging user | Suicidality and rapid-deterioration events are delivered immediately |
Authentication, rate limits and idempotency
- Authentication is a per-organization API key sent as a bearer token over TLS. Keys are scoped to one organization's data and can be rotated without downtime.
- Every write endpoint accepts an idempotency key so a retried request after a timeout cannot create a duplicate patient or a duplicate send.
- Reads are paginated with a cursor rather than an offset, so a long roster export stays consistent while new records are being written.
- Webhook payloads are signed with an HMAC-SHA256 signature over the raw body. Verify the signature before you parse the payload, and treat delivery as at-least-once.
- Rate limits are published per plan and returned in response headers, so a nightly batch can back off cleanly instead of failing.
- All access is logged with the acting key, endpoint and record identifiers, which is what an auditor will ask for.
Encounter data, attribution and why it matters for reporting
The difference between an outcome dataset that supports a payer conversation and one that does not is almost always attribution. A score with no encounter, no rendering clinician and no episode start date cannot be tied to a measure denominator, so it cannot be counted.
When you send us an external patient ID, an encounter reference and a treatment start date, every downstream artifact inherits them: the score history, the days-from-treatment-start trend, the clinician-level rollups and the HEDIS numerator and denominator counts. When you do not, the data is still clinically useful but the reporting has to be reconstructed by hand later.
- Send the external patient ID on roster sync, not later — retrofitting identifiers across historical responses is the most common rework in these projects.
- Include the encounter or episode identifier on the send request when the assessment is tied to a visit.
- Include a treatment start date so longitudinal trends can be expressed in days from start rather than calendar dates.
- Send the rendering clinician's identifier if you want clinician-level outcome comparisons.
FHIR-based quality measures
Depression and substance use quality measures depend on a documented numeric score from an approved instrument, captured in a defined window and followed up within a defined interval. Once assessment responses exist as QuestionnaireResponse and score Observations with encounter references, those measures become a query rather than a chart review.
TouchpointHQ computes the rollups on its side and exposes them through the API, so you can either pull finished numerator and denominator counts or pull the underlying Observations and compute them in your own analytics stack.
- Depression screening and follow-up: PHQ-9 or PHQ-2 followed by PHQ-9, with the follow-up interval tracked automatically.
- Depression remission and response: PHQ-9 under 5, and 50% reduction from baseline, at the defined follow-up point.
- Unhealthy alcohol use screening and counselling: AUDIT-C or AUDIT with the brief-intervention flag.
- Substance use follow-up: instrument administration and treatment engagement dates within measure windows.
- Each rollup exposes both the count and the member-level detail, because plans generally ask for the detail during validation.
What an integration project actually looks like
Cloud-native behavioral health systems can be connected in days because access is a matter of credentials. Enterprise systems are slower for organizational reasons rather than technical ones: interface queues, security review and testing environments. We scope enterprise work with your IT team rather than promising an app-store install.
| System type | Typical approach | Timeline | Main dependency |
|---|---|---|---|
| Cloud behavioral health platforms | REST API plus webhooks | Days to 2 weeks | Credential provisioning |
| Practice-management and telehealth tools | REST API or scheduled file exchange | 1-3 weeks | Field mapping decisions |
| Enterprise EHRs (Epic, Oracle Health) | FHIR resource mapping through your interface team | 4-8 weeks | Your interface queue and security review |
| Homegrown or legacy systems | REST API or SFTP with a custom mapping | 2-6 weeks | Availability of a stable export |
Security and access control
- All traffic is TLS 1.2 or higher; data is encrypted at rest.
- API keys are organization-scoped, and row-level access rules mean a key cannot read another organization's patients even by guessing an ID.
- Every read and write is written to an access log with the acting credential and the affected record.
- Webhook endpoints you register must be HTTPS; payload signatures let you reject anything you did not originate.
- Patient-facing assessment links are single-use, expiring tokens validated server-side; the token never grants direct database access.
- TouchpointHQ is built as HIPAA-ready infrastructure, and a business associate agreement is part of the onboarding paperwork for any integration that moves identified data.
The workflow end to end
1. Get credentials and read the reference
Request an API key for your organization and review the endpoint reference. Start against a small test roster rather than your full patient list.
2. Sync a roster
Push patients with your external IDs, and optionally the clinician and treatment start date. Duplicate detection is on email within a clinician, so re-running a roster is safe.
3. Trigger assessments
Send an instrument to a patient, or create a recurring schedule. Each send returns a response ID you can store against the chart.
4. Receive results
Take completion events over webhooks for near-real-time chart updates, or poll for responses on a schedule. Both give you item answers, total score and severity band.
5. Write back to the chart
Map the score to an Observation and, where you want the detail, the response to a QuestionnaireResponse. Most organizations write the score plus a link to the full report.
6. Subscribe to alerts
Route suicidality and rapid-deterioration events to the same place your clinical team already watches, so an urgent finding does not sit in a portal nobody opens.
7. Pull quality-measure rollups
Once data is flowing, pull numerator and denominator counts on a monthly cadence for internal review and payer reporting.
Related tools and guides
Frequently asked questions
Do you have an EHR integration API?
Yes. TouchpointHQ exposes a REST API for patients, assessment sends, responses, scores, alerts and quality-measure rollups, plus signed webhooks for event-driven updates and FHIR-shaped resources for interface teams that want QuestionnaireResponse and Observation payloads.
Which EHR and EMR systems can you connect to?
Any system with an API or HL7/FHIR interface, including Epic, Oracle Health (Cerner), athenahealth, eClinicalWorks, NextGen, TherapyNotes, SimplePractice, Valant, Qualifacts, Netsmart and Kipu. Cloud systems connect in days; enterprise systems are scoped with your interface team and usually take four to eight weeks.
Do you support FHIR?
Yes — assessment responses map to FHIR R4 QuestionnaireResponse and scores map to Observation, with Patient and Encounter references supplied by you. That is what makes FHIR-based quality measure calculation possible on your side rather than only on ours.
How is the API authenticated?
With a per-organization API key sent as a bearer token over TLS. There is no OAuth dance to implement for server-to-server use, keys are scoped to a single organization, and they can be rotated without downtime.
Can we get results pushed to us instead of polling?
Yes. Register an HTTPS webhook endpoint and you will receive signed events when an assessment is completed, a clinical threshold is crossed, a crisis item is endorsed, or a delivery fails. Verify the HMAC signature before parsing, and expect at-least-once delivery.
What if our EHR cannot expose an API at all?
Scheduled file exchange over SFTP covers it: a roster file in, results and score history out, on whatever cadence you choose. It is less immediate than webhooks but it produces the same reportable dataset.
How long does an integration take?
Days for cloud behavioral health systems, one to three weeks for practice-management tools, and typically four to eight weeks for enterprise EHRs where the constraint is your organization's interface queue and security review rather than the interface itself.
Is patient data safe to move through the API?
Traffic is TLS-encrypted, data is encrypted at rest, keys are organization-scoped, every access is logged, and a business associate agreement is part of onboarding for any integration handling identified data. TouchpointHQ is built as HIPAA-ready infrastructure.
References
- HL7 FHIR R4 specification — Questionnaire, QuestionnaireResponse, Observation and Encounter resources.
- SMART on FHIR app launch framework, for organizations that want the assessment view launched in context from the chart.
- NCQA HEDIS technical specifications define the measure windows and instrument requirements referenced above; confirm the current measurement-year specification before reporting.
Educational information for clinicians. Screening results are not a diagnosis and do not replace clinical assessment. If you or someone you know is in crisis, call or text 988 for the Suicide & Crisis Lifeline.