teams

Reference

5 min read

Teams

Create a Team

post/v1/teams

Create a new Team under your account. You need to send a POST request with the desired Team slug, and optionally the Team name.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/teams", {
2  "body": {
3    "slug": "a-random-team",
4    "attribution": {
5      "sessionReferrer": "SOME_STRING_VALUE",
6      "landingPage": "SOME_STRING_VALUE",
7      "pageBeforeConversionPage": "SOME_STRING_VALUE",
8      "utm": {
9        "utmSource": "SOME_STRING_VALUE",
10        "utmMedium": "SOME_STRING_VALUE",
11        "utmCampaign": "SOME_STRING_VALUE",
12        "utmTerm": "SOME_STRING_VALUE"
13      }
14    },
15    "name": "A Random Team"
16  },
17  "headers": {
18    "Authorization": "Bearer <TOKEN>"
19  },
20  "method": "post"
21})

Parameters

Body Params

Body Parameter Description

slug

string

required

The desired slug for the Team

<= 48 characters

Example:"a-random-team"

attribution

object

Attribution information for the session or current page

landingPage

string

Session landing page

pageBeforeConversionPage

string

Referrer to the signup page

sessionReferrer

string

Session referrer

utm

object

utmCampaign	string UTM campaign
utmMedium	string UTM medium
utmSource	string UTM source
utmTerm	string UTM term

name

string

The desired name for the Team. It will be generated from the provided slug if nothing is provided

<= 256 characters

Example:"A Random Team"

Response

The team was created successfully

billingobjectRequired

Properties
idstringRequired
Id of the created team
Example: team_nLlpyC6RE1qxqglFKbrMxlud

slugstringRequired

Response Codes

Code	Description
`200`	The team was created successfully
`400`	One of the provided values in the request body is invalid. The slug is already in use
`403`	You do not have permission to access this resource.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/teams", {
2  "body": {
3    "slug": "a-random-team",
4    "attribution": {
5      "sessionReferrer": "SOME_STRING_VALUE",
6      "landingPage": "SOME_STRING_VALUE",
7      "pageBeforeConversionPage": "SOME_STRING_VALUE",
8      "utm": {
9        "utmSource": "SOME_STRING_VALUE",
10        "utmMedium": "SOME_STRING_VALUE",
11        "utmCampaign": "SOME_STRING_VALUE",
12        "utmTerm": "SOME_STRING_VALUE"
13      }
14    },
15    "name": "A Random Team"
16  },
17  "headers": {
18    "Authorization": "Bearer <TOKEN>"
19  },
20  "method": "post"
21})

Delete a Team

delete/v1/teams/{teamId}

Delete a team under your account. You need to send a DELETE request with the desired team id. An optional array of reasons for deletion may also be sent.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/teams/SOME_STRING_VALUE?newDefaultTeamId=team_LLHUOMOoDlqOp8wPE4kFo9pE&slug=SOME_STRING_VALUE", {
2  "body": {
3    "reasons": [
4      {
5        "slug": "SOME_STRING_VALUE",
6        "description": "SOME_STRING_VALUE"
7      }
8    ]
9  },
10  "headers": {
11    "Authorization": "Bearer <TOKEN>"
12  },
13  "method": "delete"
14})

Parameters

Path Params

Query Params

Body Params

Path Parameter	Description
teamId	string required The Team identifier to perform the request on behalf of.

Response

The Team was successfully deleted

idstringRequired
The ID of the deleted Team
Example: team_LLHUOMOoDlqOp8wPE4kFo9pE

newDefaultTeamIdErrorboolean
Signifies whether the default team update has failed, when newDefaultTeamId is provided in request query.
Example: true

Response Codes

Code	Description
`200`	The Team was successfully deleted
`400`	One of the provided values in the request body is invalid. One of the provided values in the request query is invalid.
`401`
`402`
`403`	You do not have permission to access this resource. The authenticated user can't access the team
`404`	The team was not found
`409`

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/teams/SOME_STRING_VALUE?newDefaultTeamId=team_LLHUOMOoDlqOp8wPE4kFo9pE&slug=SOME_STRING_VALUE", {
2  "body": {
3    "reasons": [
4      {
5        "slug": "SOME_STRING_VALUE",
6        "description": "SOME_STRING_VALUE"
7      }
8    ]
9  },
10  "headers": {
11    "Authorization": "Bearer <TOKEN>"
12  },
13  "method": "delete"
14})

