Required Parameters

Making a request to Availability is what OnSched is all about. This is usually at the core of every integration to OnSched and requires a few steps to be made to ensure that the right type and number of appointments are booked exactly when, where, and with who you want.

The request URL to get available times from the API requires the Service ID, a start time, and an end time.

curl --location --request GET '{serviceId}/{startDate}/{endDate}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'Authentication=Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' 
const params = {
        client_id:     'DemoUser',
        client_secret: 'DemoUser',
        scope:         'OnSchedApi',
        grant_type:    'client_credentials',
      const availabilityURL = '{serviceId}/{startDate}/{endDate}'
      // querystring.stringify(params) will encode the param data
      // in application/x-www-form-urlencoded format, which is required
      // by the Identity Server
      axios.get( availabilityURL, querystring.stringify( params ) )
           .then( resp => {
             // return the availability object containing available times array
             resolve( )
           } )
           .catch( error => reject( error ) )
var request = require('request');
var options = {
  'method': 'GET',
  'url': '{serviceId}/{startDate}/{endDate}',
  'headers': {'Content-Type': 'application/x-www-form-urlencoded' },
  form: {
    'client_id': 'DemoUser',
    'client_secret': 'DemoUser',
    'scope': 'OnSchedApi',
    'grant_type': 'client_credentials'
request(options, function (error, response) {
  if (error) throw new Error(error);
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "{serviceId}/{startDate}/{endDate}",
  "method": "GET",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded",
    "Accept": "*/*",
    "Cache-Control": "no-cache",
    "Host": "",
    "Accept-Encoding": "gzip, deflate",
    "Content-Length": "110",
    "Connection": "keep-alive",
    "cache-control": "no-cache"
  "data": {
    "grant_type": "client_credentials",
    "scope": "OnSchedApi",
    "client_id": "DemoUser",
    "client_secret": "DemoUser"

$.ajax(settings).done(function (response) {
package main
import (
func main() {
  url := "{serviceId}/{startDate}/{endDate}"
  method := "GET"
  payload := strings.NewReader("client_id=DemoUser&client_secret=DemoUser&scope=OnSchedApi&grant_type=client_credentials")
  client := &http.Client {
  req, err := http.NewRequest(method, url, payload)
  if err != nil {
  req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
  res, err := client.Do(req)
  if err != nil {
  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
require "uri"
require "net/http"
url = URI("{serviceId}/{startDate}/{endDate}")
https =, url.port)
https.use_ssl = true
request =
request["Content-Type"] = "application/x-www-form-urlencoded"
request.body = "client_id=DemoUser&client_secret=DemoUser&scope=OnSchedApi&grant_type=client_credentials"
response = https.request(request)
puts response.read_body
import http.client
conn = http.client.HTTPSConnection("")
payload = 'client_id=DemoUser&client_secret=DemoUser&scope=OnSchedApi&grant_type=client_credentials'
headers = {'Content-Type': 'application/x-www-form-urlencoded'}
conn.request("GET", "/consumer/v1/availability/{serviceId}/{startDate}/{endDate}", payload, headers)
res = conn.getresponse()
data =
var data = "client_id=DemoUser&client_secret=DemoUser&scope=OnSchedApi&grant_type=client_credentials";
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
});"GET", "{serviceId}/{startDate}/{endDate}");
xhr.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
OkHttpClient client = new OkHttpClient().newBuilder()
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "client_id=DemoUser&client_secret=DemoUser&scope=OnSchedApi&grant_type=client_credentials");
Request request = new Request.Builder()
  .method("GET", body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
Response response = client.newCall(request).execute();
GET /consumer/v1/availability/{serviceId}/{startDate}/{endDate} HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: */*
Cache-Control: no-cache
Accept-Encoding: gzip, deflate
Content-Length: 110
Connection: keep-alive
cache-control: no-cache



The type of Service that is being searched in the request to Availability will make a great effect on Availability. There are two types of Services, the effect they will have on Availability is as follows:

  • Appointment: Weekly availability based on the business hours of the Location, Resource, and Service
  • Event: Closed every day by default with the exception of Allocations created

Service blocks will also effect Availability by filtering out the time slots that conflict with any of the blocks.

Once the Service is decided on, include the ID from that service in the Availability request URL.

Date Range

An Availability request requires both a start and end date in the request URL, submitted with a format of YYYY-MM-DD.

Since Availability is the most complex endpoint to factor the response time will grow with the number of days you're searching for. For example, searching for one day has an approximate response time of 500-600 milliseconds, compared to a month which is nearly double that time averaging 1100-1200 milliseconds.


At least one Resource is a required in order to create an Appointment. A Resource can be selected by the user, chosen programmatically by your application, or randomly selected based on whoever is available.

If you have determined the Resource that you wish to get available times for then simply include the ID for that Resource in the body of the request with the parameter name resourceId and skip to the next step.

Multiple Resources
Should an Appointment require multiple Resources on a single Appointment, provide a comma-separated list of Resource ID's in the body of the request with the parameter name resourceIds.

Resource Groups
If you do not know the specific Resource, but you do know the Resource group that you would like to be booked, you may instead provide the value of the Resource Group ID to the property resourceGroupId in the body of the request. If a Resource Group ID is provided, Round Robin Booking

Round Robin

Otherwise, if it does not matter which resource you would like to find available times for, you can provide a value of zero to the resourceId property. If a zero is provided to the resourceId property then a value of 1 (Random) or 2 (Balanced) must also be provided for roundRobin, this will change how the appointments are distributed:


Round Robin Settings

None If you are providing a resourceId to the body of the request you can use a value of zero for the roundRobin property, this is done by default if you do not include that property in the body of the request

Balanced If a value of 1 is provided to the property roundRobin the time slots will be distributed evenly when possible

Random If a value of 2 is provided to the property roundRobin the time slots will be distributed at random to whoever is available at that time

What’s Next