Partner API Overview

Authentication

The Partner API uses OAuth 2.0 with AWS Cognito for secure machine-to-machine (M2M) authentication.

Prerequisites

Before making API requests, you must complete the partner onboarding process:

1. Partner Registration: Lobbie creates a partner integrator record with your unique client_id
2. Cognito Credentials: Lobbie provides OAuth 2.0 client credentials (client ID and client secret)
3. Account Grants: Lobbie grants your integration access to specific accounts

Obtaining an Access Token

Request an access token using the OAuth 2.0 client credentials by sending an HTTPS form POST:

The response contains a JWT access token:

Making Authenticated Requests

Include the access token in the Authorization header of every API request:

Token Management

• Access tokens expire after the duration specified in expires_in (default: 60 minutes)
• Request a new token before the current one expires
• Store credentials securely—they grant access to protected health information (PHI)
• If credentials are compromised, contact Lobbie support immediately to revoke and regenerate

Authorization

Your partner integration must have an active grant to access each account. The API validates:

1. The JWT token is valid and not expired
2. Your client_id corresponds to an active partner integrator
3. Your integration has an active grant to the requested account
4. The requested location belongs to the specified account

Common Errors

HIPAA & Compliance

• All patient data is Protected Health Information (PHI)
• Encrypt data at rest and in transit
• Maintain audit logs of all data access
• Sign Business Associate Agreement (BAA) before production access
• Follow data retention policies per agreement

Terminology

This glossary defines domain-specific terms used throughout the Lobbie Partner API.

Core Entities

Account

A healthcare practice or organization using Lobbie. Each account contains practice-wide settings and configurations, and can have multiple locations. All API access is scoped to a specific account via OAuth tokens.

Location

A physical practice site, clinic, or virtual care location within an account. Locations have their own addresses, staff assignments, schedules, and operational settings. Appointments, forms, and many operations are location-scoped. Each location has timezone information critical for accurate scheduling. Locations may have an optional storeId that partners can use to correlate Lobbie locations with their own systems.

Patient

An individual receiving healthcare services from a specific account. Contains demographic information (name, date of birth) and contact details (email, phone). Serves as the central entity linking appointments, forms, invoices, and clinical data. Subject to HIPAA privacy requirements.

Scheduling

Appointment

A scheduled visit between a patient and practitioner at a specific location and time. Appointments track the complete visit lifecycle from initial scheduling through check-in, the visit itself, and completion or cancellation. Each appointment links to an appointment type, patient, practitioner, and location.

Appointment Type

A template defining a schedulable service, including duration, telehealth settings, display color, and patient-facing description/instructions. Examples: "New Patient Consultation" (30 min), "Follow-up Visit" (15 min), "Telehealth Checkup" (20 min). Appointment types determine what services patients can book and how long they're scheduled.

Practitioner

A staff member designated as a clinical provider who can see patients and be scheduled for appointments. Practitioners have credentials (MD, DO, NP, PA, RN), NPI numbers, specialties, and license information. All practitioners are staff members, but not all staff are practitioners.

Self-Scheduling

Patient-initiated appointment booking through embeddable widgets or API integration. Self-scheduling respects practice availability rules, appointment type configurations, and booking windows. Patients can browse available times and complete bookings without staff intervention.

Self-Scheduling Attempt

A record of a patient's journey through the self-scheduling process, from initiation to completion or abandonment. Captures step-by-step progress for conversion analysis, identifying drop-off points, and triggering follow-up workflows for incomplete attempts.

Staff & Access

Staff Member

Any team member with system access, including administrative staff, clinical support, and practitioners. Staff have role assignments determining their permissions and location access.

Role Group

A permission set defining capabilities and access levels for staff members. Role groups control what actions staff can perform within the system, from standard user access to full administrative privileges. Staff members can have multiple role groups assigned, combining permissions as needed.

Forms & Documentation

Form Template

A reusable form design defining structure, fields, validation rules, and conditional logic. Templates are created once and used to generate form instances for patients. Form templates support versioning—when a template is modified, a new version is created while preserving previous versions for historical form submissions. Examples: "Patient Intake Form", "HIPAA Consent", "Medical History Questionnaire".

Form Group

A collection of one or more form instances assigned to a patient for completion. Form groups track overall completion status and can include multiple related forms. A form group is considered complete when all forms within it have been submitted, and can be archived when no longer needed.

