Soracom Air for Cellular

Transferring Soracom IoT SIMs

Once an IoT SIM has been registered to a Soracom account, all aspects of the SIM, including configuration and billing, are associated with that account. In some cases, you may want to manage a SIM using a different Soracom account that you or another user controls. Although an IoT SIM cannot be registered to more than one Soracom account at a time, its registration can be transferred from one account to another using a SIM transfer request.

A SIM transfer request occurs between a source account, where the SIMs are currently registered, and a destination account, where the SIMs will be transferred:

  1. The source account creates a request, specifies the destination account details, and chooses the SIMs to transfer.
  2. After submitting the request, the destination account reviews and either approves or rejects the request.
  3. If approved, the request is processed and SIMs are transferred to the destination account.

For privacy, the destination account cannot see the email address of the source account. However, each SIM transfer request includes a Transfer Name specified by the source account, such as a project name or reference number, so the destination can identify and confirm the request.

Transfer Statuses

Each SIM transfer request will appear as an outgoing transfer for the source account, and as an incoming transfer for the destination account. As the transfer request progresses, it will have one of the following statuses:

Status Description
Draft The source account is preparing a request. The request can be modified or deleted.
Draft Validating The source account submitted the request and Soracom is validating it. The request cannot be modified or deleted during validation.
Draft Validating Failed The request failed validation. The source account can modify and resubmit or delete the request.
Requesting The request passed validation. The destination account was notified and the request is awaiting review. The source account cannot modify the request but can cancel it.
Cancelled The source account cancelled the request.
Rejected The destination account rejected the request.
Transferring The destination account accepted the request and the SIMs are being transferred. See Transfer Timing.
Completed The transfer finished and all SIMs were transferred successfully.
Partially Completed The transfer finished but some SIMs were not transferred.
Failed The transfer failed and no SIMs were transferred.

Transfer Timing

In most cases, once the destination account accepts a transfer request, it will be processed immediately. This process may take several minutes or hours depending on the number of SIMs being transferred.

However, requests are not processed during the last two days of each month or the first two days of the following month. If a request is accepted during this period, the status will remain as Transferring and SIMs will be transferred after this period ends.

Transfer of Data, Settings, and Fees

Data, settings, and fees associated with SIMs will be transferred to the destination account based on the status of each SIM at the time the transfer is processed.

Settings not listed above are reset to their default setting during the transfer. Additionally, Group and Event Handler settings, and Soracom Harvest data or files are not transferred.

Conditions and Limitations

Creating a Transfer Request

A SIM transfer request is created by the source account. You can select individual SIMs or upload a CSV file containing SIMs to transfer, then create a new SIM transfer request or add the SIMs to an existing request. You will need the Operator ID and primary email address of the destination account.

Selecting Individual SIMs

  1. Sign in to the User Console. From the Menu, open the SIM Management screen.

  2. In the list of SIMs, select one or more SIMs, then click Actions > Transfer to another operator.

  3. Select whether to create a new SIM transfer request, or to add the selected SIMs to an existing request. The selected SIMs will then appear under SIMs to transfer.

Then continue to Specifying Transfer Request Details or Submitting a Transfer Request.

Uploading a CSV File of SIMs

  1. Sign in to the User Console. From the Menu, open the SIM Transfers screen.

  2. Click + Transfer SIMs and choose Import CSV.

  3. Select whether to create a new SIM transfer request, or to add the imported SIMs to an existing request.

  4. In the Upload CSV file section, select the CSV file containing the SIMs you want to transfer. The imported SIMs will then appear under SIMs to transfer.

    The CSV must be a plain-text file containing only the SIM IDs you want to transfer, with one SIM ID per line.

Then continue to Specifying Transfer Request Details or Submitting a Transfer Request.

Specifying Transfer Request Details

When creating or modifying a SIM transfer request, the following details are required:

After entering or updating these details, click Save Draft.

If you are ready to submit the request, continue to Submitting a Transfer Request.

You can close the SIM transfer request panel and return to the SIM Management screen to add more SIMs to the request, or leave the request as a draft and submit it later.

Submitting a Transfer Request

Once you are ready to submit a SIM transfer request:

  1. Sign in to the User Console. From the Menu, open the SIM Transfers screen.

  2. Click the outgoing SIM transfer request that you want to finalize and submit.

  3. Check Finalize and submit this transfer request and review the SIM transfer terms and conditions.

  4. Click Submit Transfer Request.

Once you submit the request, the transfer request status will change to Draft Validating, and Soracom will check that each SIM in the request is eligible to be transferred to the destination account. This process may take several minutes or hours depending on the number of SIMs to be transferred.

After validation, the request status will change to Requesting and a notification will be sent to the destination account to review and accept or reject the request. If an error occurs during validation, a notification will be sent to the source account to review the error.

