ICANotes

Supergood | ICANotes API

Alex Klarfeld

Alex Klarfeld

— 7 min read
Supergood | ICANotes API

Programmatically access clients, appointments, treatment plans, clinical notes, and billing workflows in ICANotes with a stable REST API. Supergood builds and operates production-grade, unofficial ICANotes integrations so your team can automate behavioral health documentation, scheduling, and claims pipelines without heavy custom engineering.

ICANotes is an EHR purpose-built for behavioral and mental health practices. It focuses on rapid, structured clinical documentation for psychiatry and therapy, plus scheduling, patient intake/forms, treatment planning, e-prescribing, and billing support. With an unofficial API, you could synchronize client records, create and lock progress notes programmatically, align treatment plans with outcomes, manage appointment schedules, and assemble claim-ready encounter data—end to end.

If you’re a healthtech company, telehealth platform, analytics vendor, or practice management team, integrating your tech stack with ICANotes unlocks concrete data flows and features:

  • Pull: Client demographics, insurance profiles, appointments, clinical notes, diagnoses, treatment plans (goals/objectives), medication lists, encounter codes, claim statuses
  • Push: New or updated clients from intake funnels, scheduled appointments, progress notes generated from telehealth sessions, treatment plan updates, outcomes scores (PHQ-9/GAD-7), encounter coding for billing
  • Build: Automated documentation pipelines, authorization-aware scheduling, outcomes tracking dashboards, claim/charge creation tied to documented visits, compliance-grade audit exports

What is ICANotes?

ICANotes provides an ONC-certified EHR optimized for behavioral health clinicians, including psychiatrists, psychologists, counselors, social workers, and multidisciplinary clinic staff. Its structured templates enable fast intake notes, progress notes, med management notes, and treatment plans while maintaining detailed audit trails. Practices use ICANotes to schedule sessions, capture DSM-5/ICD-10 diagnoses, manage medications (often through an integrated e-prescribing partner), collect signed forms, and support billing for common behavioral health CPT codes.

Core product areas include:

  • Clinical documentation (intake, progress, med management, discharge)
  • Treatment planning (problems, goals, objectives, target dates, progress)
  • Scheduling and appointment management (in-person and telehealth)
  • Client/patient roster with insurance and consents
  • Diagnoses (DSM-5/ICD-10) and encounter coding (CPT/HCPCS modifiers)
  • E-prescribing and medication management (typically via a partner such as DrFirst)
  • Billing support and claim exports (837P, CMS-1500)
  • Patient portal and intake forms with signatures
  • Reporting and outcomes measures (e.g., PHQ-9, GAD-7)

Common data entities:

  • Clients/Patients
  • Providers/Clinicians
  • Appointments/Sessions
  • Encounters/Clinical Notes
  • Diagnoses and Problem Lists
  • Treatment Plans (goals, objectives, interventions)
  • Medications/Allergies
  • Insurance Policies and Guarantors
  • Claims, Charges, Payments/Remittances
  • Consents and Intake Forms
  • Assessments/Outcome Scores (PHQ-9, GAD-7, etc.)

The ICANotes Integration Challenge

Organizations rely on ICANotes daily, but turning portal-first behavioral health workflows into automated pipelines is hard:

  • Limited public APIs: Many users report wanting easier integrations with scheduling, telehealth, CRM, and analytics tools; most workflows live behind the web app and exports.
  • Structured templates and locking: Notes are highly structured and often “locked” post-signature; compliant edits must preserve audit trails and signatures.
  • Separate e-prescribing flows: Med management can run through external vendors (e.g., DrFirst), creating cross-system dependencies and authentication constraints.
  • Billing interfaces and batching: Practices generate encounter data and batch claims (837P/CMS-1500) via configured clearinghouses, with timing windows and file formats to respect.
  • Reporting and data export limitations: Users frequently ask for more flexible reporting/exports (treatment goals, outcomes, productivity) to feed BI tooling.
  • Strong enterprise security: MFA/SSO, role-based entitlements, and network controls complicate headless automation.

How Supergood Creates ICANotes APIs

