Calendar Events

Represents an event within a user's Calendar.

The Calendar Event model

Calendar Event Properties

Name
id
Type
string
Description
Unique identifier for the event. Read-Only
Name
title
Type
string
Description
Title or summary of the event.
Name
description
Type
string
Description
Detailed description or notes about the event.
Name
etag
Type
string
Description
ETag of the event for version control. Read-Only
Name
createdAt
Type
string
Description
ISO 8601 date-time when the event was created. Read-Only
Name
updatedAt
Type
string
Description
ISO 8601 date-time when the event was last updated. Read-Only
Name
start
Type
EventDateTime
Description
Start date and time of the event.
Name
end
Type
EventDateTime
Description
End date and time of the event.
Name
isAllDay
Type
boolean
Description
Indicates whether the event lasts all day.
Name
publicExtendedProperties
Type
object
Description
Custom key-value properties visible to others.
Name
privateExtendedProperties
Type
object
Description
Custom key-value properties visible only to the authenticated user.
Name
isRecurring
Type
boolean
Description
Indicates whether the event is part of a recurring series.
Name
isException
Type
boolean
Description
Indicates whether the event is an exception in a recurring series.
Name
isCancelled
Type
boolean
Description
Indicates whether the event has been canceled.
Name
recurrence
Type
string[] | null
Description
Recurrence rules describing how often the event repeats.
Name
originalStart
Type
EventDateTime
Description
Original start date and time of the event before modification.
Name
recurringEventId
Type
string
Description
ID of the recurring event this instance belongs to.
Name
colorId
Type
string
Description
ID representing the event color.
Name
customColor
Type
string
Description
Custom color code applied to this event.
Name
myResponseStatus
Type
enum
Description
The user's response to the event invitation. Possible values: needsAction, declined, tentative, accepted.
Name
attendees
Type
EventAttendee[]
Description
List of attendees invited to the event.
Name
visibility
Type
enum
Description
Visibility level of the event. Possible values: default, public, private, confidential.
Name
location
Type
string
Description
Physical or virtual location of the event.
Name
conferenceData
Type
object
Description
Information about an associated conference meeting, if any.
Name
webLink
Type
string
Description
URL link to view the event in a calendar interface.
Name
iCalUid
Type
string
Description
iCalendar UID for cross-system identification. Read-Only
Name
transparency
Type
enum
Description
Indicates whether the event blocks time on the calendar. Possible values: transparent, opaque.
Name
eventType
Type
enum
Description
Type of the event. Possible values: default, outOfOffice, focusTime.
Name
organizer
Type
object
Description
Information about the organizer of the event.
Name
creator
Type
object
Description
Information about the creator of the event.
Name
reminders
Type
object
Description
Reminder settings associated with the event.
Name
generateMeetingUrlProvider
Type
string
Description
Provider used to automatically generate a meeting URL.

EventDateTime Properties

Name
dateTime
Type
string
Description
The date and time in ISO 8601 format (e.g., "2025-10-08T10:00:00Z").
Name
timeZone
Type
string
Description
The time zone associated with this date and time.

EventAttendee Properties

Name
id
Type
string
Description
Unique identifier of the attendee.
Name
name
Type
string
Description
Full name of the attendee.
Name
email
Type
string
Description
Email address of the attendee.
Name
responseStatus
Type
enum
Description
The attendee’s response to the invitation. Possible values: needsAction, declined, tentative, accepted.

GET/v1/events/:endUserAccountId/:calendarId

List Calendar Events

This endpoint retrieves a paginated list of all Events associated with this Calendar.

Path parameters

Name
endUserAccountId
Type
string
Description
The unique identifier of the End User Account to retrieve.
Name
calendarId
Type
string
Description
The unique identifier of the Calendar to retrieve.

Optional query parameters

