canonical: https://jentic.com/apis/onsched.com/onsched-consumer-api

# OnSched Consumer API

OnSched is a developer-first online booking platform. The Consumer API exposes the endpoints that power consumer-facing booking flows: searching for availability, creating appointments, reserving and confirming slots, managing customer records, and reading the locations and resources that customers can book against. It is paired with separate Setup and Utility APIs that handle profile configuration and health checks. The Consumer API is the right surface for any storefront, mobile app, or AI agent that books appointments on behalf of a real end user.

## For AI agents

Search availability, create and book appointments, and manage customer records for online booking flows using OAuth 2.0 client-credentials authentication.

## Scope

Does not handle service or resource configuration, payments, or platform health - use for consumer-facing booking flows on an existing OnSched profile only.

## Capabilities

- Search availability for a service across a date range, day, or for explicit unavailability
- Create, reserve, book, and confirm appointments through their dedicated PUT actions
- Cancel, reschedule, or mark an appointment as no-show without recreating it
- Manage customer records including custom fields and required booking fields
- Read locations, resources, and resource groups available for booking
- Look up customer countries and states for valid address entry
- Authenticate with OAuth 2.0 using a ClientId and Secret bound to a company profile

## Use cases

### Consumer-facing online booking

A storefront or mobile app uses the Consumer API to power its booking widget. The flow is: search availability for the chosen service, present time slots, create the appointment, and book it once the customer confirms. The reserve and confirm actions support a two-stage flow where a slot is held while the customer pays or fills in details. Most teams ship a working booking flow in one to two weeks.

Example prompt: GET `/consumer/v1/availability/{serviceId}/{startDate}/{endDate}` for the chosen service, POST `/consumer/v1/appointments` to create the slot, then PUT `/consumer/v1/appointments/{id}/book` to confirm.

### Multi-location service business scheduling

Salons, clinics, and home-services businesses operate across many locations and resources. The Consumer API exposes locations, resourcegroups, and resources so the booking flow can route the customer to the right site and the right person, and the availability endpoint takes the resource into account. Custom fields and booking fields allow the business to capture the information they need without forking the schema.

Example prompt: GET `/consumer/v1/locations` to list sites, GET `/consumer/v1/resources` for the chosen service, then run availability and booking calls scoped to that resource.

### Reschedule and cancellation self-service

Customers want to manage their own appointments without calling the business. The Consumer API exposes per-appointment cancel, reschedule, confirm, and noshow actions on PUT `/consumer/v1/appointments/{id}`/<action> so a self-service portal can offer all four with a single auth flow. The same actions back the email and SMS reminder links that ask customers to confirm.

Example prompt: Look up the appointment by id, PUT `/consumer/v1/appointments/{id}/cancel` or /reschedule with the new time, and surface the result back to the customer.

### AI agent booking concierge through Jentic

An AI scheduling assistant can book appointments on a customer's behalf by calling the OnSched Consumer API through Jentic. The agent searches Jentic for the availability and create-appointment operations, loads their schemas, and submits the booking. Jentic injects the OAuth credential at execution time so the agent can act for many tenants without holding their secrets.

