BestNotes

Supergood | BestNotes API

Alex Klarfeld

Alex Klarfeld

— 6 min read
Supergood | BestNotes API

Programmatically access intake, client rosters, scheduling, clinical notes, assessments, and treatment planning workflows in BestNotes with a stable REST API. Supergood builds and operates production-grade, unofficial BestNotes integrations so your team can automate behavioral health EHR and CRM pipelines without heavy custom engineering.

BestNotes is a cloud-based EHR and CRM built for behavioral health and addiction treatment organizations. Teams use it to manage referrals and intake, client records, appointments, group sessions, clinical documentation (notes, assessments, treatment plans), outcomes measurement, secure messaging, and client portal engagement. With an unofficial API, you could synchronize client rosters from your other systems, automate appointment creation and updates, push structured clinical notes, pull standardized assessment results for analytics, and keep treatment plans current across platforms.

If you’re a behavioral health provider, virtual care company, care management platform, or revenue cycle team, integrating your tech stack with BestNotes unlocks concrete data flows and features:

  • Pull: Client demographics and enrollment, care team and provider rosters, appointments and statuses, clinical notes metadata, assessment results (e.g., PHQ-9, GAD-7), program participation and consent states
  • Push: New/updated clients from your CRM/EMR, scheduled appointments (telehealth or in-person), clinical note entries with template references, treatment plan goals and objectives, outcomes survey submissions
  • Build: Automated intake and referral triage, authorization-aware scheduling, measurement-based care dashboards, documentation workflows synchronized to telehealth tools, unified reporting across sites and programs

What is BestNotes?

BestNotes provides an integrated EHR + CRM designed for mental health, SUD (substance use disorder), and residential treatment programs. It centralizes referral management, intake, client and contact records, scheduling, documentation (progress notes, group notes, treatment plans), assessments/outcomes, secure communications, and client portal features. Many teams rely on BestNotes daily to coordinate care across multiple programs and locations.

Core product areas include:

  • Referral, intake, and contact management (CRM)
  • Client/patient records and care team assignments
  • Scheduling for individual and group sessions (telehealth and in-person)
  • Clinical documentation: progress notes, group notes, treatment plans
  • Assessments and outcomes (e.g., standardized questionnaires)
  • Client portal and secure messaging
  • Reporting and exports for compliance and operations

Common data entities:

  • Clients/Contacts (patients, guardians, referral sources)
  • Providers/Staff (clinicians, counselors, case managers)
  • Appointments/Sessions (individual, group, telehealth)
  • Notes/Encounters (progress notes, group notes)
  • Assessments (instrument responses, scores)
  • Treatment Plans (goals, objectives, interventions)
  • Programs/Locations (enrollments, levels of care)
  • Consents/Authorizations (HIPAA, releases)

The BestNotes Integration Challenge

Organizations depend on BestNotes for clinical operations, but turning portal-first workflows into automated pipelines is hard:

  • No public, unified API: Many teams report relying on manual exports or custom reports to move data, making real-time integration difficult
  • Custom form templates: Documentation and assessments vary by program, requiring normalization across sites and templates
  • Locked notes and audit trails: Clinical compliance rules impose strict edit and signature flows that automation must respect
  • Group session nuances: Bulk documentation and attendance tracking for groups complicate straightforward CRUD
  • SSO/MFA and role-based security: Strong enterprise identity controls can block headless automation without specialized handling
  • Reporting timing windows: Batch reports and CSV/scheduled exports don’t match operational needs for near real-time sync

How Supergood Creates BestNotes 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 client, appointment, note, and assessment objects so you can integrate once across programs and templates
  • Aligns with customer entitlements and licensing constraints to ensure compliant access
  • Bridges batch exports where applicable with signed URL retrieval and delivery

Use Cases

Intake and Referral Synchronization

  • Push new referrals and intake records from your CRM into BestNotes
  • De-duplicate contacts and assign them to the appropriate program and care team
  • Maintain a single source of truth for demographics, consents, and payer info

Scheduling and Telehealth Coordination

  • Create BestNotes appointments from your scheduling or telehealth platform
  • Update statuses (scheduled, completed, no-show) and attach telehealth join links
  • Route group session attendance to documentation workflows automatically

Measurement-Based Care and Outcomes

  • Pull standardized assessment results (e.g., PHQ-9, GAD-7) for dashboards and alerts
  • Push new questionnaire submissions collected in your app
  • Track changes over time to inform care plans and program outcomes

Documentation and Compliance

  • Generate progress notes from telehealth session artifacts with structured templates
  • Enforce signing/locking flows and reason codes when editing documentation
  • Export machine-readable audit trails for quality and compliance reviews

Billing Preparation and RCM Data Bridge

  • Align service codes and units on appointments and notes for downstream billing
  • Surface missing documentation or enrollment information before claim creation
  • Feed consolidated encounter data to your RCM system or analytics warehouse

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

