Memberships

On this page, we’ll dive into how to manage memberships within your OneCal Team through the API.

The Membership model

Properties

Name
role
Type
enum
Description
Role of the workspace membership. Possible values: OWNER, MEMBER.
Name
workspaceId
Type
string
Description
Identifier of the workspace associated with the membership.
Name
user
Type
User
Description
The user associated with the workspace membership.
Name
userId
Type
string
Description
Identifier of the user associated with the workspace membership.

The User model

Properties

Name
id
Type
string
Description
Unique identifier for the user.
Name
name
Type
string
Description
Name of the user.
Name
email
Type
string
Description
Email address of the user.
Name
image
Type
string
Description
URL of the user's profile image.
Name
createdAt
Type
timestamp
Description
Timestamp of when the user was created.
Name
updatedAt
Type
timestamp
Description
Timestamp of when the user was last updated.
Name
workspaceId
Type
string
Description
Identifier of the workspace associated with the user.
Name
syncConfigs
Type
array
Description
Array of sync configuration objects associated with the user.
Name
calendars
Type
array
Description
Array of calendar objects associated with the user.

The Calendar model

Properties

Name
id
Type
string
Description
Unique identifier for the calendar.
Name
name
Type
string
Description
Name of the calendar.
Name
email
Type
string
Description
Email address associated with the calendar.
Name
provider
Type
enum
Description
Calendar provider. Possible values: GOOGLE, MICROSOFT.

The SyncConfig model

Properties

Name
id
Type
string
Description
Unique identifier for the sync configuration.
Name
type
Type
enum
Description
Type of the sync configuration. Possible values: ONE_DIRECTIONAL, BI_DIRECTIONAL.
Name
createdAt
Type
timestamp
Description
Timestamp of when the sync configuration was created.
Name
updatedAt
Type
timestamp
Description
Timestamp of when the sync configuration was last updated.
Name
name
Type
string
Description
Name of the sync configuration.
Name
syncTitles
Type
boolean
Description
Flag indicating whether to sync event titles.
Name
syncDescription
Type
boolean
Description
Flag indicating whether to sync event descriptions.
Name
syncAttendees
Type
boolean
Description
Flag indicating whether to sync event attendees.
Name
markPrivate
Type
boolean
Description
Flag indicating whether to mark events as private.
Name
disableReminders
Type
boolean
Description
Flag indicating whether to disable event reminders.
Name
frequency
Type
enum
Description
Frequency of the sync configuration. Possible values: ONE_TIME, ALWAYS.
Name
eventTitles
Type
string
Description
Optional event titles for the sync configuration.
Name
syncWithRSVP
Type
array
Description
Array of RSVP strings to sync with.
Name
syncLocation
Type
boolean
Description
Flag indicating whether to sync event locations.
Name
syncConferenceData
Type
boolean
Description
Flag indicating whether to sync conference data for events.
Name
syncFreeEvents
Type
boolean
Description
Flag indicating whether to sync free events.
Name
eventColorId
Type
EventColorId
Description
Identifier for the event color.
Name
excludeEventColorId
Type
EventColorId
Description
Identifier for the event color to be excluded.
Name
isPaused
Type
boolean
Description
Optional flag indicating whether the sync is paused.
Name
lastEventStatus
Type
enum
Description
Last status of the sync event. Possible values: NOT_STARTED, RUNNING, SUCCESS, DELETE_QUEUED, DELETE_RUNNING, PAUSE_QUEUED, PAUSE_RUNNING, ERROR.
Name
targetCalendars
Type
array
Description
Array of target calendar objects associated with the sync configuration.
Name
userId
Type
string
Description
Identifier of the user associated with the sync configuration.

GET/v1/memberships

This endpoint retrieves a paginated list of all memberships. It returns details about each membership, including the role, workspace ID, user ID, and comprehensive user information such as sync configurations and associated calendars.

Request

GET

/v1/memberships

curl -X GET https://app.onecal.io/api/v1/memberships \
  -H "x-api-key: {apiKey}"

Response

{
  "pageNumber": 1,
  "pageSize": 10,
  "total": 200,
  "data": [
    {
      "role": "MEMBER",
      "workspaceId": "workspaceId",
      "userId": "userId",
      "user": {
        "id": "cuid",
        "name": "John Doe",
        "email": "example@email.com",
        "image": null,
        "createdAt": "2023-09-06T14:29:21.124Z",
        "updatedAt": "2023-09-06T14:29:21.124Z",
        "syncConfigs": [
          {
            "id": "syncConfigId",
            "type": "ONE_DIRECTIONAL",
            "createdAt": "2023-09-06T14:29:21.124Z",
            "updatedAt": "2023-09-06T14:29:21.124Z",
            "name": "Personal -> Work",
            "syncTitles": false,
            "syncDescription": false,
            "syncAttendees": false,
            "markPrivate": true,
            "disableReminders": true,
            "frequency": "ALWAYS",
            "eventTitles": "(Clone)",
            "syncWithRSVP": [
              "accepted",
              "tentative",
              "needsAction",
              "declined"
            ],
            "syncLocation": false,
            "syncConferenceData": false,
            "syncFreeEvents": false,
            "eventColorId": "PALE_BLUE",
            "excludeEventColorId": "RED",
            "isPaused": false,
            "lastEventStatus": "SUCCESS",
            "targetCalendars": [
              {
                "id": "clxnbd3ot000i9k8hoxb18s18",
                "createdAt": "2024-06-20T13:44:32.238Z",
                "updatedAt": "2024-06-20T13:44:32.238Z",
                "syncConfigId": "clxnbd3om000h9k8htcvr0dcm",
                "calendarId": "clxnaztf5000e9k8he1rns64r"
              },
              {
                "id": "clxnbd3ot000j9k8hi33b5244",
                "createdAt": "2024-06-20T13:44:32.238Z",
                "updatedAt": "2024-06-20T13:44:32.238Z",
                "syncConfigId": "clxnbd3om000h9k8htcvr0dcm",
                "calendarId": "clxnaztf5s000f9k8ho22xr5bi"
              }
            ]
          }
        ],
        "calendars": [
          {
            "id": "clxnaztf5000e9k8he1rns64r",
            "name": "Work Calendar",
            "email": "test@gmail.com",
            "provider": "GOOGLE"
          },
          {
            "id": "clxnaztf5s000f9k8ho22xr5bi",
            "name": "Client Calendar",
            "email": "test2@outlook.com",
            "provider": "MICROSOFT"
          }
        ]
      }
    }
  ]
}

POST/v1/memberships/revoke

Revoke a membership

This endpoint revokes a membership. It accepts a request body with either a user ID or an email, and returns a success confirmation upon successful revocation.

Request Body

One of the following properties is required:

Name
userId
Type
string
Description
The unique identifier of the user whose membership is to be revoked.
Name
email
Type
string
Description
The email address of the user whose membership is to be revoked.

Request

POST

/v1/memberships/revoke

curl -X POST https://app.onecal.io/api/v1/memberships/revoke \
  -H "x-api-key: {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "1234"
  }'

Response

{"success": true}

Memberships

The Membership model

Properties

The User model

Properties

The Calendar model

Properties

The SyncConfig model

Properties

List all memberships

Request

Response

Revoke a membership

Request Body

Request

Response