---
title: "Create or Add Team to Organization"
method: POST
path: "/v1/organizations/{organizationId}/teams"
tags: ["organizations"]
---

# Create or Add Team to Organization

`POST /v1/organizations/{organizationId}/teams`

## Request

- Base URL: `https://api.vercel.com`
- URL: `https://api.vercel.com/v1/organizations/{organizationId}/teams`
- Auth: HTTP bearer

Create a new team under an organization, or add an existing team. `mode: "create"` creates a brand-new child team from `slug` + `name` — a platform child by default, or an enterprise child (billed on the organization root's flex subscription) when `billingPlan: "enterprise"` is supplied. `mode: "link"` links an existing team identified by `teamId` or `slug`; the child's billing profile is derived from the target team's plan (enterprise team → enterprise child, else platform), or explicitly supplied. Both modes respond with the resulting organization-team link. This endpoint is in private beta. Contact your Vercel account team for access.

## Path parameters

- `organizationId` string, required: The ID of the organization to create or add a team under.

## Request body

- object
  - `mode` 'create', required: Whether to create a new team under the organization (\"create\") or link an existing one (\"link\").
  - `name` string, required: The display name for a new team. Required in create mode; rejected in link mode.
  - `teamId` string: The ID of an existing team to add to the organization (link mode).
  - `slug` string, required: The slug of an existing team to link, or the slug for a new team to create.
  - `billingPlan` 'enterprise' | 'platform'

## Response `200`

- OrganizationTeam
  - `billingPlan` 'enterprise' | 'platform': The child team's billing profile within the organization. Optional: links created before this attribute existed have no stored value.
  - `createdAt` string, required
  - `organizationId` string, required
  - `ssoMode` 'organization' | 'team', required
  - `teamId` string, required
  - `updatedAt` string, required

## Other responses

- `400`: One of the provided values in the request body is invalid. One of the provided values in the request query is invalid. The slug is already in use
- `401`: The request is not authorized.
- `403`: You do not have permission to access this resource.
- `404`
- `409`
- `410`
- `500`

## Changes

- **2026-10-16** `0e48cb239c6a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/vercel/apis/api/changes/v1/organizations/:organizationId/teams/post.md)

---

[API](https://skmtc.dev/vercel/apis/api.md) - [All operations](https://skmtc.dev/vercel/apis/api/llms.txt) - [OpenAPI document](https://skmtc.dev/vercel/apis/api/revisions/4a06e85c2848?raw)