Appointments

List appointment openings for a date interval

List appointment openings for each calendar date in the requested interval. Dates with no openings, including closed days, appear with empty openings.

Existing callers may provide duration to receive deployed regular-hours openings. New booking callers provide serviceIds; the server derives the duration and current service terms and returns legacy regular openings, exact regularOffers, and disjoint offHoursQuotes. When both are included, serviceIds is authoritative: the server ignores duration rather than validating it against the derived service duration.

GET

openings

range

List appointment openings for a date interval

curl --request GET \
  --url https://api.guile.app/openings/range \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.guile.app/openings/range', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.guile.app/openings/range",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.guile.app/openings/range"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.guile.app/openings/range")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "date": "<string>",
      "openings": [
        "9:00"
      ],
      "count": 1,
      "regularOffers": [
        {
          "offerId": "<string>",
          "expiresAt": "2023-11-07T05:31:56Z",
          "startsAt": "9:00",
          "occursOn": "2023-11-07T05:31:56Z",
          "timeZone": "<string>",
          "barber": {
            "id": "<string>",
            "givenName": "<string>",
            "surname": "<string>",
            "preferredName": "<string>",
            "biography": "<string>",
            "spokenLanguages": [],
            "experience": 50,
            "instagram": "<string>",
            "urlSlug": "<string>",
            "profileImage_URL": "<string>"
          },
          "location": {
            "id": "<string>",
            "name": "<string>",
            "shopName": "<string>"
          },
          "services": [
            {
              "id": "<string>",
              "name": "<string>",
              "cost": "456.78",
              "duration": "<string>"
            }
          ],
          "duration": "<string>",
          "serviceSubtotal": "456.78"
        }
      ],
      "offHoursQuotes": [
        {
          "quoteId": "<string>",
          "expiresAt": "2023-11-07T05:31:56Z",
          "startsAt": "9:00",
          "occursOn": "2023-11-07T05:31:56Z",
          "timeZone": "<string>",
          "barber": {
            "id": "<string>",
            "givenName": "<string>",
            "surname": "<string>",
            "preferredName": "<string>",
            "biography": "<string>",
            "spokenLanguages": [],
            "experience": 50,
            "instagram": "<string>",
            "urlSlug": "<string>",
            "profileImage_URL": "<string>"
          },
          "location": {
            "id": "<string>",
            "name": "<string>",
            "shopName": "<string>"
          },
          "services": [
            {
              "id": "<string>",
              "name": "<string>",
              "cost": "456.78",
              "duration": "<string>"
            }
          ],
          "duration": "<string>",
          "serviceSubtotal": "456.78",
          "approvalMode": "required",
          "offHoursFee": "456.78"
        }
      ]
    }
  ],
  "count": 1,
  "location": {
    "id": "<string>",
    "name": "<string>",
    "shopName": "<string>"
  },
  "barber": {
    "id": "<string>",
    "givenName": "<string>",
    "surname": "<string>",
    "preferredName": "<string>",
    "biography": "<string>",
    "spokenLanguages": [],
    "experience": 50,
    "instagram": "<string>",
    "urlSlug": "<string>",
    "profileImage_URL": "<string>"
  },
  "bookableThrough": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

Query Parameters

locationId

string

required

Limit openings to this specific location. The unique, opaque system identifier for a resource. This case-sensitive ID is also used as path parameters in URLs or in other properties or parameters that reference a resource by ID rather than URL.

barberId

string

When included, limit openings to this specific barber. The unique, opaque system identifier for a resource. This case-sensitive ID is also used as path parameters in URLs or in other properties or parameters that reference a resource by ID rather than URL.

duration

string<duration>

Calculate legacy regular openings for this appointment duration. Required when serviceIds is absent. Ignored when serviceIds is present because the server derives duration from current service terms.

serviceIds

string[]

Select the services for server-derived regular opening offers and off-hours quotes. The server owns their price, duration, eligibility, exact occurrence, and availability; callers provide identifiers only.

Required array length: 1 - 25 elements

The unique, opaque system identifier for a resource. This case-sensitive ID is also used as path parameters in URLs or in other properties or parameters that reference a resource by ID rather than URL.

dates

string

required

Limit openings to the calendar dates in this range. The range names both its start and end dates and covers at most 31 calendar dates. A date range, supporting inclusive or exclusive endpoints. Dates ranges use dates expressed in YYYY-MM-DD RFC 3339 date format. The value may have the following forms:

