TherapyNotes

Supergood | TherapyNotes API

Alex Klarfeld

Alex Klarfeld

— 7 min read

TherapyNotes is an electronic health record (EHR) and practice management platform built for behavioral and mental health practices. With an unofficial API, you could programmatically work with patients, appointments, clinical notes, billing and claims, and portal workflows instead of relying solely on the web UI and batch exports.

If your company builds healthcare software—telehealth, patient engagement, analytics, RCM, or care coordination—integrating with TherapyNotes unlocks data flows like pulling patient demographics and insurance, pushing appointments with CPT codes, creating draft progress notes, tracking note signatures and lock status, retrieving claim/ERA statuses, and syncing client portal tasks. That means you can power features such as automated intake, eligibility-aware scheduling, outcomes dashboards, and revenue cycle automation without manual double entry.

We hear common requests from TherapyNotes users for: a public API or webhooks, two-way scheduling integrations, deeper access to note metadata (while respecting clinical lock rules), and more direct billing/ERA feeds. Supergood addresses these gaps with a stable, production-grade, unofficial TherapyNotes API.

What is TherapyNotes?

TherapyNotes is a behavioral health EHR used by solo clinicians, group practices, and clinics to manage scheduling, documentation, billing, telehealth, and patient engagement. Core modules include appointment scheduling, a to-do list that drives documentation tasks, templated clinical notes, insurance billing (837P/835), patient portal and forms, telehealth, e-prescribing (for prescribers), and credit card payments.

Core product areas include:

  • Scheduling and calendar management (in-person and telehealth)
  • Patient (client) demographics, insurance, and contacts
  • Clinical documentation (intake, progress, treatment plans, discharge)
  • E-prescribing for prescribers (integrated via a third-party eRx network)
  • Patient portal (forms, document sharing, appointment requests)
  • Billing and claims (837P submission, 835 remittance posting)
  • Payments and copay collection
  • Tasks/To-Do workflows and compliance tracking

Common data entities:

  • Patients/Clients
  • Providers/Clinicians and Locations
  • Appointments (service codes, telehealth flags, statuses)
  • Clinical Notes (draft, signed, locked; note types; diagnoses)
  • Insurance Policies and Payers
  • Claims (837P) and Remittances (835/ERA)
  • Payments, Adjustments, and Statements
  • Portal Forms and Documents
  • Tasks/To-Do Items (e.g., notes due)

The TherapyNotes Integration Challenge

Organizations rely on TherapyNotes daily, but turning portal-first workflows into automated pipelines can be hard:

  • No public API/webhooks: Most workflows live in the browser UI and exports, making automation difficult
  • Strong enterprise security: MFA/SSO and role permissions complicate headless access
  • Clinical lock rules: Signed/locked notes must preserve audit trails and often cannot be edited
  • Third-party dependencies: eRx and clearinghouse connections may introduce separate authentication and timing windows
  • Data export formats: CSV/EDI/SFTP interfaces require mapping, reconciliation, and error handling
  • Calendar and portal limitations: Teams often request two-way scheduling and real-time form updates beyond read-only feeds

How Supergood Creates TherapyNotes APIs

Supergood reverse-engineers authenticated browser flows and batch interfaces to deliver a resilient API endpoint layer.

  • Handles username/password, SSO/OAuth, and MFA (SMS, email, TOTP) securely
  • Maintains session continuity with automated refresh and change detection
  • Normalizes patients, appointments, notes, billing, and ERA artifacts for consistent schemas
  • Aligns with customer entitlements and licensing constraints to ensure compliant access
  • Bridges batch exports and clearinghouse/SFTP flows with signed URL retrieval and delivery

Use Cases

Patient and Appointment Synchronization

  • Push new patient registrations and insurance policies from your intake system
  • Create appointments with CPT codes and telehealth flags from your scheduler
  • Maintain a single source of truth for demographics and primary/secondary insurance

