Companies Overview

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

What Is a Company?

In OnSched, a Company represents your organization—the top-level tenant that owns all other entities. It's your account's root, encompassing:

• All locations
• All services (company-scoped and location-scoped)
• All resources
• All appointments and customers
• API credentials and authentication
• Default settings inherited by child entities

Think of the company as your business entity in the OnSched platform.

Core Properties

Basic Information

• name (required) – Your company name (unique across OnSched)
• registrationEmail (required) – Primary contact email
• email (optional) – General company email for notifications
• phone (optional) – Company phone number
• website (optional) – Company website URL

These details appear in:

• Dashboard branding
• Customer notifications (if not overridden at location level)
• API metadata

Settings

• timezone (string) – IANA timezone (e.g., America/New_York, default: America/New_York)
• notificationType (enum) – Default notification method (EMAIL, SMS, ALL, NONE)

These settings cascade to locations and resources unless overridden.

Status

• suspended (boolean) – Whether the company account is active (default: false)

Suspended companies:

• Cannot create new appointments
• Existing appointments remain accessible
• Dashboard access is restricted
• API authentication fails

Branding

• urlName (string) – Unique URL slug for public booking pages (if applicable)
• imageUrl (string) – Company logo URL

Used for white-label booking interfaces and branding.

Retrieving Company Information

Get Your Company

curl https://v3.onsched.com/v3/company \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "id": "company-uuid",
  "name": "Acme Scheduling",
  "registrationEmail": "[email protected]",
  "email": "[email protected]",
  "phone": "+1-555-0100",
  "website": "https://acme.com",
  "timezone": "America/New_York",
  "notificationType": "EMAIL",
  "suspended": false,
  "imageUrl": "https://cdn.acme.com/logo.png",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2025-11-20T14:30:00Z"
}

This endpoint returns the company associated with your authenticated credentials.

Updating Company Information

Use PUT /v3/company to modify company settings:

curl -X PUT https://v3.onsched.com/v3/company \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+1-555-0200",
    "timezone": "America/Los_Angeles",
    "notificationType": "ALL"
  }'

Changes apply immediately and cascade to child entities using company defaults.

Company Hierarchy

Company
  ├── Locations (1 or more)
  │     ├── Services (location-scoped)
  │     ├── Resources (linked at location)
  │     ├── Appointments
  │     └── Customers (optionally location-scoped)
  └── Services (company-scoped)
  └── Resources (linked at many locations)

See Architecture Guide for detailed hierarchy explanation.

Settings Inheritance

How Inheritance Works

Company settings provide defaults for child entities:

Example:

• Company timezone: America/New_York
• Location A: Uses company default (America/New_York)
• Location B: Overrides to America/Chicago
• Resource at Location A: Uses America/New_York (inherited from location)
• Resource at Location B with timezone set: Uses America/Denver (resource-specific)

Cascade order: Resource → Location → Company

When to Use Company Settings

Set at company level when:

• All locations operate the same way
• You want centralized control
• Consistency across locations is important

Override at location or resource level when:

• Locations have different requirements
• Multi-timezone operations
• Per-location branding

Timezone Configuration

Importance of Timezone

Timezone affects:

• Availability slot calculations (operating hours)
• Notification timing
• Appointment display times
• Date-only input interpretation

Example:

Company timezone is America/New_York. Customer requests availability for 2025-12-01:

• System interprets as 2025-12-01 00:00:00 America/New_York
• Converts to UTC for calculations
• Returns results in requested timezone (or UTC if not specified)

Always set accurate timezones to avoid scheduling errors.

Changing Timezone

When updating company timezone:

curl -X PUT https://v3.onsched.com/v3/company \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "America/Chicago"
  }'

Impact:

• Future availability calculations use new timezone
• Existing appointments retain original times (stored in UTC)
• Locations without explicit timezone inherit the new default

Best practice: Set timezone correctly during initial setup. Changing mid-operation can cause confusion.

Notification Preferences

Company-Level Notifications

• EMAIL – Send notifications via email
• SMS – Send notifications via SMS (requires phone numbers and SMS gateway)
• ALL – Send both email and SMS
• NONE – Suppress automated notifications

Company default applies to:

• Locations without specific setting
• Resources without specific setting
• Customers without preference specified

Cascading Notifications

Example:

• Company: notificationType: EMAIL
• Location A: No override → uses EMAIL
• Location B: Override to ALL → uses ALL (email + SMS)
• Resource at Location A: No override → uses EMAIL
• Resource at Location B: No override → uses ALL (inherits from location)