Receiving a Transfer Request

A SIM transfer request is accepted or rejected by the destination account. When a request is submitted and validated, a notification will be sent to the destination account, and a notice will also be displayed in the User Console. When you receive a transfer request:

  1. Sign in to the User Console. From the Menu, open the SIM Transfers screen.

  2. Click the incoming SIM transfer request that you want to review.

  3. Review the Transfer Name, Source Operator ID, and other details of the request.

  4. To accept or reject the request:

    • Accept - If you want to add the SIMs to an existing group as they are transferred, select the group to assign. Then select I accept this transfer request, review the Terms & Conditions, and click Approve Transfer Request.

    • Reject - Select I reject this transfer request and click Reject Transfer Request.

If the request is accepted, the transfer will be processed automatically according to the Transfer Timing. This process may take several minutes or hours depending on the number of SIMs being transferred, and upon completion the request status will change to Completed, Partially Completed, or Failed depending on the result of the transfer.

Canceling or Deleting a Transfer Request

A SIM transfer request can be deleted by the source account before it is submitted, or cancelled by the source account before the destination account accepts or rejects the request. To delete or cancel a request:

  1. Sign in to the User Console. From the Menu, open the SIM Transfers screen.

  2. Click the outgoing SIM transfer request that you want to delete or cancel.

  3. Click the ... menu, then click Delete transfer request or Cancel transfer request.

Programmatic Usage

You can also use the Soracom API and the Soracom CLI to manage SIM transfer requests.

Soracom API

To access the Soracom API, first use the auth API to obtain an API Key and Token. Refer to the API Usage Guide for instructions on how to use the API Key and Token in API requests. The source account uses its own credentials to create, modify, submit, delete, and cancel requests. The destination account uses its own credentials to approve and reject requests.

To create a transfer request, use the createTransferRequest API from the source account:

curl -X POST \
|  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
|  -H 'X-Soracom-Token: <MY-TOKEN>' \
|  -H 'Content-Type: application/json' \
|  -d '{
|        "destinationOperatorId": "<DESTINATION-OPERATOR-ID>",
|        "destinationOperatorEmail": "<DESTINATION-OPERATOR-EMAIL>",
|        "name": "<TRANSFER-NAME>"
|      }' \
|  https://g.api.soracom.io/v1/sim_transfer_requests

The API returns the created request, including its transferRequestId.

Next, use the addSimsToTransferRequest API together with the transferRequestId to add SIMs to the request, passing the SIM IDs as a simIds array:

curl -X POST \
|  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
|  -H 'X-Soracom-Token: <MY-TOKEN>' \
|  -H 'Content-Type: application/json' \
|  -d '{
|        "simIds": [
|          "<SIM-ID>"
|        ]
|      }' \
|  https://g.api.soracom.io/v1/sim_transfer_requests/<TRANSFER-REQUEST-ID>/sims

Finally, use the submitTransferRequest API to validate and send the request to the destination account.

curl -X PUT \
|  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
|  -H 'X-Soracom-Token: <MY-TOKEN>' \
|  https://g.api.soracom.io/v1/sim_transfer_requests/<TRANSFER-REQUEST-ID>/request

To review and accept or reject a transfer request, use the listTransferRequests API from the destination account:

curl -X GET \
|  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
|  -H 'X-Soracom-Token: <MY-TOKEN>' \
|  https://g.api.soracom.io/v1/sim_transfer_requests

Then use the executeTransferRequest or rejectTransferRequest API together with the transferRequestId:

curl -X PUT \
|  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
|  -H 'X-Soracom-Token: <MY-TOKEN>' \
|  https://g.api.soracom.io/v1/sim_transfer_requests/<TRANSFER-REQUEST-ID>/transfer

The following APIs can also be used to manage transfer requests:

Soracom CLI

To use the Soracom CLI, you must first configure it to authenticate with your account information, authorization key, or SAM user credentials.

The following commands can be used to create and manage transfer requests:

  • Source account:

    • soracom sim-transfer-requests create
    • soracom sim-transfer-requests list
    • soracom sim-transfer-requests get
    • soracom sim-transfer-requests update
    • soracom sim-transfer-requests delete
    • soracom sim-transfer-requests add-sims
    • soracom sim-transfer-requests list-sims
    • soracom sim-transfer-requests remove-sims
    • soracom sim-transfer-requests submit
    • soracom sim-transfer-requests cancel

  • Destination account:

    • soracom sim-transfer-requests list
    • soracom sim-transfer-requests get
    • soracom sim-transfer-requests list-sims
    • soracom sim-transfer-requests execute
    • soracom sim-transfer-requests reject

These commands will return JSON responses similar to the API examples above.