Clients

GET /clients: Retrieve client records with demographics, program enrollment, consents, and care team assignment. Use filters to keep external systems synchronized.

Query parameters

  • programId: string
  • status: string (active, inactive)
  • updatedSince: ISO 8601 datetime
  • tag: string (e.g., referral-source or custom label)

Example response

{
  "items": [
    {
      "clientId": "cl_9b42f0",
      "mrn": "MRN-102938",
      "firstName": "Jordan",
      "lastName": "Patel",
      "birthDate": "1993-04-12",
      "gender": "male",
      "phone": "+1-614-555-0199",
      "email": "[email protected]",
      "addresses": [{"type": "home", "line1": "100 Care Way", "city": "Columbus", "region": "OH", "postalCode": "43215"}],
      "programs": [{"programId": "prog_residential", "status": "active", "startDate": "2026-01-01"}],
      "primaryProviderId": "prv_41cf92",
      "consents": [{"type": "hipaa", "signedAt": "2026-01-01T15:21:00Z", "status": "active"}],
      "tags": ["referral-community-clinic"],
      "updatedAt": "2026-01-19T12:44:12Z"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 1
}

Appointments

POST /appointments: Create or update an appointment (individual or group) with service details and telehealth metadata. Supports status updates and cancellation reasons.

curl --request POST \
  --url https://api.supergood.ai/integrations/<integration_id>/appointments \
  --header 'Authorization: Bearer <authToken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientId": "cl_9b42f0",
    "providerId": "prv_41cf92",
    "programId": "prog_outpatient",
    "serviceCode": "90834",
    "type": "individual",
    "location": "telehealth",
    "startTime": "2026-01-19T14:00:00Z",
    "endTime": "2026-01-19T14:45:00Z",
    "status": "scheduled",
    "telehealth": {
      "joinUrl": "https://tele.example.com/j/abc123",
      "platform": "zoom"
    },
    "notes": "Weekly therapy session.",
    "referenceId": "scheduler-evt-42391"
  }'

Example response

{
  "appointmentId": "apt_58d3e0",
  "status": "scheduled",
  "type": "individual",
  "serviceCode": "90834",
  "createdAt": "2026-01-19T13:50:02Z",
  "referenceId": "scheduler-evt-42391"
}

Clinical Notes

POST /clinical/notes: Create or update a clinical note with structured content, diagnoses, and signatures. Honors compliant locking 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 '{
    "clientId": "cl_9b42f0",
    "providerId": "prv_41cf92",
    "appointmentId": "apt_58d3e0",
    "templateId": "tmpl_progress_note_v2",
    "encounterDate": "2026-01-19",
    "diagnoses": ["F33.1"],
    "serviceCode": "90834",
    "content": {
      "subjective": "Client reports improved sleep.",
      "objective": "Affect congruent, cooperative.",
      "assessment": "Moderate MDD, improving.",
      "plan": "Continue CBT; follow-up in 1 week."
    },
    "attachments": [],
    "signatures": {
      "provider": {"signed": true, "signedAt": "2026-01-19T15:02:02Z"},
      "client": {"signed": false}
    },
    "locked": true,
    "editReasonCodes": [],
    "referenceId": "telehealth-session-42391"
  }'

Example response

{
  "noteId": "note_71af2b",
  "status": "locked",
  "templateId": "tmpl_progress_note_v2",
  "createdAt": "2026-01-19T15:05:42Z",
  "referenceId": "telehealth-session-42391"
}

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 clients, appointments, notes, and assessment artifacts
  • Security: Encrypted transport, scoped tokens, and audit logging; respects BestNotes entitlements and compliance requirements
  • Webhooks: Optional asynchronous delivery for appointment changes, note status updates, and assessment submissions

Performance Characteristics

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

  1. Supergood Builds and Validates Your API

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

  1. Deploy with Monitoring

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

Schedule Integration Call →

Frequently Asked Questions

Q: Which BestNotes product areas can this integration cover?

Supergood supports workflows across commonly used BestNotes EHR/CRM modules, subject to your licensing and entitlements. We scope coverage (e.g., clients/contacts, scheduling, notes, treatment plans, assessments, reporting exports) during integration assessment.

Q: How are MFA, SSO, and batch/report interfaces handled for automation?

We support username/password + MFA (SMS, email, TOTP) and can operate behind SSO/OAuth when enabled. For batch/report flows, we manage timing windows, generate normalized datasets, and retrieve signed URLs or delivery confirmations programmatically.

Q: Can I create notes and appointments directly from my telehealth or scheduling system?

Yes. You can create and update appointments (including telehealth metadata) and generate clinical notes using your chosen templates. We enforce compliant signing/locking and audit trails.

Ready to automate your BestNotes workflows?

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

Get Started →

Read more