Supergood reverse-engineers authenticated browser flows, batch interfaces, and network interactions 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 patient, appointment, note, diagnosis, and treatment plan objects so you can integrate once
  • Aligns with customer entitlements and licensing constraints to ensure compliant access
  • Bridges batch exports and clearinghouse submissions with signed URL retrieval and delivery where applicable

Use Cases

Intake and Patient Onboarding

  • Push new clients from your intake funnel or CRM into ICANotes
  • Attach signed consents and intake forms, mapping custom fields to ICANotes templates
  • Maintain a single source of truth for demographics, insurance, and emergency contacts

Scheduling and Telehealth Integration

  • Synchronize appointments between your scheduling or telehealth platform and ICANotes
  • Create session records with CPT codes and telehealth flags for downstream billing
  • Keep providers’ calendars and patient reminders up to date

Clinical Documentation and Outcomes

  • Generate progress notes from telehealth session metadata and clinician prompts
  • Update treatment plans (goals/objectives) and log outcomes (PHQ-9/GAD-7) over time
  • Lock notes with signature, track edits with reason codes, and export full audit trails

Billing and Revenue Cycle

  • Assemble encounter data into claims (837P) using documented CPT codes and modifiers
  • Route submissions to the configured clearinghouse; reconcile statuses and remittances
  • Drive productivity dashboards with session counts, code mix, and reimbursement metrics

Analytics and Compliance

  • Export machine-readable note packets and treatment plan details for quality programs
  • Monitor diagnosis trends and outcomes across cohorts
  • Prove documentation completeness and note lock signatures during audits

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_3ac75f",
    "name": "EHR Admin",
    "entitlements": ["patients", "appointments", "notes", "treatment_plans"]
  }
}

Patients

GET /patients: Retrieve client/patient profiles with demographics, insurance, and key identifiers. Use filters to target onboarding, updates, or analytics.

Query parameters

  • name: string (partial match "Last, First" or First Last)
  • dob: ISO 8601 date
  • externalId: string
  • active: boolean
  • updatedSince: ISO 8601 timestamp

Example response

{
  "items": [
    {
      "patientId": "pt_91c2e7",
      "mrn": "MRN-10293",
      "externalId": "crm_4281",
      "firstName": "Ava",
      "lastName": "Mendez",
      "dob": "1988-07-21",
      "sex": "female",
      "contact": {
        "email": "[email protected]",
        "phone": "+1-555-212-1010"
      },
      "address": {
        "line1": "45 Lakeview Dr",
        "city": "Baltimore",
        "region": "MD",
        "postalCode": "21211"
      },
      "insurance": [
        {
          "payerName": "BlueCross BlueShield",
          "memberId": "XK9281734",
          "groupNumber": "BG-120",
          "primary": true
        }
      ],
      "emergencyContact": {
        "name": "Luis Mendez",
        "phone": "+1-555-212-3434"
      },
      "status": "active",
      "updatedAt": "2026-01-22T14:13:12Z"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 1
}

Appointments

POST /appointments: Create or update an appointment with clinician, location, service coding, and telehealth flags. Sync schedules between ICANotes and external systems.

curl --request POST \
  --url https://api.supergood.ai/integrations/<integration_id>/appointments \
  --header 'Authorization: Bearer <authToken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "patientId": "pt_91c2e7",
    "providerId": "prv_12b88a",
    "locationId": "loc_baltimore",
    "startTime": "2026-01-25T15:00:00Z",
    "endTime": "2026-01-25T15:50:00Z",
    "cptCode": "90834",
    "modifiers": ["95"],
    "telehealth": true,
    "reason": "Psychotherapy, 45 minutes",
    "status": "scheduled",
    "referenceId": "telehealth-session-48201"
  }'

Example response

{
  "appointmentId": "ap_5c9f20",
  "status": "scheduled",
  "createdAt": "2026-01-22T16:05:42Z",
  "referenceId": "telehealth-session-48201"
}

Clinical Notes

POST /clinical-notes: Create or update a structured clinical note (progress, intake, med management) with diagnoses, interventions, mental status, goals addressed, and signature status. Supports compliant locks and edit reason codes.

curl --request POST \
  --url https://api.supergood.ai/integrations/<integration_id>/clinical-notes \
  --header 'Authorization: Bearer <authToken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "appointmentId": "ap_5c9f20",
    "patientId": "pt_91c2e7",
    "providerId": "prv_12b88a",
    "noteType": "progress",
    "cptCode": "90834",
    "diagnosisCodes": ["F33.1"],
    "mentalStatus": {
      "appearance": "appropriate",
      "mood": "depressed",
      "affect": "congruent",
      "thoughtContent": "no SI/HI",
      "insight": "fair",
      "judgment": "intact"
    },
    "interventions": ["CBT", "Supportive therapy"],
    "goalsAddressed": ["Reduce frequency of depressive episodes"],
    "riskAssessment": {
      "suicideRisk": "low",
      "violenceRisk": "low"
    },
    "plan": "Continue weekly psychotherapy; consider med consult if PHQ-9 > 15",
    "outcomes": {
      "PHQ9": {"score": 11, "timestamp": "2026-01-25T15:45:00Z"}
    },
    "signatures": {
      "providerSigned": true,
      "providerSignedAt": "2026-01-25T16:01:47Z"
    },
    "lockNote": true,
    "editReasonCodes": [],
    "referenceId": "telehealth-session-48201"
  }'