Name
syncToken
Type
string
Description
Token used at a later point in time to retrieve only the entries that have changed since this result was returned. Omitted if further results are available, in which case nextPageToken is provided.
Name
startDateTime
Type
string
Description
ISO 8601 date-time to filter events that start after this time.
Name
endDateTime
Type
string
Description
ISO 8601 date-time to filter events that end before this time.
Name
timeZone
Type
string
Description
Display all events in the specified time zone.
Name
metadataFilters
Type
string
Description
JSON object to filter events by custom properties.
Name
expandRecurrences
Type
boolean
Description
Whether to expand the recurrence of recurring events into individual events. If provided, startDateTime and endDateTime are required. By default recurring events are not expanded.
Name
search
Type
string
Description
Search for events by title.
Name
orderBy
Type
string
Description
Field to order events by. If not provided, events should be considered unordered. Only available when expandRecurrences is true.

Request

GET

/v1/events/:endUserAccountId/:calendarId

curl -X GET https://api.onecalunified.com/api/v1/events/:endUserAccountId/:calendarId \
  -H "x-api-key: {apiKey}"

Response

{
  "data": [
    {
      "id": "2o2k8s5n5edbhr0imlbq7g0vcm",
      "title": "Single event",
      "etag": "\"3371613172716000\"",
      "createdAt": "2023-06-03T15:36:26.000Z",
      "updatedAt": "2023-06-03T15:36:26.358Z",
      "start": {
        "dateTime": "2023-06-03T14:00:00+02:00",
        "timeZone": "Europe/Tirane"
      },
      "end": {
        "dateTime": "2023-06-03T14:45:00+02:00",
        "timeZone": "Europe/Tirane"
      },
      "isAllDay": false,
      "isRecurring": false,
      "isException": false,
      "isCancelled": false,
      "recurrence": null,
      "webLink": "",
      "iCalUid": "2o2k8s5n5edbhr0imlbq7g0vcm@google.com",
      "eventType": "default",
      "organizer": {
        "name": "John Doe",
        "email": "dc4phg9nsqnf2k5t6dfbja0gasd@group.calendar.google.com",
        "isSelf": true
      },
      "creator": {
        "email": "email@example.com"
      },
      "reminders": {
        "useDefault": true
      }
    },
    {
      "id": "pgbc860pnot5ana7b2v81kllu4",
      "title": "Recurring Event",
      "etag": "\"3436089210232000\"",
      "createdAt": "2024-06-10T15:38:55.000Z",
      "updatedAt": "2024-06-10T18:36:45.116Z",
      "start": {
        "dateTime": "2024-06-17T13:00:00+02:00",
        "timeZone": "Europe/Tirane"
      },
      "end": {
        "dateTime": "2024-06-17T14:00:00+02:00",
        "timeZone": "Europe/Tirane"
      },
      "isAllDay": false,
      "isRecurring": true,
      "isException": false,
      "isCancelled": false,
      "recurrence": ["RRULE:FREQ=DAILY;UNTIL=20240618T215959Z"],
      "webLink": "",
      "iCalUid": "pgbc860pnot5ana7b2v81kllu4@google.com",
      "eventType": "default",
      "organizer": {
        "name": "John Doe",
        "email": "dc4phg9nsqnf2k5t6dfbja0gasd@group.calendar.google.com",
        "isSelf": true
      },
      "creator": {
        "email": "email@example.com"
      },
      "reminders": {
        "useDefault": true
      }
    },
    {
      "id": "dgqjvmekl5n95lc02m2trc1uio",
      "title": "Single event with conference",
      "description": "",
      "etag": "\"3483421282293406\"",
      "createdAt": "2025-03-11T16:30:40.000Z",
      "updatedAt": "2025-03-11T16:30:41.146Z",
      "start": {
        "dateTime": "2025-03-18T14:00:00+01:00",
        "timeZone": "Europe/Tirane"
      },
      "end": {
        "dateTime": "2025-03-18T14:30:00+01:00",
        "timeZone": "Europe/Tirane"
      },
      "isAllDay": false,
      "isRecurring": false,
      "isException": false,
      "isCancelled": false,
      "recurrence": null,
      "myResponseStatus": "accepted",
      "attendees": [
        {
          "name": "John Doe",
          "email": "dc4phg9nsqnf2k5t6dfbja0gasd@group.calendar.google.com",
          "responseStatus": "accepted"
        },
        {
          "name": "Jane Doe",
          "email": "email@example.com",
          "responseStatus": "accepted"
        }
      ],
      "webLink": "",
      "iCalUid": "dgqjvmekl5n95lc02m2trc1uio@google.com",
      "eventType": "default",
      "organizer": {
        "name": "John Doe",
        "email": "dc4phg9nsqnf2k5t6dfbja0gasd@group.calendar.google.com",
        "isSelf": true
      },
      "creator": {
        "email": "email@example.com"
      },
      "reminders": {
        "useDefault": true
      },
      "conferenceData": {
        "conferenceId": "tvw-eiaa-uuk",
        "conferenceType": "Google Meet",
        "joinUrl": "https://meet.google.com/gvw-ciaa-uud",
        "conferenceDetails": {
          "createRequest": {
            "requestId": "1502701f-970b-4bf6-8252-16243e822070",
            "conferenceSolutionKey": {
              "type": "hangoutsMeet"
            },
            "status": {
              "statusCode": "success"
            }
          },
          "entryPoints": [
            {
              "entryPointType": "video",
              "uri": "https://meet.google.com/gvw-ciaa-uud",
              "label": "meet.google.com/gvw-ciaa-uud"
            }
          ],
          "conferenceSolution": {
            "key": {
              "type": "hangoutsMeet"
            },
            "name": "Google Meet",
            "iconUri": "https://fonts.gstatic.com/s/i/productlogos/meet_2020q4/v6/web-512dp/logo_meet_2020q4_color_2x_web_512dp.png"
          },
          "conferenceId": "tvw-eiaa-uuk"
        }
      }
    },
    {
      "id": "7g1n8otm00cthuu0d5p6m2dovk",
      "title": "All day event",
      "etag": "\"3504482532412158\"",
      "createdAt": "2025-07-11T13:41:06.000Z",
      "updatedAt": "2025-07-11T13:41:06.206Z",
      "start": {
        "dateTime": "2025-07-11T00:00:00",
        "timeZone": "Etc/UTC"
      },
      "end": {
        "dateTime": "2025-07-13T00:00:00",
        "timeZone": "Etc/UTC"
      },
      "isAllDay": true,
      "isRecurring": false,
      "isException": false,
      "isCancelled": false,
      "recurrence": null,
      "webLink": "",
      "iCalUid": "7g1n8otm00cthuu0d5p6m2dovk@google.com",
      "transparency": "transparent",
      "eventType": "default",
      "organizer": {
        "name": "John Doe",
        "email": "dc4phg9nsqnf2k5t6dfbja0gasd@group.calendar.google.com",
        "isSelf": true
      },
      "creator": {
        "email": "email@example.com"
      },
      "reminders": {
        "useDefault": false
      }
    },

    {
      "id": "4t2rmfbo4ohlla0jj9vjlhfrv3",
      "title": "Recurring Event With Exception",
      "etag": "\"3510023641690558\"",
      "createdAt": "2025-08-12T15:16:48.000Z",
      "updatedAt": "2025-08-12T15:17:00.845Z",
      "start": {
        "dateTime": "2025-08-13T00:00:00",
        "timeZone": "Etc/UTC"
      },
      "end": {
        "dateTime": "2025-08-14T00:00:00",
        "timeZone": "Etc/UTC"
      },
      "isAllDay": true,
      "isRecurring": true,
      "isException": false,
      "isCancelled": false,
      "recurrence": ["RRULE:FREQ=WEEKLY;BYDAY=WE"],
      "webLink": "",
      "iCalUid": "4t2rmfbo4ohlla0jj9vjlhfrv3@google.com",
      "transparency": "transparent",
      "eventType": "default",
      "organizer": {
        "name": "John Doe",
        "email": "dc4phg9nsqnf2k5t6dfbja0gasd@group.calendar.google.com",
        "isSelf": true
      },
      "creator": {
        "email": "email@example.com"
      },
      "reminders": {
        "useDefault": false
      }
    },
    {
      "id": "4t2rmfbo4ohlla0jj9vjlhfrv3_20250820",
      "title": "Recurring Event With Exception",
      "etag": "\"3515209422311486\"",
      "createdAt": "2025-08-12T15:16:48.000Z",
      "updatedAt": "2025-09-11T15:31:51.155Z",
      "start": {
        "dateTime": "2025-08-20T00:00:00",
        "timeZone": "Etc/UTC"
      },
      "end": {
        "dateTime": "2025-08-21T00:00:00",
        "timeZone": "Etc/UTC"
      },
      "isAllDay": true,
      "isRecurring": false,
      "isException": true,
      "isCancelled": true,
      "recurrence": null,
      "originalStart": {
        "date": "2025-08-20"
      },
      "recurringEventId": "4t2rmfbo4ohlla0jj9vjlhfrv3",
      "webLink": "",
      "iCalUid": "4t2rmfbo4ohlla0jj9vjlhfrv3@google.com",
      "transparency": "transparent",
      "eventType": "default",
      "organizer": {
        "name": "John Doe",
        "email": "dc4phg9nsqnf2k5t6dfbja0gasd@group.calendar.google.com",
        "isSelf": true
      },
      "creator": {
        "email": "email@example.com"
      },
      "reminders": {
        "useDefault": false
      }
    }
  ],
  "nextSyncToken": "CM_Ow7v35I8DEM_Ow7v35I8DGAUgx7T7hAMox7T7hAM="
}

