VardaCal VardaCal Developer API

Bookings API

Manage scheduling appointments and bookings through the VardaCal API.

GET /api/v1/bookings
Requires authentication

Retrieve a list of bookings for the authenticated user

Query Parameters

Parameter Type Description
status string Filter by status: confirmed, cancelled, pending
from datetime Start date for filtering bookings
to datetime End date for filtering bookings
page integer Page number for pagination (default: 1)
per_page integer Items per page (default: 25, max: 100)

Example Request

curl -X GET "https://api.vardacal.com/api/v1/bookings?status=confirmed&from=2025-01-01" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Example Response

{
  "data": [
    {
      "id": "book_123abc",
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "event_type": {
        "id": "evt_456def",
        "name": "30-minute Consultation",
        "duration": 30
      },
      "host": {
        "id": "usr_789ghi",
        "name": "John Doe",
        "email": "john@example.com"
      },
      "guest_name": "Jane Smith",
      "guest_email": "jane@example.com",
      "starts_at": "2025-02-01T10:00:00Z",
      "ends_at": "2025-02-01T10:30:00Z",
      "status": "confirmed",
      "location": {
        "type": "zoom",
        "details": "Zoom link will be sent"
      },
      "created_at": "2025-01-28T09:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 123,
    "per_page": 25
  }
}
POST /api/v1/users/:username/book
Public endpoint

Create a new booking for a specific user's event type

Request Body

{
  "event_type_slug": "consultation-30min",
  "starts_at": "2025-02-01T10:00:00Z",
  "guest_name": "Jane Smith",
  "guest_email": "jane@example.com",
  "timezone": "America/New_York",
  "notes": "Looking forward to our meeting",
  "answers": {
    "company": "Acme Corp",
    "purpose": "Discuss integration options"
  }
}

Response

{
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "confirmation_url": "https://vardacal.com/booking/550e8400-e29b-41d4-a716-446655440000",
    "starts_at": "2025-02-01T10:00:00Z",
    "ends_at": "2025-02-01T10:30:00Z",
    "status": "confirmed"
  },
  "message": "Booking confirmed successfully"
}
POST /api/v1/booking/:uuid/cancel
Public endpoint

Cancel an existing booking

Request Body

{
  "reason": "Schedule conflict"
}

Response

{
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "status": "cancelled",
    "cancelled_at": "2025-01-28T10:30:00Z"
  },
  "message": "Booking cancelled successfully"
}