Form

An individual form instance within a form group, based on a form template version. Each form tracks its own completion status and contains the patient's responses.

Form Element

A single field or component within a form template that captures patient input or displays content. Element types include: text inputs, text areas, dropdowns, checkboxes, radio buttons, date pickers, signatures, initials, file uploads, phone numbers, email addresses, addresses, and specialized types like payment fields and body diagrams. Elements can be configured as required or optional, and can have visibility rules controlling who can view or edit them (patient only, staff only, or both).

Form Answer

A patient's response to a specific form element. Answers are stored per element and can be text, selections, dates, signatures, or file uploads depending on the element type.

Form Template Group

A predefined collection of form templates commonly assigned together. Simplifies assigning multiple related forms in a single operation (e.g., "New Patient Packet" containing intake, consent, and history forms).

Billing & Payments

Invoice

An itemized billing statement for a patient detailing charges for services, products, taxes, and fees. Invoices progress through a lifecycle from creation to payment or cancellation. Invoices can be linked to appointments or created independently.

Invoice Line Item

A single charge entry within an invoice. Line items specify quantity, unit price, and description, and can represent services, products, adjustments, or taxes. May reference billing codes and associated care resources.

Payment Request

A trackable record of a payment’s lifecycle, from initiation to final settlement. Each request tracks its status from creation through payment or expiration, whether triggered as a remote request sent to a patient (via email or SMS) or entered directly by staff for immediate processing.

Recurring Payment

An automated payment plan with scheduled charges at defined intervals. Used for payment plans, memberships, and subscription services. Configured with a frequency (weekly, monthly, etc.), amount, linked payment method, and optional end date.

Labs & Clinical

Lab

A laboratory order containing one or more test panels with results. Labs track progress from order placement through result delivery. Labs can be in-house or from external vendors and link to patients and optionally appointments.

Test Panel

A grouping of related lab tests within a lab order. Examples: "Comprehensive Metabolic Panel", "Complete Blood Count", "Lipid Panel". Each panel contains multiple test components.

Test Component

An individual lab measurement within a test panel. Contains the test name, result value, unit of measurement, reference range, and an indicator of whether the result is normal or abnormal.

Health Profile

Structured patient health information including medical history, allergies, medications, and clinical data collected through intake forms and clinical encounters.

Patient Management

Category

A service category that can function as either a CRM-tracked sales pipeline or a simple organizational tag. When CRM-tracked, categories enable full pipeline tracking through status stages with dashboard visibility. When not CRM-tracked, categories function as simple groupings for billing, inventory, or reporting. Examples of CRM categories: "Men's Health - Testosterone", "Weight Loss - Semaglutide". Examples of simple categories: "Lab Supplies", "Office Visits".

Patient Category

A patient's enrollment in a specific service category with CRM status tracking. Represents the link between a patient and a category, tracking their progress through the associated CRM pipeline. Appears as an "Opportunity" in CRM dashboards. Tracks status transitions with a complete audit trail.

CRM Status Group

A reusable CRM workflow pipeline (sales/marketing funnel) that defines the customer journey stages. Think of it as the sales funnel template—the workflow (HOW you sell) is separated from the product (WHAT you sell). Multiple categories often share the same sales process. Examples: "Digital Marketing Funnel" with stages like Cold Lead → Engaged → Sales Qualified → Closed Won; "Patient Care Journey" with stages like Intake → Insurance Verified → In Treatment → Complete.

CRM Status

An individual stage within a CRM status group representing where a patient is in a workflow. Status progression is tracked through transitions, providing a complete audit trail. Examples: "Cold Lead", "Sales Qualified", "Proposal Sent", "Closed Won", "Closed Lost".

Communications

Notification

A system-generated message sent to a patient via email or SMS. Notifications are sent for various purposes including appointment reminders, form assignments, payment requests, and account recovery. Each notification tracks its delivery status.

Notification Group

Configuration defining how and when patients receive specific types of communications, customizable per location or appointment type.

Identity & Security

Identity Proof

A verification session for authenticating patient identity through email and/or SMS code verification. Used for patient portal authentication, self-scheduling verification, and secure access to patient data. Each session generates a secure token and tracks which contact methods have been verified.

Verification Method

The channel(s) required to prove identity, which can be email only, SMS only, or both. The verification method determines what must be verified before the identity proof is considered complete.