logo
API docs by Redocly

TidyCal API (0.1)

Download OpenAPI specification:Download

Introduction

TidyCal's REST API provides a handful of endpoints which can be used to get information about your account and bookings. It uses conventional OAuth 2.0 protocol for authentication.

Authentication

Personal Access Token

Create a personal access token at https://tidycal.com/integrations/oauth. Once created, it can be used to authenticate requests by passing it in the Authorization header.

Authorization: Bearer {TOKEN}

OAuth 2.0 Client

If you're building a custom integration to TidyCal which requires users to authenticate in order to get access tokens to make API requests on their behalf, you'll need to create an OAuth 2.0 client. This is easy to do from the "OAuth Apps" settings page found here https://tidycal.com/integrations/oauth

Using the authorization_code grant type to authenticate users using OAuth 2.0 to retrieve an access token is fairly conventional, more information on that process can be found here: https://www.oauth.com/oauth2-servers/server-side-apps/authorization-code/

Account

Account information

Get account details.

Responses

Response samples

Content type
application/json
{}

Bookings

List bookings

Get a list of bookings.

path Parameters
starts_at
date

Get bookings starting from a specific date.

ends_at
date

Get bookings ending before a specific date.

cancelled
boolean

Get only cancelled bookings.

page
number

Page number.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Booking Types

List booking types

Get a list of booking types.

path Parameters
page
number

Page number.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create booking type

Create a new booking type.

Request Body schema: application/json
title
required
string <= 191 characters
description
required
string <html>
duration_minutes
required
integer >= 1
url_slug
required
string <= 191 characters
padding_minutes
integer >= 0
Default: 0
latest_availability_days
integer [ 0 .. 36500 ]
Default: 60
private
boolean
Default: false
max_bookings
integer >= 1
Default: 1
max_guest_invites_per_booker
integer [ 0 .. 10 ]
Default: 0
display_seats_remaining
boolean
Default: false
booking_availability_interval_minutes
integer [ 15 .. 1440 ]
Default: 15
redirect_url
string or null <= 60000 characters
approval_required
boolean or null
booking_type_category_id
integer or null

Responses

Request samples

Content type
application/json
{
  • "title": "30 Minute Meeting",
  • "description": "Book a 30 minute meeting with me",
  • "duration_minutes": 30,
  • "url_slug": "30-minute-meeting",
  • "padding_minutes": 15,
  • "latest_availability_days": 90,
  • "private": false,
  • "max_bookings": 1,
  • "max_guest_invites_per_booker": 0,
  • "display_seats_remaining": false,
  • "booking_availability_interval_minutes": 30,
  • "redirect_url": "https://example.com/thank-you",
  • "approval_required": false,
  • "booking_type_category_id": 1
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List available timeslots

Get a list of available timeslots for a specific booking type.

path Parameters
bookingType
required
integer

The ID of the booking type.

query Parameters
starts_at
required
string <date-time>

Start date to get timeslots from (UTC).

ends_at
required
string <date-time>

End date to get timeslots until (UTC).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create booking

Create a new booking for a specific booking type.

path Parameters
bookingType
required
integer

The ID of the booking type.

Request Body schema: application/json
starts_at
required
string <date-time>

The start time of the booking in UTC

name
required
string <= 191 characters

Name of the person making the booking

email
required
string <email> <= 191 characters

Email of the person making the booking

timezone
required
string <= 191 characters

The timezone of the booking

Array of objects

Answers to booking type questions

Responses

Request samples

Content type
application/json
{
  • "starts_at": "2024-03-20T10:00:00Z",
  • "name": "John Doe",
  • "email": "john@example.com",
  • "timezone": "America/Los_Angeles",
  • "booking_questions": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Contacts

List contacts

Get a list of contacts.

path Parameters
page
number

Page number.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create contact

Create a new contact.

Request Body schema: application/json
name
required
string
email
required
string <email>
timezone
string

Responses

Request samples

Content type
application/json
{
  • "name": "John Doe",
  • "email": "john@example.com",
  • "timezone": "America/Los_Angeles"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}