YYYY-MM-DD match the date exactly; equivalent to matching dates in the range [YYYY-MM-DD,YYYY-MM-DD]
[YYYY-MM-DD,YYYY-MM-DD] between two dates, inclusive of the endpoints
(YYYY-MM-DD,YYYY-MM-DD) between two dates, exclusive of the endpoints
[YYYY-MM-DD,] on or after the date
(YYYY-MM-DD,) after the date
[,YYYY-MM-DD] before or on the date
(,YYYY-MM-DD) before the date

Examples:

'2022-05-19'
'[2022-05-01,2022-05-31]'
'[2022-05-01,2022-06-01)'
'[2022-05-19,]'
'(2022-05-19,)'
'[,2022-05-19]'
'(,2022-05-19)'.

Maximum string length: 24

Pattern: ^(\d{4}-\d{2}-\d{2}|[\[(](\d{4}-\d{2}-\d{2},(\d{4}-\d{2}-\d{2})?|,\d{4}-\d{2}-\d{2})[)\]])$

Response

Ok. The operation succeeded.

Appointment openings grouped by calendar date over a requested interval. Every date in the interval appears exactly once; a date with no openings has an empty openings list and a count of zero.

items

object[]

required

One entry per calendar date in the requested interval.

Show child attributes

count

integer<int16>

required

The number of dates in the interval. This is derived and immutable.

Required range: x >= 0

location

object

required

The shop location for the appointment openings.

Show child attributes

barber

object

required

The barber for the appointment openings.

Show child attributes

bookableThrough

string

The furthest calendar date a client may book, based on the barber's advance booking window. When absent, booking is not limited by an advance window.

Pattern: ^\d{4}-\d{2}-\d{2}$

List appointment openings for a date interval

curl --request GET \
  --url https://api.guile.app/openings/range \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.guile.app/openings/range', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.guile.app/openings/range",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.guile.app/openings/range"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.guile.app/openings/range")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "date": "<string>",
      "openings": [
        "9:00"
      ],
      "count": 1,
      "regularOffers": [
        {
          "offerId": "<string>",
          "expiresAt": "2023-11-07T05:31:56Z",
          "startsAt": "9:00",
          "occursOn": "2023-11-07T05:31:56Z",
          "timeZone": "<string>",
          "barber": {
            "id": "<string>",
            "givenName": "<string>",
            "surname": "<string>",
            "preferredName": "<string>",
            "biography": "<string>",
            "spokenLanguages": [],
            "experience": 50,
            "instagram": "<string>",
            "urlSlug": "<string>",
            "profileImage_URL": "<string>"
          },
          "location": {
            "id": "<string>",
            "name": "<string>",
            "shopName": "<string>"
          },
          "services": [
            {
              "id": "<string>",
              "name": "<string>",
              "cost": "456.78",
              "duration": "<string>"
            }
          ],
          "duration": "<string>",
          "serviceSubtotal": "456.78"
        }
      ],
      "offHoursQuotes": [
        {
          "quoteId": "<string>",
          "expiresAt": "2023-11-07T05:31:56Z",
          "startsAt": "9:00",
          "occursOn": "2023-11-07T05:31:56Z",
          "timeZone": "<string>",
          "barber": {
            "id": "<string>",
            "givenName": "<string>",
            "surname": "<string>",
            "preferredName": "<string>",
            "biography": "<string>",
            "spokenLanguages": [],
            "experience": 50,
            "instagram": "<string>",
            "urlSlug": "<string>",
            "profileImage_URL": "<string>"
          },
          "location": {
            "id": "<string>",
            "name": "<string>",
            "shopName": "<string>"
          },
          "services": [
            {
              "id": "<string>",
              "name": "<string>",
              "cost": "456.78",
              "duration": "<string>"
            }
          ],
          "duration": "<string>",
          "serviceSubtotal": "456.78",
          "approvalMode": "required",
          "offHoursFee": "456.78"
        }
      ]
    }
  ],
  "count": 1,
  "location": {
    "id": "<string>",
    "name": "<string>",
    "shopName": "<string>"
  },
  "barber": {
    "id": "<string>",
    "givenName": "<string>",
    "surname": "<string>",
    "preferredName": "<string>",
    "biography": "<string>",
    "spokenLanguages": [],
    "experience": 50,
    "instagram": "<string>",
    "urlSlug": "<string>",
    "profileImage_URL": "<string>"
  },
  "bookableThrough": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

Get started

Public APIs

API concepts

Metadata

Admin

Authentication

Appointments

Payments

Barbers

Businesses

Clients

Customers

Fees

Integrations

Invitations

Payouts

Photos

Refunds

Reviews

Services

Shops

List appointment openings for a date interval

Query Parameters

Response