Example prompt: Search Jentic for 'onsched book appointment', load the POST `/consumer/v1/appointments` operation, and execute it for a known serviceId, customerId, and start time.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/consumer/v1/availability/{serviceId}/{startDate}/{endDate}` | Search availability for a service in a date range |
| POST | `/consumer/v1/appointments` | Create an appointment |
| PUT | `/consumer/v1/appointments/{id}/book` | Book a created appointment |
| PUT | `/consumer/v1/appointments/{id}/cancel` | Cancel an appointment |
| PUT | `/consumer/v1/appointments/{id}/reschedule` | Reschedule an existing appointment |
| GET | `/consumer/v1/customers` | List customer records |
| GET | `/consumer/v1/locations` | List bookable locations |

## Key resources

- **Appointments** — Core booking record with create, book, reserve, cancel, reschedule, confirm, and noshow actions
- **Availability** — Open and closed slots for a service across a date range
- **Customers** — Customer records with custom fields and booking fields
- **Locations** — Sites the business operates from
- **Resources** — Bookable people or rooms attached to services
- **Resource Groups** — Groupings of resources for routing and reporting

## Why Jentic

- **Setup:** Wiring the OnSched Consumer API by hand means running the OAuth2 client-credentials flow to mint a token, pointing at the OnSched host, and refreshing the token yourself as it expires. Through Jentic you install once, import the OnSched Consumer API from the API Directory, store the client credentials once, and your agent calls it.
- **Permission scoping:** OnSched Consumer puts the appointment id in the URL path (`/consumer/v1/appointments/{id}/book`), so a rule can pin your agent to one appointment for booking and reschedule actions. You choose the operations it may call, so destructive ones like cancel are not included unless you add them.
- **Credential handling:** Your OnSched client credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find available appointment slots' or 'book a consultation', and Jentic returns the matching OnSched Consumer operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Calendly API** — Hosted scheduling product with a smaller embeddable booking surface
- **Acuity Scheduling API** — Scheduling API focused on small-business service providers
- **OnSched Setup API** — Companion API for configuring the company profile, services, and resources

## FAQ

### What authentication does the OnSched Consumer API use?

The Consumer API uses OAuth 2.0. Each tenant has a ClientId and Secret tied to its company profile, which the integration exchanges for an access token. Through Jentic, the credentials are stored in the vault and the access token is refreshed transparently so the agent never sees the raw secret.

### Can I book an appointment for a specific resource and location?

Yes. Resolve the resource via GET `/consumer/v1/resources` and the location via GET `/consumer/v1/locations`, then call the availability endpoint scoped to the chosen service. POST `/consumer/v1/appointments` accepts the resourceId and locationId so the booking lands on the right slot in the right diary.

### What is the difference between reserve, book, and confirm on an appointment?

PUT `/consumer/v1/appointments/{id}/reserve` holds a slot while the customer is paying or completing details. PUT `/consumer/v1/appointments/{id}/book` commits the slot. PUT `/consumer/v1/appointments/{id}/confirm` marks an existing booked appointment as confirmed by the customer, typically off the back of an email or SMS reminder.

### What are the rate limits for the OnSched Consumer API?

OnSched does not publish a global rate limit in the spec. The platform serves consumer-facing booking flows at scale, and limits are signalled via 429 responses on the rare occasions they apply. Cache the locations, resources, and customer fields lookups, and avoid scanning availability for huge date ranges from the front end.

### How do I search availability and book through Jentic?

Install the SDK with 'pip install jentic', search for the operation with the query 'onsched search availability', then load the GET `/consumer/v1/availability/{serviceId}/{startDate}/{endDate}` operation, and execute it for the customer. Once you have the slot, call POST `/consumer/v1/appointments` via the same Jentic flow to create and book it.

### Does the Consumer API support custom and required booking fields?

Yes. GET `/consumer/v1/appointments/customfields` and GET `/consumer/v1/appointments/bookingfields` return the metadata that the booking flow needs to render the form. The same pattern is available on customers via GET `/consumer/v1/customers/customfields` and `/consumer/v1/customers/bookingfields.`

### Can I limit what my agent is allowed to do with the OnSched Consumer API?

Yes. Because you self-host Jentic One, your own rules decide which OnSched Consumer operations and credentials the agent may use, so it can search availability and create appointments while a destructive action like PUT `/consumer/v1/appointments/{id}/cancel` stays off the list unless you add it. OnSched puts the appointment id in the URL path, such as `/consumer/v1/appointments/{id}/book`, so a rule can pin the agent to one appointment for its book and reschedule actions. Your client credentials are held by your Jentic One instance and injected at execution time, so the agent never sees the raw secret.