Get Started with OnSched

This tutorial uses the staging host https://api-stage.onsched.com. Production is https://v3.onsched.com. See Environments.

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 (staging)

Prerequisites: a staging dashboard login, a location, a service linked to a resource at that location, and OAuth client id / secret. Most integrations use client credentials — not an API key. See Authentication.

1. Request an access token

curl -X POST https://api-stage.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"

The body includes access_token, token_type (Bearer), expires_in (about 3600 seconds), and scope. There is no refresh token; request a new access token when it expires.

2. Get availability

Use ISO 8601 or YYYY-MM-DD. now is not valid. Names are LocationId and ServiceId (exact casing).

curl "https://api-stage.onsched.com/v3/availability?\
startDate=2026-03-21&\
endDate=2026-03-21&\
LocationId=YOUR_LOCATION_ID&\
ServiceId=YOUR_SERVICE_ID&\
timezone=America/New_York" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

If availableTimes is empty, see Availability rules.

3. Hold a slot

curl -X POST "https://api-stage.onsched.com/v3/appointment/hold?\
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": "2026-03-21T14:00:00Z",
      "endTime": "2026-03-21T14:30:00Z"
    }
  }'

Status is IN. New locations default to 900 seconds (15 minutes) of hold expiry. Set 0 or null to disable the timer. Locations created before this default may have no expiry and should set a positive delay.

4. Book the hold

curl -X PUT "https://api-stage.onsched.com/v3/appointment/HOLD_ID/book" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Status becomes BK. To book in one step, use POST /v3/appointment instead of hold + book. See Appointment Guide and Appointment statuses.

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 /v3/appointment/hold) reserve a slot temporarily while customers complete checkout
• Bookings (POST /v3/appointment) confirm the appointment immediately

The Location expirationDelay sets a hold's expiration time in seconds. New locations default to 900 seconds (15 minutes) when omitted; set a positive value to choose another delay, or 0 / null to disable the timer. Existing locations keep their current value when an update omits the field. Without a positive delay, a hold has no timer and keeps its slot until you book or delete it. Locations created before this default may have no expiry and should set a positive delay. See Settings overview.

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

Pass timezone on GET /v3/availability when you want local clock times. New locations default to America/New_York. Calendar-day caps use the location timezone. See Time zones.

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

• Changelog: API and dashboard release notes, including staging vs production highlights
• Swagger Documentation: Interactive API reference at https://v3.onsched.com/docs (see Swagger Guide)
• Other endpoints: Platform API utilities (timezones, geography, holidays, email templates, tickets, health)
• Support: Contact your account representative or submit tickets through the dashboard
• Status: Check service status and uptime at our status page

Customer-facing widgets use OnSched.js (/v3/public/*). Operator APIs use the machine token in this tutorial.