Teams

Manage teams and team memberships through the Cal.com API

The Teams API allows you to create, retrieve, update, and delete teams, as well as manage team memberships.

API Version

Team endpoints are available across all API versions:

cal-api-version: 2024-08-13

Authentication

All team endpoints require authentication:

• API Key: Pass via Authorization: Bearer <api-key> header
• Access Token: OAuth access token

Create a Team

Create a new team.

cURL

curl --request POST \
  --url https://api.cal.com/v2/teams \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Engineering Team",
    "slug": "engineering"
  }'

Request Body

name · string · required

Team name

slug · string · required

URL-friendly team slug (must be unique)

logo · string

Team logo URL

bio · string

Team description

Response

status · string

Status of the response (“success”)

data · object

Team details or payment information (if payment required)

Show child attributes

id · number

Team ID

name · string

Team name

slug · string

Team slug

pendingTeam · object

Pending team object (if payment required)

paymentLink · string

Payment link (if payment required)

message · string

Payment message (if payment required)

Example Response

{
  "status": "success",
  "data": {
    "id": 123,
    "name": "Engineering Team",
    "slug": "engineering"
  }
}

Get a Team

Retrieve a specific team by ID.

cURL

curl --request GET \
  --url https://api.cal.com/v2/teams/{teamId} \
  --header 'Authorization: Bearer <api-key>'

Path Parameters

teamId · number · required

The ID of the team to retrieve

Authorization

Requires TEAM_MEMBER role (any team member can view team details).

Get All Teams

List all teams the authenticated user belongs to.

cURL

curl --request GET \
  --url https://api.cal.com/v2/teams \
  --header 'Authorization: Bearer <api-key>'

Response

Returns an array of team objects.

{
  "status": "success",
  "data": [
    {
      "id": 123,
      "name": "Engineering Team",
      "slug": "engineering"
    },
    {
      "id": 456,
      "name": "Sales Team",
      "slug": "sales"
    }
  ]
}

Update a Team

Update team information.

cURL

curl --request PATCH \
  --url https://api.cal.com/v2/teams/{teamId} \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Engineering & DevOps",
    "bio": "Engineering and DevOps team"
  }'

Path Parameters

teamId · number · required

The ID of the team to update

Request Body

name · string

Team name

slug · string

Team slug

logo · string

Team logo URL

bio · string

Team description

Authorization

Requires TEAM_OWNER role.

Delete a Team

Delete a team.

cURL

curl --request DELETE \
  --url https://api.cal.com/v2/teams/{teamId} \
  --header 'Authorization: Bearer <api-key>'

Path Parameters

teamId · number · required

The ID of the team to delete

Authorization

Requires TEAM_OWNER role.

Rate Limiting

This endpoint is throttled to 1 request per second per user.

Team Resources

Teams can have associated resources:

Team Event Types

Create and manage event types for the entire team.

GET /v2/teams/{teamId}/event-types
POST /v2/teams/{teamId}/event-types

Team Bookings

Manage bookings for team event types.

GET /v2/teams/{teamId}/bookings

Team Schedules

Manage team-level schedules.

GET /v2/teams/{teamId}/schedules
POST /v2/teams/{teamId}/schedules

Team Memberships

Manage team members and their roles.

GET /v2/teams/{teamId}/memberships
POST /v2/teams/{teamId}/memberships
DELETE /v2/teams/{teamId}/memberships/{membershipId}

Team Invitations

Invite users to join your team.

POST /v2/teams/{teamId}/invite

Team Roles

Teams support the following roles:

• TEAM_OWNER: Full access to team settings, can add/remove members, delete team
• TEAM_ADMIN: Can manage team event types and bookings
• TEAM_MEMBER: Can view team information and use team event types

Notes

• Team slugs must be unique across the platform
• Only team owners can update or delete teams
• Deleting a team is permanent and will affect all team event types and bookings
• Some team features may require payment depending on your plan
• Team members inherit access to team event types based on their role