<!-- llms.txt: https://workos.com/llms.txt -->

# Team invitation

A team invitation adds a person to a team a platform created. The team's first admin is invited automatically when the team is created, so this endpoint is for everyone after that.

:::code-group{title="Example team invitation"}

```json language="curl"
{
  "object": "workos_team_invitation",
  "email": "bob@example.com",
  "role_slug": "member"
}
```

:::

## Roles

Each `role_slug` maps to one of the five [dashboard roles](https://workos.com/docs/dashboard/members-and-roles#roles):

| `role_slug`      | Dashboard role    | Description                                              |
| ---------------- | ----------------- | -------------------------------------------------------- |
| `admin`          | Admin             | Can invite, configure environments, and manage resources |
| `member`         | Developer         | Can configure environments and manage resources          |
| `member-sandbox` | Sandbox Developer | Can manage staging environments, read-only in production |
| `support`        | Support           | Can only manage users and organizations                  |
| `support-viewer` | Support Viewer    | Read-only access to users and organizations              |

## Endpoints

- [Invite a team member](https://workos.com/docs/reference/platform/invitation/create)

## Invite a team member

Sends an email invitation to the recipient. Inviting an address that already has a pending invitation to this team resends it.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/platform/teams/team_01K4BN3VKH8AFZC5J334QZY3PM/invitations" \
  --header "Authorization: Bearer $PLATFORM_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "email": "bob@example.com",
        "role_slug": "member"
    }
BODY
```

```json language="json" title="Response" tab="2"
{
  "object": "workos_team_invitation",
  "email": "bob@example.com",
  "role_slug": "member"
}
```

:::

### Error responses

- **400** (`user_already_team_member`): the person is already an accepted member of this team.
- **400** (`user_belongs_to_another_team`): the person belongs to a different WorkOS team. A user can only belong to one team, which makes this the most common invitation error in practice.
- **403** (`platform_not_authorized`): the platform isn't authorized on this team.
- **404** (`team_not_found`): no such team.

### workos_team_invitation

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "workos_team_invitation" | Yes | The object type. |
| `email` | string | Yes | The email address the invitation was sent to. |
| `role_slug` | "admin" \| "member" \| "member-sandbox" \| "support" \| "support-viewer" | Yes | The role the invited member will have when they join. |

### POST /platform/teams/:team_id/invitations

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `team_id` | string | Yes | The ID of the team to invite the person to. |
| `email` | string | Yes | The email address to send the invitation to. |
| `role_slug` | "admin" \| "member" \| "member-sandbox" \| "support" \| "support-viewer" | Yes | The role to assign. See the roles table on the team invitation object. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `workos_team_invitation` | object | The created invitation. |