TidyCal API Integration Tools

Overview

The TidyCal integration within Dialora’s custom tools enables users to link their TidyCal accounts and manage all scheduling directly from the platform. It provides seamless synchronization of meetings, availability, and bookings via the TidyCal API. This integration streamlines calendar management and enhances workflow efficiency within Dialora.

We have two tools:

tidycal_check_availability_of_slots – Fetches available time slots for a booking type.
tidycal_book_appointment – Creates a booking (reserves a slot).

These tools wrap calls to the TidyCal REST API. Authentication is via a Personal Access Token / OAuth bearer token.

API version: 0.1

Authentication

To authenticate with the TidyCal API, you need to use a Personal Access Token:

Use a Personal Access Token created via TidyCal integrations settings.
Send the token in the Authorization: Bearer {TOKEN} header for all tool calls.


{
  "key": "tidycal_check_availability_of_slots",
  "name": "Check TidyCal Availability",
  "description": "Fetches available time slots for a booking type between two given dates.",
  "pre_call_message": "Let me check available slots for you...",
  "parameters": {
    "type": "object",
    "required": ["startTime", "endTime"],
    "properties": {
      "startTime": {
        "type": "string",
        "description": "Start date for checking timeslots in YYYY-MM-DD format. Combined with time (usually UTC midnight) for API."
      },
      "endTime": {
        "type": "string",
        "description": "End date for checking timeslots in YYYY-MM-DD format. Combined with time (UTC) as needed. Usually end of day."
      }
    }
  },
  "value": {
    "method": "GET",
    "url": "https://tidycal.com/api/booking-types/YOUR_BOOKING_TYPE_ID/timeslots",
    "api_token": "Bearer YOUR_API_TOKEN",
    "param": {
      "starts_at": "%(startTime)sT00:00:00Z",
      "ends_at": "%(endTime)sT23:59:59Z"
    }
  }
}

Make sure to keep your token secure and never expose it in client-side code or public repositories.

Tool: tidycal_check_availability_of_slots

What it does: Fetches available slots between two given times for a specific booking type.

Parameters:

Behavior:

Converts user-supplied startTime and endTime (local dates) into full UTC-ISO datetimes for the query, e.g. YYYY-MM-DDT00:00:00Z and YYYY-MM-DDT23:59:59Z.
Sends a GET request to https://tidycal.com/api/booking-types/{bookingTypeId}/timeslots with query params starts_at and ends_at.

Success Response:

200 OK
JSON with “data” → list of objects, each with fields like starts_at, ends_at, available_bookings.

Errors / Edge Cases:

If bookingType does not exist or isn’t accessible → likely 403 or 404.
If no slots in that period → data may be empty list.

JSON Tool Definition:


{
  "key": "tidycal_check_availability_of_slots",
  "name": "Check TidyCal Availability",
  "description": "Fetches available time slots for a booking type between two given dates.",
  "pre_call_message": "Let me check available slots for you...",
  "parameters": {
    "type": "object",
    "required": ["startTime", "endTime"],
    "properties": {
      "startTime": {
        "type": "string",
        "description": "Start date for checking timeslots in YYYY-MM-DD format. Combined with time (usually UTC midnight) for API."
      },
      "endTime": {
        "type": "string",
        "description": "End date for checking timeslots in YYYY-MM-DD format. Combined with time (UTC) as needed. Usually end of day."
      }
    }
  },
  "value": {
    "method": "GET",
    "url": "https://tidycal.com/api/booking-types/YOUR_BOOKING_TYPE_ID/timeslots",
    "api_token": "Bearer YOUR_API_TOKEN",
    "param": {
      "starts_at": "%(startTime)sT00:00:00Z",
      "ends_at": "%(endTime)sT23:59:59Z"
    }
  }
}

Tool: tidycal_book_appointment

What it does: Creates a booking (reserves a timeslot) for a specified booking type.

Parameters:

Parameter	Type (Format)	Required	Description
preferred_date	string (YYYY-MM-DD)	yes	The date of booking, local time.
preferred_time	string (HH:mm, 24-hr)	yes	The time on that date. Must convert to UTC.
name	string	yes	Name of the person booking.
email	string	yes	Email address.
timezone	string (IANA)	yes	Timezone identifier required for conversion.