GET/v1/events/:endUserAccountId/:calendarId/:eventId

Get Calendar Event

This endpoint returns the details of a specific Calendar Event.

Path parameters

Name
endUserAccountId
Type
string
Description
The unique identifier of the End User Account to retrieve.
Name
calendarId
Type
string
Description
The unique identifier of the Calendar to retrieve.
Name
eventId
Type
string
Description
The unique identifier of the Event to retrieve.

Request

GET

/v1/events/:endUserAccountId/:calendarId/:eventId

curl -X GET https://api.onecalunified.com/api/v1/events/:endUserAccountId/:calendarId/:eventId \
  -H "x-api-key: {apiKey}"

Response

{
  "id": "4t2rmfbo4ohlla0jj9vjlhfrv3",
  "title": "Recurring Event",
  "etag": "\"3510023641690558\"",
  "createdAt": "2025-08-12T15:16:48.000Z",
  "updatedAt": "2025-08-12T15:17:00.845Z",
  "start": {
    "dateTime": "2025-08-13T00:00:00",
    "timeZone": "Etc/UTC"
  },
  "end": {
    "dateTime": "2025-08-14T00:00:00",
    "timeZone": "Etc/UTC"
  },
  "isAllDay": true,
  "isRecurring": true,
  "isException": false,
  "isCancelled": false,
  "recurrence": ["RRULE:FREQ=WEEKLY;BYDAY=WE"],
  "webLink": "https://www.google.com/calendar/event?eid=1234567890",
  "iCalUid": "4t2rmfbo4ohlla0jj9vjlhfrv3@google.com",
  "transparency": "transparent",
  "eventType": "default",
  "organizer": {
    "name": "Organizer",
    "email": "ddc4phg9nsqnf2k5t6dfbja0@group.calendar.google.com",
    "isSelf": true
  },
  "creator": {
    "email": "creator@example.com"
  },
  "reminders": {
    "useDefault": false
  }
}

