Glossary of Terms

A

Allocation

A defined time block when a resource or service is available to work. Two recurrence shapes exist:

• Weekly Allocation – Recurring weekly schedule (e.g., Mondays 9am-5pm)
• Single Allocation – One-time availability block (e.g., working Saturday this week only)

Scope: Allocations can target a resource only, a service only (all resources on that service), or a service + resource pair—the same recurring or one-off hours for one provider (or asset) on one service without changing that resource’s global availability mode. Pair-scoped rules layer on top of the resource’s normal schedule for that service. When a service has only pair-scoped weekly allocations (no service-level rows), leftover from a resource-wide calendar does not apply unless that resource also has a pair row for the service.

See Weekly Allocations, Single Allocations.

Allowed Domain

Hostname an operator registers so the public booking flow may run from that site for that company. The browser Origin must match exactly (www.example.com is not example.com). Wildcard * is not allowed. See Authentication.

API Key

Company secret used to scope a dashboard JWT to a tenant (Authorization: Bearer … + x-api-key). Not used when calling protected /v3/* routes with an OAuth2 client-credentials access token—company is embedded in that machine token. Not required on /v3/public/* (those use a Public Client ID and a matching Allowed Domain).

See Authentication.

Appointment

Scheduling record for a time block with a service, location and optional customer. Bookable appointments use one or more resources; imported cancelled or rescheduled-away history may have none. Not every row is a completed booking: statuses include IN (short hold), BK (booked), RS (reserved without hold expiry), RE (placeholder after reschedule), and CN (cancelled). Transitions drive notifications and webhooks. While an appointment is active, nested Unavailability is the occupancy block that holds capacity. After cancel, occupancy is removed and private responses expose the cancelled interval on scheduledStartTime and scheduledEndTime.

See Appointments Guide.

Appointment Padding Override

Authenticated appointment-specific replacement for Service padding. 0 means no
padding, null restores the Service value on update or reschedule, and omission keeps
the current behavior. See Appointment Guide.

Availability

Time slots when services can be booked. Calculated based on:

• Service duration and padding
• Resource schedules and existing appointments
• Location operating hours
• Booking limits and restrictions

See Availability Guide.

availabilityType

How an entity (typically a service or resource) expresses baseline hours in the engine: schedule — recurring weekly hours (weeklyAvailability); allocation — only explicitly allocated windows count as available (weekly + single allocations). A given entity uses one mode; locations use schedule-style weekly hours. See Entity operating hours and Resources overview.

B

BALANCED

Round robin mode that assigns appointments to the resource with the fewest existing bookings in the search window. Distributes workload evenly.

See Round Robin Booking.

Booking Interval

How often time slots are offered for a service. If set to 60 minutes, slots appear hourly regardless of service duration.

See Services Overview.

Booking Limit

Restriction on how many appointments a customer can have. Can be total active, daily count, daily duration, lifetime, or per-resource.

See Booking Limits.

bookingsPerSlot

Maximum number of customers who can book the same time slot at the same instant (concurrent capacity). Used for group classes, shared resources, or equipment pools. Applies to Service, Resource, and SingleAllocation — not weekly allocations. For Service and Resource values, the stored default 1 is fallback capacity; when both values are greater than 1, the lower value is the effective cap.

See Max Capacity.

Weekly allocation bookingsPerSlot

Maximum concurrent appointments at the same instant for a service+resource WeeklyAllocation (ServiceId and ResourceId both set). Not an ISO-week quota. Omitted or unset uses resolved Service/Resource capacity; a set value, including 1, is an explicit cap for that allocation window. Weekly booking quota fields are not supported.

See Weekly Allocations and Booking Limits.

bookingLimit

Maximum active appointments (BK + IN) one customer may have for a service, or for a service–resource pair when set on a resource. Enforced at hold/reserve/book/reschedule when a customer is known. 0 = unlimited. RS reserved slots block availability but do not count toward this cap.

See Booking Limits.

dailyBookingLimitCount

Service-wide cap on total appointments (all customers) that may start on the same calendar day. Enforced in availability and at booking. 0 = unlimited.

See Booking Limits.

dailyBookingLimitMinutes

Service-wide cap on total booked minutes (all customers) starting on the same calendar day. Enforced in availability and at booking. 0 = unlimited.

See Booking Limits.

maxBookingLimit

Lifetime maximum appointments one customer may ever book for a service. Counts non-deleted rows except RE (rescheduled-away); CN (cancelled) still counts. Enforced at hold/reserve/book/reschedule when a customer is known. 0 = unlimited.

See Booking Limits.

maxResourceBookingLimit

Lifetime maximum appointments one customer may book with a specific resource on a service. Same counting rules as maxBookingLimit (RE excluded, CN included). Enforced at hold/reserve/book/reschedule when a customer is known. 0 = unlimited.

See Booking Limits.

Bulk Migration Sync

Operator-triggered import of one or more chosen V1 companies into v3. Start it from the Merchant Portal (Getting Started or API Settings) or POST /v3/migration/jobs with { v1CompanyIds }. The response is 202 { jobId }; poll GET /v3/migration/jobs/{id} for each company's status, copied counts, and Sync gaps. Work continues if the operator closes the portal. POST /v3/migration/sync is the same alias and returns 400 when v1CompanyIds is empty or omitted.

See Migrating from v1 to v3.

C

Calendar Selection

Opt-in guest merchant-portal step after delegated Google or Outlook OAuth. Set useOnSchedCalendarSelection: true to let the resource choose read/write calendars without a dashboard login, then return to returnUrl after save or skip. Omitted or false preserves existing direct returnUrl redirects and authenticated picker links.

See External Calendar Sync.

Calendar Selection Token

Short-lived Bearer JWT minted by POST /v3/calendar/selectionSession after exchanging the opaque callback code. Authorizes list, select, and disconnect for one resource external-calendar connection during hosted selection. Distinct from Dashboard JWT, machine OAuth tokens, and Docs Handoff Token.

See Authentication, External Calendar Sync.

Calendar Sync

Integration with external calendars (Google Calendar, Outlook) to:

• Push OnSched appointments to external calendar
• Pull external events to block OnSched availability
• Maintain two-way synchronization

See External Calendar Sync.

Cascade

How settings inherit down the hierarchy: Company → Location → Resource. Lower levels can override higher levels.

See Settings Overview.

Client Credentials

OAuth2 authentication flow where client ID and secret are exchanged for an access token. Recommended for server-to-server API integrations.

See Authentication.

COMBINED

GET /v3/availability round-robin mode requiring explicit ResourceIds: a slot is returned only when every listed resource is free together for the full service duration (and padding). Use for joint bookings (e.g. clinician + room). See Availability Guide.

Company

Top-level tenant in OnSched. Represents your organization and owns all locations, services, resources, appointments, and customers.

See Companies Overview, Architecture.

Permanent Company deletion

Staging-only physical removal of a Company and its Company-owned records. A Dashboard User with an explicit owner role must type the exact company name; Google or Microsoft calendar events are not removed from those providers. The standard Company delete remains a soft delete.

See Companies Overview.

Company Sync

Import of a single V1 company and its locations, services, resources, customers, appointments, and business users into one v3 Company, keyed by Legacy ID. Customers are collected across all V1 locations and appointment history includes IN, BK, RS, CN, and RE. A repeat fills missing entities and repairs safe status, customer, blocking, or importer-owned timezone gaps without replacing operator-edited appointment fields. One Company Sync runs at a time inside a Bulk Migration Sync; a completed sync can still report Sync gaps.

See Migrating from v1 to v3.

Custom Fields

JSON object of string key–value pairs that extend appointments, customers, services, resources, and locations. Send and read them as CustomFields in API bodies and responses (values are strings; encode numbers, booleans, or nested data as strings in your app). GET /v3/customers and GET /v3/locations filter on them with CustomFields.<key>=<value>.

See Appointment Custom Fields, Customer Custom Fields, Locations.

Customer

Person who books appointments. Stored with contact information, preferences, appointment history, and custom fields.

See Customers Overview.

customerDailyBookingLimit

Maximum appointments one customer may start at a Location on the same calendar day, across all services. Day uses the Location timezone, or UTC if timezone is unset. Counts booked (BK) and non-expired holds (IN). Does not count reserved (RS), cancelled (CN), rescheduled-away (RE), or expired holds. Enforced at hold, reserve, book, and reschedule when a customer is known. Hold without a customer skips the check; book still enforces it. 0 or omitted = unlimited. Does not hide GET /v3/availability. Not returned on public Location GET.

See Booking Limits.

Cursor Pagination

Forward-only list traversal in which each response provides an opaque continuation for
the next page. Appointment cursor pagination avoids deep offsets and total-count work,
making it the preferred shape for exports and backend ingestion. See
Cursor Pagination for Appointments.

D

Dashboard JWT

Supabase-issued access token for a signed-in dashboard user. Sent as Authorization: Bearer <JWT> together with x-api-key on /v3/* routes when acting as that user. Not a Machine Token, Docs Handoff Token, or refresh token. See Authentication.

Docs Handoff Token

Short-lived identity JWT the merchant portal mints after operator login so Personalized Docs can show the operator’s name and email. It does not carry an API Key, Dashboard JWT, or Public Client ID, and it does not prefill Try It. See Authentication.

Duration

Length of a service or appointment in minutes. Core property that determines how long appointments last and affects availability calculations.

See Services Overview.

Duration Selection

Feature allowing customers to choose appointment length within a range (e.g., 30, 60, or 90 minutes) using overrideDuration parameter.

See Services Overview.

E

E.164 Format

International phone number format required for SMS notifications. Includes country code and no formatting characters (e.g., +15550123).

See Customer SMS.

External Calendar Account Connection

Resource-owned authorization for one Google or Outlook account. Personal and organization authorization are mutually exclusive for a Resource; multiple calendars can belong to its connected account. Deselecting calendars preserves authorization, while disconnecting ends the account connection.

See External Calendar Sync.

External Calendar

Google Calendar or Outlook calendar connected to a resource for two-way sync. External events block OnSched availability automatically.

See External Calendar Sync.

External Calendar Health

Resource-level status of the latest aggregate event sync across every selected read calendar. It does not describe calendar listing or write-event delivery. Resources can opt into fail-closed protection so pending or failed health removes them from availability when external events are respected.

See External Calendar Sync.

External Calendar Tenant Connection

Company-owned authorization that lets OnSched use app-only Microsoft Graph access after one Microsoft 365 administrator grants tenant-wide consent. It can serve many explicit Resource mailbox connections in that Microsoft tenant. One Microsoft tenant can belong to only one Company.

See External Calendar Sync.

External Calendar Mailbox Connection

Resource-owned application-mode Outlook connection that binds one existing Resource email to that mailbox's writable default calendar. Repeating the same connection request reverifies and resynchronizes it without another consent screen.

See External Calendar Sync.

Event Type

Appointment audit field describing the lifecycle action that produced an audit row, such as create, hold, reserve, book, reschedule, cancel, delete, validate_resources, or update_padding.

See Appointment Audit Events.

H

Hold

Temporary appointment reservation with status IN. Holds expire automatically if not confirmed within the expiration window (configurable per location). A location with no positive expirationDelay gives the hold no timer, so it protects its slot until booked or deleted.

See Appointments Guide.

I

Interval

Parameter controlling how often candidate appointment start times are generated. Separate from service duration—affects slot stepping, not appointment length.

See Availability Guide.

L

Location

Physical or virtual place where services are provided. Locations have:

• Operating hours
• Resources assigned to them
• Optional timezone override
• Webhooks and notification settings

See Architecture.

M

Machine Token

OAuth2 client-credentials access token from POST /v3/oauth/token. Sent as Authorization: Bearer <token> on /v3/* (no x-api-key). HS256, iss onsched:v3-api, aud api, about one hour. Not a Dashboard JWT. See Authentication.

Max Capacity

See bookingsPerSlot.

N

Notification Type

Preference for how notifications are sent:

• EMAIL – Email only
• SMS – Text message only
• ALL – Both email and SMS
• NONE – No notifications

Can be set at company, location, resource, and customer levels.

See Customer SMS.

O

OAuth2

Industry-standard authentication protocol. OnSched supports client credentials flow for server-to-server API access.

See Authentication.

OAuth Scope

Named grant on a machine token: read and/or write only. Every company client may request either or both. Omitting scope at token mint grants both. Unknown names are rejected. Not service COMPANY/LOCATION scope.

See Authentication.

Operating Hours

Baseline hours when a location accepts bookings, defined with weekly repeating windows (weeklyAvailability) in the location’s timezone. Closures, overrides, allocations, and external calendars further constrain slots. See Entity operating hours and Locations.

Out of Office (OOF)

Unavailability block marking a resource as unavailable during specific times (vacation, sick leave, training). Prevents booking appointments during these periods. For stored blocks and the merged calendar API, see Unavailability blocks.

Outcome

Appointment audit field describing whether a lifecycle attempt succeeded or was rejected. Common values are success and rejected.

See Appointment Audit Events.

overrideDuration

Parameter allowing customer to select appointment duration different from service default (when durationSelect: true on service).

See Availability Guide.

P

Padding

Buffer time added after an appointment. Creates gap between bookings for cleanup, transitions, or rest. Invisible to customers but blocks resource availability. allowPaddingOverflow=true lets that buffer run past that resource's own scheduled close (or location/service operating hours close) only on a fragment that ends at that close. A later-closing resource on the same slot still needs the full padding window.

See Services Overview and Availability Guide.

Public Client ID

Public identifier sent as x-client-id on /v3/public/* routes; identifies the company for the public booking flow without a dashboard session. The request Origin must match an Allowed Domain for that company. Safe to embed in browser apps. See Authentication.

R

RANDOM

Per-request or service-configured round-robin mode that picks one eligible resource at random (equal chance among candidates). For new services the API default roundRobin is NONE unless you set otherwise.

See Round Robin Booking.

Rate Limit

HTTP throttle that returns 429 Too Many Requests with Retry-After when a caller exceeds a burst or refill budget. Identity is the company (or the dashboard user when no company is on the request). Public booking and machine availability reads for the same company share one availability budget. This is not a Booking Limit and not same-slot bookingsPerSlot capacity. Appointment list and cursor walks keep their own budgets. See Error Codes.

Recurring block

Repeating unavailability pattern (e.g. “every Friday after 3pm”) managed under /v3/unavailability/recurringBlock, layered on top of schedules and allocations. See Recurring blocks and the Unavailability overview.

Reason Code

Appointment audit field describing the high-level reason for an outcome, such as slot_available or slot_unavailable. Use it for support triage before inspecting validation evidence.

See Appointment Audit Events.

Reschedule predecessor

The appointment left in rescheduled-away (RE) status after a reschedule. The successor replaced this record. Private appointment responses expose its id as rescheduledFromAppointmentId (null when the row was not created by a reschedule). When present, rescheduledFromStartTime on the successor is that predecessor’s scheduled start instant for the same hop. Existing rows from before these fields shipped stay null. See Appointments Guide and Appointment Audit Events.

Reschedule predecessor start

The scheduled start instant of the immediate reschedule predecessor. Private appointment responses expose it as rescheduledFromStartTime on the successor (null when the row was not created by a reschedule). It is not the reschedule action time and not the first booking in a chain — walk rescheduledFromAppointmentId hop by hop for earlier times. See Appointments Guide.

Reschedule successor

The new appointment created by PUT /v3/appointment/{id}/reschedule. Status at create time is booked (BK), hold (IN), or reserved (RS). The predecessor pointer stays on that row if it later becomes RE or CN.

Reschedule chain

Linked list of predecessor hops from a successor back through prior rescheduled-away appointments. Walk one hop at a time with rescheduledFromAppointmentId, or read rescheduleFromTrail on GET /v3/appointment/{id}/audit (nearest hop first, cap 50).

Resource

Person, equipment, or space that delivers services. Examples:

• Staff members (stylists, consultants, instructors)
• Equipment (treadmills, kayaks, projectors)
• Spaces (exam rooms, conference rooms, studios)

See Resources Overview.

Round Robin

Strategy for how multi-resource services pick or list resources on availability and booking. Service field roundRobin supports NONE (default for new services), RANDOM, BALANCED, and COMBINED (joint availability; see Availability Guide). Passing explicit ResourceIds overrides automatic assignment.

See Round Robin Booking.

S

Scope

Determines whether a service is company-wide (COMPANY) or location-specific (LOCATION). Company-scoped services are available at all locations (where resources exist). Not an OAuth Scope.

See Service Scoping.

Service

Bookable offering (consultation, haircut, class, equipment rental). Services define duration, padding, pricing, limits, and which resources can deliver them.

See Services Overview.

Single Allocation

One-time availability block for a resource. Used for irregular schedules, extra shifts, or temporary availability.

See Single Allocations.

Slot

A bookable time window shown in availability results. Represents a potential appointment start time that respects all scheduling rules.

SMS

Text message notifications sent to customers' mobile phones. Requires phone number in E.164 format and Twilio configuration.

See Customer SMS.

Soft Delete

Deletion strategy where records are marked as deleted (deletedAt timestamp) but not removed from database. Allows restoration and preserves historical data.

The standard Company delete uses a soft delete. In staging, an owner can permanently delete the Company and its Company-owned records from Company Settings after confirming its exact name.

Status

Appointment lifecycle state:

• IN – Initial hold (auto-expires if not confirmed)
• BK – Booked appointment
• RS – Reserved slot (long-lived lock; no hold expiry like IN)
• RE – Rescheduled (placeholder for moved appointment)
• CN – Cancelled

See Appointments Guide.

Sync gap

Non-blocking Company Sync issue recorded when an entity, appointment list, bounded date window, or timezone could not be copied or verified. The per-company result.gaps array identifies the affected entity and may include its V1 ID, location, appointment status, missing service/resource ID, or date window. A company with Sync gaps is still done; rerun Company Sync for that company after correcting the source or access problem.

See Migrating from v1 to v3.

Swagger

Interactive OpenAPI (Swagger UI) documentation for the v3 API. Served at /docs on the API host (e.g. https://v3.onsched.com/docs); / redirects to /docs.

See Swagger Documentation.

T

Timezone

IANA timezone identifier (e.g., America/New_York, Europe/London, Asia/Tokyo). Used to interpret date-only inputs and display times in local context.

Can be set at company, location, and resource levels. For a list of valid identifiers from the API, use GET /v3/timezone—see Platform API utilities.

Token

• Machine Token / OAuth2 access token — From POST /v3/oauth/token (client credentials). Bearer token (~1 hour), bound to that company; another company's resource ID returns 404. No x-api-key on subsequent /v3/* calls. Not a Dashboard JWT.
• Dashboard JWT — Supabase session access token for a logged-in user; use with x-api-key as in the Authentication guide. Not a refresh token and not a Docs Handoff Token.
• Public Client ID — x-client-id on /v3/public/* with a matching Allowed Domain Origin. Not a signed widget token.

See Authentication.

Twilio

SMS gateway service OnSched uses to send text message notifications. Handles message delivery to customer phone numbers.

See Customer SMS.

U

Unavailability

Time block that prevents booking appointments. Types include:

• APT – Appointment (customer booking)
• HLD – Hold (temporary reservation)
• PAD – Padding (buffer time)
• OOF – Out of Office (vacation, sick)
• EXT – External event (from calendar sync)

See Unavailability blocks, Recurring blocks, and the Unavailability overview.

UUID

Universally Unique Identifier. 128-bit value used as primary key for all OnSched resources (format: a1b2c3d4-e5f6-7890-abcd-ef1234567890).

V

Validation Gate

Named scheduling check inside appointment audit validation evidence. Gates summarize why a slot was accepted or rejected, for example operating hours, existing blocks, or resource/service constraints.

See Appointment Audit Events.

W

Webhook

HTTP callback triggered by appointment events. OnSched POSTs JSON to a public https destination when events occur (new appointment, cancellation, rescheduling, and similar). Private, loopback, and metadata destinations are rejected.

See Webhooks Guide.

Weekly Allocation

Recurring weekly schedule defining when a resource works at a location. Example: Resource works Mondays 9am-5pm at Location A, Tuesdays 9am-5pm at Location B.

See Weekly Allocations.

Weekly template

Named company snapshot of open weekday intervals (name plus weeklyAvailability). Applying a template copies those hours onto a weekly allocation or weekly operating hours; it does not keep a live link to the template. Template CRUD does not change availability by itself.

See Weekly Templates.

Common Acronyms

• API – Application Programming Interface
• CRM – Customer Relationship Management
• GDPR – General Data Protection Regulation (EU privacy law)
• IANA – Internet Assigned Numbers Authority (manages timezone database)
• ISO 8601 – International standard for date/time formatting
• JWT – JSON Web Token (OAuth2 access tokens and dashboard session tokens)
• OAuth2 – Open Authorization 2.0 (authentication protocol)
• REST – Representational State Transfer (API architecture style)
• SMS – Short Message Service (text messaging)
• TCPA – Telephone Consumer Protection Act (US SMS regulations)
• URL – Uniform Resource Locator
• UTC – Coordinated Universal Time (timezone reference)
• UUID – Universally Unique Identifier

Status Codes

Common HTTP status codes returned by the API:

• 200 OK – Request succeeded
• 201 Created – Resource created successfully
• 400 Bad Request – Malformed request, missing parameters, an id in the body or query that is not one of your records, or a booking rule rejection such as an unavailable slot
• 401 Unauthorized – Invalid or missing authentication
• 403 Forbidden – Authenticated but lacking permission
• 404 Not Found – The record addressed in the URL path doesn't exist
• 409 Conflict – Conflicting state or duplicate action
• 500 Internal Server Error – Unexpected server error

See Error Codes.

Related Documentation

• Get Started – Introduction to OnSched
• Architecture – Understanding the hierarchy
• Authentication – API access and credentials
• Swagger Documentation – Interactive API reference

This glossary provides quick definitions of OnSched terms. For detailed explanations and usage examples, see the linked documentation guides.

Resource-hours coverage warning

A non-blocking advisory that some or all remaining service-specific allocation hours
fall outside the resource's effective configured hours. The configuration is saved;
review the resource's schedule or resource-wide allocations to address the gap.
A clear coverage check does not guarantee bookable slots because other availability
rules still apply. See the Weekly Allocation Guide.