Clinical Documentation Workflows

  • Generate draft progress notes from completed appointments with prefilled diagnoses and CPTs
  • Track note status (draft, signed, locked) and route tasks to clinicians
  • Retrieve treatment plan metadata for outcomes and care coordination dashboards

Billing and Revenue Cycle Automation

  • Build claims from completed/signed sessions and submit via the configured clearinghouse
  • Pull 835/ERA data to reconcile payments and post adjustments automatically
  • Surface rejection codes and claim statuses to billing staff in near real time

Patient Engagement and Portal

  • Pre-assign portal intake forms based on appointment type and insurance
  • Send telehealth links and reminders triggered by schedule changes
  • Monitor outstanding consents and e-signature completion before the visit

Available Endpoints

Authentication

POST /sessions: Establish a session using credentials. Supergood manages MFA (SMS, email, TOTP) and SSO/OAuth when enabled. Returns a short-lived auth token maintained by the platform.

curl --request POST \
  --url https://api.supergood.ai/integrations/<integration_id>/sessions \
  --header 'Authorization: Basic <Base64 encoded token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "[email protected]",
    "password": "<password>",
    "mfa": {"type": "totp", "code": "123456"}
  }'

Example response

{
  "authToken": "eyJhbGciOi...",
  "expiresIn": 3600,
  "user": {
    "id": "u_8f2a31",
    "name": "Billing Admin",
    "entitlements": ["patients", "appointments", "notes", "billing"]
  }
}

Patients

GET /patients: Retrieve patients/clients with demographics, insurance, and portal status. Use filters to scope syncs.

Query parameters

  • updatedSince: ISO 8601 datetime
  • status: string (active, inactive)
  • search: string (name, MRN, DOB)
  • externalId: string

Example response

