Invites

Groups are where communities live in Protocol — they are a collection of contacts you're talking to all at once. On this page, we'll dive into the different group endpoints you can use to manage groups programmatically. We'll look at how to query, create, update, and delete groups.

The Invite model

Properties

Name
id
Type
string
Description
Unique identifier for the invite.
Name
receiverEmail
Type
string
Description
Email address of the invite recipient.
Name
receiverFullName
Type
string
Description
Full name of the invite recipient.
Name
expiresAt
Type
timestamp
Description
Date and time when the invite expires.
Name
createdAt
Type
timestamp
Description
Timestamp of when the invite was created.
Name
updatedAt
Type
timestamp
Description
Timestamp of when the invite was last updated.
Name
status
Type
enum
Description
Status of the invite. Possible values: PENDING, ACCEPTED, CANCELLED, DECLINED.
Name
inviterId
Type
string
Description
Identifier of the user who sent the invite.
Name
workspaceId
Type
string
Description
Identifier of the workspace associated with the invite.

GET/v1/invites

List all invites

This endpoint retrieves a paginated list of all invites. It returns details about each invite, including the recipient’s email, full name, expiration date, status, and related IDs. By default, the endpoint shows a fixed number of invites per page.

Optional query parameters

Name
status
Type
enum
Description
Filter invites by status. Possible values: PENDING, ACCEPTED, CANCELLED, DECLINED.

Request

GET

/v1/invites

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

Response

{
  "pageNumber": 1,
  "pageSize": 10,
  "total": 200,
  "data": [
    {
      "id": "cuid",
      "receiverEmail": "example@email.com",
      "receiverFullName": "John Doe",
      "expiresAt": "2023-10-06T14:29:21.124Z",
      "createdAt": "2023-09-06T14:29:21.124Z",
      "updatedAt": "2023-09-06T14:29:21.124Z",
      "status": "PENDING",
      "inviterId": "userid",
      "workspaceId": "workspaceid"
    }
  ]
}

POST/v1/invites/create

Send a new Invite

This endpoint allows you to send a new invite to join your workspace to an email address. The address can be either an existing OneCal user or not. If the address is already registered, the user must be either on a Free plan or have a cancelled subscription.

Request body

Name
receiverEmail
Type
string
Description
The email address of the user you want to invite.
Name
receiverFullName
Type
string
Description
The full name of the user you want to invite.
Name
role
Type
enum
Description
The role of the user you want to invite. Possible values: MEMBER.

Request

POST

/v1/invites/create

curl https://app.onecal.io/api/v1/invites/create \
  -H "x-api-key: {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{"receiverEmail": "example@email.com", "receiverFullName": "John Doe", "role": "MEMBER"}'

Response

{
  "id": "cuid",
  "receiverEmail": "example@email.com",
  "receiverFullName": "John Doe",
  "expiresAt": "2023-10-06T14:29:21.124Z",
  "createdAt": "2023-09-06T14:29:21.124Z",
  "updatedAt": "2023-09-06T14:29:21.124Z",
  "status": "PENDING",
  "inviterId": "userid",
  "workspaceId": "workspaceid"
}

POST/v1/invites/cancel

Cancel an invite

This endpoint cancels an existing invite. It accepts a request body with either an invite ID or an email, and returns the updated invite details with its status set to CANCELLED.

Request Body

One of the following properties is required:

Name
inviteId
Type
string
Description
The unique identifier of the invite to be cancelled.
Name
email
Type
string
Description
The email of the recipient whose invite is to be cancelled.

Request

POST

/v1/invites/cancel

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

Response

{
  "id": "cuid",
  "receiverEmail": "example@email.com",
  "receiverFullName": "John Doe",
  "expiresAt": "2023-10-06T14:29:21.124Z",
  "createdAt": "2023-09-06T14:29:21.124Z",
  "updatedAt": "2023-09-06T14:29:21.124Z",
  "status": "CANCELLED",
  "inviterId": "userid",
  "workspaceId": "workspaceid"
}