Skip to main content
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 --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)
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)

​
Example Response

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

​
Get a Team

Retrieve a specific team by ID. 
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 --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 --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 --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

Build docs developers (and LLMs) love

Get started for freeTalk to us