Platform Architecture

Environment tip: All examples use v3.onsched.com for production. Replace the host with api-stage.onsched.com when calling the staging environment.

Overview

OnSched organizes your scheduling data in a hierarchy designed to support both single-location businesses and multi-location enterprises. The platform also supports multi-company (multi-tenant) architectures for marketplaces, white-label platforms, and scenarios requiring complete data isolation. Understanding this structure is essential for building integrations that scale with your needs.

The Hierarchy

Company (Tenant)
  └── Locations
       ├── Services
       ├── Resources
       └── Appointments
            └── Customers

Each level serves a specific purpose and inherits or overrides settings from levels above.

Company Level

What it represents: Your organization—the top-level tenant in OnSched.

Key responsibilities:

• Authentication scope (all API calls are company-scoped)
• Default timezone and notification preferences
• User management and API credentials
• Company-wide services (when scope is COMPANY)

When to use:

• Setting organization-wide defaults
• Managing API keys and OAuth clients
• Defining services used across all locations

Example:

A dental practice chain with 5 locations has one company account. All locations share the same services (cleanings, exams, x-rays) and staff can work at multiple locations.

Company vs Business

In OnSched, "Company" and "Business" refer to the same entity—your top-level account. The terms are used interchangeably, but "Company" is the technical model name.

Location Level

What it represents: A physical or virtual place where services are delivered.

Key responsibilities:

• Operating hours and availability schedules
• Location-specific services (when scope is LOCATION)
• Resource assignments
• Appointment management
• Customer notification settings
• Webhook configuration

When to use:

• Multi-location businesses with different hours or offerings
• Physical offices, stores, or clinics
• Virtual "locations" for different service teams

Example:

The dental practice has 5 locations. Each has its own:

• Operating hours (downtown open 7am-8pm, suburban location 9am-5pm)
• Staff (resources assigned to specific offices)
• Phone number and address
• Appointment calendar

Location Flexibility

Locations don't have to be physical. Use them to organize:

• Departments – Sales, support, onboarding teams
• Service types – In-person vs telehealth
• Brands – Multiple brands under one company
• Temporary pop-ups – Events, mobile services

Service Level

What it represents: A bookable offering (consultation, haircut, equipment rental, class).

Key responsibilities:

• Duration and scheduling rules
• Pricing and payment requirements
• Booking limits and restrictions
• Which resources can fulfill the service
• Service-specific unavailability

Scoping:

Services can be scoped to:

• COMPANY – Available at all locations (centrally managed)
• LOCATION – Specific to one location

Example:

The dental practice offers company-wide services:

• Cleaning (30 min, padding: 10 min, bookingsPerSlot: 1)
• Exam (20 min, padding: 5 min)
• X-rays (15 min, padding: 0 min)

A specialized location also has a location-scoped service:

• Orthodontics Consultation (60 min, only at the downtown office)

See Services Overview for detailed configuration.

Resource Level

What it represents: Staff, equipment, or rooms that deliver services.

Key responsibilities:

• Personal schedules and availability
• Calendar sync with external providers (Google, Outlook)
• Notification preferences (email, SMS)
• Assignment to specific services and locations

Examples of resources:

• Staff – Dentists, hygienists, stylists, consultants
• Equipment – Exam rooms, vehicles, machines
• Virtual resources – Video conference licenses, phone lines

Multi-location resources:

A resource can work at multiple locations. For example, Dr. Smith works:

• Monday/Wednesday at Downtown office
• Tuesday/Thursday at Suburban office
• Friday at East Side office

Use weekly allocations to define when a resource is available at each location.

See Resources Overview for detailed configuration.

Appointment Level

What it represents: A confirmed booking connecting a customer to a service, resources, and time slot.

Key relationships:

• Belongs to one Location
• References one Service
• Assigned to one or more Resources
• Booked for one Customer
• Occupies a time block (Unavailability)

Lifecycle:

1. Check availability via GET /v3/availability
2. Create hold via POST /v3/appointment/hold (optional)
3. Confirm via PUT /v3/appointment/:id/book or create directly via POST /v3/appointment
4. Optionally reschedule, confirm, or cancel
5. Automatically trigger notifications and webhooks

See Appointment Guide for booking workflows.

Customer Level

What it represents: A person booking appointments.

Key responsibilities:

• Contact information (email, phone)
• Notification preferences
• Appointment history
• Custom fields for additional data

Scope:

Customers belong to a company but can optionally be associated with a specific location. When associated with a location, customer data can be location-specific (useful for franchises where customer lists should remain separate).

Anonymous bookings:

Some integrations create appointments without storing permanent customer records. OnSched allows customer data to be passed inline during appointment creation.

See Customers Overview for details.

How Data Flows

Scenario: Checking Availability

When you call GET /v3/availability:

1. Location provides operating hours and timezone
2. Service defines duration, padding, and intervals
3. Resources supply their schedules and existing bookings
4. System merges these constraints and returns open slots

Scenario: Creating an Appointment

When you call POST /v3/appointment:

1. Location validates the time is within operating hours
2. Service validates duration and resource compatibility
3. Resources confirm they're available (no conflicts)
4. Customer is created or linked
5. Appointment is saved and unavailability blocks are created
6. Webhooks fire and notifications send

The hierarchy ensures data consistency—appointments can't reference invalid services or unavailable resources.

Company Settings vs Location Overrides

Many settings inherit from company to location with override capability:

This pattern lets you set sensible defaults while customizing where needed.

Practical Examples

Single Location Business

A solo consultant:

• Company: "Acme Consulting"
• Location: "Virtual Office" (timezone, email settings)
• Services: "Initial Consultation" (60 min), "Follow-up" (30 min)
• Resources: "Jane Doe" (the consultant)
• Appointments: Customer bookings assigned to Jane

Even single-location businesses use this structure for future flexibility.

Multi-Location Chain

A fitness studio franchise:

• Company: "FitLife Studios"
• Locations:
  • Downtown (open 5am-10pm)
  • Suburban (open 6am-9pm)
  • Airport (open 24/7)
• Services (company-scoped):
  • Personal Training (60 min)
  • Group Class (45 min, bookingsPerSlot: 20)
• Resources (location-specific):
  • Downtown: 5 trainers, 3 class instructors
  • Suburban: 3 trainers, 2 instructors
  • Airport: 2 trainers (24-hour coverage via schedules)
• Appointments: Customers book at their preferred location

Each location operates independently but shares service definitions and branding.

Service-Based Business

A mobile car detailing service:

• Company: "Sparkle Mobile Detailing"
• Locations:
  • North Zone
  • South Zone
  • West Zone
• Services:
  • Basic Wash (30 min)
  • Full Detail (120 min)
  • Interior Only (60 min)
• Resources:
  • Detailers assigned to zones
  • Mobile equipment units
• Appointments: Customers book by zone; resources travel to customer addresses

Locations represent service areas rather than physical offices.

Design Patterns

Centralized Services

For businesses where every location offers the same services:

• Define services at company scope (scope: COMPANY)
• Link resources to services at each location
• Availability automatically respects per-location resource schedules

Location-Specific Services

For locations with unique offerings:

• Define services at location scope (scope: LOCATION)
• Service only appears in availability/booking for that location
• Useful for specialized clinics, flagship store exclusives, pilot programs

Shared Resources

For staff working at multiple locations:

• Create one resource record
• Use weekly allocations to define when they're at each location
• Appointments automatically respect allocation schedules
• See Allocations Guide

Segmented Customers

For franchises or partners who shouldn't share customer data:

• Associate customers with specific locations when creating them
• Customers remain visible only within their assigned location
• Useful for compliance, privacy, or competitive isolation

Multi-Company Architecture