GET/v1/events/:endUserAccountId/:calendarId/:eventId/occurrences

Get Calendar Event Occurrences

This endpoint returns the individual occurrences of a recurring event. It behaves similarly to the Get Calendar Events endpoint with the expandRecurrences query parameter set to true, but for a single event.

Path parameters

Name
endUserAccountId
Type
string
Description
The unique identifier of the End User Account to retrieve.
Name
calendarId
Type
string
Description
The unique identifier of the Calendar to retrieve.
Name
eventId
Type
string
Description
The unique identifier of the Event to retrieve.

Query Parameters

Name
syncToken
Type
string
Description
Token used at a later point in time to retrieve only the entries that have changed since this result was returned. Omitted if further results are available, in which case nextPageToken is provided.
Name
startDateTime
Type
string
Description
ISO 8601 date-time to filter events that start after this time. (Required)
Name
endDateTime
Type
string
Description
ISO 8601 date-time to filter events that end before this time. (Required)
Name
timeZone
Type
string
Description
Display all events in the specified time zone.
Name
metadataFilters
Type
string
Description
JSON object to filter events by custom properties.
Name
search
Type
string
Description
Search for events by title.
Name
orderBy
Type
string
Description
Field to order events by. If not provided, events should be considered unordered.

Request

GET

/v1/events/:endUserAccountId/:calendarId/:eventId/occurrences

