Reference
5 min read
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

1
await 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
})
Body Params
Body ParameterDescription

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"

The team was created successfully

  • billingobjectRequired
  • Properties
  • idstringRequired
    Id of the created team

    Example: team_nLlpyC6RE1qxqglFKbrMxlud

  • slugstringRequired
CodeDescription
200The team was created successfully
400
  • One of the provided values in the request body is invalid.

  • The slug is already in use

403You do not have permission to access this resource.
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

1
await 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
})
Path Params
Query Params
Body Params
Path ParameterDescription

teamId

string

required
The Team identifier to perform the request on behalf of.

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

CodeDescription
200The 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

404The team was not found
409
delete/v1/teams/{teamId}/invites/{inviteId}

Delete an active Team invite code.

Optional params

fetch-request

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

inviteId

string

required
The Team invite code ID.
Example:2wn2hudbr4chb1ecywo9dvzo7g9sscs6mzcz8htdde0txyom4l
  • idstringRequired
    ID of the team.
CodeDescription
200Successfully deleted Team invite code.
400One 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.

get/v2/teams/{teamId}

Get information for the Team specified by the teamId parameter.

Optional params

fetch-request

1
await 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
})
Path Params
Query Params
Path ParameterDescription

teamId

string

The Team identifier to perform the request on behalf of.
CodeDescription
200The requested team
400One 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.

404Team was not found.
get/v1/teams/{teamId}/request/{userId}

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

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

userId

string

  • 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

CodeDescription
200Successfully
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.

403You do not have permission to access this resource.
404
  • The provided user doesn't have a membership.

  • Team was not found.

get/v2/teams/{teamId}/members

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

Optional params

fetch-request

1
await 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
})
Query Params
Query ParameterDescription

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
  • emailInviteCodesarray
  • One of:

  • Properties
  • Properties
  • membersarrayRequired
  • Properties
  • paginationobjectRequired
  • Properties
CodeDescription
200
400One of the provided values in the request query is invalid.
401
403You do not have permission to access this resource.
404No team was found.
get/v2/teams

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

Optional params

fetch-request

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

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

A paginated list of teams.

  • paginationRequired
  • teamsarrayRequired
  • One of:

CodeDescription
200A paginated list of teams.
400One of the provided values in the request query is invalid.
403You do not have permission to access this resource.
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

1
await 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
})
Body Params
Body ParameterDescription

email

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"
  • One of the following objects
  • One of
CodeDescription
200The 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

404The team was not found
post/v1/teams/{teamId}/members/teams/join

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

Optional params

fetch-request

1
await 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
})
Body Params
Body ParameterDescription

inviteCode

string

The invite code to join the team.
Example:"fisdh38aejkeivn34nslfore9vjtn4ls"

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

CodeDescription
200Successfully joined a team.
400One of the provided values in the request body is invalid.
402
403You do not have permission to access this resource.
404
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

1
await 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
})
Path Params
Query Params
Body Params
Path ParameterDescription

teamId

string

required
The Team identifier to perform the request on behalf of.
CodeDescription
200
400One 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.

404Team was not found.
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

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

uid

string

required
The user ID of the member.
Example:ndlgr43fadlPyCtREAqxxdyFK
  • idstringRequired
    ID of the team.
CodeDescription
200Successfully 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.

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

1
await 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
})
Body Params
Body ParameterDescription

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
  • accessRequestedAtnumber
  • bitbucketobject or nullRequired
  • Properties
  • confirmedboolean
  • githubobject or nullRequired
  • Properties
  • gitlabobject or nullRequired
  • Properties
  • joinedFromobject
  • Properties
  • teamNamestringRequired
  • teamSlugstringRequired
CodeDescription
200Successfuly 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
403You do not have permission to access this resource.
404The team was not found.
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

1
await 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
})
Path Params
Body Params
Path ParameterDescription

uid

string

required
The ID of the member.
Example:ndfasllgPyCtREAqxxdyFKb
  • idstringRequired
    ID of the team.
CodeDescription
200Successfully 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.

401Team 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
403You 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
Last updated on May 23, 2024