{
  "items": [
    {
      "patientId": "pt_2c9a7f",
      "externalId": "ehr-44102",
      "firstName": "Avery",
      "lastName": "Nguyen",
      "dateOfBirth": "1991-07-21",
      "sex": "female",
      "phone": "+1-215-555-0182",
      "email": "[email protected]",
      "address": {
        "line1": "120 Walnut St",
        "city": "Philadelphia",
        "region": "PA",
        "postalCode": "19103"
      },
      "emergencyContact": {"name": "L. Nguyen", "phone": "+1-215-555-0199"},
      "insurance": [
        {
          "payerId": "payer_bcbs_pa",
          "planName": "BCBS PPO",
          "memberId": "M1234567",
          "groupNumber": "GRP-3321",
          "copay": 20.0,
          "isPrimary": true,
          "eligibility": {"lastChecked": "2026-01-20T14:05:00Z", "status": "active"}
        }
      ],
      "portal": {"invited": true, "activated": true},
      "status": "active",
      "createdAt": "2025-11-18T16:22:10Z",
      "updatedAt": "2026-01-20T18:00:31Z"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 1
}

POST /patients: Create or update a patient. Idempotent by externalId.

curl --request POST \
  --url https://api.supergood.ai/integrations/<integration_id>/patients \
  --header 'Authorization: Bearer <authToken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "externalId": "ehr-44102",
    "firstName": "Avery",
    "lastName": "Nguyen",
    "dateOfBirth": "1991-07-21",
    "email": "[email protected]",
    "phone": "+1-215-555-0182",
    "insurance": [
      {"payerId": "payer_bcbs_pa", "memberId": "M1234567", "planName": "BCBS PPO", "isPrimary": true}
    ]
  }'

Example response

{
  "patientId": "pt_2c9a7f",
  "status": "created",
  "externalId": "ehr-44102"
}

Appointments

GET /appointments: List appointments with CPT/service codes, telehealth flags, and note/billing linkage.

Query parameters

  • start: ISO 8601 datetime
  • end: ISO 8601 datetime
  • clinicianId: string
  • patientId: string
  • status: string (scheduled, checked_in, completed, canceled, no_show)

Example response

{
  "items": [
    {
      "appointmentId": "ap_91bd20",
      "patientId": "pt_2c9a7f",
      "clinicianId": "cln_aa45f1",
      "location": {"type": "telehealth", "roomUrl": "https://video.example/room/abc"},
      "startTime": "2026-01-22T15:00:00Z",
      "endTime": "2026-01-22T15:53:00Z",
      "serviceCode": {"cpt": "90837", "modifiers": []},
      "status": "completed",
      "note": {"noteId": "nt_6d2c01", "status": "draft"},
      "billing": {"claimId": null}
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 1
}

POST /appointments: Create or update an appointment with service metadata and telehealth options.

curl --request POST \
  --url https://api.supergood.ai/integrations/<integration_id>/appointments \
  --header 'Authorization: Bearer <authToken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "patientId": "pt_2c9a7f",
    "clinicianId": "cln_aa45f1",
    "startTime": "2026-01-29T19:00:00Z",
    "endTime": "2026-01-29T19:53:00Z",
    "location": {"type": "office", "name": "Main Office"},
    "serviceCode": {"cpt": "90834", "modifiers": ["95"]},
    "telehealth": {"enabled": true},
    "reminders": {"sms": true, "email": true},
    "referenceId": "sched-78422"
  }'

Example response

{
  "appointmentId": "ap_2f9d88",
  "status": "scheduled",
  "referenceId": "sched-78422"
}

Clinical Notes

POST /clinical-notes: Create or update a draft clinical note. Signed/locked notes are immutable; updates require a compliant addendum where supported.

curl --request POST \
  --url https://api.supergood.ai/integrations/<integration_id>/clinical-notes \
  --header 'Authorization: Bearer <authToken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "patientId": "pt_2c9a7f",
    "clinicianId": "cln_aa45f1",
    "appointmentId": "ap_91bd20",
    "type": "progress",
    "sessionDate": "2026-01-22",
    "status": "draft",
    "diagnoses": [
      {"icd10": "F41.1", "description": "Generalized anxiety disorder"}
    ],
    "cpt": "90837",
    "content": {
      "subjective": "Client reports reduced worry, improved sleep.",
      "objective": "Affect congruent, cooperative, oriented x4.",
      "assessment": "GAD stable; PHQ-9 improved from 10 to 6.",
      "plan": "Continue CBT; assign worry log."
    },
    "referenceId": "note-nt-001"
  }'

Example response

{
  "noteId": "nt_6d2c01",
  "status": "draft",
  "locked": false,
  "referenceId": "note-nt-001"
}

GET /clinical-notes: Retrieve notes with lock/signature metadata for audit and billing.

Query parameters

  • patientId: string
  • clinicianId: string
  • type: string (intake, progress, treatment_plan, discharge)
  • status: string (draft, signed, locked)
  • updatedSince: ISO 8601 datetime

Example response

{
  "items": [
    {
      "noteId": "nt_6d2c01",
      "patientId": "pt_2c9a7f",
      "clinicianId": "cln_aa45f1",
      "type": "progress",
      "status": "signed",
      "locked": true,
      "sessionDate": "2026-01-22",
      "diagnoses": [{"icd10": "F41.1"}],
      "cpt": "90837",
      "signatures": [{"name": "Dr. S. Patel", "timestamp": "2026-01-22T17:22:12Z"}],
      "lockedAt": "2026-01-22T17:22:12Z"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 1
}

Claims and ERAs

POST /claims: Assemble and submit a professional claim (837P) based on completed appointments and signed notes. Supports payer-specific rules and rendering/billing provider details.

curl --request POST \
  --url https://api.supergood.ai/integrations/<integration_id>/claims \
  --header 'Authorization: Bearer <authToken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "patientId": "pt_2c9a7f",
    "payerId": "payer_bcbs_pa",
    "billingProvider": {
      "npi": "1234567890",
      "name": "Center for Behavioral Health",
      "taxId": "12-3456789"
    },
    "serviceLines": [
      {
        "appointmentId": "ap_91bd20",
        "cpt": "90837",
        "dxPointers": ["A"],
        "units": 1,
        "fee": 150.0,
        "renderingProviderNpi": "1234567890"
      }
    ],
    "submissionChannel": "clearinghouse",
    "referenceId": "clm-batch-jan22"
  }'

Example response

{
  "claimId": "clm_71b0cd",
  "status": "submitted",
  "edi": {"format": "837P", "size": 42311},
  "createdAt": "2026-01-22T18:05:42Z",
  "referenceId": "clm-batch-jan22"
}

GET /eras: Retrieve remittance advice (835) summaries to reconcile payments.

Query parameters

  • claimId: string
  • payerId: string
  • postedSince: ISO 8601 datetime

Example response

{
  "items": [
    {
      "remittanceId": "era_5a220e",
      "claimId": "clm_71b0cd",
      "payerId": "payer_bcbs_pa",
      "paymentDate": "2026-01-29",
      "amountPaid": 110.0,
      "patientResponsibility": 20.0,
      "adjustments": [
        {"group": "CO", "reason": "45", "amount": 20.0, "description": "Contractual obligation"}
      ],
      "status": "posted"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 1
}

Get full API Specs →

Technical Specifications

  • Authentication: Username/password with MFA (SMS, email, TOTP) and SSO/OAuth where enabled; supports service accounts or customer-managed credentials
  • Response format: JSON with consistent resource schemas and pagination
  • Rate limits: Tuned for enterprise throughput while honoring licensing and usage controls
  • Session management: Automatic reauth and cookie/session rotation with health checks
  • Data freshness: Near real-time retrieval of patients, appointments, notes, claims, and ERAs
  • Security: Encrypted transport, scoped tokens, and audit logging; respects TherapyNotes entitlements and clinical lock rules
  • Webhooks: Optional asynchronous delivery for appointment changes, note status updates, claim submissions, and ERA postings

Performance Characteristics

  • Latency: Sub-second responses for list/detail queries under normal load
  • Throughput: Designed for high-volume scheduling, documentation, and billing pipelines
  • Reliability: Retry logic, backoff, and idempotency keys minimize duplicate actions
  • Adaptation: Continuous monitoring for UI/API changes with rapid adapter updates

Getting Started

  1. Schedule Integration Assessment

Book a 30-minute session to confirm your TherapyNotes product mix, licensing, and authentication model.

  1. Supergood Builds and Validates Your API

We deliver a hardened TherapyNotes adapter tailored to your workflows and entitlements.

  1. Deploy with Monitoring

Go live with continuous monitoring and automatic adjustments as TherapyNotes evolves.

Schedule Integration Call →

Frequently Asked Questions

Q: Which TherapyNotes modules can this integration cover?

Supergood supports workflows across widely used TherapyNotes features—patients, appointments, clinical notes (respecting lock/signature rules), billing/claims, ERAs, portal workflows, and telehealth metadata—subject to your licensing and entitlements. We scope coverage during integration assessment.

Q: How are MFA, SSO, and clearinghouse/eRx dependencies handled?

We support username/password + MFA (SMS, email, TOTP) and can operate behind SSO/OAuth when enabled. For batch/billing flows, we manage clearinghouse interfaces and timing windows and retrieve signed URLs or delivery confirmations. eRx connectivity observes prescriber permissions and cannot be altered where prohibited.

Q: Can I create or modify signed/locked notes?

Signed/locked notes are immutable. Our API returns lock and signature metadata and supports compliant addenda where available. Draft notes can be created/updated and routed for signature.

Q: Is this HIPAA compliant?

Supergood implements encryption in transit, scoped tokens, audit logs, and least-privilege access. We operate under a BAA and align to your TherapyNotes entitlements and clinical privacy requirements.

Ready to automate your TherapyNotes workflows?

Supergood can have your TherapyNotes integration live in days with no ongoing engineering maintenance.

Get Started →

Read more