See Notifications Guide for detailed configuration.

Authentication and API Credentials

Company-Scoped Authentication

All API authentication is company-scoped:

• OAuth2 tokens embed company ID
• API keys belong to specific companies
• Users are associated with companies

You cannot access another company's data, even with valid credentials.

Managing Credentials

API credentials are managed via:

• Dashboard → API Settings
• POST /v3/clientId (create OAuth client)
• DELETE /v3/clientId/:id (revoke client)

See Authentication Guide for details.

Multi-Company Scenarios

When to Use Multiple Companies

Create separate companies for:

• Distinct brands – Different brands with separate identities
• Franchise/partner isolation – Complete data separation
• Reseller/white-label – Each client gets their own company
• Testing/staging – Separate company for development

When to Use One Company

Use one company with multiple locations for:

• Multi-location single business
• Franchises with shared branding and customers
• Centralized reporting needs
• Staff working across locations

See Architecture Guide for decision framework.

Use Cases

Single-Location Business

Example: Solo consultant

• Company: "Jane Doe Consulting"
• Locations: 1 ("Virtual Office")
• Services: Company-scoped (available everywhere, but only 1 location)
• Resources: Just Jane

Even single-person businesses benefit from company structure for future growth.

Multi-Location Chain

Example: Fitness studio chain

• Company: "FitLife Studios"
• Locations: 10 (different cities)
• Services: Company-scoped (same classes everywhere)
• Resources: Location-specific (instructors assigned to locations)

Centralized service definitions, distributed operations.

Franchise Model

Example: Salon franchise

Option 1: One Company

• Company: "Style Salons"
• Locations: 50 (each franchise location)
• Services: Company-scoped (standardized menu)
• Resources: Location-specific (franchise-employed staff)
• Customers: Shared (customers can book at any location)

Option 2: Multiple Companies

• Company: One per franchise ("Style Salon - Downtown", "Style Salon - Midtown")
• Isolation: Complete separation of data, branding, billing

Choose based on franchisee autonomy needs.

Best Practices

Set Timezone Accurately

• Match your primary business location
• Don't change frequently
• Document timezone for team awareness

Use Descriptive Names

• Company name should match business name
• Keep urlName slug professional and memorable
• Update branding URLs (imageUrl) to reflect current logo

Configure Notifications Thoughtfully

• Start with EMAIL (most universal)
• Add SMS only when you have phone numbers and SMS gateway configured
• Override at location/resource level as needed

Protect Registration Email

• Use a monitored email address
• Don't use personal emails
• Consider team@ or admin@ addresses

Review Settings Periodically

Quarterly:

• Verify timezone is correct
• Update contact information
• Check notification preferences
• Audit child entities for overrides

Troubleshooting

Can't authenticate

Check:

1. Company is not suspended
2. OAuth credentials are valid and belong to this company
3. API key (if using dashboard auth) matches company

Locations showing wrong timezone

Check:

1. Company timezone is set correctly
2. Location isn't overriding with incorrect timezone
3. Resources aren't overriding timezone

Cascade order matters: Resource > Location > Company.

Notifications not sending

Check:

1. Company notificationType isn't NONE
2. Email/SMS gateways are configured (contact support if unsure)
3. Locations/resources aren't overriding to NONE
4. Appointment creation included customer contact info

Can't see other company's data

Expected behavior: Companies are isolated. You cannot access another company's data via API.

Solution: Use correct credentials for the target company.

Common Questions

Can I rename my company?

Yes, update via PUT /v3/company. The internal ID remains the same, only the display name changes.

Can I transfer locations between companies?

Not directly. Contact support for complex migrations.

Can I have multiple companies with the same name?

No, company names are unique across OnSched.

What happens if my company is suspended?

• Existing appointments remain visible
• New bookings are blocked
• API authentication fails
• Dashboard access restricted

Contact support to resolve suspension.

Can I delete my company?

Contact support for account deletion. This is permanent and cannot be undone.

How do I add users to my company?

User and team access is managed primarily in the OnSched dashboard. The API also exposes the current user as GET /v3/user and updates via PUT /v3/user/:id for the authenticated dashboard user—see the API reference for request shapes.

Related Documentation

• Architecture Guide – Understanding the hierarchy
• Authentication – API credentials and auth flows
• Get Started – First steps with OnSched
• Locations – Configuring locations
• Settings – Comprehensive settings guide

The company is your OnSched foundation. Configure it correctly, and all child entities inherit sensible defaults automatically.