Delete a Team invite code

delete/v1/teams/{teamId}/invites/{inviteId}

Delete an active Team invite code.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/teams/teamId/invites/2wn2hudbr4chb1ecywo9dvzo7g9sscs6mzcz8htdde0txyom4l", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "delete"
6})

Parameters

Path Params

Path Parameter	Description
inviteId	string required The Team invite code ID. Example:`2wn2hudbr4chb1ecywo9dvzo7g9sscs6mzcz8htdde0txyom4l`

Response Codes

Code	Description
`200`	Successfully deleted Team invite code.
`400`	One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource. Invite managed by directory sync Not authorized to access this team.
`404`	Team invite code not found. No team found.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/teams/teamId/invites/2wn2hudbr4chb1ecywo9dvzo7g9sscs6mzcz8htdde0txyom4l", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "delete"
6})

Get a Team

get/v2/teams/{teamId}

Get information for the Team specified by the teamId parameter.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v2/teams/SOME_STRING_VALUE?slug=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Path Params

Query Params

Path Parameter	Description
teamId	string The Team identifier to perform the request on behalf of.

Response Codes

Code	Description
`200`	The requested team
`400`	One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource. Not authorized to access the team.
`404`	Team was not found.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v2/teams/SOME_STRING_VALUE?slug=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Check the status of a join request. It'll respond with a 404 if the request has been declined. If no userId path segment was provided, this endpoint will instead return the status of the authenticated user.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/teams/teamId/request/SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Path Params

Path Parameter	Description
userId	string

Response

accessRequestedAtnumberRequired
Timestamp in milliseconds when the user requested access to the team.
Example: 1588720733602

bitbucketobject or nullRequired
Map of the connected Bitbucket account.

Properties
confirmedbooleanRequired
Current status of the membership. Will be true if confirmed, if pending it'll be false.

githubobject or nullRequired
Map of the connected GitHub account.

Properties
gitlabobject or nullRequired
Map of the connected GitLab account.

Properties
joinedFromobjectRequired
A map that describes the origin from where the user joined.

Properties
teamNamestringRequired
The name of the team.
Example: My Team

teamSlugstringRequired
The slug of the team.
Example: my-team

Response Codes

Code	Description
`200`	Successfully
`400`	One of the provided values in the request query is invalid. User is already a confirmed member of the team and did not request access. Only visible when the authenticated user does have access to the team.
`403`	You do not have permission to access this resource.
`404`	The provided user doesn't have a membership. Team was not found.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/teams/teamId/request/SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

List team members

get/v2/teams/{teamId}/members

Get a paginated list of team members for the provided team.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v2/teams/teamId/members?eligibleMembersForProjectId=SOME_STRING_VALUE&excludeProject=SOME_STRING_VALUE&limit=20&role=OWNER&search=SOME_STRING_VALUE&since=1540095775951&until=1540095775951", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Query Params

Query Parameter	Description
eligibleMembersForProjectId	string Include team members who are eligible to be members of the specified project.
excludeProject	string Exclude members who belong to the specified project.
limit	number Limit how many teams should be returned `>=1` Example:`20`
role	string of the following Only return members with the specified team role. Example:`OWNER` Allowed values:`OWNERMEMBERDEVELOPERVIEWERBILLINGCONTRIBUTOR`
search	string Search team members by their name, username, and email.
since	number Timestamp in milliseconds to only include members added since then. Example:`1540095775951`
until	number Timestamp in milliseconds to only include members added until then. Example:`1540095775951`

Response

emailInviteCodesarray

One of:

Properties
Properties
membersarrayRequired
Properties
paginationobjectRequired

Properties

Response Codes

Code	Description
`200`
`400`	One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.
`404`	No team was found.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v2/teams/teamId/members?eligibleMembersForProjectId=SOME_STRING_VALUE&excludeProject=SOME_STRING_VALUE&limit=20&role=OWNER&search=SOME_STRING_VALUE&since=1540095775951&until=1540095775951", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

