Migrating a Standalone Team to an Organization

This guide walks you through migrating an existing, standalone team into your new Organization.

Because unified governance requires all team members to also be organization members, migrations can sometimes hit a roadblock if the team contains external users. This tutorial demonstrates how to handle such a conflict using the API.

Scenario Overview

You are an Organization Admin. You have a legacy team (teamId: 42) that you want to move into your organization. However, two users in this team ([email protected] and [email protected]) are not yet part of your organization. We want to keep Alice, but we are fine with Bob being removed from the team during the move.

Step 1: Retrieve your Organization ID

Before we can migrate the team, we need to know the target organizationId. We fetch a list of all organizations we belong to.

• Endpoint: GET /organizations
• Action: Find your target organization in the response array and copy its id (e.g., 123e4567-e89b-12d3-a456-426614174000).

Step 2: Attempt the Migration (and fail)

We attempt to migrate the team. Because we want to be safe, we omit the force flag (which defaults to false).

• Endpoint: POST /teams/42/migrate

• Payload:

  {
    "organizationId": "123e4567-e89b-12d3-a456-426614174000"
  }

• Result: The API rejects the request because Alice and Bob are not in the organization. You will receive a 400 Bad Request with the following error detail:

  Cannot migrate team to organization because the following team members are not members of the new organization: [email protected], [email protected]. Either add the members to the organization before migrating, or use the force option to remove them from the team and proceed with the migration.

Step 3: Add the Required Member

We decide we want Alice to remain on the team, so we must first invite her to the umbrella organization.

• Endpoint: POST /organizations/123e4567-e89b-12d3-a456-426614174000/members
• Payload:

  {
    "email": "[email protected]",
    "role": "member"
  }

• Result: Alice is now officially part of the organization.

Step 4: Force the Migration

We do not want to add Bob to our organization. We accept that he will lose access to the team once it is migrated. We run the migration endpoint again, this time explicitly setting force: true.

• Endpoint: POST /teams/42/migrate
• Payload:

  {
    "organizationId": "123e4567-e89b-12d3-a456-426614174000",
    "force": true
  }

• Result: Success! HTTP 200 OK. The team is moved into the organization. Bob is automatically removed from the team, while Alice remains a team member.

Step 5: Verify the Migration

Finally, we check our organization's team list to ensure the legacy team is now properly grouped under our governance structure.

• Endpoint: GET /organizations/123e4567-e89b-12d3-a456-426614174000/teams
• Result: The response array will now include the newly migrated team.