Transfer

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.

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:

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.

• When the status is Ready, the following is transferred to the destination account:

  • Tags (including SIM name), Bundles, Subscription Containers, IMEI Lock, and Speed Class settings
  • Monthly fees for the entire month in which the transfer is processed
  • Daily fees which accrue starting from the date of transfer, inclusive (daily fees accrued prior to the date of transfer are not transferred)
  • Data usage, SIM status history, and session status information are not carried over to the destination account

• When the status is Active, Inactive, Standby, or Suspended the following is transferred to the destination account:

  • Tags (including SIM name), Bundles, Subscription Containers, IMEI Lock, Expiration, and Termination Protection settings
  • Data usage and SIM status history for the entire month in which the transfer is processed (data prior to the month of transfer is not transferred)
  • Session status information, including the SIM's last connection date and time, connected network, and device IMEI
  • Monthly and daily fees for the entire month in which 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

• The destination account must have a valid payment method configured for the coverage types that correspond to the transferred SIMs.
• Fees associated with the SIMs being transferred will continue to be billed to the source account until the transfer is complete. Once transferred, fees will be transferred according to Transfer of Data, Settings, and Fees.
• In general, SIMs that cannot be purchased by the destination account, such as regional SIMs, cannot be transferred.
• eSIM profiles cannot be transferred.
• Subscription Containers cannot be transferred separately. A Subscription Container is transferred together with its corresponding plan01s or plan-US SIM.
• If a SIM is determined to be ineligible for transfer, it will remain registered to the source account while the remaining SIMs of the transfer request will be transferred.
• A SIM transfer request cannot be split to multiple destination accounts.
• If a SIM's session status is online at the time of transfer, it will be disconnected during the transfer.
• Once a SIM in Active, Inactive, Standby, or Suspended status has been transferred, it cannot be transferred again within the same month. This restriction does not apply to SIMs in Ready status.

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.

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:

• Transfer Name - A descriptive name for the transfer. This information is visible to the destination account and helps them identify and confirm the transfer request.
• Destination Operator ID - The Operator ID (OP + 10 digits) of the Soracom account you are transferring SIMs to.
• Destination Email - The primary email address of the Soracom account, for verification.

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.

[block=api]

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:

[ui-tabs theme=code] [ui-tab title=Global]

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

[/ui-tab] [ui-tab title=Japan]

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://jp.api.soracom.io/v1/sim_transfer_requests

[/ui-tab] [/ui-tabs]

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:

[ui-tabs theme=code] [ui-tab title=Global]

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

[/ui-tab] [ui-tab title=Japan]

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://jp.api.soracom.io/v1/sim_transfer_requests/<TRANSFER-REQUEST-ID>/sims

[/ui-tab] [/ui-tabs]

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

[ui-tabs theme=code] [ui-tab title=Global]

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

[/ui-tab] [ui-tab title=Japan]

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

[/ui-tab] [/ui-tabs]

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

[ui-tabs theme=code] [ui-tab title=Global]

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

[/ui-tab] [ui-tab title=Japan]

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

[/ui-tab] [/ui-tabs]

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

[ui-tabs theme=code] [ui-tab title="Accept (Global)"]

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

[/ui-tab] [ui-tab title="Accept (Japan)"]

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

[/ui-tab] [ui-tab title="Reject (Global)"]

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>/reject

[/ui-tab] [ui-tab title="Reject (Japan)"]

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

[/ui-tab] [/ui-tabs]

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

• Source account:

  • getTransferRequest
  • updateTransferRequest
  • deleteTransferRequest
  • listTransferRequestSims
  • removeSimsFromTransferRequest
  • cancelTransferRequest

• Destination account:

  • getTransferRequest
  • listTransferRequestSims [/block]

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.