Swagger Documentation

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

Interactive API Documentation

OnSched provides auto-generated Swagger documentation for all API endpoints. Access it at:

https://v3.onsched.com/v3/

The Swagger UI allows you to explore available endpoints, view request/response schemas, and even test API calls directly from your browser.

What Is Swagger?

Swagger (also known as OpenAPI) is an industry-standard format for describing REST APIs. It provides:

Complete endpoint catalog with HTTP methods, paths, and parameters
Request schemas showing exactly what data each endpoint expects
Response examples with success and error payloads
Interactive testing to try endpoints without writing code
Type definitions for every field with validation rules

Think of it as a living reference manual that's always in sync with the API.

Using the Swagger Interface

Navigating Endpoints

Endpoints are grouped by resource type:

Appointments – Create, update, cancel bookings
Availability – Check open time slots
Services – Manage bookable offerings
Resources – Staff, rooms, equipment
Locations – Physical or virtual service locations
Customers – Customer records and profiles
Webhooks – Configure event notifications
Company – Organization settings
And more...

Click any group to expand and see available operations.

Understanding Endpoint Entries

Each endpoint shows:

HTTP Method – GET, POST, PUT, DELETE
Path – URL with path parameters in {braces}
Description – What the endpoint does
Parameters – Query params, path params, headers, and request body
Responses – Status codes with example payloads

Query Parameters

Parameters are marked as required or optional. For example, GET /v3/availability shows:

startDate (required) – Search window start
endDate (required) – Search window end
LocationId (required) – Location UUID
ServiceId (required) – Service UUID
ResourceIds (optional) – Filter to specific resources
timezone (optional) – Result timezone (defaults to UTC)

Request Body Schemas

For POST and PUT operations, expand the request body section to see the expected structure. Schemas indicate:

Field names and their types (string, integer, boolean, object, array)
Validation rules (min/max length, format requirements)
Required vs optional fields
Nested objects (e.g., Customer within an appointment)
Default values when applicable

Response Examples

Each endpoint includes example responses for:

Success cases (usually 200, 201)
Common errors (400, 401, 404, 422, etc.)

Response examples show the exact JSON structure you'll receive, including field types and nesting.

Testing Endpoints Interactively

The Swagger UI includes a "Try it out" feature for live testing.

Step 1: Authorize

Before testing protected endpoints, authenticate:

Click the Authorize button at the top of the page
Enter your access token in the format: Bearer YOUR_ACCESS_TOKEN
Click Authorize then Close

Your token is now attached to all requests. See Authentication for obtaining tokens.

Step 2: Try an Endpoint

Expand an endpoint (e.g., GET /v3/company)
Click Try it out
Fill in required parameters
Click Execute

The interface shows:

Request URL – Full URL with query params
Response status – HTTP status code
Response body – Actual JSON returned
Response headers – Metadata like content-type
Request duration – How long the call took

Example: Checking Availability

Let's test availability for a service:

Navigate to Availability → GET /v3/availability
Click Try it out
Fill in parameters:
- startDate: 2025-12-01
- endDate: 2025-12-07
- LocationId: (your location UUID)
- ServiceId: (your service UUID)
- timezone: America/New_York
Click Execute

You'll see available slots in the response body, formatted by day.

Example: Creating an Appointment

Test the booking flow:

Navigate to Appointment → POST /v3/appointment
Click Try it out
Set query parameters:
- LocationId: (your location UUID)
- ServiceId: (your service UUID)
Edit the request body JSON:

{
  "Customer": {
    "firstName": "Test",
    "lastName": "User",
    "email": "[email protected]"
  },
  "Unavailability": {
    "startTime": "2025-12-01T14:00:00Z",
    "endTime": "2025-12-01T14:30:00Z"
  },
  "duration": 30
}

Click Execute

If successful, you'll get a 201 response with the created appointment details, including the generated id.

Schemas and Models

The Schemas section at the bottom of the Swagger page defines reusable data structures:

Appointment – Complete appointment object
Customer – Customer profile structure
Service – Service configuration
Resource – Resource details
Unavailability – Time block structure
And many more...

These schemas document every field including:

Data types – string, integer, boolean, uuid, date-time, enum
Constraints – maxLength, minimum, pattern (regex)
Format – email, uuid, ipv4, uri
Enums – Valid values (e.g., status: ["IN", "BK", "RS", "RE", "CN"])

