> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/calcom/cal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

### Request Body

<ParamField body="name" type="string" required>
  Team name
</ParamField>

<ParamField body="slug" type="string" required>
  URL-friendly team slug (must be unique)
</ParamField>

<ParamField body="logo" type="string">
  Team logo URL
</ParamField>

<ParamField body="bio" type="string">
  Team description
</ParamField>

### Response

<ResponseField name="status" type="string">
  Status of the response ("success")
</ResponseField>

<ResponseField name="data" type="object">
  Team details or payment information (if payment required)

  <Expandable>
    <ResponseField name="id" type="number">
      Team ID
    </ResponseField>

    <ResponseField name="name" type="string">
      Team name
    </ResponseField>

    <ResponseField name="slug" type="string">
      Team slug
    </ResponseField>

    <ResponseField name="pendingTeam" type="object">
      Pending team object (if payment required)
    </ResponseField>

    <ResponseField name="paymentLink" type="string">
      Payment link (if payment required)
    </ResponseField>

    <ResponseField name="message" type="string">
      Payment message (if payment required)
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Response

```json theme={null}
{
  "status": "success",
  "data": {
    "id": 123,
    "name": "Engineering Team",
    "slug": "engineering"
  }
}
```

## Get a Team

Retrieve a specific team by ID.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.cal.com/v2/teams/{teamId} \
    --header 'Authorization: Bearer <api-key>'
  ```
</CodeGroup>

### Path Parameters

<ParamField path="teamId" type="number" required>
  The ID of the team to retrieve
</ParamField>

### Authorization

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

## Get All Teams

List all teams the authenticated user belongs to.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.cal.com/v2/teams \
    --header 'Authorization: Bearer <api-key>'
  ```
</CodeGroup>

### Response

Returns an array of team objects.

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

## Update a Team

Update team information.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

### Path Parameters

<ParamField path="teamId" type="number" required>
  The ID of the team to update
</ParamField>

### Request Body

<ParamField body="name" type="string">
  Team name
</ParamField>

<ParamField body="slug" type="string">
  Team slug
</ParamField>

<ParamField body="logo" type="string">
  Team logo URL
</ParamField>

<ParamField body="bio" type="string">
  Team description
</ParamField>

### Authorization

Requires `TEAM_OWNER` role.

## Delete a Team

Delete a team.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url https://api.cal.com/v2/teams/{teamId} \
    --header 'Authorization: Bearer <api-key>'
  ```
</CodeGroup>

### Path Parameters

<ParamField path="teamId" type="number" required>
  The ID of the team to delete
</ParamField>

### 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.

```bash theme={null}
GET /v2/teams/{teamId}/event-types
POST /v2/teams/{teamId}/event-types
```

### Team Bookings

Manage bookings for team event types.

```bash theme={null}
GET /v2/teams/{teamId}/bookings
```

### Team Schedules

Manage team-level schedules.

```bash theme={null}
GET /v2/teams/{teamId}/schedules
POST /v2/teams/{teamId}/schedules
```

### Team Memberships

Manage team members and their roles.

```bash theme={null}
GET /v2/teams/{teamId}/memberships
POST /v2/teams/{teamId}/memberships
DELETE /v2/teams/{teamId}/memberships/{membershipId}
```

### Team Invitations

Invite users to join your team.

```bash theme={null}
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