While most businesses use a single company with multiple locations, OnSched supports multi-company (multi-tenant) architectures for scenarios requiring complete data isolation.

When to Use Multiple Companies

Create separate companies when you need:

• Complete data isolation – No shared customers, appointments, or resources
• Separate authentication – Each organization has its own API credentials
• Independent billing – Different contracts, pricing, or payment terms
• Brand separation – Distinct brands that shouldn't appear related
• Regulatory compliance – Legal requirements for data separation
• White-label platforms – Each client organization is a separate tenant

Multi-Company vs Multi-Location

Marketplace Platform Example

A scheduling marketplace where your platform hosts multiple independent organizations:

Architecture:

Your Platform (OnSched)
  ├── Company: "Downtown Yoga Studio"
  │     └── Locations: Downtown Studio, Uptown Studio
  │           └── Services: Vinyasa Flow, Hot Yoga
  │                 └── Resources: Instructors, Equipment
  │
  ├── Company: "Elite Fitness Center"
  │     └── Locations: Main Gym, CrossFit Box
  │           └── Services: Personal Training, Group Classes
  │                 └── Resources: Trainers, Equipment
  │
  ├── Company: "Wellness Spa"
  │     └── Locations: Day Spa, Medical Spa
  │           └── Services: Massage, Facials, Consultations
  │                 └── Resources: Therapists, Estheticians
  │
  └── Company: "Mobile Pet Grooming"
        └── Locations: North Zone, South Zone
              └── Services: Full Groom, Nail Trim
                    └── Resources: Groomers, Mobile Vans

Benefits:

• Complete isolation – Each studio/gym/spa has its own data
• Independent management – Each organization manages its own settings, users, and API access
• Separate branding – Each company can have its own logo, colors, and branding
• Individual billing – Charge each organization separately
• Privacy compliance – Customer data never crosses company boundaries

Implementation:

1. Create a company for each organization when they sign up
2. Each organization gets its own OAuth client credentials
3. Organizations manage their own locations, services, and resources
4. Your platform acts as the marketplace aggregator (if needed, build aggregation layer)

API Access:

Each organization authenticates with their own credentials:

# Downtown Yoga Studio's API call
curl https://v3.onsched.com/v3/appointments \
  -H "Authorization: Bearer YOGA_STUDIO_TOKEN"

# Elite Fitness Center's API call  
curl https://v3.onsched.com/v3/appointments \
  -H "Authorization: Bearer FITNESS_CENTER_TOKEN"

These calls return only data for the authenticated company—complete isolation.

White-Label SaaS Example

A SaaS platform offering scheduling as a service to other businesses:

Architecture:

Your SaaS Platform
  ├── Company: "Client A - Law Firm"
  │     └── Locations: Main Office, Branch Office
  │           └── Services: Consultations, Document Review
  │
  ├── Company: "Client B - Medical Practice"
  │     └── Locations: Clinic A, Clinic B
  │           └── Services: Checkups, Procedures
  │
  └── Company: "Client C - Tutoring Center"
        └── Locations: Learning Center
              └── Services: Math Tutoring, Test Prep

Benefits:

• Client isolation – Each client's data is completely separate
• Custom branding – Each client can brand their booking experience
• Independent scaling – Clients don't affect each other's performance
• Compliance – Healthcare clients (HIPAA) isolated from others
• Billing flexibility – Charge per client, per seat, or per appointment

Franchise Network Example

A franchise where each franchisee operates independently:

Architecture:

Franchise Network
  ├── Company: "Franchisee A - Downtown"
  │     └── Locations: Store #1
  │           └── Services: Standard Menu
  │
  ├── Company: "Franchisee B - Suburban"
  │     └── Locations: Store #2
  │           └── Services: Standard Menu + Local Specials
  │
  └── Company: "Franchisee C - Airport"
        └── Locations: Store #3
              └── Services: Express Menu (airport-specific)

Benefits:

