Migrate SIMs between Workspaces | emnify Documentation

import requests
url = "https://cdn.emnify.net/api/v1/sim/migration/workspace"
payload = {
    "target_workspace": { "id": 1 },
    "iccids": ["1234567890123456789", "1234567890123456790"],
    "allowed_sim_statuses": [{ "id": 1 }],
    "dry_run": False,
    "auto_detach_devices": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

{
  "sim_count": 2,
  "dry_run": false,
  "target_workspace": {
    "id": 98,
    "name": "My Target Workspace"
  },
  "auto_detach_devices": true,
  "sims": [
    {
      "status": {
        "id": 1,
        "description": "ACTIVATED"
      },
      "id": 1,
      "iccid": "1234567890123456789",
      "iccid_with_luhn": "12345678901234567891",
      "endpoint": {
        "id": 75,
        "name": "My Device"
      },
      "source_workspace": {
        "id": 53,
        "name": "My Workspace"
      }
    },
    {
      "status": {
        "id": 2,
        "description": "SUSPENDED"
      },
      "id": 24,
      "iccid": "1234567890123456790",
      "iccid_with_luhn": "12345678901234567901",
      "source_workspace": {
        "id": 53,
        "name": "My Workspace"
      }
    }
  ]
}

Migrate SIMs from one Workspace to another.

Requirements

The calling user must have Administrator permissions on both the target and source Workspaces
The target Workspace must be an enterprise Workspace
Only 500 SIMs can be migrated per request
You must provide exactly one of: sims, iccids, or iccid_range

This endpoint requires authentication with user credentials, as application tokens are scoped to a single Workspace.

Behavior

Dry run mode: The dry_run parameter defaults to true. Set it to false to execute the migration.
Activated SIMs: SIMs in status ACTIVATED are automatically suspended during migration.
Attached devices: If SIMs are attached to devices, set auto_detach_devices: true or the request fails.

The request fails if one or more SIMs don’t meet the requirements for migration. Check the errors array in the response for details.

Migrate SIMs from one Workspace to another. ## Requirements - The calling user must have **Administrator** permissions on both the target and source Workspaces - The target Workspace must be an enterprise Workspace - Only 500 SIMs can be migrated per request - You must provide exactly one of: `sims`, `iccids`, or `iccid_range` <Note> This endpoint requires authentication with [user credentials](/developers/auth/user-credentials), as application tokens are scoped to a single Workspace. </Note> ## Behavior - **Dry run mode**: The `dry_run` parameter defaults to `true`. Set it to `false` to execute the migration. - **Activated SIMs**: SIMs in status `ACTIVATED` are automatically suspended during migration. - **Attached devices**: If SIMs are attached to devices, set `auto_detach_devices: true` or the request fails. <Warning> The request fails if one or more SIMs don't meet the requirements for migration. Check the `errors` array in the response for details. </Warning>

Authentication

AuthorizationBearer

An auth_token should be provided to authenticate a session.

To obtain an auth_token, see the /api/v1/authenticate POST request.

Request

This endpoint expects an object.

target_workspaceobjectRequired

Target Workspace to migrate SIMs to. Must be an enterprise Workspace. The calling user must have Administrator permissions on the target Workspace.

simslist of objectsOptional

List of SIMs to migrate. The list may include up to 500 SIMs.

Cannot be used in combination with the iccids or the iccid_range field.

List of SIMs to migrate. The list may include up to 500 SIMs. <Info> Cannot be used in combination with the `iccids` or the `iccid_range` field. </Info>

iccidslist of stringsOptional

List of ICCIDs to migrate. All SIMs must belong to the source Workspace. The list may include up to 500 ICCIDs.

Cannot be used in combination with the sims or the iccid_range field.

List of ICCIDs to migrate. All SIMs must belong to the source Workspace. The list may include up to 500 ICCIDs. <Info> Cannot be used in combination with the `sims` or the `iccid_range` field. </Info>

iccid_rangeobjectOptional

ICCID range to migrate. All SIMs within the range must belong to the source Workspace. The range may include up to 500 ICCIDs. The end value must be greater than or equal to the start value.

Cannot be used in combination with the iccids or the sims field.

ICCID range to migrate. All SIMs within the range must belong to the source Workspace. The range may include up to 500 ICCIDs. The `end` value must be greater than or equal to the `start` value. <Info> Cannot be used in combination with the `iccids` or the `sims` field. </Info>

allowed_sim_statuseslist of objectsOptional

List of SIM statuses that are allowed to be migrated. The request is rejected if a SIM has a status that isn't in this list. If not provided, all SIM statuses are allowed.

dry_runbooleanOptionalDefaults to true

Controls whether the migration is executed or simulated.

true (default): Returns a preview of SIMs that would be migrated without making changes
false: Executes the migration

Always test with a dry run first to verify the SIMs match your expectations.

Controls whether the migration is executed or simulated. - `true` (default): Returns a preview of SIMs that would be migrated without making changes - `false`: Executes the migration <Tip> Always test with a dry run first to verify the SIMs match your expectations. </Tip>

auto_detach_devicesbooleanOptional

If set to true, the SIMs automatically detach from the devices before being migrated. Otherwise, the request is rejected if one or more SIMs are attached to devices.

Response

Successful migration request. If dry_run was set to false, the migration is processed. If dry_run was set to true, the response contains a summary of the changes that would be executed.

sim_countdouble

The amount of SIMs to be migrated

dry_runboolean

The dry_run option specified in the request

target_workspaceobject

The target_workspace specified in the request

auto_detach_devicesboolean

The auto_detach_devices option specified in the request

simslist of objects

List of SIMs to be migrated

allowed_sim_statuseslist of objects or null

The allowed_sim_statuses option specified in the request

Errors

Migrate SIMs from one Workspace to another.

Requirements

The calling user must have Administrator permissions on both the target and source Workspaces
The target Workspace must be an enterprise Workspace
Only 500 SIMs can be migrated per request
You must provide exactly one of: sims, iccids, or iccid_range

This endpoint requires authentication with user credentials, as application tokens are scoped to a single Workspace.

Behavior

Dry run mode: The dry_run parameter defaults to true. Set it to false to execute the migration.
Activated SIMs: SIMs in status ACTIVATED are automatically suspended during migration.
Attached devices: If SIMs are attached to devices, set auto_detach_devices: true or the request fails.

The request fails if one or more SIMs don’t meet the requirements for migration. Check the errors array in the response for details.