Appointments

List appointment openings

Lists regular and off-hours availability for a location and/or barber. Anonymous browse tokens and customer bearer tokens may use this operation.

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

Either a locationId or barberId is required. If a location is not included and a barber is associated with multiple locations, a single location is selected at random by the system. If a barber is not included, a random barber is selected by the system.

GET

openings

List appointment openings

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

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

fetch('https://api.guile.app/openings', 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",
  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"

	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")

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

{
  "openings": [
    "9:00"
  ],
  "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>"
  },
  "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"
    }
  ],
  "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

Limit openings to this specific location.

Either a locationId or barberId is required. 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

Limit openings to this specific barber.

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.

date

string

required

Limit openings to this specific calendar date. A date, expressed in YYYY-MM-DD RFC 3339 date format.

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

Response

Ok. The operation succeeded.

Available openings based on request parameters.

openings

string[]

required

Regular-hours appointment opening times for the requested date. This preserves the deployed string[] meaning; off-hours times never appear in this list.

The starting time for an appointment opening time slot, in 24 hour time.

count

integer<int16>

required

The number of regular-hours entries in openings. Off-hours quotes are excluded to preserve deployed count semantics. 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

regularOffers

object[]

Short-lived exact regular-hours offers corresponding one-to-one with openings. Present only for service-scoped requests. Each offer carries the exact UTC occurrence and location time zone the customer may submit.

Show child attributes

offHoursQuotes

object[]

Short-lived off-hours quotes, disjoint from openings. Absent for legacy duration-only requests.

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

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

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

fetch('https://api.guile.app/openings', 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",
  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"

	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")

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

{
  "openings": [
    "9:00"
  ],
  "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>"
  },
  "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"
    }
  ],
  "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

Query Parameters

Response