List all teams

get/v2/teams

Get a paginated list of all the Teams the authenticated User is a member of.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v2/teams?limit=20&since=1540095775951&until=1540095775951", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Query Params

Query Parameter	Description
limit	number Maximum number of Teams which may be returned. Example:`20`
since	number Timestamp (in milliseconds) to only include Teams created since then. Example:`1540095775951`
until	number Timestamp (in milliseconds) to only include Teams created until then. Example:`1540095775951`

Response

A paginated list of teams.

paginationRequired

teamsarrayRequired

One of:

Response Codes

Code	Description
`200`	A paginated list of teams.
`400`	One of the provided values in the request query is invalid.
`403`	You do not have permission to access this resource.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v2/teams?limit=20&since=1540095775951&until=1540095775951", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Invite a user

post/v1/teams/{teamId}/members

Invite a user to join the team specified in the URL. The authenticated user needs to be an OWNER in order to successfully invoke this endpoint. The user can be specified with an email or an ID. If both email and ID are provided, ID will take priority.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/teams/teamId/members", {
2  "body": {
3    "email": "john@example.com",
4    "projects": [
5      {
6        "projectId": "prj_ndlgr43fadlPyCtREAqxxdyFK",
7        "role": "ADMIN"
8      }
9    ],
10    "role": "[MEMBER,VIEWER]",
11    "uid": "kr1PsOIzqEL5Xg6M4VZcZosf"
12  },
13  "headers": {
14    "Authorization": "Bearer <TOKEN>"
15  },
16  "method": "post"
17})

Parameters

Body Params

Body Parameter Description

string

The email address of the user to invite

Example:"john@example.com"

projects

array of object

projectId	string required The ID of the project. `<= 64 characters` Example:`prj_ndlgr43fadlPyCtREAqxxdyFK`
role	string of the following required Sets the project roles for the invited user Example:`ADMIN` Allowed values:`ADMINPROJECT_VIEWERPROJECT_DEVELOPER`

role

string of the following

The role of the user to invite

Example:[MEMBER,VIEWER]

Allowed values:OWNERMEMBERDEVELOPERBILLINGVIEWERCONTRIBUTOR

uid

string

The id of the user to invite

Example:"kr1PsOIzqEL5Xg6M4VZcZosf"

Response

One of the following objects
One of

Response Codes

Code	Description
`200`	The member was successfully added to the team
`400`	One of the provided values in the request body is invalid. One of the provided values in the request query is invalid. The user already requested access to the team Hobby teams are not allowed to add seats. The team reached the maximum allowed amount of members
`401`
`403`	You do not have permission to access this resource. The authenticated user must be a team owner to perform the action
`404`	The team was not found

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/teams/teamId/members", {
2  "body": {
3    "email": "john@example.com",
4    "projects": [
5      {
6        "projectId": "prj_ndlgr43fadlPyCtREAqxxdyFK",
7        "role": "ADMIN"
8      }
9    ],
10    "role": "[MEMBER,VIEWER]",
11    "uid": "kr1PsOIzqEL5Xg6M4VZcZosf"
12  },
13  "headers": {
14    "Authorization": "Bearer <TOKEN>"
15  },
16  "method": "post"
17})

Join a team

post/v1/teams/{teamId}/members/teams/join

Join a team with a provided invite code or team ID.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/teams/teamId/members/teams/join", {
2  "body": {
3    "inviteCode": "fisdh38aejkeivn34nslfore9vjtn4ls"
4  },
5  "headers": {
6    "Authorization": "Bearer <TOKEN>"
7  },
8  "method": "post"
9})

Parameters

Body Params

Body Parameter	Description
inviteCode	string The invite code to join the team. Example:`"fisdh38aejkeivn34nslfore9vjtn4ls"`

Response

Successfully joined a team.

fromstringRequired
The origin of how the user joined.
Example: email

namestringRequired
The name of the team the user joined.
Example: My Team

slugstringRequired
The slug of the team the user joined.
Example: my-team

teamIdstringRequired
The ID of the team the user joined.
Example: team_LLHUOMOoDlqOp8wPE4kFo9pE

