Getting Started with OnSched

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

Welcome to OnSched

OnSched is a flexible scheduling platform that helps you manage appointments, availability, and resources through a REST API. Whether you're building a booking interface for customers or integrating scheduling into your existing application, OnSched provides the tools you need.

What You Can Build

• Customer booking portals that show available time slots and let users book appointments
• Staff scheduling tools for managing resource availability and assignments
• Automated booking systems that sync with external calendars
• Multi-location businesses with centralized scheduling management
• Resource booking for rooms, equipment, or services with capacity constraints

Architecture Overview

OnSched uses a hierarchical structure:

• Company – Your organization's top-level account
• Locations – Physical or virtual places where services are provided
• Services – Bookable offerings (haircuts, consultations, equipment rentals)
• Resources – Staff, rooms, or equipment that deliver services
• Appointments – Confirmed bookings connecting customers to services and resources

For a detailed explanation, see our Architecture Guide.

Quick Start

1. Get Your Credentials

Log into the OnSched dashboard and navigate to API Settings. You'll need:

• Company ID – Your unique company identifier
• Client ID and Secret – OAuth2 credentials for API access
• API Key – Used alongside dashboard authentication

Most integrations use OAuth2 client credentials. See Authentication for details.

2. Request an Access Token

Exchange your credentials for a time-limited access token:

curl -X POST https://v3.onsched.com/v3/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials&scope=read write"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Tokens expire after one hour. Request a new one when needed—no refresh token is issued.

3. Make Your First Request

Retrieve your company details:

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

Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Acme Scheduling",
  "timezone": "America/New_York",
  "email": "[email protected]",
  "phone": "+1-555-0100"
}

4. Explore Available Services

List services offered by your company:

curl "https://v3.onsched.com/v3/services?limit=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Services define what customers can book—each has a duration, optional padding time, and links to resources that can fulfill it.

5. Check Availability

Before creating an appointment, check when slots are open:

curl "https://v3.onsched.com/v3/availability?\
startDate=2025-12-01&\
endDate=2025-12-07&\
LocationId=YOUR_LOCATION_ID&\
ServiceId=YOUR_SERVICE_ID&\
timezone=America/New_York" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

This returns available time slots respecting service duration, resource schedules, and existing bookings. See Availability Guide for all parameters.

6. Create an Appointment

Book a slot returned by the availability check:

curl -X POST "https://v3.onsched.com/v3/appointment?\
LocationId=YOUR_LOCATION_ID&\
ServiceId=YOUR_SERVICE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Customer": {
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "[email protected]",
      "phone": "+15550123"
    },
    "Unavailability": {
      "startTime": "2025-12-01T14:00:00Z",
      "endTime": "2025-12-01T14:30:00Z"
    },
    "duration": 30
  }'

The appointment is confirmed immediately unless you use POST /v3/appointment/hold for a temporary reservation. See Appointment Guide for booking patterns.

Core Concepts

Availability vs Appointments

• Availability tells you when bookings are possible
• Appointments are confirmed bookings that block availability for other customers

Always check availability before creating appointments to avoid conflicts.

Holds vs Bookings

• Holds (POST /appointment/hold) reserve a slot temporarily while customers complete checkout
• Bookings (POST /appointment) confirm the appointment immediately

Holds expire automatically based on location settings (expirationDelay in seconds).

Services vs Resources

• Services define what is being booked (duration, pricing, availability rules)
• Resources define who or what delivers the service (staff, rooms, equipment)

A service can be fulfilled by multiple resources. Use round robin assignment to distribute bookings fairly. See Services and Resources.

Timezones

OnSched respects multiple timezone levels:

1. Company timezone – Default for all operations
2. Location timezone – Overrides company default
3. Resource timezone – Used for individual availability
4. Request timezone – Optional parameter on API calls

Always specify timezone when requesting availability to ensure results match user expectations. See Availability Timezones.

Dashboard vs API

The OnSched dashboard provides a visual interface for:

• Managing company settings, locations, services, and resources
• Viewing appointments in calendar format
• Configuring webhooks and email templates
• Generating API credentials

Most users configure their account through the dashboard, then use the API to build custom booking experiences. You can also give customers direct access to the dashboard for self-service management.

Next Steps

Explore these guides based on what you're building:

Getting Help

• Swagger Documentation: Interactive API reference at https://v3.onsched.com/v3/ (see Swagger Guide)
• Support: Contact your account representative or submit tickets through the dashboard
• Status: Check service status and uptime at our status page

Ready to build? Start with Authentication to secure your integration.