Skip to main content

​
Overview

The Guide Calendar API manages calendar events for guides, including booked tours, blocked time slots, and availability. This helps guides manage their schedule and prevents double-booking.

​
Base URL

/api/guide_calendar_events

​
Create Calendar Event

Add a new event to a guide’s calendar. Events can be booked tours or blocked time slots. 
curl -X POST "https://api.kinconecta.com/api/guide_calendar_events" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "guideProfileId": 123,
    "eventType": "blocked",
    "title": "Personal Time Off",
    "startDateTime": "2024-03-15T09:00:00Z",
    "endDateTime": "2024-03-15T18:00:00Z",
    "description": "Family commitment",
    "isAllDay": false
  }'

​
Request Body

​
guideProfileId
Long
required
ID of the guide profile this event belongs to
​
eventType
String
required
Type of calendar event:
  • booked - Confirmed tour booking
  • blocked - Blocked time slot (unavailable)
  • tentative - Pending booking
​
title
String
required
Event title (e.g., “Tour with John Smith”, “Blocked - Personal”)
​
startDateTime
DateTime
required
Start date and time of the event (ISO 8601 format)
​
endDateTime
DateTime
required
End date and time of the event (ISO 8601 format)
​
description
String
Additional notes or description for the event
​
isAllDay
Boolean
Whether this is an all-day event (default: false)
​
tripBookingId
Long
Associated trip booking ID (for booked events)
​
tourId
Long
Associated tour ID (for booked events)
​
location
String
Meeting location or event location
​
googleEventId
String
Google Calendar event ID if synced with Google Calendar

​
Response

Returns the created calendar event with generated ID. 
{
  "id": 789,
  "guideProfileId": 123,
  "eventType": "blocked",
  "title": "Personal Time Off",
  "startDateTime": "2024-03-15T09:00:00Z",
  "endDateTime": "2024-03-15T18:00:00Z",
  "description": "Family commitment",
  "isAllDay": false,
  "location": null,
  "tripBookingId": null,
  "tourId": null,
  "googleEventId": null,
  "createdAt": "2024-03-10T15:30:00Z",
  "updatedAt": "2024-03-10T15:30:00Z"
}

​
Get All Calendar Events

Retrieve all calendar events for all guides (admin use). 
curl -X GET "https://api.kinconecta.com/api/guide_calendar_events" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Response

Returns an array of all calendar events.
To get events for a specific guide, filter by guideProfileId on the client side or use query parameters if supported.

​
Get Calendar Event by ID

Retrieve a specific calendar event. 
curl -X GET "https://api.kinconecta.com/api/guide_calendar_events/{id}" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Path Parameters

​
id
Long
required
The ID of the calendar event

​
Response

Returns a single calendar event object.

​
Update Calendar Event

Update an existing calendar event. 
curl -X PUT "https://api.kinconecta.com/api/guide_calendar_events/{id}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated: Personal Time Off",
    "endDateTime": "2024-03-15T20:00:00Z"
  }'

​
Path Parameters

​
id
Long
required
The ID of the calendar event to update

​
Request Body

Same fields as create, all optional. Only include fields you want to update.

​
Response

Returns the updated calendar event object.

​
Delete Calendar Event

Remove an event from a guide’s calendar. 
curl -X DELETE "https://api.kinconecta.com/api/guide_calendar_events/{id}" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Path Parameters

​
id
Long
required
The ID of the calendar event to delete

​
Response

Returns 204 No Content on success.
Deleting a booked event does not cancel the associated trip booking. Handle booking cancellations separately through the Trip Bookings API.

​
Event Types

Booked

Confirmed tour bookings automatically create calendar events

Blocked

Time slots when the guide is unavailable (vacation, personal time)

Tentative

Pending bookings or holds while awaiting confirmation

​
Calendar Management Best Practices

1

Block Unavailable Time

Create blocked events for vacations, personal commitments, or days off to prevent booking conflicts.
2

Sync with Google Calendar

Use the googleEventId field to sync events with Google Calendar for unified schedule management.
3

Set Buffer Time

Add buffer time between tours by creating short blocked events to allow for travel and preparation.
4

Regular Updates

Keep your calendar updated to ensure accurate availability for tourists browsing tours.

​
Integration Examples

​
Creating a Blocked Day

// Block an entire day for vacation
const response = await fetch('https://api.kinconecta.com/api/guide_calendar_events', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    guideProfileId: 123,
    eventType: 'blocked',
    title: 'Vacation',
    startDateTime: '2024-04-01T00:00:00Z',
    endDateTime: '2024-04-01T23:59:59Z',
    description: 'Family vacation in Cancún',
    isAllDay: true
  })
});

​
Auto-Creating Event from Booking

// When a tour is booked, automatically create a calendar event
async function createBookingEvent(tripBooking) {
  const response = await fetch('https://api.kinconecta.com/api/guide_calendar_events', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      guideProfileId: tripBooking.guideId,
      eventType: 'booked',
      title: `Tour: ${tripBooking.tourName}`,
      startDateTime: tripBooking.startDateTime,
      endDateTime: tripBooking.endDateTime,
      tripBookingId: tripBooking.id,
      tourId: tripBooking.tourId,
      location: tripBooking.meetingPoint
    })
  });
  return response.json();
}

Build docs developers (and LLMs) love

Get started for freeTalk to us