Documentation

Getting Started

Dashboard overview

After signing up and completing the onboarding wizard, you land on your practice dashboard. The left sidebar gives you quick access to every section: Overview, Appointments, Patients, Providers, and Settings.

The Overview page is your mission control. It displays:

• Today's appointments — see upcoming visits at a glance
• Practice stats — total patients, active providers, services available
• Quick actions — buttons to create appointments, add patients, or manage providers without navigating away
• Plan info — your current plan and usage relative to limits

First steps checklist

New to Genkō? Work through these steps in order to get fully set up. Expect to spend 10–15 minutes:

1. Add your services — Go to Settings → Services and create at least one appointment type. Examples: “Initial Consultation (60 min)”, “Follow-up (30 min)”, “Assessment (45 min)”.
   Services define duration and help patients understand what to expect. You can add more later.
2. Add a provider — Go to Providers and register the first practitioner. Fill in their name, specialty, and optional bio. Then click Set Availability to define their weekly schedule (e.g. "Mon–Fri, 9am–5pm").
3. Add a patient — Go to Patients and click Add Patient. Only first and last name are required; email and phone help with communication.
4. Book your first appointment — Go to Appointments → New Appointment. Select the patient, provider, service, date, and time. Your first booking will help you understand the calendar.
5. Enable the patient portal (optional) — Go to Settings → Portal to turn on self-service booking. You'll get a public link to share with patients.
   Next step after setup: Invite your team members via Settings → Members so they can help manage appointments.

Appointments

Booking an appointment

Click New Appointment at the top right of the Appointments page. A dialog opens where you fill in:

• Patient — search by name or email. If the patient doesn't exist, you can add them inline.
• Provider — only providers with availability on the chosen date are shown.
• Service — the appointment type, which determines the default duration (adjustable if needed).
• Date & Time — the date picker highlights days with available slots. Unavailable times are grayed out.
• Notes — internal notes visible to your team but not shown to the patient.

Once saved, the appointment appears on the calendar. Confirmation emails are sent automatically to the patient and provider (if email notifications are enabled in Settings).

Calendar views

Toggle between three views using the controls at the top of the Appointments page:

• Day view — focus on a single day, hour by hour. Ideal for detailed scheduling.
• Week view — see the full week at a glance. Best for spotting gaps and managing multiple providers.
• Month view — overview of the entire month. Good for long-term planning.

You can also filter by provider to focus on a single practitioner's schedule, or view all providers together. Your last view preference is remembered, so you return to the same view after navigating away.

Conflict detection

Genkō automatically prevents double-booking. The system checks every booking in real time:

• If you try to schedule a provider at a time they're already booked, you'll see an error and the slot will not save.
• Conflicts are checked on the server, so multiple staff members booking simultaneously are also safe—only one succeeds.
• The calendar grays out unavailable times, preventing mistakes before they happen.

Buffer minutes (available on Practice plan+) add a gap between appointments so providers have time to prepare, write notes, or take a break. For example, a 60-minute appointment with 10-minute buffer means the next slot can't start until 70 minutes later.

Appointment statuses

Every appointment moves through a lifecycle with four possible states:

• Scheduled — the appointment is confirmed and appears on the calendar. This is the initial state.
• Completed — mark this after the visit has taken place. Useful for tracking provider hours and practice productivity.
• Cancelled — the appointment was cancelled by staff or by the patient via the portal. The time slot is freed up for rebooking.
• No-show — the patient did not attend. This is separate from cancellation and helps track attendance patterns.

Staff, providers, and admins can update the status from the appointment detail view. Only owners and admins can delete appointments. Cancelled and no-show appointments don't block provider availability—the slot is immediately available for new bookings.

Patients

Adding patients

Go to Patients in the sidebar and click Add Patient. Fill in:

• First & Last Name — required. Used to identify the patient in the system.
• Email — optional but recommended. Used to send appointment confirmations and reminders.
• Phone — optional. Helpful for quick follow-ups or confirmation calls.
• Date of Birth — optional. Useful for clinical context and age-related notes.
• Notes — optional. Add any relevant medical history, allergies, or preferences visible to your staff.

Patient records

Click a patient's name to open their detail page. Here you can:

• View and update contact information
• See full appointment history (past, upcoming, cancelled)
• Add or edit notes visible only to your team
• Check their usage against your plan limits

Permissions: Owners and admins can edit and delete patient records. Providers and staff have read-only access, protecting patient privacy.

Plan limits

Each plan includes a patient limit. When you reach your plan's limit, you'll need to upgrade before adding more patients. Current usage is visible in Settings → Billing.

• Free — up to 100 patients
• Solo — up to 250 patients
• Starter — up to 500 patients
• Group — up to 1,000 patients
• Practice — up to 5,000 patients
• Enterprise — unlimited

Providers

Adding providers

Go to Providers and click Add Provider. Enter:

