Build on ICANotes: a FHIR API for integration partners
Connect your scheduling platform, patient portal, referral network, or telehealth product directly to ICANotes, the behavioral health EHR trusted by practices across the country.
or call 866-847-3590
Behavioral health practices increasingly rely on best-of-breed tools alongside their EHR: online scheduling widgets, patient engagement apps, referral networks, telehealth platforms. Those tools need to talk to the system where the clinical and scheduling data actually lives. The ICANotes FHIR API gives approved integration partners a standards-based, secure way to do exactly that: look up providers and locations, search and register patients, check real-time availability, and book appointments, without asking practices to duplicate data entry across systems.
What is the ICANotes FHIR API?
A partner-facing interface that exposes ICANotes clinical practice data using the HL7 FHIR R4 standard. It is built for server-to-server integrations, authenticated with OAuth2 client credentials, so your systems can exchange data with ICANotes programmatically, without routing through an end-user login.
Server-to-server, by design
Built for system integrations, not embedded in a partner's end-user login flow.
FHIR R4 wire format
Responses follow standard FHIR Bundle and resource conventions, so your existing FHIR client libraries work without custom parsing.
Scoped, multi-tenant access
Your partner credential sees only the practices explicitly linked to your account. There is no cross-partner data exposure.
What you can build with the ICANotes API
Six integration scenarios cover most of what partners need to connect a scheduling, engagement, or referral product to an ICANotes practice.
Provider Directory & Staff Lookup
Search and retrieve the complete roster of practitioners within your partnered practices: names, NPI numbers, specialties, credentials, and location assignments.
- Populate a "find a provider" experience in a patient portal or scheduling widget
- Sync the provider directory into an external system (EHR, referral network, directory listing)
- Filter providers by specialty, location, or active status
Facility & Location Discovery
Search physical and virtual (telehealth) practice locations, with addresses, hours of operation, services offered, and a telehealth flag.
- Show patients where they can be seen, in person or via telehealth
- Filter locations by geography (city, state, zip)
- Identify which locations offer a specific service
Patient Search & Registration
Search existing patients by demographics (name, date of birth, gender, chart number, phone, email) and create new patient records.
- Check whether a patient already exists before creating a new one in an intake workflow
- Pre-register new patients from an external portal or intake form
- Rely on built-in duplicate detection: the API returns candidate records when a likely duplicate is submitted, instead of silently creating a second chart
Real-Time Appointment Availability
Query available time slots for a specific provider, filtered by date range, location, service or visit type, and appointment type, computed in real time from the provider's configured availability.
- Build a "pick a time" calendar in an online scheduling widget
- Show open appointments for a particular visit reason
- Filter for telehealth-only availability
Appointment Booking
Book an appointment against a specific available slot. Booking is idempotent, so retries are safe and will not create duplicate appointments.
- Power end-to-end self-service scheduling: find provider, pick slot, book
- Integrate with third-party scheduling platforms
- Support booking from mobile apps or kiosks, where network retries are common
Reference Data & Terminology
Retrieve standardized code lists for visit reasons, appointment statuses, cancellation reasons, administrative genders, gender identities, telehealth place-of-service codes, and appointment types.
- Populate dropdowns and picker controls with the correct option set
- Keep your system's terminology in sync with ICANotes
Who integrates with ICANotes
The API is built for the kinds of partners behavioral health practices already work with.
Built with integrators in mind
A few characteristics of the API matter most once you are actually building against it.
_count / _offset pagination with next and previous links in the response.OperationOutcome with issue codes, not an opaque error string.A typical integration flow
Most partner integrations follow the same five steps.
Discover
Search providers, locations, and visit reasons to populate your UI.
Identify
Search for an existing patient, or create a new one.
Find availability
Query open slots for the chosen provider, location, and visit type.
Book
Submit an appointment referencing the chosen slot and patient.
Confirm
Receive the booked appointment's ID and status back.
Questions from API partners
Is the ICANotes API standards-based?
How is my data kept separate from other partners' data?
What can partners actually search or retrieve through the API?
Can partners book appointments through the API, or just view availability?
What happens if I try to register a patient who already exists?
Is write access available beyond patient registration and appointment booking?
Is ICANotes itself HIPAA-compliant?
Request API access
Tell us about your platform and what you want to build. Our integrations team will follow up.
Ready to build on ICANotes?
If your platform needs to talk to the EHR where behavioral health practices actually keep their scheduling and patient data, the ICANotes FHIR API is built to make that connection straightforward: standards-based, scoped to your practices, and designed for real integration work, not screen-scraping.
Questions? Call 866-847-3590