Example response

{
  "noteId": "note_72af3b",
  "status": "locked",
  "appointmentId": "ap_5c9f20",
  "patientId": "pt_91c2e7",
  "providerId": "prv_12b88a",
  "signedAt": "2026-01-25T16:01:47Z",
  "referenceId": "telehealth-session-48201"
}

Treatment Plans

GET /treatment-plans: Retrieve treatment plans with problems, goals, objectives, target dates, and progress. Use this to track outcomes and update plans programmatically.

Query parameters

  • patientId: string
  • activeOn: ISO 8601 date
  • providerId: string

Example response

{
  "items": [
    {
      "planId": "tp_84b9a1",
      "patientId": "pt_91c2e7",
      "providerId": "prv_12b88a",
      "startDate": "2026-01-01",
      "endDate": "2026-04-30",
      "status": "active",
      "problems": ["Major depressive disorder, recurrent"],
      "goals": [
        {
          "goalId": "goal_992f",
          "description": "Improve mood stability and reduce depressive symptoms",
          "objectives": [
            {
              "objectiveId": "obj_1a2b",
              "description": "Complete CBT homework 3x/week",
              "targetDate": "2026-03-15",
              "progress": "in_progress"
            }
          ]
        }
      ],
      "updatedAt": "2026-01-22T17:08:12Z"
    }
  ],
  "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, and treatment plans
  • Security: Encrypted transport, scoped tokens, and audit logging; respects ICANotes entitlements and compliance requirements
  • Webhooks: Optional asynchronous delivery for appointment changes, note locking, and claim exports

Performance Characteristics

  • Latency: Sub-second responses for list/detail queries under normal load
  • Throughput: Designed for high-volume documentation and scheduling 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 ICANotes product mix, licensing, and authentication model.

  1. Supergood Builds and Validates Your API

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

  1. Deploy with Monitoring

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

Schedule Integration Call →

Frequently Asked Questions

Q: Which ICANotes modules can this integration cover?

Supergood supports workflows across commonly used ICANotes areas, subject to your licensing and entitlements. We typically cover patients, appointments, diagnoses, treatment plans, clinical notes (including lock/signature handling), and billing exports. E-prescribing flows can be bridged where permitted through the configured partner.

Q: How are MFA, SSO, and external e-prescribing handled?

We support username/password + MFA (SMS, email, TOTP) and can operate behind SSO/OAuth when enabled. For e-prescribing managed via third-party vendors (e.g., DrFirst), we integrate within the constraints of your configuration, preserving audit trails and consent requirements.

Q: Can I generate claims directly from documented encounters?

Yes. You can assemble 837P lines from documented encounters (CPT/HCPCS, modifiers, units) and route submissions via your configured clearinghouse. We return statuses and artifacts for reconciliation alongside encounter data.

TherapyNotes API - Programmatically access Behavioral Health EHR workflows with Supergood

Ready to automate your ICANotes workflows?

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

Get Started →

Read more