• Name — the provider's full name (displayed to patients if portal is enabled).
• Specialty — e.g. “General Practitioner”, “Physical Therapist”, “Registered Nurse”. Helps patients understand who they're booking with.
• Bio — optional. A short description of experience or approach (shown in patient portal).

After creating a provider, click Set Availability to define when they work. Without availability set, they cannot be booked.

Setting availability

After creating a provider, click Set Availability to define their weekly schedule. Genkō uses this to show only bookable slots when creating appointments or in the patient portal.

How it works:

• Set availability for each day of the week (Monday through Sunday)
• For each working day, specify start time and end time (e.g. "9:00 AM - 5:00 PM")
• Providers not working a day can be marked as unavailable
• The system blocks bookings outside these hours

Advanced scheduling rules

Practices on the Practice plan and above can configure fine-grained rules per provider to enforce your scheduling policies:

• Buffer minutes — adds a gap between consecutive appointments. Example: 60-min appointment + 10-min buffer = next slot starts 70 minutes later. Great for note-taking or prep time.
• Max appointments per day — caps the total number of bookings for a provider on any given day. Example: max 8 appointments prevents overbooking.
• Booking window — limits how far in advance patients can book. Example: "up to 60 days ahead" prevents far-future bookings. Useful for practices that want to keep scheduling flexible.
• Day-of-week restrictions — limit which days a provider is bookable via the patient portal (staff can still book them on restricted days). Useful for specialists who work limited hours.

Services

Appointment types

Services (also called appointment types) define the kinds of visits your practice offers. Each service has:

• Name — the appointment type displayed to staff and patients (e.g. "Initial Consultation")
• Duration — default length in minutes. When you book an appointment with this service, the duration pre-fills (adjustable per booking if needed).
• Description — optional. Explains what the appointment includes. Shown to patients in the portal to set expectations.

Managing services

Go to Settings → Services to create, edit, or archive services. You can:

• Create new services — click Add Service and fill in name, duration, and optional description.
• Edit services — click the pencil icon next to any service to change its details.
• Archive services — hide old or unused services without deleting them. Archived services can't be booked but appear in historical records.

Permissions: Owners and admins can manage services; providers and staff have read-only access. There is no per-plan limit on the number of services you can create.

Team Members

Inviting team members

Go to Settings → Members and click Invite Member. Enter their email and choose a role. Here's how it works:

• An invitation email is sent to the team member's inbox with a magic link (no password needed)
• They click the link and gain immediate access to your practice
• Invites expire after 72 hours for security. You can resend from the Members page.
• Team member limits are enforced per your plan (see Billing below)

Roles & permissions

Genkō has four staff roles. Each role has different access levels:

• Owner — full access to everything, including billing, organization settings, and team management. Each organization has exactly one owner. Can transfer ownership or delete the organization.
• Admin — same access as owner except cannot transfer ownership, delete the organization, or access advanced compliance features. Good for practice managers.
• Provider — can view and manage their own schedule and appointments. Can read patient records but cannot modify members, billing, or organizational settings. Good for clinicians who don't manage the practice.
• Staff — can manage appointments and read patient/provider information. Cannot modify members, billing, settings, or provider information. Good for schedulers and administrative assistants.

Team limits: Your plan includes a maximum number of staff members (excluding the owner). Owners and admins can change a member's role or remove them from the Members page at any time.

Plans & Billing

Available plans

Genkō offers six tiers designed to grow with your practice. All plans include core features: appointment scheduling, conflict detection, email notifications, patient self-service portal, and provider availability management.

Advanced features unlock as you scale:

• Practice plan and above: Advanced scheduling rules (buffer minutes, booking window, max appointments per day, day-of-week restrictions)
• Practice plan and above: Google Calendar sync, compliance exports, and audit logs
• Enterprise: Custom integrations, dedicated support, and SLA guarantees

Upgrading or downgrading

Go to Settings → Billing to manage your plan:

• Upgrade: Click Upgrade Plan to move to a higher tier. Redirects to Stripe Checkout where you choose monthly or yearly billing. Takes effect immediately. Prorated charges apply if mid-cycle.
• Downgrade: Downgrades apply at the end of your current billing period, so you keep access until then. Make sure your usage will fit the new plan's limits (e.g. patient count).
• Billing interval: Switch between monthly and yearly at any time from the same page.

Billing portal

After subscribing, manage billing details through the Stripe billing portal accessible from Settings → Billing → Manage Subscription:

• Update your payment method
• View and download invoices and receipts
• Cancel your subscription (access continues until period end)
• View billing history and upcoming charges

Permissions: Only owners and admins can access billing settings. This protects your payment information while allowing authorized staff to view their role limitations.

Patient Portal

Enabling the portal

The patient portal lets patients self-book appointments without staff involvement, reducing administrative overhead and improving patient convenience.

To enable:

1. Go to Settings → Portal
2. Toggle Enable Patient Portal to on
3. Your practice gets a unique public booking URL: https://www.getgenko.com/portal/your-slug
4. Share this link with patients via email, website, appointment confirmations, or anywhere else

Patient self-booking