Response Codes

Code	Description
`200`	Successfully joined a team.
`400`	One of the provided values in the request body is invalid.
`402`
`403`	You do not have permission to access this resource.
`404`

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/teams/teamId/members/teams/join", {
2  "body": {
3    "inviteCode": "fisdh38aejkeivn34nslfore9vjtn4ls"
4  },
5  "headers": {
6    "Authorization": "Bearer <TOKEN>"
7  },
8  "method": "post"
9})

Update a Team

patch/v2/teams/{teamId}

Update the information of a Team specified by the teamId parameter. The request body should contain the information that will be updated on the Team.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v2/teams/SOME_STRING_VALUE?slug=SOME_STRING_VALUE", {
2  "body": {
3    "avatar": "SOME_STRING_VALUE",
4    "description": "Our mission is to make cloud computing accessible to everyone",
5    "emailDomain": "example.com",
6    "enablePreviewFeedback": "on",
7    "hideIpAddresses": true,
8    "name": "My Team",
9    "previewDeploymentSuffix": "example.dev",
10    "regenerateInviteCode": true,
11    "remoteCaching": {
12      "enabled": true
13    },
14    "saml": {
15      "enforced": true,
16      "roles": "SOME_OBJECT_VALUE"
17    },
18    "sensitiveEnvironmentVariablePolicy": "on",
19    "slug": "my-team"
20  },
21  "headers": {
22    "Authorization": "Bearer <TOKEN>"
23  },
24  "method": "patch"
25})

Parameters

Path Params

Query Params

Body Params

Path Parameter	Description
teamId	string required The Team identifier to perform the request on behalf of.

Response

Response Codes

Code	Description
`200`
`400`	One of the provided values in the request body is invalid.
`401`
`402`
`403`	You do not have permission to access this resource. Not authorized to update the team. Must be an OWNER.
`404`	Team was not found.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v2/teams/SOME_STRING_VALUE?slug=SOME_STRING_VALUE", {
2  "body": {
3    "avatar": "SOME_STRING_VALUE",
4    "description": "Our mission is to make cloud computing accessible to everyone",
5    "emailDomain": "example.com",
6    "enablePreviewFeedback": "on",
7    "hideIpAddresses": true,
8    "name": "My Team",
9    "previewDeploymentSuffix": "example.dev",
10    "regenerateInviteCode": true,
11    "remoteCaching": {
12      "enabled": true
13    },
14    "saml": {
15      "enforced": true,
16      "roles": "SOME_OBJECT_VALUE"
17    },
18    "sensitiveEnvironmentVariablePolicy": "on",
19    "slug": "my-team"
20  },
21  "headers": {
22    "Authorization": "Bearer <TOKEN>"
23  },
24  "method": "patch"
25})

Remove a Team Member

delete/v1/teams/{teamId}/members/{uid}

Remove a Team Member from the Team, or dismiss a user that requested access, or leave a team.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/teams/teamId/members/ndlgr43fadlPyCtREAqxxdyFK?newDefaultTeamId=team_nllPyCtREAqxxdyFKbbMDlxd", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "delete"
6})

Parameters

Path Params

Query Params

Path Parameter	Description
uid	string required The user ID of the member. Example:`ndlgr43fadlPyCtREAqxxdyFK`

Response

idstringRequired
ID of the team.

Response Codes

Code	Description
`200`	Successfully removed a member of the team.
`400`	One of the provided values in the request query is invalid. Cannot leave the team as the only owner.
`401`
`403`	You do not have permission to access this resource. Not authorized to update the team.
`404`	A user with the specified ID does not exist. No team found.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/teams/teamId/members/ndlgr43fadlPyCtREAqxxdyFK?newDefaultTeamId=team_nllPyCtREAqxxdyFKbbMDlxd", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "delete"
6})

Request access to a team

post/v1/teams/{teamId}/request

Request access to a team as a member. An owner has to approve the request. Only 10 users can request access to a team at the same time.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/teams/teamId/request", {
2  "body": {
3    "joinedFrom": {
4      "origin": "github",
5      "commitId": "f498d25d8bd654b578716203be73084b31130cd7",
6      "repoId": "67753070",
7      "repoPath": "jane-doe/example",
8      "gitUserId": 103053343,
9      "gitUserLogin": "jane-doe"
10    }
11  },
12  "headers": {
13    "Authorization": "Bearer <TOKEN>"
14  },
15  "method": "post"
16})