Behavior:

Combines preferred_date + preferred_time in the user’s timezone → converts to a UTC ISO datetime string. E.g. 2025-09-17T12:30:00.000000Z.
starts_at (UTC datetime)
name, email
timezone
Optionally booking_questions if the booking type defines questions

Success Response:

HTTP 201 Created
JSON with data field containing the booking details (id, contact_id, booking_type_id, starts_at, ends_at, etc.).

Error / Edge Cases:

403 Forbidden: if token doesn’t have access rights.
409 Conflict: if timeslot is no longer available.
422 Validation Error: malformed input (e.g. invalid email, timezone, or missing required fields).

JSON Tool Definition:


{
  "key": "tidycal_book_appointment",
  "name": "Book TidyCal Appointment",
  "description": "Creates a booking (reserves a timeslot) for a specified booking type.",
  "pre_call_message": "Let me schedule that appointment for you...",
  "parameters": {
    "type": "object",
    "required": ["preferred_date", "preferred_time", "name", "email", "timezone"],
    "properties": {
      "preferred_date": {
        "type": "string",
        "description": "The date of booking in YYYY-MM-DD format (local time)."
      },
      "preferred_time": {
        "type": "string",
        "description": "The time on that date in HH:mm format (24-hour). Must convert to UTC."
      },
      "name": {
        "type": "string",
        "description": "Full name of the person booking the appointment."
      },
      "email": {
        "type": "string",
        "description": "Email address of the person booking."
      },
      "timezone": {
        "type": "string",
        "description": "IANA timezone identifier (e.g., America/Los_Angeles, Europe/London). Needed for UTC conversion."
      }
    }
  },
  "value": {
    "method": "POST",
    "url": "https://tidycal.com/api/booking-types/YOUR_BOOKING_TYPE_ID/bookings",
    "api_token": "Bearer YOUR_API_TOKEN",
    "param": {
      "starts_at": "%(preferred_date)sT%(preferred_time)s:00.000000Z",
      "name": "%(name)s",
      "email": "%(email)s",
      "timezone": "%(timezone)s"
    }
  }
}

Endpoints Used

From the official TidyCal API documentation, these are the relevant endpoints:

Purpose	HTTP Method	Path
List available timeslots for a booking type	GET	`/api/booking-types/{bookingType}/timeslots`
Create a booking	POST	`/api/booking-types/{bookingType}/bookings`

Both endpoints require authentication via the Authorization: Bearer {TOKEN} header.

Usage Examples

Checking availability:


curl --location 'https://tidycal.com/api/booking-types/1367385/timeslots?starts_at=2025-09-17T00:00:00Z&ends_at=2025-09-18T23:59:59Z' \\
  --header 'Accept: application/json' \\
  --header 'Authorization: Bearer YOUR_TOKEN'

Booking an appointment:


curl --location 'https://tidycal.com/api/booking-types/1367385/bookings' \\
  --header 'Content-Type: application/json' \\
  --header 'Accept: application/json' \\
  --header 'Authorization: Bearer YOUR_TOKEN' \\
  --data-raw '{
    "starts_at": "2025-09-17T12:30:00.000000Z",
    "name": "John Doe Dialora Test",
    "email": "john@example.com",
    "timezone": "America/Los_Angeles"
  }'

Best Practices & Notes

Date-Time Format: Make sure all date-time values sent to the API are in UTC, and valid ISO 8601 format. TidyCal expects this.
Timezone Handling: Always include timezone in booking calls so that TidyCal can interpret correctly. Use IANA timezone identifiers (e.g., America/Los_Angeles, Europe/London).
Error Handling: Handle errors properly: conflict (slot already taken), forbidden, validation errors. Always check response status codes and provide meaningful error messages to users.
Availability Checking: For availability checking, use precise start and end datetimes; avoid off-by-one day issues. Always convert local dates to UTC properly.
Security: Always store API tokens securely. Never expose tokens in client-side code, public repositories, or documentation. Use environment variables or secure configuration management practices.
Booking Type ID: Replace YOUR_BOOKING_TYPE_ID in the URLs with your actual TidyCal booking type ID. You can find this in your TidyCal dashboard.