curl -X GET https://api.onecalunified.com/api/v1/events/:endUserAccountId/:calendarId/:eventId/occurrences?startDateTime=2025-08-13T00:00:00&endDateTime=2025-08-14T00:00:00 \
  -H "x-api-key: {apiKey}"

Response

{
  "data": [
    {
      "id": "4t2rmfbo4ohlla0jj9vjlhfrv3_20250813",
      "title": "Recurring Event",
      "etag": "\"3510023641690558\"",
      "createdAt": "2025-08-12T15:16:48.000Z",
      "updatedAt": "2025-08-12T15:17:00.845Z",
      "start": {
        "dateTime": "2025-08-13T00:00:00",
        "timeZone": "Etc/UTC"
      },
      "end": {
        "dateTime": "2025-08-14T00:00:00",
        "timeZone": "Etc/UTC"
      },
      "isAllDay": true,
      "isRecurring": false,
      "isException": true,
      "isCancelled": false,
      "recurrence": null,
      "originalStart": {
        "date": "2025-08-13"
      },
      "recurringEventId": "4t2rmfbo4ohlla0jj9vjlhfrv3",
      "webLink": "",
      "iCalUid": "4t2rmfbo4ohlla0jj9vjlhfrv3@google.com",
      "transparency": "transparent",
      "eventType": "default",
      "organizer": {
        "name": "Organizer",
        "email": "ddc4phg9nsqnf2k5t6dfbja0@group.calendar.google.com",
        "isSelf": true
      },
      "creator": {
        "email": "creator@example.com"
      },
      "reminders": {
        "useDefault": false
      }
    }
  ],
  "nextSyncToken": "CM_equb3lJADEM_equb3lJADGAUgx7T7hAMox7T7hAM="
}

POST/v1/events/:endUserAccountId/:calendarId

Create a new Calendar Event

Creates a new Calendar Event in the specified Calendar.

Request body

This endpoint accepts the same properties as the Calendar Event model except the properties marked as Read-Only. title and start are required.

Request

POST

/v1/events/:endUserAccountId/:calendarId

curl https://api.onecalunified.com/api/v1/events/:endUserAccountId/:calendarId \
  -H "x-api-key: {apiKey}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"title": "Created from API","start": {"dateTime": "2025-08-13T00:00:00", "timeZone": "Etc/UTC"},"end": {"dateTime": "2025-08-14T00:00:00", "timeZone": "Etc/UTC"}}'

Response

{
  "id": "kv8tte1cge479ivm113i66bsjg",
  "title": "Created from API",
  "etag": "\"3519875915275934\"",
  "createdAt": "2025-10-08T15:39:17.000Z",
  "updatedAt": "2025-10-08T15:39:17.637Z",
  "start": {
    "dateTime": "2025-08-13T02:00:00+02:00",
    "timeZone": "Etc/UTC"
  },
  "end": {
    "dateTime": "2025-08-14T02:00:00+02:00",
    "timeZone": "Etc/UTC"
  },
  "isAllDay": false,
  "isRecurring": false,
  "isException": false,
  "isCancelled": false,
  "recurrence": null,
  "webLink": "https://www.google.com/calendar/event?eid=1234567890",
  "iCalUid": "kv8tte1cge479ivm113i66bsjg@google.com",
  "eventType": "default",
  "organizer": {
    "name": "Organizer",
    "email": "ddc4phg9nsqnf2k5t6dfbja0@group.calendar.google.com",
    "isSelf": true
  },
  "creator": {
    "email": "creator@example.com"
  },
  "reminders": {
    "useDefault": true
  }
}

PUT/v1/events/:endUserAccountId/:calendarId/:eventId

Update a Calendar Event

Updates an existing Calendar Event in the specified Calendar.