Parameters

Body Params

Body Parameter Description

joinedFrom

object

required

commitId	string The commit sha if the origin is a git provider. Example:`f498d25d8bd654b578716203be73084b31130cd7`
gitUserId	One of the following The ID of the Git account of the user who requests access. Example:`103053343` type: `string` type: `number`
gitUserLogin	string The login name for the Git account of the user who requests access. Example:`jane-doe`
origin	string of the following required The origin of the request. Example:`github` Allowed values:`importteamsgithubgitlabbitbucketfeedbackorganization-teams`
repoId	string The ID of the repository for the given Git provider. Example:`67753070`
repoPath	string The path to the repository for the given Git provider. Example:`jane-doe/example`

Response

accessRequestedAtnumber

bitbucketobject or nullRequired

Properties
confirmedboolean

githubobject or nullRequired

Properties
gitlabobject or nullRequired

Properties
joinedFromobject

Properties
teamNamestringRequired

teamSlugstringRequired

Response Codes

Code	Description
`200`	Successfuly requested access to the team.
`400`	One of the provided values in the request body is invalid. One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.
`404`	The team was not found.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/teams/teamId/request", {
2  "body": {
3    "joinedFrom": {
4      "origin": "github",
5      "commitId": "f498d25d8bd654b578716203be73084b31130cd7",
6      "repoId": "67753070",
7      "repoPath": "jane-doe/example",
8      "gitUserId": 103053343,
9      "gitUserLogin": "jane-doe"
10    }
11  },
12  "headers": {
13    "Authorization": "Bearer <TOKEN>"
14  },
15  "method": "post"
16})

Update a Team Member

patch/v1/teams/{teamId}/members/{uid}

Update the membership of a Team Member on the Team specified by teamId, such as changing the role of the member, or confirming a request to join the Team for an unconfirmed member. The authenticated user must be an OWNER of the Team.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/teams/teamId/members/ndfasllgPyCtREAqxxdyFKb", {
2  "body": {
3    "confirmed": true,
4    "joinedFrom": {
5      "ssoUserId": "SOME_NULL_VALUE"
6    },
7    "projects": [
8      {
9        "projectId": "prj_ndlgr43fadlPyCtREAqxxdyFK",
10        "role": "ADMIN"
11      }
12    ],
13    "role": "[MEMBER,VIEWER]"
14  },
15  "headers": {
16    "Authorization": "Bearer <TOKEN>"
17  },
18  "method": "patch"
19})

Parameters

Path Params

Body Params

Path Parameter	Description
uid	string required The ID of the member. Example:`ndfasllgPyCtREAqxxdyFKb`

Response

idstringRequired
ID of the team.

Response Codes

Code	Description
`200`	Successfully updated the membership.
`400`	One of the provided values in the request body is invalid. One of the provided values in the request query is invalid. Cannot disconnect SSO from a Team member that does not have a SSO connection. Cannot confirm a member that is already confirmed. Cannot confirm a member that did not request access.
`401`	Team members can only be updated by an owner, or by the authenticated user if they are only disconnecting their SAML connection to the Team.
`402`
`403`	You do not have permission to access this resource.
`404`	The provided user is not part of this team. A user with the specified ID does not exist. Team not found.
`500`

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/teams/teamId/members/ndfasllgPyCtREAqxxdyFKb", {
2  "body": {
3    "confirmed": true,
4    "joinedFrom": {
5      "ssoUserId": "SOME_NULL_VALUE"
6    },
7    "projects": [
8      {
9        "projectId": "prj_ndlgr43fadlPyCtREAqxxdyFK",
10        "role": "ADMIN"
11      }
12    ],
13    "role": "[MEMBER,VIEWER]"
14  },
15  "headers": {
16    "Authorization": "Bearer <TOKEN>"
17  },
18  "method": "patch"
19})

Last updated on April 27, 2024

Change secret name

Create a Team

Was this helpful?