Endpoints

Create a team, get team metadata, or invite members to a team.

GET team

Returns metadata for a team the caller can access.

Private OAuth apps can use this endpoint for Professional, Organization, and Enterprise plans. Plan access tokens can use it for Organization and Enterprise plans.

info

This is a Tier 2 endpoint. OAuth apps require the teams:read scope.

HTTP Endpoint

GET /v1/teams/:team_id

Path parameters	Description
team_id	String The ID of the team.

Return value

Returns a Team.

Error codes	Description
401	The access token is missing or incorrect.
403	The caller does not have permission to access the team.
429	The request was rate-limited.
500	An internal server error occurred.

POST team

Creates a team in the Enterprise plan associated with a private OAuth app. The app uses the authenticated user's permissions, and that user becomes the team owner. The request is subject to the same team-creation controls and permissions as team creation in Figma.

info

This is a Tier 2 endpoint, requires the teams:write scope, and is available only to private OAuth apps associated with an Enterprise plan.

HTTP Endpoint

POST /v1/teams

Body parameters	Description
name	String The name of the team.
description	String Optional. A description of the team.
sharing_audience_control	String The audience that can discover and join the team: org_view, org_edit, invite_only, workspace_view, or workspace_edit.
org_discoverability	String Required when sharing_audience_control is invite_only and omitted otherwise. Must be hidden or discoverable.
workspace_id	String Optional. The destination workspace. Required for workspace_view and workspace_edit.

Return value

Returns the created Team.

Error codes	Description
400	The request parameters are invalid.
401	The access token is missing or incorrect.
403	The caller does not have permission to create the team.
429	The request was rate-limited.
500	An internal server error occurred.

POST team invites

Invites people to a team in the Enterprise plan associated with a private OAuth app. The team must belong to that plan, and the authenticated user must be allowed to grant the requested role.

Each email address is processed independently. Per-address failures are returned in the errors array with a 200 response, even if invites is empty. Always inspect errors to determine which addresses could not be invited. Existing team members keep their current role when it is higher than the requested role.

info

This is a Tier 2 endpoint, requires the team_members:write scope, and is available only to private OAuth apps associated with an Enterprise plan.

HTTP Endpoint

POST /v1/teams/:team_id/invites

Path parameters	Description
team_id	String The ID of the team to invite people to.

Body parameters	Description
emails	String[] Between 1 and 99 email addresses to invite.
role	String The role to grant each invited member: viewer, editor, or admin. Existing roles are never downgraded.

Return value

Returns the normalized email addresses that were invited and any policy errors for individual addresses. An invitation can still require approval from an organization admin before the user joins the team.

{
  "invites": [
    {
      "email": String,
      "role": String
    }
  ],
  "errors": [
    {
      "email": String,
      "error": String
    }
  ]
}

Error codes	Description
400	The request body, role, email address, or number of email addresses is invalid.
401	The request is not authenticated.
403	The token, OAuth app, or authenticated user does not have permission to invite team members.
404	The team was not found, or the endpoint is not enabled.
413	The request body is too large.
429	The request was throttled or rate-limited. Wait before trying the request again.
500	An internal server error occurred.