• Operational independence – Each franchisee manages their own operations
• Customer data privacy – Franchisees don't see each other's customers
• Pricing flexibility – Each franchisee can set their own pricing
• Local customization – Services and offerings can vary by franchisee

Alternative: If franchisees should share customers and branding, use one company with multiple locations instead.

Multi-Company Implementation Considerations

API Credentials:

Each company needs separate OAuth client credentials:

# Create credentials for Company A
POST /v3/clientId
{
  "name": "Company A Integration"
}
# Returns: client_id_A, client_secret_A

# Create credentials for Company B
POST /v3/clientId
{
  "name": "Company B Integration"
}
# Returns: client_id_B, client_secret_B

User Management:

• Users are company-scoped
• Each company manages its own users
• No cross-company user access (by design)

Reporting and Analytics:

• Reports are per-company
• To aggregate across companies, build your own aggregation layer
• Each company's data remains isolated

Webhooks:

• Webhooks are configured per location (within a company)
• Each company's webhooks are independent
• No cross-company webhook triggers

Customer Isolation:

• Customers belong to one company only
• Customers cannot book across companies
• Customer email uniqueness is per-company (same email can exist in multiple companies)

Managing Multi-Company Platforms

If you're building a platform that manages multiple companies:

Onboarding Flow:

1. New organization signs up
2. Create company via POST /v3/company
3. Generate OAuth credentials via POST /v3/clientId
4. Provide credentials to organization
5. Organization configures their locations, services, resources

Platform-Level Operations:

• You may need super-admin access to manage all companies
• Build aggregation layer for cross-company analytics (if needed)
• Implement company provisioning and deprovisioning workflows

Billing Integration:

• Track usage per company
• Bill each company separately
• Monitor resource usage per tenant

Common Questions

Can a customer book at multiple locations?

Yes. Customers are company-scoped, so one customer record can have appointments at any location under your company.

Can a service use resources from multiple locations?

Not for a single appointment. Each appointment is location-scoped and uses resources assigned to that location.

However, the same service definition (if company-scoped) can be fulfilled by different resources at different locations.

How do I restrict who can access certain locations?

User permissions are managed through the dashboard. You can grant users access to:

• All locations (company-wide admins)
• Specific locations (location managers)
• Read-only access for reporting

API authentication is company-scoped—if you need location-level API isolation, use separate companies.

What happens if I delete a location?

Locations use soft-delete (paranoid mode). Deleting a location:

• Archives the location and its configuration
• Preserves historical appointments (they remain linked to the deleted location)
• Removes the location from availability searches
• Can be restored if needed

Never delete locations with active appointments unless you've migrated data first.

Should I use one company or multiple?

Use one company if:

• Locations share customers and branding
• Centralized reporting is important
• Staff might work across locations
• You want customers to book at any location
• You're a single business with multiple sites

Use multiple companies if:

• You're building a marketplace or platform hosting multiple organizations
• Each organization needs complete data isolation
• Organizations have separate billing/contracts
• You're white-labeling scheduling to different clients
• Regulatory compliance requires data separation (e.g., HIPAA, GDPR)
• Organizations are competitors and shouldn't see each other's data
• Each organization needs independent API credentials

Decision framework:

• Same business, multiple locations → One company, multiple locations
• Different businesses/organizations → Multiple companies
• Marketplace or SaaS platform → Multiple companies (one per client organization)
• Franchise with shared branding → One company, multiple locations
• Franchise with independent operations → Multiple companies (one per franchisee)

Most businesses with multiple locations use one company with multiple location records. Multi-company is primarily for platforms, marketplaces, and white-label scenarios.

Related Documentation

• Services Overview – Configuring bookable offerings
• Resources Overview – Managing staff and equipment
• Availability Guide – How the hierarchy affects slot calculation
• Getting Started – First steps with the API
• Glossary – Key terminology

Understanding the OnSched hierarchy ensures you design integrations that scale smoothly from one location to hundreds.