Use schemas as a reference when building requests programmatically.

Understanding Parameter Types

Swagger documents four parameter locations:

Path Parameters

Embedded in the URL, marked with {braces}:

GET /v3/appointment/{id}

Path parameters are always required. They typically represent resource identifiers (UUIDs).

Query Parameters

Appended to the URL after ?:

GET /v3/appointments?limit=20&page=1&status=BK

Query parameters are used for filtering, pagination, and optional behavior flags.

Header Parameters

Sent in HTTP headers:

Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY
x-client-id: YOUR_CLIENT_ID

Most endpoints require the Authorization header. Dashboard authentication also needs x-api-key and x-client-id.

Body Parameters

JSON payload for POST and PUT requests:

{
  "name": "Haircut",
  "duration": 30
}

Body parameters are documented in the request schema for each endpoint.

Common Use Cases

Discovering Available Endpoints

Not sure which endpoint to use? Browse by resource type:

Need to create bookings? → Appointment section
Want to check open slots? → Availability section
Managing staff? → Resource section
Configuring services? → Service section

Understanding Data Relationships

Swagger shows how resources connect:

Services reference CompanyId or LocationId (via scope)
Appointments require LocationId, ServiceId, and Customer
Resources link to services through join tables
Unavailability blocks reference appointments or resources

Validating Your Integration

Compare your code's request/response handling against Swagger schemas:

Are you sending all required fields?
Do your field names match exactly (case-sensitive)?
Are data types correct (string vs integer, etc.)?
Are you handling all documented error responses?

Exploring Advanced Features

Swagger documents less obvious capabilities:

overrideDuration parameter on availability checks
roundRobin modes for resource assignment
CustomFields for extending data models
syncExternal flag for real-time calendar sync
Filtering options on list endpoints

Swagger vs Guides

Use Swagger for:

Complete field-level API reference
Testing endpoints quickly
Validating request formats
Discovering all available options

Use Guides for:

Understanding concepts and workflows
Learning how features work together
Best practices and patterns
Real-world examples with context

This documentation provides both—Swagger for technical reference, guides for practical implementation. For example:

Swagger shows GET /v3/availability accepts 15+ parameters
The Availability Guide explains when and why to use each one

Generating API Clients

The OpenAPI specification (available at https://v3.onsched.com/v3/openapi.json) can generate API client libraries automatically.

Popular tools:

openapi-generator – Clients for 40+ languages
swagger-codegen – Java, Python, JavaScript, and more
autorest – C#, TypeScript

Example generating a JavaScript client:

openapi-generator generate \
  -i https://v3.onsched.com/v3/openapi.json \
  -g javascript \
  -o ./onsched-client

This creates a type-safe SDK matching the OnSched API structure.

Swagger Tips

Bookmark Frequently Used Endpoints

Use direct links to jump to specific endpoints:

https://v3.onsched.com/v3/#/Appointment/post_v3_appointment

Export as JSON or YAML

Download the OpenAPI specification for offline reference or code generation:

JSON: https://v3.onsched.com/v3/openapi.json
YAML: Usually available at the same root with .yaml extension

Check Response Schemas Carefully

Some endpoints return different schemas based on authentication:

Public routes return limited fields
Authenticated company routes return full details

Always test with your actual auth method.

Use Model Definitions

Instead of guessing field names, copy from schema definitions in the Schemas section. They're guaranteed to match what the API expects.

Limitations

Swagger documentation has some limitations:

No workflow examples – Shows individual endpoints but not multi-step processes (use guides for flows)
Limited context – Doesn't explain why fields exist or how to use them strategically
Static examples – Response examples are generic; your data will differ
No troubleshooting – For debugging, see Error Codes

Staying Updated

The Swagger documentation auto-updates with API changes. When new features launch or fields are added, they appear immediately in Swagger.

For major changes:

Check release notes (if available)
Review updated endpoint descriptions
Test existing integrations against new schemas

Related Resources

Getting Started – First steps with the API
Authentication – How to authorize Swagger requests
Error Codes – Understanding response status codes
Glossary – API terminology reference

Start exploring at https://v3.onsched.com/v3/ and use this guide alongside the interactive documentation to build your integration faster.