--- updatedAt: 2025-12-18T17:04:51.000Z --- # Getting Started with OnSched Begin building with OnSched's scheduling API. Learn how to authenticate, make your first request, and navigate the platform's features. > **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](https://docs.onsched.com/docs/company-vs-location). ## 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](https://docs.onsched.com/docs/authentication) for details. ### 2. Request an Access Token Exchange your credentials for a time-limited access token: ```bash 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: ```json { "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: ```bash curl https://v3.onsched.com/v3/company \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` Response: ```json { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Acme Scheduling", "timezone": "America/New_York", "email": "hello@acme.com", "phone": "+1-555-0100" } ``` ### 4. Explore Available Services List services offered by your company: ```bash 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: ```bash 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](https://docs.onsched.com/docs/availability) for all parameters. ### 6. Create an Appointment Book a slot returned by the availability check: ```bash 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": "jane@example.com", "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](https://docs.onsched.com/docs/appointments) 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](https://docs.onsched.com/docs/services-overview) and [Resources](https://docs.onsched.com/docs/resources-overview). ### 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](https://docs.onsched.com/docs/availability#working-with-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: | If you want to... | Read this | | --------------------------------- | ----------------------------------------------------------------------- | | Understand authentication options | [Authentication Guide](https://docs.onsched.com/docs/authentication) | | Display available booking times | [Availability Guide](https://docs.onsched.com/docs/availability) | | Create and manage bookings | [Appointment Guide](https://docs.onsched.com/docs/appointments) | | Set up automated notifications | [Webhook Guide](https://docs.onsched.com/docs/webhooks) | | Configure services and resources | [Services](https://docs.onsched.com/docs/services-overview) & [Resources](https://docs.onsched.com/docs/resources-overview) | | Migrate from v1 to v3 | [Migration Guide](https://docs.onsched.com/docs/migrating-from-v1) | | Handle errors gracefully | [Error Codes](https://docs.onsched.com/docs/error-codes) | | Understand platform terminology | [Glossary](https://docs.onsched.com/docs/glossary) | ## Getting Help * **Swagger Documentation**: Interactive API reference at `https://v3.onsched.com/v3/` (see [Swagger Guide](https://docs.onsched.com/docs/swagger-docs)) * **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](https://docs.onsched.com/docs/authentication) to secure your integration.