Request body

This endpoint accepts the same properties as the Calendar Event model except the properties marked as Read-Only. You only need to provide the properties you want to update.

Request

PUT

/v1/events/:endUserAccountId/:calendarId/:eventId

curl https://api.onecalunified.com/api/v1/events/:endUserAccountId/:calendarId/:eventId \
  -H "x-api-key: {apiKey}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{"title": "Updated Title"}'

Response

{
  "id": "kv8tte1cge479ivm113i66bsjg",
  "title": "Updated Title",
  "etag": "\"3519875915275934\"",
  "createdAt": "2025-10-08T15:39:17.000Z",
  "updatedAt": "2025-10-08T15:39:17.637Z",
  "start": {
    "dateTime": "2025-08-13T02:00:00+02:00",
    "timeZone": "Etc/UTC"
  },
  "end": {
    "dateTime": "2025-08-14T02:00:00+02:00",
    "timeZone": "Etc/UTC"
  },
  "isAllDay": false,
  "isRecurring": false,
  "isException": false,
  "isCancelled": false,
  "recurrence": null,
  "webLink": "https://www.google.com/calendar/event?eid=1234567890",
  "iCalUid": "kv8tte1cge479ivm113i66bsjg@google.com",
  "eventType": "default",
  "organizer": {
    "name": "Organizer",
    "email": "ddc4phg9nsqnf2k5t6dfbja0@group.calendar.google.com",
    "isSelf": true
  },
  "creator": {
    "email": "creator@example.com"
  },
  "reminders": {
    "useDefault": true
  }
}

POST/v1/events/:endUserAccountId/:calendarId/:eventId/rsvp

Update a Calendar Event RSVP

Updates the RSVP status of an attendee for a specific Calendar Event.

Request body

This endpoint accepts an array of EventAttendee objects.

Request

POST

/v1/events/:endUserAccountId/:calendarId/:eventId/rsvp

curl https://api.onecalunified.com/api/v1/events/:endUserAccountId/:calendarId/:eventId/rsvp \
  -H "x-api-key: {apiKey}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '[{"email": "attendee@example.com", "responseStatus": "accepted", "name": "Jane Doe" }]'

Response

{
  "id": "kv8tte1cge479ivm113i66bsjg",
  "title": "Updated Title",
  "etag": "\"3519875915275934\"",
  "createdAt": "2025-10-08T15:39:17.000Z",
  "updatedAt": "2025-10-08T15:39:17.637Z",
  "start": {
    "dateTime": "2025-08-13T02:00:00+02:00",
    "timeZone": "Etc/UTC"
  },
  "end": {
    "dateTime": "2025-08-14T02:00:00+02:00",
    "timeZone": "Etc/UTC"
  },
  "isAllDay": false,
  "isRecurring": false,
  "isException": false,
  "isCancelled": false,
  "recurrence": null,
  "webLink": "https://www.google.com/calendar/event?eid=1234567890",
  "iCalUid": "kv8tte1cge479ivm113i66bsjg@google.com",
  "eventType": "default",
  "organizer": {
    "name": "Organizer",
    "email": "ddc4phg9nsqnf2k5t6dfbja0@group.calendar.google.com",
    "isSelf": true
  },
  "creator": {
    "email": "creator@example.com"
  },
  "attendees": [
    {
      "name": "John Doe",
      "email": "dc4phg9nsqnf2k5t6dfbja0gasd@group.calendar.google.com",
      "responseStatus": "accepted"
    },
    {
      "name": "Jane Doe",
      "email": "attendee@example.com",
      "responseStatus": "accepted"
    }
  ],
  "reminders": {
    "useDefault": true
  }
}

DELETE/v1/events/:endUserAccountId/:calendarId/:eventId

Delete a Calendar Event

Deletes an existing Calendar Event in the specified Calendar.

Request

DELETE

/v1/events/:endUserAccountId/:calendarId/:eventId

curl https://api.onecalunified.com/api/v1/events/:endUserAccountId/:calendarId/:eventId \
  -H "x-api-key: {apiKey}" \
  -X DELETE

Response

{
  "success": true
}