When patients visit your portal link, they follow a simple flow:

1. Browse offerings: See available services with descriptions and providers with specialties/bios
2. Select service & provider: Choose which service they want and who they prefer (or auto-assign)
3. Pick date & time: Calendar shows only available slots based on provider availability and scheduling rules
4. Enter contact info: First name, last name, email, phone. Account creation is not required.
5. Confirmation: Patient receives an email with appointment details; booking appears in your calendar immediately

Smart matching: If the patient's email already exists in your database, the booking automatically links to their existing record. Otherwise, a new patient record is created.

Integrations

Google Calendar sync

Genkō can sync appointments to Google Calendar so providers always have their schedule in sync, whether checking Genkō or Google Calendar. This reduces context switching and missed appointments.

How to connect:

1. Go to Settings → Integrations
2. Click Connect Google Calendar and sign in with the Google account you want to sync to
3. Grant Genkō permission to create and modify events in your calendar
4. Select which calendar to sync to (default is "Calendar")
5. Click Confirm — sync begins immediately

What syncs: New appointments, updates (time/date changes), and cancellations sync in both directions:

• Appointments created in Genkō appear in Google Calendar within seconds
• Cancelled or rescheduled appointments update in Google Calendar
• Provider names, patient names, and appointment notes appear in the event details

Plan requirement: Google Calendar sync is available on the Practice plan and above. Free and Solo plans can still create appointments but cannot sync to Google Calendar.

Disconnect: You can disconnect the integration at any time from Settings → Integrations. Your past events in Google Calendar remain untouched.

API & AI (MCP)

What is the MCP API?

Genkō exposes a Model Context Protocol (MCP) server that lets external AI agents and tools read and write your practice data in a structured, tool-call format. This is the same underlying registry used by the built-in WhatsApp AI scheduler and the dashboard AI assistant — so any agent you connect gets access to the same capabilities.

The MCP endpoint is a stateless HTTP server compatible with any client that speaks the MCP Streamable HTTP transport (e.g. Claude Desktop, OpenAI Agents SDK, or any custom agent built with @modelcontextprotocol/sdk).

Quick start

1. Go to Settings → Integrations and scroll to the API Access (MCP) panel.
2. Click Add key, give the key a name (e.g. "Claude Desktop"), and choose a scope.
3. Copy the raw key shown immediately — it is only displayed once.
4. In your MCP client, set the server URL and the Authorization header:

{
  "mcpServers": {
    "genko": {
      "url": "https://www.getgenko.com/api/mcp",
      "headers": {
        "Authorizationwww.getgenko.com_YOUR_KEY_HERE"
      }
    }
  }
}

Authentication

All requests to /api/mcp must include a valid API key as a Bearer token:

Authorization: Bearer genko_...

Keys are created in Settings → Integrations → API Access (MCP). Each key has a scope:

• Read — can call list/get tools only (Group plan)
• Read + Write — can also create and update records (Practice+ plan)
• Admin — full access including patient intake overrides (Enterprise)

Keys can be revoked at any time. Revocation is immediate — in-flight requests are not interrupted, but subsequent requests with the revoked key return 401 Unauthorized.

Available tools

The tools exposed depend on the scope of your API key. All tools operate on data scoped to your organization only.

Read tools (available on all scopes):

• list_appointments — list upcoming appointments with optional date/status filters
• get_appointment — fetch a single appointment by ID with full details
• list_patients — search patients by name or email (paginated)
• get_patient — fetch a single patient record by ID
• list_providers — list all providers with their specialties
• get_provider — fetch a provider's profile and upcoming availability
• list_appointment_types — list all appointment types (services) with durations
• check_availability — return open time slots for a provider within a date range

Write tools (read + write or admin scope only):

• create_appointment — book a new appointment (conflict-checked)
• update_appointment — change the time, status, or notes of an existing appointment (conflict-checked)
• cancel_appointment — set an appointment to cancelled status
• create_patient — create a new patient record
• update_patient — update a patient's name, email, or phone
• find_or_create_patient — look up by name/email, optionally auto-create if not found

Rate limits

MCP API requests are rate-limited per key using a fixed 60-second window. The default limit is 100 requests per minute. If you exceed the limit, the server responds with:

HTTP 429 Too Many Requests
Retry-After: 60

Usage for each key (calls in the last 7 days) is visible in the Settings → Integrations panel next to each key name.

Dashboard AI assistant

Practice+ organizations can enable a built-in AI assistant directly in the dashboard. When enabled, a floating chat widget appears in the bottom-right corner of every dashboard page. Only org admins and owners can see and use it.

The assistant has full admin-scope tool access and can answer questions like:

• “Who is my next patient today?”
• “Find all appointments for Maria Santos this month”
• “What slots are available for Dr. Reyes on Friday?”
• “Update appointment #abc123 to 3pm”

To enable: Go to Settings → Integrations and toggle on Dashboard AI Assistant. The toggle is visible only on the Practice plan and above. No API key is required — the assistant uses your session automatically.