API docs by Redocly

Soracom API (20260225-131851)

Download OpenAPI specification:

Soracom API v1

AuditLog

Audit logs

Retrieve audit logs for Soracom API calls

Retrieve audit logs for Soracom API calls.

Authorizations:
(api_keyapi_token)
query Parameters
api_kind
string

Filter item for audit log retrieval by API kind (e.g. /v1/auth).

from_epoch_ms
integer

Start time for the log search range (unixtime milliseconds).

to_epoch_ms
integer

End time for the log search range (unixtime milliseconds).

limit
integer [ 1 .. 1000 ]

Maximum number of log entries to retrieve (value range is 1 to 1000).

last_evaluated_key
string

The value of requestedTimeEpochMs in the last log entry retrieved in the previous page. By specifying this parameter, you can continue to retrieve the list from the next page onward.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve audit logs for Soracom Napter

Retrieve audit logs for Soracom Napter.

Authorizations:
(api_keyapi_token)
query Parameters
resource_type
string
Value: "Subscriber"

Type of the target resource to query log entries.

resource_id
string

Identity of the target resource to query log entries.

from
integer

Start time for the log search range (unixtime milliseconds).

to
integer

End time for the log search range (unixtime milliseconds).

limit
integer [ 1 .. 1000 ]

Maximum number of log entries to retrieve (value range is 1 to 1000).

last_evaluated_key
string

The value of time in the last log entry retrieved in the previous page. By specifying this parameter, you can continue to retrieve the list from the next page onward.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Analysis

Soracom Query

Execute a new SQL query asynchronously

Executes a SQL query asynchronously. You can check the status of a SQL query execution with the Analysis:getAnalysisQueries API.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

A SQL query execution request.

from
integer

Start of the period to apply the SQL query (UNIX time (seconds)).

sql
string

A SQL query.

to
integer

End of the period to apply the SQL query (UNIX time (seconds)).

Responses

Request samples

Content type
application/json
{
  • "from": 1743465600,
  • "sql": "SELECT * FROM SIM_SESSION_EVENTS LIMIT 10",
  • "to": 1743552000
}

Response samples

Content type
application/json
{
  • "queryId": "ffa91d0c371d45c4bf53d55ab5c14955"
}

Retrieve the execution status of a SQL query

Retrieve the execution status of a SQL query.

Authorizations:
(api_keyapi_token)
path Parameters
query_id
required
string

SQL query ID.

Responses

Response samples

Content type
application/json
{}

Retrieve available database schemas

Retrieves the available schemas and their column information within the database. You can use this information as a reference when converting data types of data retrieved with the Analysis:startAnalysisQueries API. Example: If the column type is string as shown below, it can be treated as a string.

{
  "name": "SIM_SESSION_EVENTS",
  "columnInfo": [
      {
          "name": "APN",
          "type": "string",
          "databaseType": "TEXT",
          "description": "Access Point Name indicating the network gateway for the SIM session."
      }
  ]
}
Authorizations:
(api_keyapi_token)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Auth

Performs authentication to access to the Soracom API.

Performs authentication to access to the Soracom API. Please include the following information in your request.

  • To perform authentication by a root account, specify email and password.
  • To perform authentication by an AuthKey, specify authKeyId and authKey.
  • To perform authentication by a SAM user, specify operatorId, userName and password.

An API key and API token will be included in the response if successful. Use the API key and API token to perform subsequent requests.

Request Body schema: application/json
required

Authentication request.

authKey
string
authKeyId
string
email
string
mfaOTPCode
string
operatorId
string
password
string
tokenTimeoutSeconds
integer <int64> <= 172800
Default: 86400
userName
string

Responses

Request samples

Content type
application/json
Example
{
  • "operatorId": "OPXXXXXXXXXX",
  • "password": "p@$$w0rd",
  • "userName": "SORACOMAPI"
}

Response samples

Content type
application/json
{
  • "apiKey": "api-abcde123-45fg-hij6-7890-klmno12345pq",
  • "operatorId": "OPXXXXXXXXXX",
  • "token": "abcde12345fghij67890klmno12345pqrst67890uvwxy12345abcde67890fghi...",
  • "userName": "SORACOMAPI"
}

Revokes an API key and API token in order to remove access to the Soracom API.

Revokes the API key and API token that was used to call this API. Once revoked, the API key and API token cannot be used to make further requests to the API, regardless of the key and token's original expiration time. This API can be called regardless of any permission settings.

Authorizations:
(api_keyapi_token)

Responses

Issues a password reset token for the operator.

Generates a password reset token and sends it to the operator's primary email address. After receiving the password reset token, call /v1/auth/password_reset_token/verify API with the token to update the operator's password.

Request Body schema: application/json
required

email address

email
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "soracomapi@example.com"
}

Verifies the password reset token and updates password.

Updates the operator's password if the password reset token is verified.

Request Body schema: application/json
required

token, password

password
required
string
token
required
string

Responses

Request samples

Content type
application/json
{
  • "password": "p@$$w0rd",
  • "token": "abcde12345fghij67890klmno12345pqrst67890uvwxy12345abcde67890fghi..."
}

Generates an API key and an API token to call APIs as a different user.

Using the API key and API token of the original user, call this API to issue an API key and API token of the target user that you are switching to. The original user should already be registered in the target user's trust policy. See User:updateUserTrustPolicy for information on updating the trust policy.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

Specify the user to switch to and the validity period of the API token to be issued.

operatorId
string

Operator ID to be switched to.

tokenTimeoutSeconds
integer [ 180 .. 3600 ]
Default: 3600

API key and API token validity period (in seconds) for the switched user. The default is 3600 seconds (1 hour). The minimum and maximum values are also shown below.

  • Minimum: 180 seconds (3 minutes)
  • Maximum value: 3600 seconds (1 hour)
userName
string

The SAM user name of the specified operator ID to be switched to.

Responses

Request samples

Content type
application/json
{
  • "operatorId": "string",
  • "tokenTimeoutSeconds": 3600,
  • "userName": "string"
}

Response samples

Content type
application/json
{
  • "apiKey": "api-abcde123-45fg-hij6-7890-klmno12345pq",
  • "operatorId": "OPXXXXXXXXXX",
  • "token": "abcde12345fghij67890klmno12345pqrst67890uvwxy12345abcde67890fghi...",
  • "userName": "SORACOMAPI"
}

Gets a list of finalized past billing history

Gets a list of finalized past billing history.

Warning: The maximum information you can get is for the last 18 months. If you need the information before that time, please contact Soracom Support.

Authorizations:
(api_keyapi_token)

Responses

Response samples

Content type
application/json
{
  • "billList": [
    ]
}

Gets a finalized past billing history for the specified month

Gets a finalized past billing history for the specified month. If you specify current month (the month in which the usage fee has not yet been finalized), you will get the preliminary value.

Warning: The maximum information you can get is for the last 18 months. If you need the information before that time, please contact Soracom Support.

Authorizations:
(api_keyapi_token)
path Parameters
yyyyMM
required
string

Target year and month

Responses

Response samples

Content type
application/json
{
  • "amount": 28734,
  • "currency": "JPY",
  • "paymentStatus": "paid",
  • "paymentTransactionId": "12345678901234567_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  • "state": "closed",
  • "yearMonth": "202208"
}

Get a daily bill

Gets a daily bill for the specified month. Fees charged on a monthly basis cannot be retrieved. If you specify current month (a month for which the fee has not yet been finalized), a preliminary value will be returned.

Warning: The maximum information you can get is for the last 18 months. If you need the information before that time, please contact Soracom Support.

Authorizations:
(api_keyapi_token)
path Parameters
yyyyMM
required
string

Target year and month

Responses

Response samples

Content type
application/json
{
  • "billList": [
    ]
}

Export historical Detailed billing CSV to dedicated storage

Export historical Detailed billing CSV to dedicated storage and issue URL to download.

Warning: The maximum information you can get is for the last 18 months. If you need the information before that time, please contact Soracom Support.

Authorizations:
(api_keyapi_token)
path Parameters
yyyyMM
required
string

Target year and month

query Parameters
export_mode
string
Enum: "async" "sync"

Specify how to get the URL to download the billing details CSV.

  • async: Get the exportedFieldId without waiting for the URL to be issued on the Soracom platform. Specify this exportedFieldId in Files:getExportedFile API to get the URL. If the file size of the billing details CSV is huge, use async.
  • sync (default): Wait for the URL to be issued on the Soracom platform. However, if the file size of the billing details CSV is huge, it may time out and the URL cannot be retrieved. If the timeout occurs, specify async.

Responses

Response samples

Content type
application/json
Example
{
  • "exportedFileId": "fe_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  • "exportedFilePath": "//files/exported/fe_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Get latest bill

Retrieves the preliminary usage fee for the current month (the month in which the usage fee has not yet been finalized).

Authorizations:
(api_keyapi_token)

Responses

Response samples

Content type
application/json
{
  • "amount": 0.1,
  • "currency": "JPY",
  • "lastEvaluatedTime": "yyyyMMddHHmmss"
}

Export latest billing CSV file to S3

Export Detailed Billing CSV for current month (the month in which the usage fee has not yet been finalized) to dedicated storage and issue a URL to download it. The fees will be finalized by the second business day of the following month. The Detailed billing CSV exported using this API will output preliminary values.

Authorizations:
(api_keyapi_token)
query Parameters
export_mode
string
Enum: "async" "sync"

Specify how to get the URL to download the billing details CSV.

  • async: Get the exportedFieldId without waiting for the URL to be issued on the Soracom platform. Specify this exportedFieldId in Files:getExportedFile API to get the URL. If the file size of the billing details CSV is huge, use async.
  • sync (default): Wait for the URL to be issued on the Soracom platform. However, if the file size of the billing details CSV is huge, it may time out and the URL cannot be retrieved. If the timeout occurs, specify async.

Responses

Response samples

Content type
application/json
Example
{
  • "exportedFileId": "fe_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  • "exportedFilePath": "//files/exported/fe_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Gets a billing summary of bill items.

Get a billing summary of bill items for the last 4 months (this month to 3 months ago). Sorted by date from newest to oldest.

The summary you can get from this API is equivalent to the usage fees displayed in the [COSTS BY SERVICE] panel of the Billing Dashboard. For more information, please refer to Billing Information.

Authorizations:
(api_keyapi_token)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Gets a billing summary of SIMs

Get a billing summary of SIMs for the last 4 months (current month to 3 months ago). Sorted by date from newest to oldest.

The summary you get from this API is equivalent to the rates displayed in the [COSTS PER SIM (TOP 100)] panel of the Rates Dashboard. For more information, please refer to Billing Information.

Authorizations:
(api_keyapi_token)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get location information for a cell tower

Retrieves location information (latitude/longitude) for a cell tower based on cell information such as Cell ID.

  • For 3G, please specify MCC, MNC, LAC, and CID. It is possible to retrieve approximate location information without CID, but the accuracy will be low.

    3G example

    $ curl -X GET "https://api.soracom.io/v1/cell_locations?mcc=440&mnc=10&lac=196" \
-H "X-Soracom-API-Key: $X_SORACOM_API_KEY" \
-H "X-Soracom-Token: $X_SORACOM_TOKEN"

  • For LTE (4G), please specify MCC, MNC, TAC, and ECID.

    4G example

    $ curl -X GET "https://api.soracom.io/v1/cell_locations?mcc=440&mnc=10&tac=5680&ecid=48872466" \
-H "X-Soracom-API-Key: $X_SORACOM_API_KEY" \
-H "X-Soracom-Token: $X_SORACOM_TOKEN"

The conversion of cell tower information to location information uses the OpenCelliD Project database. The specified cell tower information is used to extract the corresponding location information from the OpenCelliD Project database, but it is possible that the location information may not exist or may be different from the actual location.

Creative Commons License OpenCelliD Project is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License

Authorizations:
(api_keyapi_token)
query Parameters
mcc
required
string
Example: mcc=440

MCC - Mobile Country Code.

mnc
required
string
Example: mnc=10

MNC - Mobile Network Code.

lac
string

LAC - Location Area Code (for 3G).

cid
string

CID - Cell ID (for 3G).

tac
string
Example: tac=5680

TAC - Tracking Area Code (for 4G).

ecid
string
Example: ecid=48872466

ECID - Enhanced Cell ID (for 4G) - specify either ecid or eci. The result is the same regardless of which value is specified.

eci
string

ECID - Enhanced Cell ID (for 4G) - specify either ecid or eci. The result is the same regardless of which value is specified.

Responses

Response samples

Content type
application/json
{
  • "avg_strength": 0,
  • "created": "2022-01-01T00:00:00.000Z",
  • "exact": 0,
  • "lat": 35.7119449,
  • "lon": 139.813642,
  • "range": 476,
  • "samples": 7,
  • "updated": "2022-01-01T00:00:00:000Z"
}

List location information for multiple cell towers.

Retrieves a list of location information (latitude/longitude) for multiple cell towers based on cell information such as Cell ID. For 3G, please specify MCC, MNC, LAC, and CID. It is possible to retrieve approximate location information without CID, but the accuracy will be low. For LTE (4G), please specify MCC, MNC, TAC, and ECID. The conversion of cell tower information to location information uses the OpenCelliD Project database, so it is possible that the information may not exist or may be incorrect.

Creative Commons License OpenCelliD Project is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

List of cell identifiers.

Array
cid
string
eci
string
ecid
string
identifier
string

An identifier to link a request to the result of that request. Optional.

lac
string
mcc
string
mnc
string
tac
string

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

List coupons.

Returns a list of currently registered coupons.

Authorizations:
(api_keyapi_token)

Responses

Response samples

Content type
application/json
{
  • "couponList": [
    ]
}

Register Coupon

Registers a coupon.

Authorizations:
(api_keyapi_token)
path Parameters
coupon_code
required
string

Coupon code.

Responses

Response samples

Content type
application/json
{
  • "amount": 0.1,
  • "balance": 0.1,
  • "billItemName": "string",
  • "couponCode": "string",
  • "currency": "JPY",
  • "expiryYearMonth": "string",
  • "orderId": "string"
}

Get payment transaction result.

Returns result of a payment transaction.

Warning: The maximum information you can get is for the last 18 months. If you need the information before that time, please contact Soracom Support.

Authorizations:
(api_keyapi_token)
path Parameters
payment_transaction_id
required
string

Payment transaction ID. It can be obtained via Billing:getBillingHistory API or Billing:getBilling API.

Responses

Response samples

Content type
application/json
{
  • "amount": {
    },
  • "description": {
    },
  • "message": "string",
  • "messageCode": "success",
  • "status": "success"
}

Get current payment method information.

Returns current payment methods. Detailed information is included in the properties.

Authorizations:
(api_keyapi_token)

Responses

Response samples

Content type
application/json
{
  • "errorCode": "success",
  • "errorMessage": "string",
  • "properties": "string",
  • "providerType": "WebPay",
  • "updateDate": "yyyyMMddHHmmss"
}

Activate current payment method

Activates a current payment method that has an error.

Authorizations:
(api_keyapi_token)

Responses

Response samples

Content type
application/json
{ }

List payment statements

List payment statements.

Warning: The maximum information you can get is for the last 18 months. If you need the information before that time, please contact Soracom Support.

Authorizations:
(api_keyapi_token)

Responses

Response samples

Content type
application/json
{
  • "paymentStatementsList": [
    ]
}

Export payment statement

Export payment statement.

Warning: The maximum information you can get is for the last 18 months. If you need the information before that time, please contact Soracom Support.

Authorizations:
(api_keyapi_token)
path Parameters
payment_statement_id
required
string

Payment statement ID

query Parameters
export_mode
string
Enum: "async" "sync"

Export mode (async, sync)

Responses

Response samples

Content type
application/json
{
  • "exportedFileId": "string",
  • "exportedFilePath": "string",
  • "url": "string"
}

Export payer information

Export payer information.

Authorizations:
(api_keyapi_token)

Responses

Response samples

Content type
application/json
{
  • "companyName": "string",
  • "department": "string",
  • "fullName": "string"
}

Register payer information

Register payer information.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

Payer information to be registered in the accounting specification.

companyName
string

Company name

department
string

Department.

fullName
string

Full name.

Responses

Request samples

Content type
application/json
{
  • "companyName": "string",
  • "department": "string",
  • "fullName": "string"
}

List long term discounts

Returns a list of contracted long term discounts.

Warning: Information can be obtained up to 18 months in the past or 6 months after the contract ends. If you need the information before that time, please contact Soracom Support.

Authorizations:
(api_keyapi_token)

Responses

Response samples

Content type
application/json
{
  • "volumeDiscountList": [
    ]
}

Get long term discount

Returns contracted long term discount.

Warning: Information can be obtained up to 18 months in the past or 6 months after the contract ends. If you need the information before that time, please contact Soracom Support.

Authorizations:
(api_keyapi_token)
path Parameters
contract_id
required
string

Contract ID.

Responses

Response samples

Content type
application/json
{
  • "contractDateTime": "yyyyMMddHHmmss",
  • "contractId": "string",
  • "contractTermMonth": 12,
  • "currency": "JPY",
  • "endDate": "yyyyMMdd",
  • "initialCost": 0.1,
  • "quantity": 0,
  • "startDate": "yyyyMMdd",
  • "status": "active",
  • "unitPrice": 0.1,
  • "volumeDiscountPaymentType": "MONTHLY",
  • "volumeDiscountType": "SORACOM_AIR_BASIC_CHARGE_V2"
}

Order

Create coupon quotation

Creates a new coupon quotation. If the orderId is put in /coupons/{order_id}/confirm, the order is complete.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

Coupon details.

amount
required
number <double>

Amount.

Responses

Request samples

Content type
application/json
{
  • "amount": 0.1
}

Response samples

Content type
application/json
{
  • "amount": 0.1,
  • "currency": "JPY",
  • "expiryYearMonth": "string",
  • "orderId": "string",
  • "taxAmount": 0.1,
  • "totalAmount": 0.1
}

Confirm coupon order

Performs a credit limit and confirms the order if no problems are encountered.

Authorizations:
(api_keyapi_token)
path Parameters
order_id
required
string

Order ID. You can get it by calling Order:createCouponQuotation API.

Responses

Response samples

Content type
application/json
{
  • "amount": 0.1,
  • "balance": 0.1,
  • "billItemName": "string",
  • "couponCode": "string",
  • "currency": "JPY",
  • "expiryYearMonth": "string",
  • "orderId": "string"
}

Get a list of confirmed order history

Get a list of confirmed order history.

Warning: The maximum information you can get is for the last 18 months. If you need the information before that time, please contact Soracom Support.

Authorizations:
(api_keyapi_token)

Responses

Response samples

Content type
application/json
{
  • "orderList": [
    ]
}

Create Quotation

Creates a new order quotation. If the orderId is put in /orders/{order_id}/confirm, the order is complete.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

Order item list and shipping address ID.

Array of objects (OrderItemModel)

Order item list.

preferredDeliveryDate
string <yyyyMMdd>

Preferred delivery date.

shippingAddressId
string

Shipping address ID.

Array of ShippingOptionOfNekopos (object) or ShippingOptionOfExpeditedShipping (object)

Shipping options.

Responses

Request samples

Content type
application/json
{
  • "orderItemList": [
    ],
  • "preferredDeliveryDate": "string",
  • "shippingAddressId": "string",
  • "shippingOptions": [
    ]
}

Response samples

Content type
application/json
{
  • "appliedShippingOptions": [
    ],
  • "balanceDue": 0.1,
  • "containsTaxIncludedAmounts": true,
  • "currency": "JPY",
  • "email": "string",
  • "orderChannel": "string",
  • "orderId": "string",
  • "orderItemList": [
    ],
  • "preferredDeliveryDate": "string",
  • "purchaseOrderNumber": "string",
  • "shippingAddress": {
    },
  • "shippingAddressId": "string",
  • "shippingCost": 0.1,
  • "taxAmount": 0.1,
  • "taxIncludedInShippingCost": 0.1,
  • "taxOnShippingCost": true,
  • "totalAmount": 0.1,
  • "withholdingTaxAmount": 0.1
}

Get a confirmed order

Returns a confirmed order.

Warning: The maximum information you can get is for the last 18 months. If you need the information before that time, please contact Soracom Support.

Authorizations:
(api_keyapi_token)
path Parameters
order_id
required
string

Order ID. You can get it by calling Order:listOrders API.

Responses

Response samples

Content type
application/json
{
  • "appliedShippingOptions": [
    ],
  • "balanceDue": 0.1,
  • "containsTaxIncludedAmounts": true,
  • "currency": "JPY",
  • "email": "string",
  • "orderChannel": "string",
  • "orderDateTime": "string",
  • "orderId": "string",
  • "orderItemList": [
    ],
  • "orderStatus": "orderProcessing",
  • "paymentStatus": "lessThanMinimumCharge",
  • "preferredDeliveryDate": "string",
  • "purchaseOrderNumber": "string",
  • "resourceInitialSetting": {
    },
  • "shippingAddress": {
    },
  • "shippingAddressId": "string",
  • "shippingCost": 0.1,
  • "shippingDateTime": 20231004123456,
  • "shippingLabelDetails": [],
  • "shippingLabelNumber": "0000-1111-2222",
  • "shippingLabelNumbers": [
    ],
  • "taxAmount": 0.1,
  • "taxIncludedInShippingCost": 0.1,
  • "taxOnShippingCost": true,
  • "totalAmount": 0.1,
  • "withholdingTaxAmount": 0.1
}

Cancel order

Cancels an order. If the order has already been dispatched, an error is returned.

Authorizations:
(api_keyapi_token)
path Parameters
order_id
required
string

Order ID. You can get it by calling Order:listOrders API.

Responses

Response samples

Content type
application/json
"string"

Confirm order

Performs a credit limit and confirms the order if no problems are encountered.

Warning: Only orders completed within the past month can be confirmed. If one month has elapsed, please redo the order placement operation.

Authorizations:
(api_keyapi_token)
path Parameters
order_id
required
string

Order ID. You can get it by calling Order:listOrders API.

Responses

Response samples

Content type
application/json
{
  • "appliedShippingOptions": [
    ],
  • "balanceDue": 0.1,
  • "containsTaxIncludedAmounts": true,
  • "currency": "JPY",
  • "email": "string",
  • "orderChannel": "string",
  • "orderDateTime": "string",
  • "orderId": "string",
  • "orderItemList": [
    ],
  • "orderStatus": "orderProcessing",
  • "paymentStatus": "lessThanMinimumCharge",
  • "preferredDeliveryDate": "string",
  • "purchaseOrderNumber": "string",
  • "resourceInitialSetting": {
    },
  • "shippingAddress": {
    },
  • "shippingAddressId": "string",
  • "shippingCost": 0.1,
  • "shippingDateTime": 20231004123456,
  • "shippingLabelDetails": [],
  • "shippingLabelNumber": "0000-1111-2222",
  • "shippingLabelNumbers": [
    ],
  • "taxAmount": 0.1,
  • "taxIncludedInShippingCost": 0.1,
  • "taxOnShippingCost": true,
  • "totalAmount": 0.1,
  • "withholdingTaxAmount": 0.1
}

Update resource initial setting for an order

Update resource initial setting for an order.

Warning: Initial settings of IoT SIM cannot be specified after confirmation of receipt.

Authorizations:
(api_keyapi_token)
path Parameters
order_id
required
string

Order ID. You can get it by calling Order:listOrders API.

Request Body schema: application/json
required

Resource initial setting for an order.

object

Initial setting of SIMs for each subscription. The key specifies a subscription.

  • plan01s
  • plan01s-low_data_volume: plan01s - Low Data Volume.
  • planX3: planX3 (X3-5MB).
  • planP1
  • plan-D: plan-D (without bundle), plan-D (D-500MB).
  • plan-K2: plan-K2 (K2-500MB).
  • plan-DU
  • plan-KM1
  • plan-K
  • plan-US

Responses

Request samples

Content type
application/json
{
  • "simInitialSettings": {
    }
}

Response samples

Content type
application/json
{
  • "appliedShippingOptions": [
    ],
  • "balanceDue": 0.1,
  • "containsTaxIncludedAmounts": true,
  • "currency": "JPY",
  • "email": "string",
  • "orderChannel": "string",
  • "orderDateTime": "string",
  • "orderId": "string",
  • "orderItemList": [
    ],
  • "orderStatus": "orderProcessing",
  • "paymentStatus": "lessThanMinimumCharge",
  • "preferredDeliveryDate": "string",
  • "purchaseOrderNumber": "string",
  • "resourceInitialSetting": {
    },
  • "shippingAddress": {
    },
  • "shippingAddressId": "string",
  • "shippingCost": 0.1,
  • "shippingDateTime": 20231004123456,
  • "shippingLabelDetails": [],
  • "shippingLabelNumber": "0000-1111-2222",
  • "shippingLabelNumbers": [
    ],
  • "taxAmount": 0.1,
  • "taxIncludedInShippingCost": 0.1,
  • "taxOnShippingCost": true,
  • "totalAmount": 0.1,
  • "withholdingTaxAmount": 0.1
}

List ordered subscribers

List ordered subscribers.

Warning: The maximum information you can get is for the last 18 months. If you need the information before that time, please contact Soracom Support.

Authorizations:
(api_keyapi_token)
path Parameters
order_id
required
string

Order ID. You can get it by calling Order:listOrders API.

query Parameters
last_evaluated_key
string

The value of the x-soracom-next-key header returned when the previous page was retrieved. Specify if the next page is to be retrieved. For details, see Handling Pagination.

limit
integer <int32>

Maximum number of subscribers in a response.

Responses

Response samples

Content type
application/json
{
  • "orderedSubscriberList": [
    ]
}

Register subscribers for operator

Registers the ordered SIM with the operator.

Warning: IoT SIMs can only be registered for the past 18 months. If you need to register an IoT SIM that was ordered before the time period, please contact Soracom Support.

Authorizations:
(api_keyapi_token)
path Parameters
order_id
required
string

Order ID. You can get it by calling Order:listOrders API.

Responses

Response samples

Content type
application/json
"string"

List products

Returns a list of products.

Authorizations:
(api_keyapi_token)
query Parameters
campaign_code
string

Responses

Response samples

Content type
application/json
{
  • "productList": [
    ],
  • "shippingCostList": [
    ]
}

Create long term discount quotation

Creates a new long term discount quotation. If the orderId is put in /volume_discounts/{order_id}/confirm, the order is complete (Currently, long term discount is only applied to plan-D (without bundle), plan-K).

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

Long term discount contract details.

contractTermMonth
required
integer <int32>
Default: 12

Contract months.

quantity
required
integer <int32>

Quantity.

startDate
string

Start date.

volumeDiscountPaymentType
required
string
Enum: "MONTHLY" "PREPAYMENT"

Payment type.

volumeDiscountType
required
string
Enum: "SORACOM_AIR_BASIC_CHARGE_V2" "SORACOM_AIR_BASIC_CHARGE" "SORACOM_AIR_MONTHLY_FIXED_BASIC_CHARGE"

Long term discount type.

Responses

Request samples

Content type
application/json
{
  • "contractTermMonth": 12,
  • "quantity": 1,
  • "startDate": "20220401",
  • "volumeDiscountPaymentType": "MONTHLY",
  • "volumeDiscountType": "SORACOM_AIR_BASIC_CHARGE_V2"
}

Response samples

Content type
application/json
{
  • "currency": "JPY",
  • "orderId": "xxxxxxxxxxxxxx_xxxxxxxx",
  • "taxAmount": 0,
  • "totalAmount": 0,
  • "volumeDiscount": {
    }
}

Confirm long-term discount order

Performs a credit check and confirms the order if there are no issues.

Authorizations:
(api_keyapi_token)
path Parameters
order_id
required
string
Example: xxxxxxxxxxxxxx_xxxxxxxx

Order ID. The order ID can be obtained from the Order:createVolumeDiscountQuotation API.

Responses

Response samples

Content type
application/json
{
  • "contractDateTime": "yyyyMMddHHmmss",
  • "contractId": "string",
  • "contractTermMonth": 12,
  • "currency": "JPY",
  • "endDate": "yyyyMMdd",
  • "initialCost": 0.1,
  • "quantity": 0,
  • "startDate": "yyyyMMdd",
  • "status": "active",
  • "unitPrice": 0.1,
  • "volumeDiscountPaymentType": "MONTHLY",
  • "volumeDiscountType": "SORACOM_AIR_BASIC_CHARGE_V2"
}

List available long term discounts

Returns a list of available long term discounts.

Authorizations:
(api_keyapi_token)

Responses

Response samples

Content type
application/json
{
  • "availableLongTermDiscounts": [
    ]
}

Credential

Credentials store Create, update, and delete credentials

List credential sets

Returns a list of credential sets.

Authorizations:
(api_keyapi_token)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete a credential set

Deletes a credential set.

Authorizations:
(api_keyapi_token)
path Parameters
credentials_id
required
string

Credential set ID.

Responses

Create a credential set

Creates a new credential set.

Authorizations:
(api_keyapi_token)
path Parameters
credentials_id
required
string

Credential set ID.

Request Body schema: application/json
required

Credential set.

credentials
object
description
string
type
string
Enum: "aws-credentials" "azure-credentials" "psk" "x509"

Responses

Request samples

Content type
application/json
Example
{
  • "credentials": {
    },
  • "type": "api-token-credentials"
}

Response samples

Content type
application/json
{
  • "createDateTime": 0,
  • "credentials": { },
  • "credentialsId": "string",
  • "description": "string",
  • "lastUsedDateTime": 0,
  • "type": "api-token-credentials",
  • "updateDateTime": 0
}

Update a credential set

Updates a credential set.

Authorizations:
(api_keyapi_token)
path Parameters
credentials_id
required
string

Credential set ID.

Request Body schema: application/json
required

Credential set.

credentials
object
description
string
type
string
Enum: "aws-credentials" "azure-credentials" "psk" "x509"

Responses

Request samples

Content type
application/json
{
  • "credentials": { },
  • "description": "string",
  • "type": "aws-credentials"
}

Response samples

Content type
application/json
{
  • "createDateTime": 0,
  • "credentials": { },
  • "credentialsId": "string",
  • "description": "string",
  • "lastUsedDateTime": 0,
  • "type": "api-token-credentials",
  • "updateDateTime": 0
}

Get data sent to Harvest Data from a resource.

Returns a list of data entries sent to Harvest Data from a device that match certain criteria. If the total number of entries does not fit in one page, a URL for accessing the next page is returned in the link header of the response.

Authorizations:
(api_keyapi_token)
path Parameters
resource_type
required
string
Enum: "Subscriber" "LoraDevice" "Sim" "SigfoxDevice" "Device" "SoraCam"

Type of data source resource.

resource_id
required
string

ID of data source resource. The ID to be specified depends on the value of resource_type.

resource_type The ID you specify
Subscriber IMSI of the IoT SIM
LoraDevice ID of the LoRaWAN device
Sim SIM ID of the IoT SIM
SigfoxDevice ID of the Sigfox device
Device ID of the Inventory device
SoraCam Device ID of the compatible camera device
query Parameters
from
integer

Start time for the data entries search range (UNIX time in milliseconds).

to
integer

End time for the data entries search range (UNIX time in milliseconds).

sort
string
Default: "desc"
Enum: "desc" "asc"

Sort order of the data entries. Either descending (latest data entry first) or ascending (oldest data entry first).

limit
integer [ 1 .. 1000 ]

Maximum number of data entries to retrieve (value range is 1 to 1000). The default is 10.

last_evaluated_key
string

The value of the x-soracom-next-key header from the previous response. Specify this to retrieve the next page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Deletes a data entry

Deletes a data entry identified with resource ID and timestamp

Authorizations:
(api_keyapi_token)
path Parameters
resource_type
required
string
Enum: "Subscriber" "LoraDevice" "Sim" "SigfoxDevice" "Device" "SoraCam"

Type of data source resource.

resource_id
required
string

ID of data source resource. The ID to be specified depends on the value of resource_type.

resource_type The ID you specify
Subscriber IMSI of the IoT SIM
LoraDevice ID of the LoRaWAN device
Sim SIM ID of the IoT SIM
SigfoxDevice ID of the Sigfox device
Device ID of the Inventory device
SoraCam Device ID of the compatible camera device
time
required
integer

Timestamp of the target data entry to delete (UNIX time in milliseconds).

Responses

Gets a data entry

Gets a data entry identified with resource ID and timestamp

Authorizations:
(api_keyapi_token)
path Parameters
resource_type
required
string
Enum: "Subscriber" "LoraDevice" "Sim" "SigfoxDevice" "Device" "SoraCam"

Type of data source resource.

resource_id
required
string

ID of data source resource. The ID to be specified depends on the value of resource_type.

resource_type The ID you specify
Subscriber IMSI of the IoT SIM
LoraDevice ID of the LoRaWAN device
Sim SIM ID of the IoT SIM
SigfoxDevice ID of the Sigfox device
Device ID of the Inventory device
SoraCam Device ID of the compatible camera device
time
required
integer

Timestamp of the target data entry to get (UNIX time in milliseconds).

Responses

Response samples

Content type
application/json
{
  • "category": "string",
  • "content": "string",
  • "contentType": "string",
  • "resourceId": "string",
  • "resourceType": "Subscriber",
  • "time": 0
}

Get data entries for a specific category

Returns a list of data entries that belong to a specific category. If the total number of entries does not fit in one page, a URL for accessing the next page is returned in the link header of the response.

Authorizations:
(api_keyapi_token)
path Parameters
category
required
string

Name of the category to filter data entries.

query Parameters
from
integer

Start time for the data entries search range (UNIX time in milliseconds).

to
integer

End time for the data entries search range (UNIX time in milliseconds).

sort
string
Default: "desc"
Enum: "desc" "asc"

Sort order of the data entries. Either descending (latest data entry first) or ascending (oldest data entry first).

limit
integer [ 1 .. 1000 ]

Maximum number of data entries to retrieve (value range is 1 to 1000). The default is 10.

last_evaluated_key
string

The value of the x-soracom-next-key header from the previous response. Specify this to retrieve the next page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the list of data source resources

Returns a list of data source resources that have sent data. If the total number of data source resources does not fit in one page, a URL for accessing the next page is returned in the link header of the response.

Authorizations:
(api_keyapi_token)
query Parameters
resource_type
string
Enum: "Subscriber" "LoraDevice" "Sim" "SigfoxDevice" "Device" "SoraCam"

Type of data source resource.

  • Subscriber: IoT SIM.
  • LoraDevice: LoRaWAN device.
  • Sim: IoT SIM.
  • SigfoxDevice: Sigfox device.
  • Device: Inventory device.
  • SoraCam: Compatible camera device.
limit
integer

Maximum number of data entries to retrieve.

last_evaluated_key
string

The value of the x-soracom-next-key header from the previous response. Specify this to retrieve the next page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the list of data source resources Deprecated

Returns a list of data source resources that have sent data. If the total number of data source resources does not fit in one page, a URL for accessing the next page is returned in the link header of the response.

Authorizations:
(api_keyapi_token)
query Parameters
resource_type
string
Enum: "Subscriber" "LoraDevice" "Sim" "SigfoxDevice" "Device" "SoraCam"

Type of data source resource.

  • Subscriber: IoT SIM.
  • LoraDevice: LoRaWAN device.
  • Sim: IoT SIM.
  • SigfoxDevice: Sigfox device.
  • Device: Inventory device.
  • SoraCam: Compatible camera device.
limit
integer

Maximum number of data entries to retrieve.

last_evaluated_key
string

The value of the x-soracom-next-key header from the previous response. Specify this to retrieve the next page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Returns a list of device object models

Returns a list of device object models

Authorizations:
(api_keyapi_token)
query Parameters
last_evaluated_key
string

ID of the last device object model in the previous page. By specifying this parameter, you can continue to retrieve the list from the next device object models onward.

limit
integer <int32>
Default: -1

Max number of device object models in a response

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a new device object model

Creates a new device object model

Authorizations:
(api_keyapi_token)
Request Body schema:
required
createdTime
string <date-time>
format
string
Enum: "xml" "json"
lastModifiedTime
string <date-time>
objectId
string
objectName
string
operatorId
string
scope
string

Responses

Request samples

Content type
{
  • "createdTime": "2019-08-24T14:15:22Z",
  • "format": "xml",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "objectId": "string",
  • "objectName": "string",
  • "operatorId": "string",
  • "scope": "string"
}

Response samples

Content type
application/json
{
  • "createdTime": "2019-08-24T14:15:22Z",
  • "format": "xml",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "objectId": "string",
  • "objectName": "string",
  • "operatorId": "string",
  • "scope": "string"
}

Deletes a device object model

Deletes a device object model

Authorizations:
(api_keyapi_token)
path Parameters
model_id
required
string

Target device object model ID

Responses

Gets a device object model

Gets a device object model

Authorizations:
(api_keyapi_token)
path Parameters
model_id
required
string

Target device object model ID

Responses

Response samples

Content type
application/json
{
  • "createdTime": "2019-08-24T14:15:22Z",
  • "format": "xml",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "objectId": "string",
  • "objectName": "string",
  • "operatorId": "string",
  • "scope": "string"
}

Updates a device object model

Updates a device object model

Authorizations:
(api_keyapi_token)
path Parameters
model_id
required
string

Target device object model ID

Request Body schema:
required
createdTime
string <date-time>
format
string
Enum: "xml" "json"
lastModifiedTime
string <date-time>
objectId
string
objectName
string
operatorId
string
scope
string

Responses

Request samples

Content type
{
  • "createdTime": "2019-08-24T14:15:22Z",
  • "format": "xml",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "objectId": "string",
  • "objectName": "string",
  • "operatorId": "string",
  • "scope": "string"
}

Response samples

Content type
application/json
{
  • "createdTime": "2019-08-24T14:15:22Z",
  • "format": "xml",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "objectId": "string",
  • "objectName": "string",
  • "operatorId": "string",
  • "scope": "string"
}

Sets scope for a device object model

Sets scope for a device object model

Authorizations:
(api_keyapi_token)
path Parameters
model_id
required
string

Target device object model ID

Request Body schema: application/json
required

Scope value that is applied to the target device object model

scope
string

Responses

Request samples

Content type
application/json
{
  • "scope": "string"
}

Response samples

Content type
application/json
{
  • "createdTime": "2019-08-24T14:15:22Z",
  • "format": "xml",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "objectId": "string",
  • "objectName": "string",
  • "operatorId": "string",
  • "scope": "string"
}

Returns a list of Devices

Returns a list of Devices

Authorizations:
(api_keyapi_token)
query Parameters
tag_name
string

Tag name

tag_value
string

Tag value

tag_value_match_mode
string

Tag value match mode (exact | prefix)

last_evaluated_key
string

ID of the last Device in the previous page. By specifying this parameter, you can continue to retrieve the list from the next device onward.

limit
integer <int32>
Default: -1

Max number of Devices in a response

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a new Device

Creates a new Device

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

Device to create

device_id
string
endpoint
string
firmwareVersion
string
groupId
string
ipAddress
string
lastModifiedTime
string <date-time>
lastRegistrationUpdate
string <date-time>
manufacturer
string
modelNumber
string
objects
object
online
boolean
Default: false
operatorId
string
registrationId
string
registrationLifeTime
integer <int64>
serialNumber
string
object

Responses

Request samples

Content type
application/json
{
  • "device_id": "string",
  • "endpoint": "string",
  • "firmwareVersion": "string",
  • "groupId": "string",
  • "ipAddress": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastRegistrationUpdate": "2019-08-24T14:15:22Z",
  • "manufacturer": "string",
  • "modelNumber": "string",
  • "objects": { },
  • "online": false,
  • "operatorId": "string",
  • "registrationId": "string",
  • "registrationLifeTime": 0,
  • "serialNumber": "string",
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "endpoint": "string",
  • "firmwareVersion": "string",
  • "groupId": "string",
  • "ipAddress": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastRegistrationUpdate": "2019-08-24T14:15:22Z",
  • "manufacturer": "string",
  • "modelNumber": "string",
  • "objects": { },
  • "online": false,
  • "operatorId": "string",
  • "registrationId": "string",
  • "registrationLifeTime": 0,
  • "serialNumber": "string",
  • "tags": {
    }
}

Delete Device

Delete Device

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device to delete

Responses

Returns a Device identified by device ID

Returns a Device identified by device ID

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID

query Parameters
model
boolean
Default: false

Whether or not to add model information

Responses

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "endpoint": "string",
  • "firmwareVersion": "string",
  • "groupId": "string",
  • "ipAddress": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastRegistrationUpdate": "2019-08-24T14:15:22Z",
  • "manufacturer": "string",
  • "modelNumber": "string",
  • "objects": { },
  • "online": false,
  • "operatorId": "string",
  • "registrationId": "string",
  • "registrationLifeTime": 0,
  • "serialNumber": "string",
  • "tags": {
    }
}

Get resources under an object instance of a device

Get resources under an object instance of a device

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Target device

object
required
string

Object ID

instance
required
string

Instance ID

query Parameters
model
boolean
Default: false

Whether or not to add model information

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "observed": false,
  • "resources": {
    }
}

Get the specified resource of a device

Get the specified resource of a device

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Target device

object
required
string

Object ID

instance
required
string

Instance ID

resource
required
string

Resource ID

query Parameters
model
boolean
Default: false

Whether or not to add model information

Responses

Response samples

Content type
application/json
{
  • "description": "string",
  • "id": 0,
  • "mandatory": false,
  • "multiple": false,
  • "name": "string",
  • "observed": false,
  • "operations": "NONE",
  • "rangeEnumeration": "string",
  • "type": "STRING",
  • "units": "string",
  • "value": { },
  • "values": { }
}

Write value to a resource of a device

Write value to a resource of a device

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Target device

object
required
string

Object ID

instance
required
string

Instance ID

resource
required
string

Resource ID

Request Body schema: application/json
required

Value(s) to write to the resource. This value accepts LwM2M basic data types. You have to use the property name values (instead of value) with an array value if the resource model is multiple-mode.

string or number or boolean

Responses

Request samples

Content type
application/json
{
  • "value": "string"
}

Executes a resource of a device

Executes a resource of a device

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Target device

object
required
string

Object ID

instance
required
string

Instance ID

resource
required
string

Resource ID

Request Body schema: application/json

Argument string when executing the resource

value
string

Responses

Request samples

Content type
application/json
{
  • "value": "string"
}

Triggers observation of the specified resource of a device

Triggers observation of the specified resource of a device. Once observation is started, the server will be notified when there is a change in value on the device side.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Target device

object
required
string

Object ID

instance
required
string

Instance ID

resource
required
string

Resource ID

query Parameters
model
boolean
Default: false

Whether or not to add model information

Responses

Stops observation of a resource of a device

Stops observation of a resource of a device

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Target device

object
required
string

Object ID

instance
required
string

Instance ID

resource
required
string

Resource ID

Responses

Triggers observation of resources under an object instance of a device

Triggers observation of resources under an object instance of a device

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Target device

object
required
string

Object ID

instance
required
string

Instance ID

query Parameters
model
boolean
Default: false

Whether or not to add model information

Responses

Stops observation of resources under an object instance of a device

Stops observation of resources under an object instance of a device

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Target device

object
required
string

Object ID

instance
required
string

Instance ID

Responses

Retrieves data sent from an Inventory device to Harvest Data

Retrieves data that matches the specified conditions from the data sent by the specified Inventory device to Harvest Data. If the data entries do not fit in one page, a URL to retrieve the next page with the same conditions will be included in the link header of the response.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

ID of the Inventory device from which to retrieve data. The ID of an Inventory device can be obtained using the Device:listDevices API.

query Parameters
from
integer

Start time of the target period (UNIX time in milliseconds).

to
integer

End time of the target period (UNIX time in milliseconds).

sort
string
Default: "desc"
Enum: "desc" "asc"

Sort order of data entries. Either descending order (latest data entry first) or ascending order (oldest data entry first).

limit
integer [ 1 .. 1000 ]

Maximum number of data entries to retrieve (1 to 1000). The default is 10.

last_evaluated_key
string

Timestamp of the last data entry retrieved on the previous page. By specifying this parameter, the list starting from the next data entry can be obtained.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Adds an Inventory device to an Inventory group

Adds an Inventory device to an Inventory group.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target Inventory device.

Request Body schema: application/json
required
groupId
string

Group ID. The group ID can be obtained using the Group:listGroups API.

Responses

Request samples

Content type
application/json
{
  • "groupId": "string"
}

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "endpoint": "string",
  • "firmwareVersion": "string",
  • "groupId": "string",
  • "ipAddress": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastRegistrationUpdate": "2019-08-24T14:15:22Z",
  • "manufacturer": "string",
  • "modelNumber": "string",
  • "objects": { },
  • "online": false,
  • "operatorId": "string",
  • "registrationId": "string",
  • "registrationLifeTime": 0,
  • "serialNumber": "string",
  • "tags": {
    }
}

Updates device tags

Updates device tags

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device to update

Request Body schema: application/json
required

Array of values for tags to be updated.

Array
tagName
required
string
tagValue
required
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "endpoint": "string",
  • "firmwareVersion": "string",
  • "groupId": "string",
  • "ipAddress": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastRegistrationUpdate": "2019-08-24T14:15:22Z",
  • "manufacturer": "string",
  • "modelNumber": "string",
  • "objects": { },
  • "online": false,
  • "operatorId": "string",
  • "registrationId": "string",
  • "registrationLifeTime": 0,
  • "serialNumber": "string",
  • "tags": {
    }
}

Delete device tag

Delete device tag

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device to update

tag_name
required
string

Name of tag to delete

Responses

Removes an Inventory device from an Inventory group

Removes an Inventory device from an Inventory group.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target Inventory device.

Responses

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "endpoint": "string",
  • "firmwareVersion": "string",
  • "groupId": "string",
  • "ipAddress": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastRegistrationUpdate": "2019-08-24T14:15:22Z",
  • "manufacturer": "string",
  • "modelNumber": "string",
  • "objects": { },
  • "online": false,
  • "operatorId": "string",
  • "registrationId": "string",
  • "registrationLifeTime": 0,
  • "serialNumber": "string",
  • "tags": {
    }
}

Send diagnostic request

Send a diagnostic request.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

request

from
integer <int64>

Start time for diagnostic (UNIX time in milliseconds).

resourceId
required
string

Identifier according to resourceType.

  • If resourceType is sim, specify the SIM ID.
resourceType
required
string
Value: "sim"
service
required
string
Value: "Air"
to
integer <int64>

End time for diagnostic (UNIX time in milliseconds).

Responses

Request samples

Content type
application/json
{
  • "from": 1655251200000,
  • "resouceType": "sim",
  • "resourceId": "XXXXXXXXXXXXXXXXXXX",
  • "service": "Air",
  • "to": 1655337600000
}

Response samples

Content type
application/json
{
  • "diagnosticId": "string",
  • "from": 0,
  • "insights": [
    ],
  • "resourceId": "string",
  • "resourceType": "sim",
  • "service": "Air",
  • "status": "diagnosing",
  • "to": 0
}

Get diagnostic

Returns a diagnostic.

Authorizations:
(api_keyapi_token)
path Parameters
diagnostic_id
required
string

The identifier of diagnostic request.

Responses

Response samples

Content type
application/json
{
  • "diagnosticId": "string",
  • "from": 0,
  • "insights": [
    ],
  • "resourceId": "string",
  • "resourceType": "sim",
  • "service": "Air",
  • "status": "diagnosing",
  • "to": 0
}

EventHandler

Event handlers

List Event Handlers

Returns a list of event handlers.

Authorizations:
(api_keyapi_token)
query Parameters
target
string
Enum: "operator" "imsi" "sim" "group"

The event handler target (the target for executing events).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Event Handler

Creates a new event handler. Please see also https://developers.soracom.io/en/docs/air/event-handler/.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

Event handler settings.

required
Array of objects (ActionConfig)

Action type. For more details, refer to Actions.

description
string

Summary.

name
required
string

Event name.

required
object (RuleConfig)
status
required
string
Enum: "inactive" "active"

The status of the event handler, whether it is active or inactive.

  • active: Active
  • inactive: Inactive
targetGroupId
string

The target group. All IoT SIMs belonging to the group are monitored.

Specify only one of targetGroupId, targetImsi, targetOperatorId, or targetSimId.

targetImsi
string

The target IMSI of the IoT SIM.

Specify only one of targetGroupId, targetImsi, targetOperatorId, or targetSimId.

targetOperatorId
string

The target operator. All IoT SIMs in your account.

Specify only one of targetGroupId, targetImsi, targetOperatorId, or targetSimId.

targetSimId
string

The target SIM ID of the IoT SIM.

Specify only one of targetGroupId, targetImsi, targetOperatorId, or targetSimId.

Responses

Request samples

Content type
application/json
Example
{
  • "actionConfigList": [
    ],
  • "description": "Sample description",
  • "name": "Event handler",
  • "ruleConfig": {
    },
  • "status": "active",
  • "targetImsi": "xxxxxxxxxxxxxxx"
}

Response samples

Content type
application/json
{
  • "actionConfigList": [
    ],
  • "description": "string",
  • "handlerId": "string",
  • "name": "string",
  • "ruleConfig": {
    },
  • "status": "inactive",
  • "targetGroupId": "string",
  • "targetImsi": "string",
  • "targetOperatorId": "string",
  • "targetSimId": "string"
}

Delete Event Handler

Deletes the specified event handler.

Authorizations:
(api_keyapi_token)
path Parameters
handler_id
required
string

Event handler ID.

Responses

Get Event Handler

Returns information about the specified event handler.

Authorizations:
(api_keyapi_token)
path Parameters
handler_id
required
string

Event handler ID.

Responses

Response samples

Content type
application/json
{
  • "actionConfigList": [
    ],
  • "description": "string",
  • "handlerId": "string",
  • "name": "string",
  • "ruleConfig": {
    },
  • "status": "inactive",
  • "targetGroupId": "string",
  • "targetImsi": "string",
  • "targetOperatorId": "string",
  • "targetSimId": "string"
}

Update Event Handler

Updates the specified event handler. Please see also https://developers.soracom.io/en/docs/air/event-handler/.

Authorizations:
(api_keyapi_token)
path Parameters
handler_id
required
string

Event handler ID.

Request Body schema: application/json
required

Event handler settings.

required
Array of objects (ActionConfig)

Action type. For more details, refer to Actions.

description
string

Summary.

name
required
string

Event name.

required
object (RuleConfig)
status
required
string
Enum: "inactive" "active"

The status of the event handler, whether it is active or inactive.

  • active: Active
  • inactive: Inactive
targetGroupId
string

The target group. All IoT SIMs belonging to the group are monitored.

Specify only one of targetGroupId, targetImsi, targetOperatorId, or targetSimId.

targetImsi
string

The target IMSI of the IoT SIM.

Specify only one of targetGroupId, targetImsi, targetOperatorId, or targetSimId.

targetOperatorId
string

The target operator. All IoT SIMs in your account.

Specify only one of targetGroupId, targetImsi, targetOperatorId, or targetSimId.

targetSimId
string

The target SIM ID of the IoT SIM.

Specify only one of targetGroupId, targetImsi, targetOperatorId, or targetSimId.

Responses

Request samples

Content type
application/json
{
  • "actionConfigList": [
    ],
  • "description": "string",
  • "name": "string",
  • "ruleConfig": {
    },
  • "status": "inactive",
  • "targetGroupId": "string",
  • "targetImsi": "string",
  • "targetOperatorId": "string",
  • "targetSimId": "string"
}

Delete Ignore Event Handler

Deletes the setting for ignoring the specified event handler of the specified IMSI.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

IMSI.

handler_id
required
string

Event handler ID.

Responses

Ignore Event Handler

Adds a setting for ignoring the specified event handler of the specified IMSI.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

IMSI.

handler_id
required
string

Event handler ID.

Responses

List Event Handlers related to Subscriber

Returns a list of event handlers related to the specified IMSI.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

IMSI.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Find files with prefix query parameter in the scope

Returns a list of file entries which beginnings of their file paths are matched with the prefix query string in the ascending sorted UTF-8 bytes order of their file paths. An empty list is returned if the prefix does not match with any paths of file entries.

Authorizations:
(api_keyapi_token)
query Parameters
scope
required
string
Enum: "private" "public"

Scope of the request. Specify private to handle files uploaded to Harvest Files.

prefix
required
string

Prefix to match with file path.

limit
integer
Default: 10

Maximum number of file entries to be returned.

last_evaluated_key
string

The filePath of the last file entry retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next file entry onward.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Deletes the file specified by scope and path.

Deletes the file specified by scope and path. Only private scope is allowed for the operation.

Authorizations:
(api_keyapi_token)
path Parameters
scope
required
string
Default: "private"
Value: "private"

Scope of the request. Specify private to handle files uploaded to Harvest Files.

path
required
string

Target path.

Responses

Download file specified by the path and the scope

Download file specified by the path and the scope. Note that FileEntry:listFiles API will be called if the path ends with /.

Authorizations:
(api_keyapi_token)
path Parameters
scope
required
string
Default: "private"
Enum: "private" "public"

Scope of the request. Specify private to handle files uploaded to Harvest Files.

path
required
string

Target path.

Responses

Gets the metadata of the file specified by the path and the scope

Gets the metadata of the file specified by the path and the scope.

Authorizations:
(api_keyapi_token)
path Parameters
scope
required
string
Default: "private"
Enum: "private" "public"

Scope of the request. Specify private to handle files uploaded to Harvest Files.

path
required
string

Target path.

Responses

Uploads the file to the specified path in the scope.

Uploads the file to the specified path in the scope. Only private scope is allowed for the operation.

Authorizations:
(api_keyapi_token)
path Parameters
scope
required
string
Default: "private"
Value: "private"

Scope of the request. Specify private to handle files uploaded to Harvest Files.

path
required
string

Target path.

header Parameters
content-type
string

Content-Type of the file to be uploaded.

Request Body schema: */*
required

Contents of the file to be updated.

string <binary>

Responses

Deletes the directory specified by scope and path

Deletes the directory specified by scope and path. Only private scope is allowed for the operation.

Authorizations:
(api_keyapi_token)
path Parameters
scope
required
string
Default: "private"
Value: "private"

Scope of the request. Specify private to handle files uploaded to Harvest Files.

path
required
string

Target path.

Responses

Returns files and directories from the directory specified by the scope and path.

Returns files and directories from the directory specified by the scope and path. Note that FileEntry:getFile API will be called if the path does not end in /. If the total number of entries does not fit in one page, a URL for accessing the next page is returned in the link header of the response.

Authorizations:
(api_keyapi_token)
path Parameters
scope
required
string
Default: "private"
Enum: "private" "public"

Scope of the request. Specify private to handle files uploaded to Harvest Files.

path
required
string
Default: "/"

Target path.

query Parameters
limit
integer
Default: 10

Maximum number of file entries to be returned.

last_evaluated_key
string

The filename of the last file entry retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next file entry onward.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Files

Download files exported by the following APIs:

Get the progress of the process when the file is exported asynchronously.

Get the progress of the process when the file is exported asynchronously. If the export is complete, you will get the URL to download the file. You can download the file from the URL.

The following APIs are available to export files asynchronously. The exported_file_id is the file output ID (the value of exportedFileId) obtained from the following API.

Authorizations:
(api_keyapi_token)
path Parameters
exported_file_id
required
string

File export ID.

Responses

Response samples

Content type
application/json
{}

Gadget

Gadget API compatible devices

List gadgets

Returns a list of gadgets that match certain criteria. If the total number of gadgets does not fit in one page, a URL for accessing the next page is returned in the link header of the response.

Authorizations:
(api_keyapi_token)
query Parameters
product_id
string
Enum: "button" "wimax"

Product ID of the target Gadget API compatible device for filtering the search.

  • wimax: Soracom Cloud Camera Services Cellular Pack.
tag_name
string

Tag name for filtering the search. The search is always an exact match, regardless of the setting of tag_value_match_mode.

tag_value
string

Specifies a tag value to search for in a URL-encoded (percent-encoded) string. Required when tag_name has been specified.

tag_value_match_mode
string
Default: "exact"
Enum: "exact" "prefix"

Tag match mode.

  • exact: exact match.
  • prefix: prefix match.
limit
integer

Maximum number of Gadget API compatible devices data to retrieve.

last_evaluated_key
string

The ID ({product_id}/{serial_number}) of the last gadget retrieved on the previous page in URL encoding (percent encoding).

By specifying this parameter, you can continue to retrieve the list from the next Gadget API compatible device onward.

The value of the last_evaluated_key of rel=next returned in the link header when the API is called is expected to be specified in the next call, but any ID ({productId}/{serialNumber}) can be specified.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Gadget API compatible device

Returns information about the specified Gadget API compatible device.

Authorizations:
(api_keyapi_token)
path Parameters
product_id
required
string
Enum: "button" "wimax"

Product ID of the target Gadget API compatible device.

  • wimax: Soracom Cloud Camera Services Cellular Pack.
serial_number
required
string

Serial Number of the target Gadget API compatible device.

Responses

Response samples

Content type
application/json
{
  • "attributes": {
    },
  • "createdTime": 0,
  • "id": "string",
  • "lastModifiedTime": 0,
  • "operatorId": "string",
  • "productId": "button",
  • "serialNumber": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminatedTime": 0,
  • "terminationEnabled": false
}

Disables Termination of Gadget API compatible device

Disables termination of specified Gadget API compatible device.

Authorizations:
(api_keyapi_token)
path Parameters
product_id
required
string
Enum: "button" "wimax"

Product ID of the target Gadget API compatible device.

  • wimax: Soracom Cloud Camera Services Cellular Pack.
serial_number
required
string

Serial Number of the target Gadget API compatible device.

Responses

Response samples

Content type
application/json
{
  • "attributes": {
    },
  • "createdTime": 0,
  • "id": "string",
  • "lastModifiedTime": 0,
  • "operatorId": "string",
  • "productId": "button",
  • "serialNumber": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminatedTime": 0,
  • "terminationEnabled": false
}

Enables Termination of Gadget API compatible device

Enables termination of specified Gadget API compatible device.

Authorizations:
(api_keyapi_token)
path Parameters
product_id
required
string
Enum: "button" "wimax"

Product ID of the target Gadget API compatible device.

  • wimax: Soracom Cloud Camera Services Cellular Pack.
serial_number
required
string

Serial Number of the target Gadget API compatible device.

Responses

Response samples

Content type
application/json
{
  • "attributes": {
    },
  • "createdTime": 0,
  • "id": "string",
  • "lastModifiedTime": 0,
  • "operatorId": "string",
  • "productId": "button",
  • "serialNumber": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminatedTime": 0,
  • "terminationEnabled": false
}

Registers a Gadget API compatible device

Registers a Gadget API compatible device.

Authorizations:
(api_keyapi_token)
path Parameters
product_id
required
string
Enum: "button" "wimax"

Product ID of the target Gadget API compatible device.

  • wimax: Soracom Cloud Camera Services Cellular Pack.
serial_number
required
string

Serial Number of the target Gadget API compatible device.

Request Body schema: application/json
required

Gadget registration request.

object

Tags.

Responses

Request samples

Content type
application/json
{
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "attributes": {
    },
  • "createdTime": 0,
  • "id": "string",
  • "lastModifiedTime": 0,
  • "operatorId": "string",
  • "productId": "button",
  • "serialNumber": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminatedTime": 0,
  • "terminationEnabled": false
}

Bulk Insert or Update Gadget API compatible device tags

Inserts/updates tags for the specified Gadget API compatible device.

Authorizations:
(api_keyapi_token)
path Parameters
product_id
required
string
Enum: "button" "wimax"

Product ID of the target Gadget API compatible device.

  • wimax: Soracom Cloud Camera Services Cellular Pack.
serial_number
required
string

Serial Number of the target Gadget API compatible device.

Request Body schema: application/json
required

Array of tags to be inserted/updated.

Array
tagName
required
string
tagValue
required
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "attributes": {
    },
  • "createdTime": 0,
  • "id": "string",
  • "lastModifiedTime": 0,
  • "operatorId": "string",
  • "productId": "button",
  • "serialNumber": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminatedTime": 0,
  • "terminationEnabled": false
}

Deletes tags from Gadget API compatible device

Deletes a tag from the specified Gadget API compatible device.

Authorizations:
(api_keyapi_token)
path Parameters
product_id
required
string
Enum: "button" "wimax"

Product ID of the target Gadget API compatible device.

  • wimax: Soracom Cloud Camera Services Cellular Pack.
serial_number
required
string

Serial Number of the target Gadget API compatible device.

tag_name
required
string

Tag name to be deleted. (This will be part of a URL path, so it needs to be percent-encoded. In JavaScript, specify the name after it has been encoded using encodeURIComponent().)

Responses

Terminates the specified Gadget API compatible device

Terminates the specified Gadget API compatible device.

Authorizations:
(api_keyapi_token)
path Parameters
product_id
required
string
Enum: "button" "wimax"

Product ID of the target Gadget API compatible device.

  • wimax: Soracom Cloud Camera Services Cellular Pack.
serial_number
required
string

Serial Number of the target Gadget API compatible device.

Responses

Response samples

Content type
application/json
{
  • "attributes": {
    },
  • "createdTime": 0,
  • "id": "string",
  • "lastModifiedTime": 0,
  • "operatorId": "string",
  • "productId": "button",
  • "serialNumber": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminatedTime": 0,
  • "terminationEnabled": false
}

List Groups.

Returns a list of Groups.

Authorizations:
(api_keyapi_token)
query Parameters
tag_name
string

Tag name of the group. Filters through all groups that exactly match the tag name. When tag_name is specified, tag_value is required.

tag_value
string

Tag value of the groups.

tag_value_match_mode
string
Default: "exact"
Enum: "exact" "prefix"

Search criteria for tag strings (tag_value).

limit
integer

Maximum number of results per response page.

last_evaluated_key
string

The last Group ID retrieved on the current page. By specifying this parameter, you can continue to retrieve the list from the next group onward.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Group

Create a new group.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

Tags and configuration for a new group to be created.

object (GroupConfiguration)
object (TagSet)

An object which always contains at least one property "name" with a string value. If you give a subscriber/SIM a name, the name will be returned as the value of the "name" property. If the subscriber/SIM does not have a name, an empty string "" is returned. In addition, if you create any custom tags for the subscriber/SIM, each custom tag will appear as additional properties in the object.

Responses

Request samples

Content type
application/json
{
  • "configuration": {
    },
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "configuration": {
    },
  • "createdAt": 1698796800000,
  • "createdTime": 1698796800000,
  • "groupId": "12345678-abcd-9012-efab-345678901234",
  • "lastModifiedAt": 1698796800000,
  • "lastModifiedTime": 1698796800000,
  • "operatorId": "OP0012345678",
  • "tags": {
    }
}

Delete Group

Deletes the group specified by Group ID.

Authorizations:
(api_keyapi_token)
path Parameters
group_id
required
string

ID of the target Group.

Responses

Get Group

Returns the group specified by the group ID.

Authorizations:
(api_keyapi_token)
path Parameters
group_id
required
string

ID of the target Group.

Responses

Response samples

Content type
application/json
{
  • "configuration": {
    },
  • "createdTime": 0,
  • "groupId": "string",
  • "lastModifiedTime": 0,
  • "operatorId": "string",
  • "tags": {
    }
}

Delete Group Configuration Namespace

Delete a namespace for the specified group.

Authorizations:
(api_keyapi_token)
path Parameters
group_id
required
string

ID of the target Group.

namespace
required
string
Enum: "SoracomAir" "SoracomBeam" "SoracomEndorse" "SoracomOrbit" "SoracomFlux" "SoracomFunk" "SoracomFunnel" "SoracomHarvest" "SoracomHarvestFiles" "SoracomKrypton" "UnifiedEndpoint"

Namespace to be deleted.

Responses

Update group configuration

Updates the configuration of the specified group.

Authorizations:
(api_keyapi_token)
path Parameters
group_id
required
string

ID of the target group. The group ID can be obtained via the Group:listGroups API.

namespace
required
string
Enum: "SoracomAir" "SoracomBeam" "SoracomEndorse" "SoracomFlux" "SoracomFunk" "SoracomFunnel" "SoracomHarvest" "SoracomHarvestFiles" "SoracomKrypton" "SoracomOrbit" "UnifiedEndpoint"

A string indicating the configuration target. It varies depending on the configuration content.

  • SoracomAir: SORACOM Air for Cellular (Custom DNS, Metadata Service, VPG, CHAP Authentication, Simple Location Tracking, Binary Parser, IP Link MTU Configuration).
  • SoracomBeam: SORACOM Beam.
  • SoracomEndorse: SORACOM Endorse.
  • SoracomFlux: SORACOM Flux.
  • SoracomFunk: SORACOM Funk.
  • SoracomFunnel: SORACOM Funnel.
  • SoracomHarvest: SORACOM Harvest Data.
  • SoracomHarvestFiles: SORACOM Harvest Files.
  • SoracomKrypton: SORACOM Krypton.
  • SoracomOrbit: SORACOM Orbit.
  • UnifiedEndpoint: Unified Endpoint.
Request Body schema: application/json
required

Group configuration. This operation updates a value of the specified key in the namespace.

Select [Examples] below and then click the [Example Value] tab to view sample request bodies.

Array
key
required
string
value
required
any

Responses

Request samples

Content type
application/json
Example

When configuring Custom DNS for IoT SIM, please note the following points.

  • Specify SoracomAir for the namespace path parameter.
  • For more information about the key and value pairs, refer to Advanced Configuration.
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "configuration": {
    },
  • "createdTime": 0,
  • "groupId": "string",
  • "lastModifiedTime": 0,
  • "operatorId": "string",
  • "tags": {
    }
}

Delete Group Configuration Parameters

Delete parameters for the specified group.

Authorizations:
(api_keyapi_token)
path Parameters
group_id
required
string

ID of the target Group.

namespace
required
string
Enum: "SoracomAir" "SoracomBeam" "SoracomEndorse" "SoracomFlux" "SoracomFunk" "SoracomFunnel" "SoracomHarvest" "SoracomHarvestFiles" "SoracomKrypton" "UnifiedEndpoint"

Namespace of target parameters.

name
required
string

Parameter name to be deleted. (This will be part of a URL path, so it needs to be percent-encoded. In JavaScript, specify the name after it has been encoded using encodeURIComponent().)

Responses

List Subscribers in a group

Returns a list of subscribers that belong to the specified group by group ID.

Authorizations:
(api_keyapi_token)
path Parameters
group_id
required
string

ID of the target Group.

query Parameters
limit
integer

Maximum number of results per response page.

last_evaluated_key
string

The IMSI of the last subscriber retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next subscriber onward.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update Group Tags

Adds/updates tags of specified configuration group.

Authorizations:
(api_keyapi_token)
path Parameters
group_id
required
string

ID of the target Group.

Request Body schema: application/json
required

Array of values for tags to be updated.

Array
tagName
required
string
tagValue
required
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "configuration": {
    },
  • "createdTime": 0,
  • "groupId": "string",
  • "lastModifiedTime": 0,
  • "operatorId": "string",
  • "tags": {
    }
}

Delete Group Tag

Deletes tag from the specified group.

Authorizations:
(api_keyapi_token)
path Parameters
group_id
required
string

ID of the target Group.

tag_name
required
string

Tag name to be deleted. (This will be part of a URL path, so it needs to be percent-encoded. In JavaScript, specify the name after it has been encoded using encodeURIComponent().)

Responses

Lagoon

Soracom Lagoon User and plan management

Get the status of active Soracom Lagoon license packs

Get the status of active Soracom Lagoon license packs.

Authorizations:
(api_keyapi_token)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update the quantities for license packs of Soracom Lagoon

Update the quantities for license packs of Soracom Lagoon.

Warning: This API must be called with the root user credentials. The quantities for license packs of Soracom Lagoon cannot be updated with SAM user credentials.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

Request.

Array of objects

Responses

Request samples

Content type
application/json
{
  • "licensePackQuantities": [
    ]
}

Update the plan of Soracom Lagoon

Update the plan of Soracom Lagoon.

Warning: This API must be called with the root user credentials. The plan of Lagoon cannot be updated with SAM user credentials.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required
plan
string
Enum: "maker" "pro" "free"

Responses

Request samples

Content type
application/json
{
  • "plan": "maker"
}

Register (activate) Soracom Lagoon

Register (activate) Soracom Lagoon.

Warning: This API must be called with the root user credentials. Lagoon cannot be registered with SAM user credentials.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

Request.

plan
string
Enum: "free" "maker" "pro"
userPassword
string

This password is used by the initial user's login.

Responses

Request samples

Content type
application/json
{
  • "plan": "free",
  • "userPassword": "string"
}

Response samples

Content type
application/json
{
  • "lagoonUserEmail": "string"
}

Terminate (deactivate) Soracom Lagoon

Terminate (deactivate) Soracom Lagoon.

Warning: This API must be called with the root user credentials. Lagoon cannot be terminated with SAM user credentials.

Authorizations:
(api_keyapi_token)

Responses

List Soracom Lagoon users that belong to operator

List Soracom Lagoon users that belong to operator.

Authorizations:
(api_keyapi_token)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a Soracom Lagoon user

Create a Soracom Lagoon user.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

Request.

role
string
Enum: "Viewer" "Editor"

A role that represents the permission.

userEmail
string
userPassword
string

Responses

Request samples

Content type
application/json
{
  • "role": "Viewer",
  • "userEmail": "string",
  • "userPassword": "string"
}

Response samples

Content type
application/json
{
  • "id": 0
}

Delete a Soracom Lagoon user

Delete a Soracom Lagoon user.

Authorizations:
(api_keyapi_token)
path Parameters
lagoon_user_id
required
integer

Target ID of the lagoon user.

Responses

Update email address of a Soracom Lagoon user

Update email address of a Soracom Lagoon user.

Authorizations:
(api_keyapi_token)
path Parameters
lagoon_user_id
required
integer

Target ID of the lagoon user.

Request Body schema: application/json
required

Request.

userEmail
string

Responses

Request samples

Content type
application/json
{
  • "userEmail": "string"
}

Update password of a Soracom Lagoon user

Update password of a Soracom Lagoon user.

Authorizations:
(api_keyapi_token)
path Parameters
lagoon_user_id
required
integer

Target ID of the lagoon user.

Request Body schema: application/json
required

Request.

newPassword
string
oldPassword
string

Responses

Request samples

Content type
application/json
{
  • "newPassword": "string",
  • "oldPassword": "string"
}

Update permission of a Soracom Lagoon user

Update permission of a Soracom Lagoon user.

Authorizations:
(api_keyapi_token)
path Parameters
lagoon_user_id
required
integer

Target ID of the lagoon user.

Request Body schema: application/json
required

Request.

role
string
Enum: "Viewer" "Editor"

A role that represents the permission.

Responses

Request samples

Content type
application/json
{
  • "role": "Viewer"
}

Log

Error logs

Retrieve Error Logs

Fetches error logs that meet specified criteria. If the error logs exceed one page, a URL to retrieve the next page under the same conditions is included in the link header of the response.

Authorizations:
(api_keyapi_token)
query Parameters
resource_type
string
Enum: "Subscriber" "Device" "LoraDevice" "SigfoxDevice"

The type of resource for which to retrieve error logs.

  • Subscriber: IoT SIM.
  • Device: Inventory device.
  • LoraDevice: LoRaWAN device.
  • SigfoxDevice: Sigfox device.
resource_id
string

The ID of the resource for which to retrieve error logs. The ID to specify varies depending on the value of resource_type.

resource_type ID to specify
Subscriber The IMSI of the IoT SIM. The IMSI can be obtained from the Sim:listSims API.
Device The ID of the Inventory device. The ID can be obtained from the Device:listDevices API.
LoraDevice The ID of the LoRaWAN device. The ID can be obtained from the LoraDevice:listLoraDevices API.
SigfoxDevice The ID of the Sigfox device. The ID can be obtained from the SigfoxDevice:listSigfoxDevices API.
service
string
Enum: "Air" "Beam" "Funk" "Funnel" "Harvest" "Napter" "Orbit" "Unified"

The service name to filter error logs.

  • Air: SORACOM Air
  • Beam: SORACOM Beam
  • Funk: SORACOM Funk
  • Funnel: SORACOM Funnel
  • Harvest: SORACOM Harvest Data/Files
  • Napter: SORACOM Napter
  • Orbit: SORACOM Orbit
  • Unified: Unified Endpoint
from
integer

Start time of the period for which to retrieve error logs (UNIX time in milliseconds).

to
integer

End time of the period for which to retrieve error logs (UNIX time in milliseconds).

limit
integer

The maximum number of error logs to retrieve.

last_evaluated_key
string

The value contained in the x-soracom-next-key header returned when fetching the previous page. Specify this to retrieve the next page. For more information, see Retrieving Large Amounts of Data (Paging).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

LoraDevice

Soracom Air for LoRaWAN devices

List LoRaWAN devices.

Returns a list of LoRaWAN devices that match certain criteria. If the total number of LoRaWAN devices does not fit in one page, a URL for accessing the next page is returned in the link header of the response.

Authorizations:
(api_keyapi_token)
query Parameters
tag_name
string

Tag name for filtering the search (exact match).

tag_value
string

Tag search string for filtering the search. Required when tag_name has been specified.

tag_value_match_mode
string
Default: "exact"
Enum: "exact" "prefix"

Tag match mode.

limit
integer

Maximum number of LoRaWAN devices to retrieve.

last_evaluated_key
string

The device ID of the last LoRaWAN device retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next LoRaWAN device onward.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get LoRaWAN device.

Returns information about the specified LoRaWAN device.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target LoRaWAN device.

Responses

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "groupId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastSeen": {
    },
  • "operatorId": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Retrieves data sent from a LoRaWAN device to Harvest Data

Retrieves data that matches the specified conditions from the data sent by the specified LoRaWAN device to Harvest Data. If the data entries do not fit in one page, a URL to retrieve the next page with the same conditions will be included in the link header of the response.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

ID of the LoRaWAN device from which to retrieve data. The ID of a LoRaWAN device can be obtained using the LoraDevice:listLoraDevices API.

query Parameters
from
integer

Start time of the target period (UNIX time in milliseconds).

to
integer

End time of the target period (UNIX time in milliseconds).

sort
string
Default: "desc"
Enum: "desc" "asc"

Sort order of data entries. Either descending order (latest data entry first) or ascending order (oldest data entry first).

limit
integer [ 1 .. 1000 ]

Maximum number of data entries to retrieve (1 to 1000). The default is 10.

last_evaluated_key
string

Timestamp of the last data entry retrieved on the previous page. By specifying this parameter, the list starting from the next data entry can be obtained.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Send data to a LoRaWAN device.

Sends data to the specified LoRaWAN device. The data is sent to the LoRa network server, to be sent out to the device using the next available slot. If another message destined for the same LoRaWAN device ID is already waiting to be sent on the LoRa Network Server, the existing message will be discarded, and the new message will be sent instead. Data is discarded if it is not received by the device for a certain period of time (2 hours).

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

ID of the recipient device.

Request Body schema: application/json
required

Binary data encoded as a hexadecimal string. Maximum length of original binary data is 11 octets (22 characters when encoded as a hexadecimal string). The number of characters must be even. fPort can be specified optionally. fPort MUST be equal to or greater than 0. 0 is used for the control plane and 1 or greater values should be used in general. It defaults to 2 to avoid the issues of some devices from some vendors and all invalid values that can not be parsed fallback to 2.

data
string
fPort
integer
Default: 2

Responses

Request samples

Content type
application/json
{
  • "data": "string",
  • "fPort": 2
}

Disable Termination of LoRaWAN device.

Disables termination of specified LoRaWAN device.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target LoRaWAN device.

Responses

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "groupId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastSeen": {
    },
  • "operatorId": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Enable Termination of LoRaWAN device.

Enables termination of specified LoRaWAN device.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target LoRaWAN device.

Responses

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "groupId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastSeen": {
    },
  • "operatorId": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Register LoRaWAN device.

Register a LoRaWAN device.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target LoRaWAN device.

Request Body schema: application/json
required

LoRaWAN Device

groupId
string
registrationSecret
string
object

Responses

Request samples

Content type
application/json
{
  • "groupId": "string",
  • "registrationSecret": "string",
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "groupId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastSeen": {
    },
  • "operatorId": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Adds a LoRaWAN device to a LoRaWAN group

Adds a LoRaWAN device to a LoRaWAN group.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

ID of the target LoRaWAN device. The ID of a LoRaWAN device can be obtained using the LoraDevice:listLoraDevices API.

Request Body schema: application/json
required
groupId
string

Group ID. The group ID can be obtained using the Group:listGroups API.

Responses

Request samples

Content type
application/json
{
  • "groupId": "string"
}

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "groupId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastSeen": {
    },
  • "operatorId": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Bulk Insert or Update LoRaWAN device Tags.

Inserts/updates tags for the specified LoRaWAN device.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target LoRaWAN device.

Request Body schema: application/json
required

Array of tags to be inserted/updated.

Array
tagName
required
string
tagValue
required
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "groupId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastSeen": {
    },
  • "operatorId": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Delete LoRaWAN device Tag.

Deletes a tag from the specified LoRaWAN device.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target LoRaWAN device.

tag_name
required
string

Tag name to be deleted. (This will be part of a URL path, so it needs to be percent-encoded. In JavaScript, specify the name after it has been encoded using encodeURIComponent().)

Responses

Terminate LoRaWAN device.

Terminates the specified LoRaWAN device.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target LoRaWAN device.

Responses

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "groupId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastSeen": {
    },
  • "operatorId": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Removes a LoRaWAN device from a LoRaWAN group

Removes a LoRaWAN device from a LoRaWAN group.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

ID of the target LoRaWAN device. The ID of a LoRaWAN device can be obtained using the LoraDevice:listLoraDevices API.

Responses

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "groupId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastSeen": {
    },
  • "operatorId": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

LoraGateway

Soracom Air for LoRaWAN gateways

List LoRaWAN Gateways

Returns a list of LoRaWAN gateways that match certain criteria. If the total number of LoRaWAN gateways does not fit in one page, a URL for accessing the next page is returned in the link header of the response.

Authorizations:
(api_keyapi_token)
query Parameters
tag_name
string

Tag name for filtering the search (exact match).

tag_value
string

Tag search string for filtering the search. Required when tag_name has been specified.

tag_value_match_mode
string
Default: "exact"
Enum: "exact" "prefix"

Tag match mode.

limit
integer <int32d>

Maximum number of LoRaWAN gateways to retrieve.

last_evaluated_key
string

The Gateway ID of the last LoRaWAN gateway retrieved on the current page. By specifying this parameter, you can continue to retrieve the list from the next LoRaWAN gateway onward.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get LoRaWAN gateway

Returns information about the specified LoRaWAN gateway.

Authorizations:
(api_keyapi_token)
path Parameters
gateway_id
required
string

Gateway ID of the target LoRaWAN gateway.

Responses

Response samples

Content type
application/json
{
  • "address": "string",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "gatewayId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "networkSetId": "string",
  • "online": false,
  • "operatorId": "string",
  • "owned": false,
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Disable Termination of LoRaWAN gateway

Disables termination of specified LoRaWAN gateway.

Authorizations:
(api_keyapi_token)
path Parameters
gateway_id
required
string

ID of the target LoRaWAN gateway.

Responses

Response samples

Content type
application/json
{
  • "address": "string",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "gatewayId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "networkSetId": "string",
  • "online": false,
  • "operatorId": "string",
  • "owned": false,
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Enable Termination of LoRaWAN gateway

Enables termination of specified LoRaWAN gateway.

Authorizations:
(api_keyapi_token)
path Parameters
gateway_id
required
string

ID of the target LoRaWAN gateway.

Responses

Response samples

Content type
application/json
{
  • "address": "string",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "gatewayId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "networkSetId": "string",
  • "online": false,
  • "operatorId": "string",
  • "owned": false,
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Set Network Set ID of LoRaWAN gateway

Sets or overwrites network set ID for the specified LoRaWAN gateway.

Authorizations:
(api_keyapi_token)
path Parameters
gateway_id
required
string

ID of the target LoRaWAN gateway.

Request Body schema: application/json

LoRaWAN Network Set ID.

networkSetId
string

Responses

Request samples

Content type
application/json
{
  • "networkSetId": "string"
}

Response samples

Content type
application/json
{
  • "address": "string",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "gatewayId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "networkSetId": "string",
  • "online": false,
  • "operatorId": "string",
  • "owned": false,
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Bulk Insert or Update LoRaWAN gateway Tags

Inserts/updates tags for the specified LoRaWAN gateway.

Authorizations:
(api_keyapi_token)
path Parameters
gateway_id
required
string

ID of the target LoRaWAN gateway.

Request Body schema: application/json
required

Array of tags to be inserted/updated.

Array
tagName
required
string
tagValue
required
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "address": "string",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "gatewayId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "networkSetId": "string",
  • "online": false,
  • "operatorId": "string",
  • "owned": false,
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Delete LoRaWAN gateway tag

Deletes a tag from the specified LoRaWAN gateway.

Authorizations:
(api_keyapi_token)
path Parameters
gateway_id
required
string

ID of the target LoRaWAN gateway.

tag_name
required
string

Tag name to be deleted. (This will be part of a URL path, so it needs to be percent-encoded. In JavaScript, specify the name after it has been encoded using encodeURIComponent().)

Responses

Terminate LoRaWAN gateway

Terminates the specified LoRaWAN gateway.

Authorizations:
(api_keyapi_token)
path Parameters
gateway_id
required
string

ID of the target LoRaWAN gateway.

Responses

Response samples

Content type
application/json
{
  • "address": "string",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "gatewayId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "networkSetId": "string",
  • "online": false,
  • "operatorId": "string",
  • "owned": false,
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Unset Network Set ID of LoRaWAN gateway

Unset network set ID of the specified LoRaWAN gateway.

Authorizations:
(api_keyapi_token)
path Parameters
gateway_id
required
string

ID of the target LoRaWAN gateway.

Responses

Response samples

Content type
application/json
{
  • "address": "string",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "gatewayId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "networkSetId": "string",
  • "online": false,
  • "operatorId": "string",
  • "owned": false,
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

LoraNetworkSet

Soracom Air for LoRaWAN network sets

List LoRaWAN Network Sets

Returns a list of LoRaWAN network sets that match certain criteria. If the total number of LoRaWAN network sets does not fit in one page, a URL for accessing the next page is returned in the link header of the response.

Authorizations:
(api_keyapi_token)
query Parameters
tag_name
string

Tag name for filtering the search (exact match).

tag_value
string

Tag search string for filtering the search. Required when tag_name has been specified.

tag_value_match_mode
string
Default: "exact"
Enum: "exact" "prefix"

Tag match mode.

limit
integer <int32d>

Maximum number of LoRaWAN network set to retrieve.

last_evaluated_key
string

The ID of the last network set retrieved on the current page. By specifying this parameter, you can continue to retrieve the list from the next device onward.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a LoRaWAN network set

Creates a specified LoRaWAN network set.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

Additional metadata such as tags for a LoRaWAN network set to create.

allowedOperators
Array of strings unique
createdTime
string <date-time>
lastModifiedTime
string <date-time>
networkSetId
string
operatorId
string
object

Responses

Request samples

Content type
application/json
{
  • "allowedOperators": [
    ],
  • "createdTime": "2019-08-24T14:15:22Z",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "networkSetId": "string",
  • "operatorId": "string",
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "allowedOperators": [
    ],
  • "createdTime": "2019-08-24T14:15:22Z",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "networkSetId": "string",
  • "operatorId": "string",
  • "tags": {
    }
}

Delete LoRaWAN network set

Deletes the specified LoRaWAN network set.

Authorizations:
(api_keyapi_token)
path Parameters
ns_id
required
string

ID of the target LoRaWAN network set.

Responses

Get LoRaWAN network set

Returns information about the specified LoRaWAN network set.

Authorizations:
(api_keyapi_token)
path Parameters
ns_id
required
string

ID of the target LoRaWAN network set.

Responses

Response samples

Content type
application/json
{
  • "allowedOperators": [
    ],
  • "createdTime": "2019-08-24T14:15:22Z",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "networkSetId": "string",
  • "operatorId": "string",
  • "tags": {
    }
}

Adds permission to a LoRaWAN network set

Adds permission to allow another operator to use the network set.

Authorizations:
(api_keyapi_token)
path Parameters
ns_id
required
string

ID of the target LoRaWAN network set.

Request Body schema: application/json
required

ID of the operator to be added to the list of allowed operators.

operatorId
string

Responses

Request samples

Content type
application/json
{
  • "operatorId": "string"
}

Response samples

Content type
application/json
{
  • "allowedOperators": [
    ],
  • "createdTime": "2019-08-24T14:15:22Z",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "networkSetId": "string",
  • "operatorId": "string",
  • "tags": {
    }
}

List LoRaWAN Gateways in a Network Set

Returns a list of LoRaWAN gateways that belong to the specified network set. If the total number of LoRaWAN gateways does not fit in one page, a URL for accessing the next page is returned in the link header of the response.

Authorizations:
(api_keyapi_token)
path Parameters
ns_id
required
string

ID of the target LoRaWAN network set.

query Parameters
limit
integer <int32d>

Maximum number of LoRaWAN gateways to retrieve.

last_evaluated_key
string

The Gateway ID of the last LoRaWAN gateway retrieved on the current page. By specifying this parameter, you can continue to retrieve the list from the next LoRaWAN gateway onward.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Revokes a permission from a LoRaWAN network set

Revokes a permission and removes an operator from the list of allowed operators in the network set.

Authorizations:
(api_keyapi_token)
path Parameters
ns_id
required
string

ID of the target LoRaWAN network set.

Request Body schema: application/json
required

ID of the operator to be added to the list of allowed operators.

operatorId
string

Responses

Request samples

Content type
application/json
{
  • "operatorId": "string"
}

Response samples

Content type
application/json
{
  • "allowedOperators": [
    ],
  • "createdTime": "2019-08-24T14:15:22Z",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "networkSetId": "string",
  • "operatorId": "string",
  • "tags": {
    }
}

Bulk Insert or Update LoRaWAN network set tags

Inserts/updates tags for the specified LoRaWAN network set.

Authorizations:
(api_keyapi_token)
path Parameters
ns_id
required
string

ID of the target LoRaWAN network set.

Request Body schema: application/json
required

Array of tags to be inserted/updated.

Array
tagName
required
string
tagValue
required
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "allowedOperators": [
    ],
  • "createdTime": "2019-08-24T14:15:22Z",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "networkSetId": "string",
  • "operatorId": "string",
  • "tags": {
    }
}

Delete LoRaWAN network set tag

Deletes a tag from the specified LoRaWAN network set.

Authorizations:
(api_keyapi_token)
path Parameters
ns_id
required
string

ID of the target LoRaWAN network set.

tag_name
required
string

Tag name to be deleted. (This will be part of a URL path, so it needs to be percent-encoded. In JavaScript, specify the name after it has been encoded using encodeURIComponent().)

Responses

Operator

Get Operator

Returns information about the operator.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Responses

Response samples

Content type
application/json
{
  • "createDate": "string",
  • "description": "string",
  • "email": "string",
  • "operatorId": "string",
  • "rootOperatorId": "string",
  • "updateDate": "string"
}

List Operator AuthKeys

Returns the operator's AuthKey list.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Generate Operator AuthKey

Generates an AuthKey for the operator.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Responses

Response samples

Content type
application/json
{
  • "authKey": "string",
  • "authKeyId": "string"
}

Delete Operator AuthKey

Deletes an AuthKey from the operator.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

auth_key_id
required
string

AuthKey ID.

Responses

Get company information

Gets the operator's company information.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Responses

Response samples

Content type
application/json
{
  • "addressLine1": "string",
  • "addressLine2": "string",
  • "building": "string",
  • "city": "string",
  • "companyName": "string",
  • "contactPersonName": "string",
  • "countryCode": "string",
  • "department": "string",
  • "phoneNumber": "string",
  • "state": "string",
  • "vatIdentificationNumber": "string",
  • "zipCode": "string"
}

Create company information

Creates the operator's company information.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Request Body schema: application/json
required

Model.

addressLine1
string
addressLine2
string
building
string
city
string
companyName
required
string
contactPersonName
required
string
countryCode
required
string
department
required
string
phoneNumber
required
string
state
string
vatIdentificationNumber
string
zipCode
required
string

Responses

Request samples

Content type
application/json
{
  • "addressLine1": "string",
  • "addressLine2": "string",
  • "building": "string",
  • "city": "string",
  • "companyName": "string",
  • "contactPersonName": "string",
  • "countryCode": "string",
  • "department": "string",
  • "phoneNumber": "string",
  • "state": "string",
  • "vatIdentificationNumber": "string",
  • "zipCode": "string"
}

Update company information

Updates the operator's company information.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Request Body schema: application/json
required

Model.

addressLine1
string
addressLine2
string
building
string
city
string
companyName
required
string
contactPersonName
required
string
countryCode
required
string
department
required
string
phoneNumber
required
string
state
string
vatIdentificationNumber
string
zipCode
required
string

Responses

Request samples

Content type
application/json
{
  • "addressLine1": "string",
  • "addressLine2": "string",
  • "building": "string",
  • "city": "string",
  • "companyName": "string",
  • "contactPersonName": "string",
  • "countryCode": "string",
  • "department": "string",
  • "phoneNumber": "string",
  • "state": "string",
  • "vatIdentificationNumber": "string",
  • "zipCode": "string"
}

Delete operator configuration of the namespace

Deletes operator configuration of the namespace.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

namespace
required
string

Namespace of operator configuration.

Responses

Get operator configuration of the namespace

Gets operator configuration of the namespace.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

namespace
required
string

Namespace of operator configuration.

Responses

Response samples

Content type
application/json
{
  • "configuration": {
    },
  • "isModifiable": true,
  • "namespace": "Support",
  • "version": 0
}

Set operator configuration of the namespace

Sets operator configuration of the namespace.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

namespace
required
string

Namespace of operator configuration.

Request Body schema: application/json
required
required
OperatorConfigurationOfSupport (object) or OperatorConfigurationOfEmail (object) or OperatorConfigurationOfUserConsole (object)
expectedVersion
number

This property is used to avoid update confliction. To use it, retrieve the version by getOperatorConfigurationNamespace API, then specify the version here. If the expectedVersion is not specified, the API does not check an update confliction.

Responses

Request samples

Content type
application/json
{
  • "configuration": {
    },
  • "expectedVersion": 0
}

Response samples

Content type
application/json
{
  • "configuration": {
    },
  • "isModifiable": true,
  • "namespace": "Support",
  • "version": 0
}

Add Operator Contract

Adds the operator's contract.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Request Body schema: application/json
required

Model.

ContractDetailOfHarvest (object) or ContractDetailOfSupport (object)
contractName
required
string
Enum: "api_audit_log" "harvest" "napter" "support"

Responses

Request samples

Content type
application/json
{
  • "contractDetail": {
    },
  • "contractName": "harvest"
}

Response samples

Content type
application/json
{
  • "contractDetail": {
    },
  • "contractName": "api_audit_log"
}

Delete Operator Contract

Deletes the operator's contract.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

contract_name
required
string
Enum: "api_audit_log" "harvest" "napter" "support"

Contract name.

Responses

Add coverage type

Adds the operator's coverage type.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

coverage_type
required
string

Coverage type.

Responses

Get individual information

Gets the operator's individual information.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Responses

Response samples

Content type
application/json
{
  • "addressLine1": "string",
  • "addressLine2": "string",
  • "building": "string",
  • "city": "string",
  • "countryCode": "string",
  • "fullName": "string",
  • "phoneNumber": "string",
  • "state": "string",
  • "zipCode": "string"
}

Create individual information

Creates the operator's individual information.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Request Body schema: application/json
required

Model.

addressLine1
string
addressLine2
string
building
string
city
string
countryCode
required
string
fullName
required
string
phoneNumber
required
string
state
string
zipCode
required
string

Responses

Request samples

Content type
application/json
{
  • "addressLine1": "string",
  • "addressLine2": "string",
  • "building": "string",
  • "city": "string",
  • "countryCode": "string",
  • "fullName": "string",
  • "phoneNumber": "string",
  • "state": "string",
  • "zipCode": "string"
}

Update individual information

Updates the operator's individual information.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Request Body schema: application/json
required

Model.

addressLine1
string
addressLine2
string
building
string
city
string
countryCode
required
string
fullName
required
string
phoneNumber
required
string
state
string
zipCode
required
string

Responses

Request samples

Content type
application/json
{
  • "addressLine1": "string",
  • "addressLine2": "string",
  • "building": "string",
  • "city": "string",
  • "countryCode": "string",
  • "fullName": "string",
  • "phoneNumber": "string",
  • "state": "string",
  • "zipCode": "string"
}

Revoke Operator's MFA

Revokes operator's MFA without backup codes.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Request Body schema: application/json
required
password
required
string

Root user's password.

Responses

Request samples

Content type
application/json
{
  • "password": "string"
}

Get Operator's MFA Status

Gets operator's MFA status. The MFA status is one of ACTIVE, INACTIVE or UNCONFIRMED.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Enable Operator's MFA

Enables operator's MFA. After calling this API, it should be verified by calling Operator:verifyMFA API.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Responses

Response samples

Content type
application/json
{
  • "totpUri": "string"
}

Verify Operator's MFA OTP Code

Verifies operator's MFA with OTP code. This API must be called after calling Operator:enableMFA. MFA will not be activated unless the MFA OTP is verified with this API. Be sure to securely store the backup code returned in the response to this API.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Request Body schema: application/json
required

Request.

mfaOTPCode
string

Responses

Request samples

Content type
application/json
{
  • "mfaOTPCode": "string"
}

Response samples

Content type
application/json
{
  • "backupCodes": [
    ]
}

Update Operator Password

Updates the operator's password.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Request Body schema: application/json
required

current password, new password.

currentPassword
required
string
newPassword
required
string

Responses

Request samples

Content type
application/json
{
  • "currentPassword": "string",
  • "newPassword": "string"
}

Generate Token for Support Console

Returns a token for accessing the support console.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Responses

Response samples

Content type
application/json
{
  • "token": "string"
}

Generate API Token

Generates a new API token. If you insert the current API token into the header and make a request, a response is returned containing the new API token. You can then use the new API token in future requests.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Request Body schema: application/json
required

Token timeout seconds.

tokenTimeoutSeconds
integer <= 172800
Default: 86400

New API token expiry duration in seconds. Default: 86400 [seconds] (24 hours). Maximum: 172800 [seconds] (48 hours).

Responses

Request samples

Content type
application/json
{
  • "tokenTimeoutSeconds": 86400
}

Response samples

Content type
application/json
{
  • "token": "string"
}

Revoke all API keys and API tokens that were generated by the root user

Revoke all API keys and API tokens that were generated by the root user. Once revoked, the API key and API token cannot be used to call the Soracom API, regardless of their expiration time.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Responses

Issue Operator's MFA Revoke Token

Issues a token to revoke operator's MFA. The issued token will be sent to the operator via email.

Request Body schema: application/json
required

Request.

email
string
password
string

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string"
}

Verify Operator's MFA revoke token

Verifies the one-time token which is previously issued by calling /operators/mfa_revoke_token/issue API, operator's email address, password, and one of the backup codes. If verified, operator's MFA is going to be revoked.

Request Body schema: application/json
required

Request.

backupCode
string
email
string
password
string
token
string

Responses

Request samples

Content type
application/json
{
  • "backupCode": "string",
  • "email": "string",
  • "password": "string",
  • "token": "string"
}

List email addresses

Retrieves a list of email addresses registered to the operator.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete email address

Deletes the email address corresponding to the specified email address ID from the operator.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

email_id
required
string

Email address ID.

Responses

Get email address

Retrieves information for the email address corresponding to the specified email address ID.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

email_id
required
string

Email address ID.

Responses

Response samples

Content type
application/json
{
  • "createDateTime": 0,
  • "email": "string",
  • "emailId": "string",
  • "updateDateTime": 0,
  • "verified": true
}

Issue an authentication token to add an email address

Generates an authentication token for adding a new email address and sends it to the specified email address. This authentication token is used with Email:verifyAddEmailToken API to complete email address verification and addition.

Warning: This API can only be executed with root user credentials.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

Request.

email
required
string

Email address to be added. Please enter a valid email address format (e.g., user@example.com).

password
required
string

Password of the root user. Required for authentication.

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string"
}

Verify an authentication token to add an email address

Verifies the authentication token issued by Email:issueAddEmailToken API and adds the email address to the operator.

Warning: Authentication tokens have an expiration time. Expired authentication tokens cannot be used.

Request Body schema: application/json
required

Request.

token
required
string

Authentication token issued by Email:issueAddEmailToken API. The authentication token is sent to the target email address.

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

List Roles

Returns a list of roles.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

query Parameters
owner
string
Enum: "operator" "soracom" "all"

Filters by the type of the role. Specify one of the following:

  • operator: Operator managed role (default)
  • soracom: Soracom managed role
  • all: All roles

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete Operator Managed Role

Deletes an operator managed role.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

role_id
required
string

Role ID.

Responses

Get Role

Retrieves a role.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

role_id
required
string

Role ID. For operator managed roles, specify the role ID provided during role creation. For Soracom managed roles, specify in SRN (Soracom Resource Name) format.

Responses

Response samples

Content type
application/json
{
  • "createDateTime": 0,
  • "description": "string",
  • "owner": "operator",
  • "permission": "string",
  • "roleId": "string",
  • "roleName": "my-role",
  • "updateDateTime": 0
}

Create Operator Managed Role

Adds a new operator managed role.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

role_id
required
string

Role ID.

Request Body schema: application/json
required

Permission.

description
string

The description of the operator managed role.

permission
required
string

Permission as JSON for the operator managed role.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "permission": "string"
}

Response samples

Content type
application/json
{
  • "roleId": "string"
}

Update Operator Managed Role

Edits an operator managed role.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

role_id
required
string

Role ID.

Request Body schema: application/json
required

Permission.

description
string

The description of the operator managed role.

permission
required
string

Permission as JSON for the operator managed role.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "permission": "string"
}

List Role Attached Users

Retrieves a list of users attached to a role.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

role_id
required
string

Role ID. For operator managed roles, specify the role ID provided during role creation. For Soracom managed roles, specify in SRN (Soracom Resource Name) format.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Soracom Managed Role Versions

Retrieves a list of versions for a Soracom managed role.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

role_id
required
string

SRN (Soracom Resource Name) of the Soracom managed role. The format is srn:soracom:::Role:[roleName].

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List User Roles

Retrieves a list of the user's roles.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

user_name
required
string

SAM user name.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Attach Role to User

Attaches a role to a user.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

user_name
required
string

SAM user name.

Request Body schema: application/json
required

Role ID.

roleId
string

The ID of the role to attach. For an operator managed role, specify the role ID (roleId) obtained from the Role:listRoles API. For a Soracom managed role, specify the SRN (Soracom Resource Name).

Responses

Request samples

Content type
application/json
{
  • "roleId": "string"
}

Detach Role from User

Detaches a role from a user.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

user_name
required
string

SAM user name.

role_id
required
string

Role ID. For operator managed roles, specify the role ID provided during role creation. For Soracom managed roles, specify in SRN (Soracom Resource Name) format.

Responses

ShippingAddress

Shipping address operations for direct sales

List shipping addresses

Returns a list of shipping addresses.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Responses

Response samples

Content type
application/json
{
  • "shippingAddresses": [
    ]
}

Create shipping address

Creates a new shipping address.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

Request Body schema: application/json
required

Shipping address.

addressLine1
required
string
addressLine2
string
building
string
city
required
string
companyName
string
countryCode
string
department
string
email
string
fullName
string
phoneNumber
string
state
required
string
zipCode
required
string

Responses

Request samples

Content type
application/json
{
  • "addressLine1": "string",
  • "addressLine2": "string",
  • "building": "string",
  • "city": "string",
  • "companyName": "string",
  • "countryCode": "string",
  • "department": "string",
  • "email": "string",
  • "fullName": "string",
  • "phoneNumber": "string",
  • "state": "string",
  • "zipCode": "string"
}

Response samples

Content type
application/json
{
  • "addressLine1": "string",
  • "addressLine2": "string",
  • "building": "string",
  • "city": "string",
  • "companyName": "string",
  • "department": "string",
  • "fullName": "string",
  • "phoneNumber": "string",
  • "shippingAddressId": "string",
  • "shippingArea": "string",
  • "state": "string",
  • "zipCode": "string"
}

Delete shipping address

Deletes a shipping address.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

shipping_address_id
required
string

Shipping address ID.

Responses

Get shipping address

Returns a shipping address.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

shipping_address_id
required
string

Shipping address ID.

Responses

Response samples

Content type
application/json
{
  • "addressLine1": "string",
  • "addressLine2": "string",
  • "building": "string",
  • "city": "string",
  • "companyName": "string",
  • "department": "string",
  • "fullName": "string",
  • "phoneNumber": "string",
  • "shippingAddressId": "string",
  • "shippingArea": "string",
  • "state": "string",
  • "zipCode": "string"
}

Update shipping address

Updates a shipping address.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

shipping_address_id
required
string

Shipping address ID.

Request Body schema: application/json
required

Shipping address.

addressLine1
required
string
addressLine2
string
building
string
city
required
string
companyName
string
countryCode
string
department
string
email
string
fullName
string
phoneNumber
string
state
required
string
zipCode
required
string

Responses

Request samples

Content type
application/json
{
  • "addressLine1": "string",
  • "addressLine2": "string",
  • "building": "string",
  • "city": "string",
  • "companyName": "string",
  • "countryCode": "string",
  • "department": "string",
  • "email": "string",
  • "fullName": "string",
  • "phoneNumber": "string",
  • "state": "string",
  • "zipCode": "string"
}

List SoraCam compatible camera devices.

Obtains a list of cameras that are compatible with the Soracom Cloud Camera Services.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete the SoraCam compatible camera device identified by device_id.

Delete a SoraCam compatible camera device from the operator identified by device_id.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Responses

Get the SoraCam compatible camera device information identified by device_id.

Obtain a SoraCam compatible camera device record for the device identified by device_id.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Responses

Response samples

Content type
application/json
{
  • "appliedLicenses": [
    ],
  • "configuration": {
    },
  • "connected": true,
  • "deviceCategory": "Camera",
  • "deviceId": "7CDDDEADBEEF",
  • "firmwareVersion": "4.58.0.97",
  • "isShared": false,
  • "lastConnectedTime": 1664512183393,
  • "name": "My ATOM Cam 2",
  • "powerState": "on",
  • "productDisplayName": "ATOM Cam 2"
}

Retrieve firmware update information for a SoraCam compatible camera device

Returns available firmware update information for a SoraCam compatible camera device.

Warning: If you will run this API with a SAM user's API key and API token, please add the OAuth2:authorize permission to the SAM user in addition to the permission required to call this API (e.g. SoraCam:*). For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update a firmware for a SoraCam compatible camera device

Update a firmware for a SoraCam compatible camera device if it is available. The SoraCam compatible camera device will be offline while updating.

Warning: Please do not turn off the power while updating.

Warning: If you will run this API with a SAM user's API key and API token, please add the OAuth2:authorize permission to the SAM user in addition to the permission required to call this API (e.g. SoraCam:*). For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Responses

Unassign the license from a SoraCam compatible camera device

Unassigns the license from a specified SoraCam compatible camera device.

Warning: If you will run this API with a SAM user's API key and API token, please add the OAuth2:authorize permission to the SAM user in addition to the permission required to call this API (e.g. SoraCam:*). For more information on setting permissions, see Access Levels.

Warning: Devices will not undergo cloud recording by Soracom Cloud Camera Services unless a license is assigned.

Warning: A license is required to view footage already recorded to the cloud. This does not affect already exported videos/still images.

Warning: Unassigning the license will not stop license charges from being applied. To stop billing, cancel the license after unassigning it via the SoraCam:listSoraCamLicensePacks API or the User Console.

Authorizations:
api_keyapi_token
path Parameters
device_id
required
string

Responses

Update the assigned license for a SoraCam compatible camera device

Updates the license for a specified SoraCam compatible camera device.

Warning: If you will run this API with a SAM user's API key and API token, please add the OAuth2:authorize permission to the SAM user in addition to the permission required to call this API (e.g. SoraCam:*). For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string
Request Body schema: application/json
required
type
string
Enum: "CR7-SC" "CR14-SC" "CR30-SC" "CR60-SC" "CR90-SC" "MR7-SC" "MR14-SC" "MR30-SC" "MR60-SC" "MR90-SC"

Type of license to assign.

  • CR7-SC: Cloud Recording License (7 Days).
  • CR14-SC: Cloud Recording License (14 Days).
  • CR30-SC: Cloud Recording License (30 Days).
  • CR60-SC: Cloud Recording License (60 Days).
  • CR90-SC: Cloud Recording License (90 Days).
  • MR7-SC: Cloud Motion Detection "Unlimited" Recording License (7 Days).
  • MR14-SC: Cloud Motion Detection "Unlimited" Recording License (14 Days).
  • MR30-SC: Cloud Motion Detection "Unlimited" Recording License (30 Days).
  • MR60-SC: Cloud Motion Detection "Unlimited" Recording License (60 Days).
  • MR90-SC: Cloud Motion Detection "Unlimited" Recording License (90 Days).

Responses

Request samples

Content type
application/json
{
  • "type": "CR7-SC"
}

Response samples

Content type
application/json
{
  • "type": "CR14-SC"
}

Get a live image from a SoraCam compatible camera device

Gets a live image from a SoraCam compatible camera device. Images are captured at the time the API is called and a download URL is returned.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Responses

Retrieve enabled options for a SoraCam-compatible camera

Gets a list of whether the following options are enabled for a SoraCam-compatible camera.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

The device ID of the SoraCam-compatible camera.

Responses

Response samples

Content type
application/json
{
  • "realTimeAccess": {
    }
}

Enable or disable real-time access for a SoraCam-compatible camera

Enables or disables the real-time access feature for a SoraCam-compatible camera. When enabled, the camera can be accessed directly via P2P communication for retrieving camera feed and performing operations in real time.

Warning: Real-time access is a paid feature. For more details, see the documentation (Japanese).

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

The device ID of the SoraCam-compatible camera.

Request Body schema: application/json
enabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "enabled": true
}

Retrieve the camera's various settings

Retrieve the camera's various settings.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Responses

Response samples

Content type
application/json
{
  • "logo": "on",
  • "motion": "off",
  • "motionSensitivity": "low",
  • "motionTagging": "on",
  • "nightVision": "auto",
  • "quality": "high",
  • "rotation": 0,
  • "sound": "off",
  • "soundSensitivity": "low",
  • "statusLight": "on",
  • "timestamp": "on"
}

Retrieve the settings for motion detection

Retrieve the settings for motion detection. If motion detection is enabled, recording will start when the SoraCam compatible camera device detects moving objects.

Warning: Even if a Cloud Motion Detection "Unlimited" Recording License is assigned to the SoraCam compatible camera device, no recording will occur if motion detection is disabled, as it will not detect any moving objects.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Responses

Response samples

Content type
application/json
{
  • "state": "on"
}

Change the settings for motion

Change the settings for motion detection. If motion detection is enabled, recording will start when the SoraCam compatible camera device detects moving objects.

Warning: Even if a Cloud Motion Detection "Unlimited" Recording License is assigned to the SoraCam compatible camera device, no recording will occur if motion detection is disabled, as it will not detect any moving objects.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Request Body schema: application/json
state
required
string
Enum: "on" "off"

Settings for motion detection.

  • on
  • off

Responses

Request samples

Content type
application/json
{
  • "state": "on"
}

Retrieve the settings for motion sensitivity

Retrieve the settings for motion sensitivity.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Responses

Response samples

Content type
application/json
{
  • "state": "low"
}

Change the settings for motion sensitivity

Change the settings for motion sensitivity.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Request Body schema: application/json
state
required
string
Enum: "high" "medium" "low"

Settings for the motion detection sensitivity. The higher the sensitivity, the smaller the image changes that can be detected.

  • high
  • medium
  • low

Responses

Request samples

Content type
application/json
{
  • "state": "low"
}

Retrieve the display settings for motion tagging

Retrieve the display settings for motion tagging. Motion tagging is a green frame that is displayed when motion is detected.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Responses

Response samples

Content type
application/json
{
  • "state": "on"
}

Change the display settings for motion tagging

Change the display settings for motion tagging. Motion tagging is a green frame that is displayed when motion is detected.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Request Body schema: application/json
state
required
string
Enum: "on" "off"

Display settings for motion tagging.

  • on
  • off

Responses

Request samples

Content type
application/json
{
  • "state": "on"
}

Retrieve the settings for night vision mode

Retrieve the settings for night vision mode.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Responses

Response samples

Content type
application/json
{
  • "state": "auto"
}

Change the settings for night vision mode

Change the settings for night vision mode.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Request Body schema: application/json
state
required
string
Enum: "on" "off" "auto"

Settings for night vision mode.

  • on: Night vision mode.
  • off: Normal mode.
  • auto: Auto-switching.

Responses

Request samples

Content type
application/json
{
  • "state": "auto"
}

Retrieve the quality settings

Retrieve the quality settings.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Responses

Response samples

Content type
application/json
{
  • "state": "low"
}

Change the quality settings

Changes the quality settings. The quality settings will be applied to all videos and still images captured by the specified SoraCam compatible camera device. Note that if the Wi-Fi bandwidth is insufficient, the quality settings may automatically be adjusted.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Request Body schema: application/json
state
required
string
Enum: "low" "medium" "high"

Settings for the live video and cloud recording quality. Note that for cloud recordings, the resolution is 1080p (1920 x 1080 pixels), regardless of the quality setting.

  • low: The same quality as selecting "360p" in the ATOM app.
  • medium: The same quality as selecting "SD" in the ATOM app.
  • high: The same quality as selecting "HD (1080p)" in the ATOM app.

Responses

Request samples

Content type
application/json
{
  • "state": "low"
}

Retrieve the settings for rotating the image by 180 degrees

Retrieve the settings for rotating the image by 180 degrees.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Responses

Response samples

Content type
application/json
{
  • "state": 180
}

Change the settings for rotating the image by 180 degrees

Change the settings for rotating the image by 180 degrees.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Request Body schema: application/json
state
required
integer
Enum: 0 180

Settings for rotating the image by 180 degrees. Set to 180 when installing the SoraCam compatible camera device upside down.

  • 0: OFF (no rotation).
  • 180: ON (180-degree rotation).

Responses

Request samples

Content type
application/json
{
  • "state": 180
}

Retrieve the settings for sound detection

Retrieve the settings for sound detection. If sound detection is enabled, recording will start when the SoraCam compatible camera device detects sound.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Warning: Video recorded via sound detection cannot be downloaded separately via the Soracom User Console, Soracom CLI, or Soracom API. However, if a Cloud Continuous Recording License is assigned, you can check the time that sound was detected using SoraCam:listSoraCamDeviceEventsForDevice API and then download the video recorded during that time.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Responses

Response samples

Content type
application/json
{
  • "state": "on"
}

Change the settings for sound detection

Change the settings for sound detection. If sound detection is enabled, recording will start when the SoraCam compatible camera device detects sound.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Warning: Video recorded via sound detection cannot be downloaded separately via the Soracom User Console, Soracom CLI, or Soracom API. However, if a Cloud Continuous Recording License is assigned, you can check the time that sound was detected using SoraCam:listSoraCamDeviceEventsForDevice API and then download the video recorded during that time.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Request Body schema: application/json
state
required
string
Enum: "on" "off"

Settings for sound detection.

  • on
  • off

Responses

Request samples

Content type
application/json
{
  • "state": "on"
}

Retrieve the settings for sound sensitivity

Retrieve the settings for sound sensitivity.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Responses

Response samples

Content type
application/json
{
  • "state": "low"
}

Change the settings for sound sensitivity

Change the settings for sound sensitivity.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Request Body schema: application/json
state
required
string
Enum: "high" "medium" "low"

Settings for sound detection sensitivity. The higher the sensitivity, the easier it is to detect small sounds.

  • high
  • medium
  • low

Responses

Request samples

Content type
application/json
{
  • "state": "low"
}

Retrieve the settings for the status light (indicator light that shows the status of the camera)

Retrieve the settings for the status light (indicator light that shows the status of the camera).

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Responses

Response samples

Content type
application/json
{
  • "state": "on"
}

Change the settings for the status light (indicator light that shows the status of the camera)

Change the settings for the status light (indicator light that shows the status of the camera).

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Request Body schema: application/json
state
required
string
Enum: "on" "off"

Settings for the status light (indicator light that shows the status of the camera).

  • on
  • off

Responses

Request samples

Content type
application/json
{
  • "state": "on"
}

Retrieve the display settings for the timestamp shown on the bottom right of the captured image

Retrieve the display settings for the timestamp shown on the bottom right of the captured image.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Responses

Response samples

Content type
application/json
{
  • "state": "on"
}

Change the display settings for the timestamp shown on the bottom right of the captured image

Change the display settings for the timestamp shown on the bottom right of the captured image.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Info: To use this API, you must either assign a cloud license to the target Soracom-compatible camera or enable real-time access.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Request Body schema: application/json
state
required
string
Enum: "on" "off"

Display settings for the timestamp shown on the bottom right of the captured image.

  • on
  • off

Responses

Request samples

Content type
application/json
{
  • "state": "on"
}

Save arbitrary data to Harvest Data linked to a SoraCam compatible camera device

Saves arbitrary data to Harvest Data that will be associated to a SoraCam compatible camera device specified by its device ID (device_id).

For example, to save JSON data, set Content-Type: application/json in the header and specify { "person_count": 5 } in the request body.

Warning: When using a SAM user's API key and API token to execute this API, you must grant the SAM user the OAuth2:authorize permission in addition to the permissions required to call this API (e.g., SoraCam:*). For details about permission settings, refer to Configuring SAM User Permissions.

Info: To retrieve saved data entries, use the DataEntry:getDataEntry API. To delete data entries, use the DataEntry:deleteDataEntry API.

Info: For more information about Harvest Data, please refer to Soracom Harvest.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

header Parameters
content-type
string

The Content-Type of the data to be saved.

  • For JSON data, specify application/json.
  • For text data, specify text/plain.
  • For binary data, specify application/octet-stream.
Request Body schema:
required

The data to be saved.

string

Responses

Request samples

Content type
"string"

Save arbitrary data to Harvest Data linked to a SoraCam compatible camera device and timestamp

Saves arbitrary data to Harvest Data with a particular timestamp that will be associated to a SoraCam compatible camera device specified by its device ID (device_id).

  • If no data exists for the specified timestamp, a new data entry will be created.
  • If data already exists for the specified timestamp, it will be overwritten according to the specifications of Harvest Data.

For example, to save JSON data, set Content-Type: application/json in the header and specify { "person_count": 5 } in the request body.

Warning: When using a SAM user's API key and API token to execute this API, you must grant the SAM user the OAuth2:authorize permission in addition to the permissions required to call this API (e.g., SoraCam:*). For details about permission settings, refer to Configuring SAM User Permissions.

Info: To retrieve saved data entries, use the DataEntry:getDataEntry API. To delete data entries, use the DataEntry:deleteDataEntry API.

Info: For more information about Harvest Data, please refer to Soracom Harvest.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

time
required
integer <int64>

The timestamp of the target data entry (UNIX time in milliseconds).

header Parameters
content-type
string

The Content-Type of the data to be saved.

  • For JSON data, specify application/json.
  • For text data, specify text/plain.
  • For binary data, specify application/octet-stream.
Request Body schema:
required

The data to be saved.

string

Responses

Request samples

Content type
"string"

List SoraCam events for the specified device.

Returns list of SoraCam events for the specified device.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

query Parameters
last_evaluated_key
string

Value of the x-soracom-next-key header in the previous response. Use this to continue pagination.

limit
integer [ 1 .. 100 ]
Default: 10

Maximum number of events to retrieve in one request (value range is 1 to 100). Note that the response may contain fewer events than the specified limit.

from
integer <int64>

Start time of the events to retrieve (unix time in milliseconds). If not specified, from is set to the oldest event time.

to
integer <int64>

End time of the events to retrieve (unix time in milliseconds). If not specified, to is set to the current time.

sort
string
Default: "desc"
Enum: "desc" "asc"

Event list sort order.

  • desc: Descending order (newest events detected by target SoraCam compatible camera device first).
  • asc: Ascending order (oldest events detected by target SoraCam compatible camera device first).

Responses

Response samples

Content type
application/json
[]

Get the remaining number of still images that can be exported and the remaining exportable time of recorded video.

Get the remaining number of still images that can be exported and the remaining exportable time of recorded video.

Warning: Exporting either still images or recorded video will consume the available video viewing time (72 hours per month by default).

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Responses

Response samples

Content type
application/json
{
  • "deviceId": "7CDDDEADBEEF",
  • "image": {
    },
  • "meteredYearMonth": "202209",
  • "video": {
    }
}

Reset the monthly limit on the recorded video time available for export for SoraCam compatible camera device to the default value.

Reset the monthly limit on the recorded video time available for export to the default value. By default, the limit is set to 72 hours per month.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Responses

Set the monthly limit on the recorded video time available for export for SoraCam compatible camera device.

Set the monthly limit on the recorded video time available for export. By default, the limit is set to 72 hours per month. A maximum of 1,500 hours can be set.

Warning: Additional costs will be incurred for recorded video exported beyond 72 hours. Simply changing the monthly limit does not result in any charges.. However, exceeding 72 hours of export time consumption will incur charges regardless of the set export time limit. For more information about fees, see Soracom Cloud Camera Services about fees (Japanese).

Warning: The monthly limit can be set to less than 72 hours. In such cases, there will be no change in the charge.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Request Body schema: application/json
required
limitHours
required
integer

New value for the monthly limit for the amount of hours that recorded video can be exported.

Responses

Request samples

Content type
application/json
{
  • "limitHours": 144
}

Response samples

Content type
application/json
{
  • "deviceId": "7CDDDEADBEEF",
  • "image": {
    },
  • "meteredYearMonth": "202209",
  • "video": {
    }
}

Get a list of the current status of the process of exporting still image from recorded video taken with a SoraCam compatible camera device.

Gets the list of the current status of the process of exporting still image from recorded video taken with a SoraCam compatible camera device started by SoraCam:exportSoraCamDeviceRecordedImage API. This API limits the target to one SoraCam compatible camera device.

If the target is not limited to one SoraCam compatible camera device, but all SoraCam compatible camera devices owned by the operator, use SoraCam:listSoraCamDeviceImageExports API.

Warning: The URL becomes unusable 10 minutes after export completion. The time until the URL becomes unusable can be checked with expiryTime. Additionally, over time, it will be removed from the list.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

query Parameters
last_evaluated_key
string

Value of the x-soracom-next-key header in the previous response. Use this to continue pagination.

limit
integer
Default: 10

Maximum number of items to retrieve in one request. Note that the response may contain fewer items than the specified limit.

sort
string
Default: "desc"
Enum: "desc" "asc"

Export list sort order.

  • desc: Descending order (newest export process first).
  • asc: Ascending order (oldest export process first).

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Start the process of exporting still images from recorded video saved on the cloud

Starts the process of extracting and exporting still images from recorded video saved on the cloud. The export process is processed asynchronously. The progress of the export process and the URL of the exported file can be obtained with the SoraCam:listSoraCamDeviceImageExports API. The URL has an expiration time.

  • At the time of obtaining the URL, the available video viewing time (72 hours per month by default) will be consumed regardless of whether the download has started or not.
  • Exporting results are not cached. If you export the same time twice, it will consume twice the available video viewing time (72 hours per month by default).
  • Exporting to Harvest Files will incur costs according to Harvest Files fees, and files will be retained for a period according to the Harvest Files retention period. For details, refer to Pricing & Fee Schedule.

Warning: Images from cameras that have not been assigned a Cloud Continuous Recording License or Cloud Motion Detection "Unlimited" Recording License cannot be exported.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. Additionally, to export to Harvest Files, the FileEntry:putFile API permission must be granted. For more information on setting permissions, see Access Levels.

Info: The image size of the exported still images is 1920 x 1080 pixels.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Request Body schema: application/json
required
object (SoraCamExportImageToHarvestFiles)

Specifies the settings for exporting images to Harvest Files.

Example: harvestFiles: { pathPrefix: "/sora_cam/{device_id}" }

If the pathPrefix is omitted or set to an empty string, the export will be saved in the root directory of Harvest Files.

Example of exporting to the root directory: harvestFiles: { pathPrefix: "" }

imageFilters
Array of strings
Items Value: "wide_angle_correction"

Image filters to be applied to the exported image.

time
required
integer <int64>

Time to be exported (unix time in milliseconds). A still image is exported from the recorded video taken at the specified time.

Responses

Request samples

Content type
application/json
Example
{
  • "time": 1658400332905
}

Response samples

Content type
application/json
{
  • "deviceId": "7CDDDEADBEEF",
  • "exportId": "5ed62746-6c53-47e5-94e6-90697057cf5b",
  • "operatorId": "OP0012345678",
  • "requestedTime": 1662973200000,
  • "status": "initializing"
}

Get the current status of the process of exporting still images from recorded video taken with a SoraCam compatible camera device

Gets the current status of the process of exporting still image from recorded video taken with a SoraCam compatible camera device started by SoraCam:exportSoraCamDeviceRecordedImage API. This API limits the target to one export process.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

export_id
required
string

Export ID of the target export operation.

Responses

Response samples

Content type
application/json
Example
{
  • "deviceId": "7CDDDEADBEEF",
  • "exportId": "5ed62746-6c53-47e5-94e6-90697057cf5b",
  • "operatorId": "OP0012345678",
  • "requestedTime": 1662973200000,
  • "status": "initializing"
}

Get the current name of the SoraCam compatible camera device.

Get the current name of the SoraCam compatible camera device.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Responses

Response samples

Content type
application/json
{
  • "name": "ATOM Cam 2"
}

Changes the name of the SoraCam compatible camera device.

Changes the name of the SoraCam compatible camera device.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Request Body schema: application/json
name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "ATOM Cam 2"
}

Get the current power state of the SoraCam compatible camera device.

Get the current power state of the SoraCam compatible camera device.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Responses

Response samples

Content type
application/json
{
  • "powerState": "on"
}

Changes the power state of the SoraCam compatible camera device.

Changes the power state of the SoraCam compatible camera device.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Request Body schema: application/json
powerState
required
string
Enum: "on" "sleep"

Power state of the SoraCam compatible camera device.

  • on
  • sleep

Responses

Request samples

Content type
application/json
{
  • "powerState": "on"
}

Reboot the SoraCam compatible camera device.

Reboot the SoraCam compatible camera device.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Responses

Retrieve a list of recording periods and events for a SoraCam compatible camera device

Returns a list of recordings and events for a SoraCam compatible camera device.

Warning: If you will run this API with a SAM user's API key and API token, please add the OAuth2:authorize permission to the SAM user in addition to the permission required to call this API (e.g. SoraCam:*). For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

query Parameters
last_evaluated_key
string

Value of the x-soracom-next-key header in the previous response. Use this to continue pagination.

from
integer <int64>

Start time of the recordings and events to retrieve (unix time in milliseconds). If not specified, from is set to the oldest time within the retention period of the license that is assigned to the SoraCam compatible camera device.

to
integer <int64>

End time of the recordings and events to retrieve (unix time in milliseconds). If not specified, to is set to the current time.

sort
string
Default: "desc"
Enum: "desc" "asc"

Recordings and events list sort order.

  • desc: Descending order (newest data first).
  • asc: Ascending order (oldest data first).

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "records": [
    ]
}

Get information for streaming recorded video from the cloud.

Get information for streaming recorded video from the cloud. Specifically, you can get an array of URLs that support a streaming method called MPEG-DASH (Dynamic Adaptive Streaming over HTTP). The URL has an expiration time.

  • To stream the latest video, omit both from and to. Please be aware of the following points in that case:
    • You can get a URL to stream the latest 300 seconds (5 minutes) of video based on the time of the API called. To continue watching, call the API again to get the next URL.
    • At the time of obtaining the URL, 5 minutes of the available video viewing time (72 hours per month by default) will be consumed regardless of the viewing status.
  • To stream recorded video at a specific point in time, specify either from or to. Please be aware of the following points:
    • You can get a URL to stream up to 900 seconds (15 minutes) of recorded video.
    • At the time of obtaining the URL, the available video viewing time (72 hours per month by default) will be consumed regardless of the viewing status.

Warning: Latest video refers to the most recent recorded footage saved in the cloud. This API cannot be used to play Live streaming video that can be played on the ATOM app. To view Live streaming video, use real-time access (Early access).

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

query Parameters
from
integer <int64>

Start time of recorded video (UNIX time in milliseconds).

  • Omit both from and to to get information for streaming the latest video.
to
integer <int64>

End time of recorded video (UNIX time in milliseconds).

  • Omit both from and to to get information for streaming the latest video.
  • The maximum duration that can be viewed in a single API call is 900 seconds (15 minutes). Make sure the difference between from and to does not exceed 900 seconds.

Responses

Response samples

Content type
application/json
{}

Get a list of the current status of the process of exporting recorded video taken with a SoraCam compatible camera device.

Gets the list of the current status of the process of exporting recorded video taken with a SoraCam compatible camera device started by SoraCam:exportSoraCamDeviceRecordedVideo API. This API limits the target to one SoraCam compatible camera device.

If the target is not limited to one SoraCam compatible camera device, but all SoraCam compatible camera devices owned by the operator, use SoraCam:listSoraCamDeviceVideoExports API.

Warning: The URL becomes unusable 10 minutes after export completion. The time until the URL becomes unusable can be checked with expiryTime. Additionally, over time, it will be removed from the list.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

query Parameters
last_evaluated_key
string

Value of the x-soracom-next-key header in the previous response. Use this to continue pagination.

limit
integer
Default: 10

Maximum number of items to retrieve in one request. Note that the response may contain fewer items than the specified limit.

sort
string
Default: "desc"
Enum: "desc" "asc"

Export list sort order.

  • desc: Descending order (newest export process first).
  • asc: Ascending order (oldest export process first).

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Start the process of exporting recorded video saved on the cloud

Starts the process of exporting recorded video saved on the cloud in a format that can be downloaded (zipped mp4 files). The export process is processed asynchronously. The progress of the export process and the URL of the exported file can be obtained with the SoraCam:listSoraCamDeviceVideoExports API. The URL has an expiration time.

  • The maximum export time for a single URL is 900 seconds (15 minutes).
  • At the time of obtaining the URL, the available video viewing time (72 hours per month by default) will be consumed regardless of whether the download has started or not.
  • Exporting results are not cached. If you export the same time twice, it will consume twice the available video viewing time (72 hours per month by default).
  • Exporting to Harvest Files will incur costs according to Harvest Files fees, and files will be retained for a period according to the Harvest Files retention period. For details, refer to Pricing & Fee Schedule.

Warning: Recordings from cameras that have not been assigned a Cloud Continuous Recording License or Cloud Motion Detection "Unlimited" Recording License cannot be exported.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. Additionally, to export to Harvest Files, the FileEntry:putFile API permission must be granted. For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

Request Body schema: application/json
required
archive
boolean
Default: true

Specifies whether exported files should be compressed. Defaults to true.

  • true: Compresses video files in zip format.
  • false: Exports video files as uncompressed MP4 files.
audioCodec
string
Default: "pcm_s16le"
Enum: "pcm_s16le" "mp3"

Specifies the audio codec for exported videos. Defaults to pcm_s16le.

  • mp3: MP3
  • pcm_s16le: PCM 16-bit (WAV file)

Warning: If mp3 is specified, it will consume twice the recorded video time available for export.

from
required
integer <int64>

Start time for exporting (unix time in milliseconds).

object (SoraCamExportVideoToHarvestFiles)

Specifies the settings for exporting video to Harvest Files.

Example: harvestFiles: { pathPrefix: "/sora_cam/{device_id}" }

If the pathPrefix is omitted or set to an empty string, the export will be saved in the root directory of Harvest Files.

Example of exporting to the root directory: harvestFiles: { pathPrefix: "" }

to
required
integer <int64>

End time for exporting (unix time in milliseconds).

  • The maximum duration that can be exported in a single API call is 900 seconds (15 minutes). Make sure the difference between from and to does not exceed 900 seconds.

Responses

Request samples

Content type
application/json
{
  • "from": 1662962400000,
  • "to": 1662962430000
}

Response samples

Content type
application/json
{
  • "deviceId": "7CDDDEADBEEF",
  • "exportId": "5ed62746-6c53-47e5-94e6-90697057cf5b",
  • "operatorId": "OP0012345678",
  • "requestedTime": 1662973200000,
  • "status": "initializing"
}

Get the current status of the process of exporting recorded video taken with a SoraCam compatible camera device

Gets the current status of the process of exporting recorded video taken with a SoraCam compatible camera device started by SoraCam:exportSoraCamDeviceRecordedVideo API. This API limits the target to one export process.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target SoraCam compatible camera device.

export_id
required
string

Export ID of the target export operation.

Responses

Response samples

Content type
application/json
Example
{
  • "deviceId": "7CDDDEADBEEF",
  • "exportId": "5ed62746-6c53-47e5-94e6-90697057cf5b",
  • "operatorId": "OP0012345678",
  • "requestedTime": 1662973200000,
  • "status": "initializing"
}

Retrieve a list of SoraCam compatible camera devices that can update the firmware

Returns a list of SoraCam compatible camera devices that can update the firmware.

Warning: If you will run this API with a SAM user's API key and API token, please add the OAuth2:authorize permission to the SAM user in addition to the permission required to call this API (e.g. SoraCam:*). For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List SoraCam events.

Returns list of SoraCam events.

Authorizations:
(api_keyapi_token)
query Parameters
device_id
string

Device ID of the target SoraCam compatible camera device. If not specified, retrieves event history for all SoraCam compatible camera devices owned by the operator.

last_evaluated_key
integer

Value of the x-soracom-next-key header in the previous response. Use this to continue pagination.

limit
integer [ 1 .. 100 ]
Default: 10

Maximum number of events to retrieve in one request (value range is 1 to 100). Note that the response may contain fewer events than the specified limit.

from
integer <int64>

Start time of the events to retrieve (unix time in milliseconds). If not specified, from is set to the oldest event time.

to
integer <int64>

End time of the events to retrieve (unix time in milliseconds). If not specified, to is set to the current time.

sort
string
Default: "desc"
Enum: "desc" "asc"

Event list sort order.

  • desc: Descending order (newest events detected by SoraCam compatible camera device first).
  • asc: Ascending order (oldest events detected by SoraCam compatible camera device first).

Responses

Response samples

Content type
application/json
[]

Get a list of the current status of the process of exporting still image from recorded video taken with a SoraCam compatible camera device.

Gets the list of the current status of the process of exporting still image from recorded video taken with a SoraCam compatible camera device started by SoraCam:exportSoraCamDeviceRecordedImage API. This API can target all devices owned by the operator, or limit it to one SoraCam compatible camera device.

Warning: The URL becomes unusable 10 minutes after export completion. The time until the URL becomes unusable can be checked with expiryTime. Additionally, over time, it will be removed from the list.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)
query Parameters
device_id
string

Device ID of the target SoraCam compatible camera device. If not specified, returns all SoraCam compatible camera devices owned by the operator.

last_evaluated_key
string

Value of the x-soracom-next-key header in the previous response. Use this to continue pagination.

limit
integer
Default: 10

Maximum number of items to retrieve in one request. Note that the response may contain fewer items than the specified limit.

sort
string
Default: "desc"
Enum: "desc" "asc"

Export list sort order.

  • desc: Descending order (newest export process first).
  • asc: Ascending order (oldest export process first).

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Get a list of the current status of the process of exporting recorded video taken with a SoraCam compatible camera device.

Gets the list of the current status of the process of exporting recorded video taken with a SoraCam compatible camera device started by SoraCam:exportSoraCamDeviceRecordedVideo API. This API can target all devices owned by the operator, or limit it to one SoraCam compatible camera device.

Warning: The URL becomes unusable 10 minutes after export completion. The time until the URL becomes unusable can be checked with expiryTime. Additionally, over time, it will be removed from the list.

Warning: When calling this API using a SAM User's API key and API token, the SAM User must also have permission to call the OAuth2:authorize API in addition to permission to call this API. For more information on setting permissions, see Access Levels.

Authorizations:
(api_keyapi_token)
query Parameters
device_id
string

Device ID of the target SoraCam compatible camera device. If not specified, returns all SoraCam compatible camera devices owned by the operator.

last_evaluated_key
string

Value of the x-soracom-next-key header in the previous response. Use this to continue pagination.

limit
integer
Default: 10

Maximum number of items to retrieve in one request. Note that the response may contain fewer items than the specified limit.

sort
string
Default: "desc"
Enum: "desc" "asc"

Export list sort order.

  • desc: Descending order (newest export process first).
  • asc: Ascending order (oldest export process first).

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

List license packs of Soracom Cloud Camera Services

Returns the list of license packs which you can use. Currently, this API is only available for Japan coverage.

Authorizations:
(api_keyapi_token)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Update the license quantity of Soracom Cloud Camera Services

Updates the license quantity for the license pack identified by license_pack_id. This operation will cost you monthly fee based on number of licenses. Currently, this API is only available for Japan coverage.

Authorizations:
(api_keyapi_token)
path Parameters
license_pack_id
required
string
Enum: "CR7-SC" "CR14-SC" "CR30-SC" "CR60-SC" "CR90-SC" "MR7-SC" "MR14-SC" "MR30-SC" "MR60-SC" "MR90-SC"
Examples:
  • CR7-SC - Cloud Recording License (7 Days)
  • CR14-SC - Cloud Recording License (14 Days)
  • CR30-SC - Cloud Recording License (30 Days)
  • CR60-SC - Cloud Recording License (60 Days)
  • CR90-SC - Cloud Recording License (90 Days)
  • MR7-SC - Cloud Motion Detection "Unlimited" Recording License (7 Days)
  • MR14-SC - Cloud Motion Detection "Unlimited" Recording License (14 Days)
  • MR30-SC - Cloud Motion Detection "Unlimited" Recording License (30 Days)
  • MR60-SC - Cloud Motion Detection "Unlimited" Recording License (60 Days)
  • MR90-SC - Cloud Motion Detection "Unlimited" Recording License (90 Days)

Specify one of the following license IDs.

  • CR7-SC: Cloud Recording License (7 Days).
  • CR14-SC: Cloud Recording License (14 Days).
  • CR30-SC: Cloud Recording License (30 Days).
  • CR60-SC: Cloud Recording License (60 Days).
  • CR90-SC: Cloud Recording License (90 Days).
  • MR7-SC: Cloud Motion Detection "Unlimited" Recording License (7 Days).
  • MR14-SC: Cloud Motion Detection "Unlimited" Recording License (14 Days).
  • MR30-SC: Cloud Motion Detection "Unlimited" Recording License (30 Days).
  • MR60-SC: Cloud Motion Detection "Unlimited" Recording License (60 Days).
  • MR90-SC: Cloud Motion Detection "Unlimited" Recording License (90 Days).
Request Body schema: application/json
required

The change in the license quantity.

currentQuantity
integer <int32>

Current license quantity of the license pack.

desiredQuantity
integer <int32>

Desired license quantity of the license pack.

Responses

Request samples

Content type
application/json
{
  • "currentQuantity": 1,
  • "desiredQuantity": 2
}

SystemNotification

Email addresses

List email settings

Returns a list of email settings.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete an email address from the email settings

Delete an email address from the email settings.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

type
required
string
Enum: "recovery" "billing" "support"

Email address type.

Responses

Get information on email settings

Return information on email settings.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

type
required
string
Enum: "primary" "recovery" "billing" "support"

Email address type.

Responses

Response samples

Content type
application/json
{
  • "emailIdList": [
    ],
  • "type": "primary",
  • "updateDateTime": 0
}

Set an email address in the email settings

Set an email address in the email settings.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

type
required
string
Enum: "primary" "recovery" "billing" "support"

Email address type.

Request Body schema: application/json
required

Request.

emailIdList
required
Array of strings
password
string

Password of the operator. This is necessary when type is primary.

Responses

Request samples

Content type
application/json
{
  • "emailIdList": [
    ],
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "emailIdList": [
    ],
  • "type": "primary",
  • "updateDateTime": 0
}

Retrieve a list of SAM users

Retrieves a list of SAM users.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

The operator ID.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete User.

Deletes the SAM user.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

user_name

Responses

Response samples

Content type
application/json
{
  • "errorMessage": {
    },
  • "httpStatus": 0
}

Get User.

Returns a SAM user.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

user_name

Responses

Response samples

Content type
application/json
{
  • "authKeyList": [
    ],
  • "createDateTime": 1722480500,
  • "description": "This is my user",
  • "hasPassword": true,
  • "permission": "{\"statements\":[{\"api\":\"*\",\"effect\":\"allow\"}]}",
  • "roleList": [
    ],
  • "updateDateTime": 1722480600,
  • "userName": "my-user"
}

Create User.

Adds a new SAM user.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

user_name

Request Body schema: application/json
required

description

description
string

Responses

Request samples

Content type
application/json
{
  • "description": "string"
}

Update User.

Updates the SAM user.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

user_name

Request Body schema: application/json
required

description

description
string

Responses

Request samples

Content type
application/json
{
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "errorMessage": {
    },
  • "httpStatus": 0
}

List User AuthKeys.

Returns the SAM user's AuthKey list.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

user_name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Generate AuthKey.

Generates an AuthKey for the SAM user.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

user_name

Responses

Response samples

Content type
application/json
{
  • "authKey": "string",
  • "authKeyId": "string"
}

Delete User AuthKey.

Deletes an AuthKey from the SAM user.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

user_name

auth_key_id
required
string

auth_key_id

Responses

Response samples

Content type
application/json
{
  • "errorMessage": {
    },
  • "httpStatus": 0
}

Get AuthKey.

Returns the SAM user's AuthKey.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

user_name

auth_key_id
required
string

auth_key_id

Responses

Response samples

Content type
application/json
{
  • "authKeyId": "keyId-xxx",
  • "createDateTime": 1722480500,
  • "lastUsedDateTime": 1722480600
}

Revoke SAM user's MFA

Revoke SAM user's MFA

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

SAM user name

Responses

Get SAM user's MFA status

Get SAM user's MFA status

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

SAM user name

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Enable SAM user's MFA

Enable SAM user's MFA

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

SAM user name

Responses

Response samples

Content type
application/json
{
  • "totpUri": "string"
}

Verify SAM user's MFA OTP code when MFA activation phase

Verify SAM user's MFA OTP code when MFA activation phase

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

SAM user name

Request Body schema: application/json
required

request

mfaOTPCode
string

Responses

Request samples

Content type
application/json
{
  • "mfaOTPCode": "string"
}

Delete Password.

Deletes the user's password.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

user_name

Responses

Response samples

Content type
application/json
{
  • "errorMessage": {
    },
  • "httpStatus": 0
}

Has User Password.

Retrieves whether the SAM user has a password or not.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

user_name

Responses

Response samples

Content type
application/json
{
  • "hasPassword": true
}

Create Password.

Creates a password for the SAM user.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

user_name

Request Body schema: application/json
required

password

password
string

Responses

Request samples

Content type
application/json
{
  • "password": "string"
}

Update Password.

Updates the password of the SAM user.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

user_name

Request Body schema: application/json
required

password

currentPassword
required
string
newPassword
required
string

Responses

Request samples

Content type
application/json
{
  • "currentPassword": "string",
  • "newPassword": "string"
}

Delete user permission.

Deletes the SAM user's permission.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

SAM user name

Responses

Get User Permission.

Retrieves the SAM user's permissions.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

SAM user name

Responses

Response samples

Content type
application/json
{
  • "permission": "string"
}

Update user permission.

Updates the SAM user's permissions.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

SAM user name

Request Body schema: application/json
required

permission

description
string
permission
required
string

JSON string of permissions

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "permission": "string"
}

Revoke all API keys and API tokens that were generated by the specified SAM user.

Revoke all API keys and API tokens that were generated by the specified SAM user. Once revoked, the API key and API token cannot be used to call the SORACOM API, regardless of their expiration time.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

user_name
required
string

SAM user name

Responses

Deletes user trust policy.

Deletes user trust policy for switching user.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

user_name
required
string

SAM user name.

Responses

Gets user trust policy.

Gets user trust policy for switching user.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

user_name
required
string

SAM user name.

Responses

Response samples

Content type
application/json
{
  • "trustPolicy": "string"
}

Updates user trust policy

Updates the trust policy of the user specified by operator_id and user_name parameters.

Warning: Setting a trust policy will allow the operator(s) or user(s) specified in the request body to switch to this SAM user. When switching, the trusted operator(s) or user(s) will be granted the same permissions as this SAM user, and may be able to see session history, traffic history, and other account information.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

user_name
required
string

SAM user name.

Request Body schema: application/json
required

Specify a trust policy.

trustPolicy
string

Trust policy that describes who can switch to this user.

Responses

Request samples

Content type
application/json
{
  • "trustPolicy": "{\"statements\": [{\"effect\":\"allow\",\"principal\":{\"soracom\":[\"srn:soracom:OPXXXXXXXXXX::User:accounting\"]}}]}"
}

Delete the default permissions

Delete the default permissions rule that is applied to all of the SAM

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

Responses

Get the default permissions

Get the default permissions rule that is applied to all of the SAM users

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

Responses

Response samples

Content type
application/json
{
  • "defaultPermissions": "string"
}

Update the default permissions

Update the default permissions rule that is applied to all of the SAM

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

Request Body schema: application/json
required

request

permissions
required
string

JSON string of permissions

Responses

Request samples

Content type
application/json
{
  • "permissions": "string"
}

PortMapping

Soracom Napter

Retrieve a list of Napter On-Demand Remote Access entries

Returns a list of Napter On-Demand Remote Access entries.

Authorizations:
(api_keyapi_token)
query Parameters
limit
integer

Maximum number of results per response page.

last_evaluated_key
string

The last On-Demand Remote Access ID retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next entry onward.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Napter On-Demand Remote Access entry

Create a new Napter On-Demand Remote Access entry.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

Settings for the On-Demand Remote Access to be created.

required
object (PortMappingDestination)

When creating an On-Demand Remote Access entry, you must specify either imsi or simId.

duration
number

The duration (in seconds) to maintain the On-Demand Remote Access entry (the time to allow remote access). After the specified time has passed, the On-Demand Remote Access entry will be automatically deleted. The maximum duration is 8 hours.

object (PortMappingSource)
tlsRequired
boolean

Whether to encrypt the connection from the source to Soracom using TLS.

  • true: Encrypt using TLS. Specify this if the device is listening on HTTP.
  • false: Do not use TLS. Specify this when connecting to the device via SSH or if the device is listening on HTTPS. Note that communication from the source to the device is encrypted in SSH and HTTPS.

Responses

Request samples

Content type
application/json
{
  • "destination": {
    },
  • "duration": 0,
  • "source": {
    },
  • "tlsRequired": true
}

Response samples

Content type
application/json
{
  • "createdTime": 0,
  • "destination": {
    },
  • "duration": 0,
  • "endpoint": "string",
  • "expired": true,
  • "expiredTime": 0,
  • "hostname": "string",
  • "imsi": "string",
  • "ipAddress": "string",
  • "operatorId": "string",
  • "placement": "string",
  • "port": 0,
  • "simId": "string",
  • "source": {
    },
  • "tlsRequired": true
}

Delete Napter On-Demand Remote Access entry

Deletes the specified Napter On-Demand Remote Access entry.

Authorizations:
(api_keyapi_token)
path Parameters
ip_address
required
string

IP address of the On-Demand Remote Access entry to be deleted.

port
required
string

Port number of the On-Demand Remote Access entry to be deleted.

Responses

Retrieve a list of Napter On-Demand Remote Access entries created with specified SIM ID

Retrieves a list of Napter On-Demand Remote Access entries created with the specified SIM ID.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target IoT SIM.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Napter On-Demand Remote Access entry with specified SIM ID

Create a new Napter On-Demand Remote Access entry with the specified SIM ID.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target IoT SIM.

Request Body schema: application/json
required

Settings for the On-Demand Remote Access to be created.

required
object (PortMappingDestinationForSim)

Information about the destination when creating an On-Demand Remote Access entry.

duration
number

The duration (in seconds) to maintain the On-Demand Remote Access entry (the time to allow remote access). After the specified time has passed, the On-Demand Remote Access entry will be automatically deleted. The maximum duration is 8 hours.

object (PortMappingSource)
tlsRequired
boolean

Whether to encrypt the connection from the source to Soracom using TLS.

  • true: Encrypt using TLS. Specify this if the device is listening on HTTP.
  • false: Do not use TLS. Specify this when connecting to the device via SSH or if the device is listening on HTTPS. Note that communication from the source to the device is encrypted in SSH and HTTPS.

Responses

Request samples

Content type
application/json
{
  • "destination": {
    },
  • "duration": 0,
  • "source": {
    },
  • "tlsRequired": true
}

Response samples

Content type
application/json
{
  • "createdTime": 0,
  • "destination": {
    },
  • "duration": 0,
  • "endpoint": "string",
  • "expired": true,
  • "expiredTime": 0,
  • "hostname": "string",
  • "imsi": "string",
  • "ipAddress": "string",
  • "operatorId": "string",
  • "placement": "string",
  • "port": 0,
  • "simId": "string",
  • "source": {
    },
  • "tlsRequired": true
}

Retrieve a list of Napter On-Demand Remote Access entries created with specified IMSI

Retrieves a list of Napter On-Demand Remote Access entries where destinationChoosingStrategy is IMSI_PRIORITIZED (entries created with specified IMSI).

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

IMSI of the target.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Query

Search SIMs, Soracom Inventory devices, and Sigfox devices

Search Soracom Inventory devices by query

Search Soracom Inventory devices by query terms. It returns partial match results. When this API permission is allowed, it grants the authority to search and retrieve all Soracom Inventory devices that include their group information.

Warning: Use this API when the device ID of the target Inventory device is unknown, or when you want to retrieve a list of Inventory devices that match conditions. If you know the device ID, use the Device:getDevice API.

Authorizations:
(api_keyapi_token)
query Parameters
name
Array of strings

Name to search.

group
Array of strings

Group name to search.

group_id
Array of strings

Group ID to search.

deviceId
Array of strings

Soracom Inventory device ID to search.

tag
Array of strings

String of tag values to search.

imsi
Array of strings

IMSI of the device that was used on bootstrapping.

imei
Array of strings

IMEI of the device that was used on bootstrapping.

limit
integer <int32> <= 100
Default: 10

The maximum number of items to retrieve.

last_evaluated_key
string

The Soracom Inventory device ID of the last Inventory device retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next Inventory device onward.

search_type
string
Default: "and"
Enum: "and" "or"

Type of the search ('AND searching' or 'OR searching').

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Search Sigfox devices by query

Search Sigfox devices by query terms. It returns partial match results. When this API permission is allowed, it grants the authority to search and retrieve all Sigfox devices that includes their group information.

Warning: Use this API when the device ID of the target Sigfox device is unknown, or when you want to retrieve a list of Sigfox devices that match conditions. If you know the device ID, use the SigfoxDevice:getSigfoxDevice API.

Authorizations:
(api_keyapi_token)
query Parameters
name
Array of strings

Name to search.

group
Array of strings

Group name to search.

group_id
Array of strings

Group ID to search.

deviceId
Array of strings

Sigfox device ID to search.

tag
Array of strings

String of tag values to search.

status
string
Default: "and"
Enum: "active" "inactive" "suspended" "terminated" "shipped" "ready" "inStock" "banned" "standby"

Status of Sigfox devices.

registration
string
Default: "and"
Enum: "notStarted" "pending" "success" "failed"

Registration status of Sigfox devices.

limit
integer <int32> <= 100
Default: 10

The maximum number of items to retrieve.

last_evaluated_key
string

The Sigfox device ID of the last Sigfox device retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next Sigfox device onward.

search_type
string
Default: "and"
Enum: "and" "or"

Type of the search ('AND searching' or 'OR searching').

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Search SIMs by query terms

Searches for SIMs using specified query parameters.

  • Supports partial matching.
  • Case-insensitive.
  • Multiple search values can be specified for the following parameters by separating each value with a comma , (or %2C when URL-encoded). Note that the literal character , itself cannot be used as part of a search value.
    • name
    • group
    • sim_id
    • imsi
    • msisdn
    • iccid
    • serial_number
    • tag
    • status
    • subscription
    • module_type
  • Each search value must be at least 2 characters long. When using a comma , to specify multiple search values, each value must also be at least 2 characters long (e.g., ab,c is invalid because c is only 1 character long).
  • When multiple query parameters are specified, the search type (AND search or OR search) can be specified using search_type.

Warning: When this API permission is allowed, it grants the authority to search and retrieve all SIMs that include their group information.

Warning: Use this API when the SIM ID of the target IoT SIM is unknown, or when you want to retrieve a list of SIMs that match certain conditions. If you know the SIM ID, please use the Sim:getSim API instead.

Authorizations:
(api_keyapi_token)
query Parameters
name
Array of strings
Examples:
  • - No filter
  • name=example-sim - Search for IoT SIMs with specific name

Name to search.

group
Array of strings
Examples:
  • - No filter
  • group=example-group - Search for IoT SIMs in specific group

Name of the group to which the IoT SIM belongs.

group_id
Array of strings

Search for IoT SIMs whose group ID matches the specified value.

sim_id
Array of strings

Identifier of the SIM to search.

imsi
Array of strings

IMSI to search.

msisdn
Array of strings

MSISDN to search.

iccid
Array of strings

ICCID to search. An identifier used to identify a SIM card or virtual IoT SIM (Virtual SIM/Subscriber).

serial_number
Array of strings

Serial number to search. This is set only for IoT SIMs for specific regions.

tag
Array of strings

String of tag values to search. For more information, please refer to Using Tags with Soracom Air.

bundles
Array of strings

Bundles type to search.

status
Array of strings

Status of the IoT SIM to search.

  • ready
  • active
  • inactive
  • standby
  • suspended
  • terminated
  • shipped
session_status
string <string>
Default: "NA"
Enum: "NA" "ONLINE" "OFFLINE"

Status of the session to search. Specify one of the following:

  • NA: Any.
  • ONLINE: Online.
  • OFFLINE: Offline.
subscription
Array of strings

Subscription to search. Use exact match for the search. If specifying multiple subscriptions, please set search_type to OR.

  • For Japan coverage, specify one of the following:
    • plan-D: plan-D (without bundle), plan-D (D-500MB).
    • plan-K2: plan-K2 (K2-500MB).
    • plan-DU
    • plan-KM1
    • plan-K
    • planArc01: Virtual SIM/Subscriber.
  • For global coverage, specify one of the following:
    • plan01s
    • plan01s-low_data_volume: plan01s - Low Data Volume.
    • planX3: planX3 (X3-5MB), planX3.
    • planP1
    • plan-US
    • plan-US-max
    • planX1
    • planX2
    • planX3-EU
    • plan-US-NA
    • planArc01: Virtual SIM/Subscriber.
module_type
Array of strings

The form factor of the physical SIM to search.

  • mini: standard (2FF) size.
  • micro: micro (3FF) size.
  • nano: nano (4FF) size.
  • trio: 3 in 1 (can be cut into 2FF/3FF/4FF depending on how you cut it).
  • embedded: Embedded (MFF2).
  • virtual: Virtual SIM/Subscriber.
  • integrated: Embedded (iSIM).
  • profilePackage: Profile Package (eSIM profile).
limit
integer <int32> <= 100
Default: 10

The maximum number of items to retrieve.

last_evaluated_key
string

The SIM ID of the last SIM retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next SIM onward.

search_type
string
Default: "and"
Enum: "and" "or"

The type of search condition.

  • AND: SIMs which match all of the search parameters will be returned (default).
  • OR: SIMs which match any of the search parameters will be returned.

If the value of a search parameter contains a comma , (or %2C when URL-encoded), the value will be split at each comma and treated as multiple search values, each of which will be evaluated based on the specified AND or OR condition.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

(DEPRECATED) Search subscribers by query terms Deprecated

(DEPRECATED: please consider to use /query/sims API instead ) Search subscribers by query terms. It returns partial match results. When this API permission is allowed, it grants the authority to search and retrieve all SIMs that includes their group information.

Authorizations:
(api_keyapi_token)
query Parameters
name
Array of strings

Name to search.

group
Array of strings

Group name to search.

imsi
Array of strings

IMSI to search.

msisdn
Array of strings

MSISDN to search.

iccid
Array of strings

ICCID to search.

serial_number
Array of strings

Serial number to search.

tag
Array of strings

String of tag values to search.

subscription
Array of strings

Subscription to search. Use exact match for the search. If specifying multiple subscriptions, please set search_type to OR.

  • For Japan coverage, specify one of the following:
    • plan-D: plan-D (without bundle), plan-D (D-500MB).
    • plan-K2: plan-K2 (K2-500MB).
    • plan-DU
    • plan-KM1
    • plan-K
    • planArc01: Virtual SIM/Subscriber.
  • For global coverage, specify one of the following:
    • plan01s
    • plan01s-low_data_volume: plan01s - Low Data Volume.
    • planX3: planX3 (X3-5MB), planX3.
    • planP1
    • plan-US
    • plan-US-max
    • planX1
    • planX2
    • planX3-EU
    • plan-US-NA
    • planArc01: Virtual SIM/Subscriber.
module_type
Array of strings

Module type (e.g. mini, virtual) to search.

limit
integer <int32> <= 100
Default: 10

The maximum number of item to retrieve.

last_evaluated_key
string

The IMSI of the last subscriber retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next subscriber onward.

search_type
string
Default: "and"
Enum: "and" "or"

Type of the search ('AND searching' or 'OR searching').

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Search traffic volume ranking of subscribers

Search traffic volume ranking of subscribers.

Authorizations:
(api_keyapi_token)
query Parameters
from
required
integer <int64>

The beginning point of searching range (UNIX time in milliseconds).

to
required
integer <int64>

The end point of searching range (UNIX time in milliseconds).

limit
integer <int32> <= 500
Default: 10

The maximum number of item to retrieve.

order
string
Default: "desc"
Enum: "asc" "desc"

The order of ranking.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

SigfoxDevice

Soracom Air for Sigfox devices

List Sigfox devices.

Returns a list of Sigfox devices that match certain criteria. If the total number of Sigfox devices does not fit in one page, a URL for accessing the next page is returned in the link header of the response.

Authorizations:
(api_keyapi_token)
query Parameters
tag_name
string

Tag name for filtering the search (exact match).

tag_value
string

Tag search string for filtering the search. Required when tag_name has been specified.

tag_value_match_mode
string
Default: "exact"
Enum: "exact" "prefix"

Tag match mode.

limit
integer

Maximum number of Sigfox devices to retrieve.

last_evaluated_key
string

The device ID of the last Sigfox device retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next Sigfox device onward.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Sigfox device.

Returns information about the specified Sigfox device.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target Sigfox device.

Responses

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "groupId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastSeen": {
    },
  • "operatorId": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Retrieves data sent from a Sigfox device to Harvest Data

Retrieves data that matches the specified conditions from the data sent by the specified Sigfox device to Harvest Data. If the data entries do not fit in one page, a URL to retrieve the next page with the same conditions will be included in the link header of the response.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

ID of the Sigfox device from which to retrieve data. The ID of a Sigfox device can be obtained using the SigfoxDevice:listSigfoxDevices API.

query Parameters
from
integer

Start time of the target period (UNIX time in milliseconds).

to
integer

End time of the target period (UNIX time in milliseconds).

sort
string
Default: "desc"
Enum: "desc" "asc"

Sort order of data entries. Either descending order (latest data entry first) or ascending order (oldest data entry first).

limit
integer [ 1 .. 1000 ]

Maximum number of data entries to retrieve (1 to 1000). The default is 10.

last_evaluated_key
string

Timestamp of the last data entry retrieved on the previous page. By specifying this parameter, the list starting from the next data entry can be obtained.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Send data to a Sigfox device.

Sends data to the specified Sigfox device. The data will be stored until the device sends a next uplink message. If another message destined for the same Sigfox device ID is already waiting to be sent, the existing message will be discarded, and the new message will be sent instead.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

ID of the recipient device.

Request Body schema: application/json
required

Binary data encoded as a hexadecimal string. Length of original binary data must be 8 octets (16 characters when encoded as a hexadecimal string).

data
string

Responses

Request samples

Content type
application/json
{
  • "data": "string"
}

Disable Termination of Sigfox device.

Disables termination of specified Sigfox device.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target Sigfox device.

Responses

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "groupId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastSeen": {
    },
  • "operatorId": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Enable Termination of Sigfox device.

Enables termination of specified Sigfox device.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target Sigfox device.

Responses

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "groupId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastSeen": {
    },
  • "operatorId": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Registers a Sigfox device.

Registers a Sigfox device.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target Sigfox device to register.

Request Body schema: application/json
required

Sigfox device registration request.

productCertificationId
string
registrationSecret
string
object

Responses

Request samples

Content type
application/json
{
  • "productCertificationId": "string",
  • "registrationSecret": "string",
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "groupId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastSeen": {
    },
  • "operatorId": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Adds a Sigfox device to a Sigfox group

Adds a Sigfox device to a Sigfox group.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

ID of the target Sigfox device. The ID of a Sigfox device can be obtained using the SigfoxDevice:listSigfoxDevices API.

Request Body schema: application/json
required
groupId
string

Group ID. The group ID can be obtained using the Group:listGroups API.

Responses

Request samples

Content type
application/json
{
  • "groupId": "string"
}

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "groupId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastSeen": {
    },
  • "operatorId": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Bulk Insert or Update Sigfox device Tags.

Inserts/updates tags for the specified Sigfox device.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target Sigfox device.

Request Body schema: application/json
required

Array of tags to be inserted/updated.

Array
tagName
required
string
tagValue
required
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "groupId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastSeen": {
    },
  • "operatorId": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Delete Sigfox device Tag.

Deletes a tag from the specified Sigfox device.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target Sigfox device.

tag_name
required
string

Tag name to be deleted. (This will be part of a URL path, so it needs to be percent-encoded. In JavaScript, specify the name after it has been encoded using encodeURIComponent().)

Responses

Terminate Sigfox device.

Terminates the specified Sigfox device.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

Device ID of the target Sigfox device.

query Parameters
delete_immediately
boolean
Default: false

If the Sigfox device is deleted immediately.

Responses

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "groupId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastSeen": {
    },
  • "operatorId": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Removes a Sigfox device from a Sigfox group

Removes a Sigfox device from a Sigfox group.

Authorizations:
(api_keyapi_token)
path Parameters
device_id
required
string

ID of the target Sigfox device. The ID of a Sigfox device can be obtained using the SigfoxDevice:listSigfoxDevices API.

Responses

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "groupId": "string",
  • "lastModifiedTime": "2019-08-24T14:15:22Z",
  • "lastSeen": {
    },
  • "operatorId": "string",
  • "status": "active",
  • "tags": {
    },
  • "terminationEnabled": false
}

Sim

Soracom Air for Cellular SIM information, operations, and cancellation

(New API equivalent to Subscriber but supports subscription containers)

List SIMs

Returns a list of SIMs. If the total number of SIMs does not fit in one page, a URL for accessing the next page is returned in the link header of the response.

Authorizations:
(api_keyapi_token)
query Parameters
limit
integer

Maximum number of SIMs to retrieve. However, the number of SIMs returned may be less than the specified value.

last_evaluated_key
string

The value of the x-soracom-next-key header from the previous response. Specify this to retrieve the next page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a new virtual SIM/Subscriber

Creates a new Soracom Arc virtual SIM/Subscriber. For details, please refer to Creating Virtual SIMs.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

Virtual SIM/Subscriber creation request.

subscription
required
string
Value: "planArc01"

To create a virtual SIM/Subscriber, specify planArc01.

type
required
string
Value: "virtual"

To create a virtual SIM/Subscriber, specify virtual.

Responses

Request samples

Content type
application/json
{
  • "subscription": "planArc01",
  • "type": "virtual"
}

Response samples

Content type
application/json
{
  • "activeProfileId": "string",
  • "arcSessionStatus": {
    },
  • "capabilities": {
    },
  • "createdTime": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "imeiLock": {
    },
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "localInfo": {
    },
  • "moduleType": "mini",
  • "operatorId": "string",
  • "otaSerialNumber": "string",
  • "pcapEndTime": 0,
  • "pcapStartTime": 0,
  • "previousSession": {
    },
  • "profiles": {
    },
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "testmodeExhaustedTime": 0,
  • "type": "euicc"
}

Gets information about the IoT SIM

Gets information about the IoT SIM.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM. The SIM ID can be obtained from the Sim:listSims API.

Responses

Response samples

Content type
application/json
{
  • "activeProfileId": "string",
  • "arcSessionStatus": {
    },
  • "capabilities": {
    },
  • "createdTime": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "imeiLock": {
    },
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "localInfo": {
    },
  • "moduleType": "mini",
  • "operatorId": "string",
  • "otaSerialNumber": "string",
  • "pcapEndTime": 0,
  • "pcapStartTime": 0,
  • "previousSession": {
    },
  • "profiles": {
    },
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "testmodeExhaustedTime": 0,
  • "type": "euicc"
}

Activate SIM

Changes status of specified SIM to "active".

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target SIM. The SIM ID can be obtained from the Sim:listSims API.

Responses

Response samples

Content type
application/json
{
  • "activeProfileId": "string",
  • "arcSessionStatus": {
    },
  • "capabilities": {
    },
  • "createdTime": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "imeiLock": {
    },
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "localInfo": {
    },
  • "moduleType": "mini",
  • "operatorId": "string",
  • "otaSerialNumber": "string",
  • "pcapEndTime": 0,
  • "pcapStartTime": 0,
  • "previousSession": {
    },
  • "profiles": {
    },
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "testmodeExhaustedTime": 0,
  • "type": "euicc"
}

(DEPRECATED) Removes the credentials for Arc from a SIM Deprecated

(DEPRECATED) Removes the credentials (public key) for Soracom Arc from the SIM.

Warning: Do not use this API.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM.

Responses

(DEPRECATED) Attaches the credentials for Arc to a SIM Deprecated

(DEPRECATED) Attaches the credentials (public key) for Soracom Arc to the SIM.

Warning: Please use the renewArcSimCredentials API instead.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target SIM.

Request Body schema: application/json
required

Arc credential attach request

arcClientPeerPublicKey
string

If this parameter is missing, the server generates a keypair.

Responses

Request samples

Content type
application/json
{
  • "arcClientPeerPublicKey": "string"
}

Response samples

Content type
application/json
{
  • "arcClientPeerPrivateKey": "string",
  • "arcClientPeerPublicKey": "string"
}

Renew the credentials for Arc to a SIM

Attaches Arc credential to a SIM and re-initialize a session at once.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target SIM.

Request Body schema: application/json
required

Arc credential attach request

arcClientPeerPublicKey
string

Public key of the Arc client to be granted to the SIM. If this parameter is missing, the server generates a key pair.

Responses

Request samples

Content type
application/json
{
  • "arcClientPeerPublicKey": "string"
}

Response samples

Content type
application/json
{
  • "arcClientPeerPrivateKey": "string",
  • "arcClientPeerPublicKey": "string"
}

Get data sent from a SIM to Harvest Data.

Returns a list of data entries sent to Harvest Data from a SIM that match certain criteria. If the total number of data entries does not fit in one page, a URL for accessing the next page is returned in the link header of the response.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM. The SIM ID can be obtained from the Sim:listSims API.

query Parameters
from
integer

Start time for the data entries search range (UNIX time in milliseconds).

to
integer

End time for the data entries search range (UNIX time in milliseconds).

sort
string
Default: "desc"
Enum: "desc" "asc"

Sort order of the data entries. Either descending (latest data entry first) or ascending (oldest data entry first).

limit
integer [ 1 .. 1000 ]

Maximum number of data entries to retrieve (value range is 1 to 1000). The default is 10.

last_evaluated_key
string

The value of the x-soracom-next-key header from the previous response. Specify this to retrieve the next page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Deactivate SIM

Changes status of specified SIM to "inactive".

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target SIM. The SIM ID can be obtained from the Sim:listSims API.

Responses

Response samples

Content type
application/json
{
  • "activeProfileId": "string",
  • "arcSessionStatus": {
    },
  • "capabilities": {
    },
  • "createdTime": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "imeiLock": {
    },
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "localInfo": {
    },
  • "moduleType": "mini",
  • "operatorId": "string",
  • "otaSerialNumber": "string",
  • "pcapEndTime": 0,
  • "pcapStartTime": 0,
  • "previousSession": {
    },
  • "profiles": {
    },
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "testmodeExhaustedTime": 0,
  • "type": "euicc"
}

Delete and reconnect the Session

Deletes and then reconnects the session for the specified SIM.

Warning: If you attempt to delete the session for an offline IoT SIM, the following error message will be returned:

Error: {"code":"SEM0016","message":"The specified subscriber is offline"}
Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM. The SIM ID can be obtained from the Sim:listSims API.

Responses

Response samples

Content type
application/json
{
  • "activeProfileId": "string",
  • "arcSessionStatus": {
    },
  • "capabilities": {
    },
  • "createdTime": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "imeiLock": {
    },
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "localInfo": {
    },
  • "moduleType": "mini",
  • "operatorId": "string",
  • "otaSerialNumber": "string",
  • "pcapEndTime": 0,
  • "pcapStartTime": 0,
  • "previousSession": {
    },
  • "profiles": {
    },
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "testmodeExhaustedTime": 0,
  • "type": "euicc"
}

Disables termination of the SIM

Enables termination protection for the specified IoT SIM (disables termination).

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target SIM. The SIM ID can be obtained from the Sim:listSims API.

Responses

Response samples

Content type
application/json
{
  • "activeProfileId": "string",
  • "arcSessionStatus": {
    },
  • "capabilities": {
    },
  • "createdTime": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "imeiLock": {
    },
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "localInfo": {
    },
  • "moduleType": "mini",
  • "operatorId": "string",
  • "otaSerialNumber": "string",
  • "pcapEndTime": 0,
  • "pcapStartTime": 0,
  • "previousSession": {
    },
  • "profiles": {
    },
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "testmodeExhaustedTime": 0,
  • "type": "euicc"
}

Send an HTTP request to a device using an IoT SIM

Sends an HTTP request to a device using an IoT SIM and returns the HTTP response from the device in the API response body.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target IoT SIM. The SIM ID can be obtained from the Sim:listSims API.

Request Body schema: application/json
required

Configuration of the HTTP request to send to the device.

body
string

HTTP request body.

Warning: The maximum size of an HTTP request, including the URL, headers, and body, is 5 MiB. If it exceeds 5 MiB, an error will be returned.

object

HTTP request headers. Specify header names and values as key-value pairs.

host
string

Hostname. If not specified, the IP address of the IoT SIM will be used.

method
string
Enum: "GET" "HEAD" "POST" "PUT" "DELETE" "PATCH" "OPTIONS" "TRACE"

HTTP method.

path
string

URL path (e.g., /path/to/resource).

port
integer [ 1 .. 65535 ]
Default: 80

Port number for the HTTP connection.

skipVerify
boolean
Default: false

Whether to skip SSL certificate verification for HTTPS connections.

  • true: Skip verification.
  • false: Perform verification. However, if ssl is false (not using SSL communication), this setting will be ignored.
ssl
boolean
Default: false

Whether to use SSL communication.

  • true: Use SSL communication (HTTPS).
  • false: Do not use SSL communication (HTTP).

Responses

Request samples

Content type
application/json
{
  • "method": "GET",
  • "path": "/readyz?verbose",
  • "port": 6443,
  • "skipVerify": true,
  • "ssl": false
}

Response samples

Content type
application/json
{
  • "body": "string",
  • "headers": {
    },
  • "isBase64Encoded": true,
  • "statusCode": 0
}

Sends ping requests to a SIM.

Sends ICMP ping requests to a SIM.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target SIM. The SIM ID can be obtained from the Sim:listSims API.

Request Body schema: application/json
required

Options for ping requests

numberOfPingRequests
integer <= 5
Default: 1

The number of attempt ping.

timeoutSeconds
integer <= 3
Default: 1

The timeout duration of each ping.

Responses

Request samples

Content type
application/json
{
  • "numberOfPingRequests": 5,
  • "timeoutSeconds": 2
}

Response samples

Content type
application/json
{
  • "rtt": "string",
  • "stat": "string",
  • "success": true
}

Send a command to a RTSP stream to a device using an IoT SIM

Sends a command to a device using an IoT SIM and returns a response based on specified command and options in request.

  • An error occurs if the command does not complete within 10 seconds.
Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target IoT SIM. The SIM ID can be obtained from the Sim:listSims API.

Request Body schema: application/json
required

Command for the RTSP request

SimDownlinkRtspAuthenticationBasic (object) or SimDownlinkRtspAuthenticationNone (object)

Authentication method for RTSP connection. Specify one of the following for type, and provide the required information according to the authentication method.

  • none: No authentication.
  • basic: Basic authentication.

If not specified, the default is none.

required
SimDownlinkRtspCommandSnapshot (string)

RTSP request configuration. Specify the RTSP command to be executed and the options for the RTSP connection.

SimDownlinkRtspCommandSnapshotOptions (object)
path
string

Path of RTSP stream started with /

port
integer [ 1 .. 65535 ]
Default: 554

Port number for the RTSP connection.

Responses

Request samples

Content type
application/json
{
  • "authentication": {
    },
  • "command": "snapshot",
  • "port": 544
}

Connect to a device using an IoT SIM via SSH and execute a specified command

Connects to a device using an IoT SIM via SSH, executes a specified command, and returns the standard output and standard error output in the API response body.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target IoT SIM. The SIM ID can be obtained from the Sim:listSims API.

Request Body schema: application/json
required

Configuration of the SSH connection and the command to execute.

required
SimDownlinkSshPasswordAuthentication (object) or SimDownlinkSshPublicKeyAuthentication (object) or SimDownlinkSshNoAuthentication (object)

Authentication method for SSH connection. Specify one of the following for type, and provide the required information according to the authentication method.

  • password: Password authentication.
  • publickey: Public key authentication.
  • none: No authentication.
command
required
string

Command to be executed on the device via SSH connection. Maximum size is 8192 bytes.

port
integer [ 1 .. 65535 ]
Default: 22

Port number for SSH connection.

username
required
string

Username for SSH connection.

Responses

Request samples

Content type
application/json
Example

Connects to the device using public key authentication and retrieves a list of files.

The private key should be specified as a string in the key field. Use \n to represent newline characters.

{
  • "authentication": {
    },
  • "command": "ls -l",
  • "port": 22,
  • "username": "username"
}

Response samples

Content type
application/json
{
  • "exitcode": 0,
  • "isStderrBase64Encoded": true,
  • "isStdoutBase64Encoded": true,
  • "stderr": "string",
  • "stdout": "string"
}

Connect to a device using an IoT SIM via TCP and send/receive data

Connects to a device using an IoT SIM via TCP, sends specified data, and returns data received from the device.

  • The maximum size of sent and received data is 5 MiB each.
  • If sending and receiving data is not completed within the time specified by timeout, an error will occur.
Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target IoT SIM. The SIM ID can be obtained from the Sim:listSims API.

Request Body schema: application/json
required

Options for TCP connection and data transmission/reception.

SimDownlinkTcpConnectionFireAndForgetOptions (object) or SimDownlinkTcpConnectionWaitFirstOptions (object) or SimDownlinkTcpConnectionWaitAllOptions (object) or SimDownlinkTcpConnectionWaitForPatternOptions (object) or SimDownlinkTcpConnectionIdleTimeoutOptions (object)
Default: {"type":"wait_all"}

Options that specify the behavior of data reception during TCP connection (how the SORACOM API handles responses from the device). Choose one of the following.

payload
required
string

Data to be sent, encoded as a string in the format specified by payloadEncoding. The maximum size is 5 MiB for the encoded string.

payloadEncoding
string (SimDownlinkBinaryEncoding)
Default: "string"
Enum: "string" "base64" "hex"

Encoding format for binary data. "string" is treated as a UTF-8 string. "base64" is Base64 encoding, and "hex" is hexadecimal encoding. Case insensitive for hex.

port
required
integer [ 1 .. 65535 ]

Port number for the TCP connection.

timeout
integer [ 1 .. 300 ]
Default: 30

Timeout duration (seconds) for data transmission and reception. The default value is 30 and the maximum value is 300.

Responses

Request samples

Content type
application/json
{
  • "connectionOptions": {
    },
  • "payload": "SGVsbG8gV29ybGQ=",
  • "payloadEncoding": "base64",
  • "port": 5000,
  • "timeout": 5
}

Response samples

Content type
application/json
{
  • "data": "string",
  • "dataEncoding": "string"
}

Send data using IoT SIM via UDP

Sends specified data to a device using an IoT SIM via UDP.

Warning: Unlike TCP, UDP communication lacks retransmission and sequencing mechanisms, which may lead to packet loss or out-of-order arrival.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target IoT SIM. The SIM ID can be obtained from the Sim:listSims API.

Request Body schema: application/json
required

Options for UDP data transmission.

payload
required
string

Data to be sent, encoded as a string in the format specified by payloadEncoding. The maximum size is 1,472 bytes for the encoded string.

Warning: Depending on the network path, the actual maximum size may be smaller. Data exceeding the maximum allowable size for the network path may be discarded.

payloadEncoding
string (SimDownlinkBinaryEncoding)
Default: "string"
Enum: "string" "base64" "hex"

Encoding format for binary data. "string" is treated as a UTF-8 string. "base64" is Base64 encoding, and "hex" is hexadecimal encoding. Case insensitive for hex.

port
required
integer [ 1 .. 65535 ]

Port number for UDP.

Responses

Request samples

Content type
application/json
{
  • "payload": "SGVsbG8gV29ybGQ=",
  • "payloadEncoding": "base64",
  • "port": 5000
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Enables termination of the SIM.

Disables termination protection for the specified IoT SIM (enables termination).

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target SIM. The SIM ID can be obtained from the Sim:listSims API.

Responses

Response samples

Content type
application/json
{
  • "activeProfileId": "string",
  • "arcSessionStatus": {
    },
  • "capabilities": {
    },
  • "createdTime": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "imeiLock": {
    },
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "localInfo": {
    },
  • "moduleType": "mini",
  • "operatorId": "string",
  • "otaSerialNumber": "string",
  • "pcapEndTime": 0,
  • "pcapStartTime": 0,
  • "previousSession": {
    },
  • "profiles": {
    },
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "testmodeExhaustedTime": 0,
  • "type": "euicc"
}

Retrieves session event history (session history)

Retrieves event history of session creation/modification/disconnection for the past 32 days for the specified SIM. If the total number of events does not fit in one page, a URL for accessing the next page is returned in the link header of the response.

Check the current session using the Sim:getSim API. To check the current session with this API, check the value of event in the latest session history. Refer to Subscriber Status for the meaning of a session.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM. The SIM ID can be obtained from the Sim:listSims API.

query Parameters
from
integer

Start time (UNIX time in milliseconds) of the period to retrieve the session event history.

to
integer

End time (UNIX time in milliseconds) of the period to retrieve the session event history.

limit
integer

Maximum number of event histories to retrieve. However, the number of event histories returned may be less than the specified value.

last_evaluated_key
string

The value of the x-soracom-next-key header from the previous response. Specify this to retrieve the next page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Lists packet capture sessions associated with the SIM

Lists packet capture sessions associated with the SIM.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM.

query Parameters
last_evaluated_key
string

The value of the x-soracom-next-key header from the previous response. Specify this to retrieve the next page.

limit
integer <int32>
Default: 10

Max number of results in a response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a packet capture session associated with the SIM

Creates a packet capture session associated with the SIM.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM.

Request Body schema: application/json
required

A packet capture session request.

duration
required
integer <int32> [ 30 .. 86400 ]
prefix
string^[0-9A-Za-z_\-]{0,100}$

Responses

Request samples

Content type
application/json
{
  • "duration": 30,
  • "prefix": "string"
}

Response samples

Content type
application/json
{
  • "createdTime": "2019-08-24T14:15:22Z",
  • "duration": 0,
  • "endedTime": "2019-08-24T14:15:22Z",
  • "failedReason": "string",
  • "prefix": "string",
  • "sessionId": "string",
  • "startedTime": "2019-08-24T14:15:22Z",
  • "status": "REQUESTED",
  • "url": "http://example.com"
}

Deletes a packet capture session associated with the SIM

Deletes a packet capture session associated with the SIM.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM.

session_id
required
string

Packet capture session ID

Responses

Response samples

Content type
application/json
{
  • "createdTime": "2019-08-24T14:15:22Z",
  • "duration": 0,
  • "endedTime": "2019-08-24T14:15:22Z",
  • "failedReason": "string",
  • "prefix": "string",
  • "sessionId": "string",
  • "startedTime": "2019-08-24T14:15:22Z",
  • "status": "REQUESTED",
  • "url": "http://example.com"
}

Gets a packet capture session associated with the SIM

Gets a packet capture session associated with the SIM.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM.

session_id
required
string

Packet capture session ID

Responses

Response samples

Content type
application/json
{
  • "createdTime": "2019-08-24T14:15:22Z",
  • "duration": 0,
  • "endedTime": "2019-08-24T14:15:22Z",
  • "failedReason": "string",
  • "prefix": "string",
  • "sessionId": "string",
  • "startedTime": "2019-08-24T14:15:22Z",
  • "status": "REQUESTED",
  • "url": "http://example.com"
}

Stops a packet capture session associated with the SIM

Stops a packet capture session associated with the SIM.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM.

session_id
required
string

Packet capture session ID

Responses

Response samples

Content type
application/json
{
  • "createdTime": "2019-08-24T14:15:22Z",
  • "duration": 0,
  • "endedTime": "2019-08-24T14:15:22Z",
  • "failedReason": "string",
  • "prefix": "string",
  • "sessionId": "string",
  • "startedTime": "2019-08-24T14:15:22Z",
  • "status": "REQUESTED",
  • "url": "http://example.com"
}

Adds a new secondary subscription to an IoT SIM

Add a new secondary subscription (additional subscription or virtual SIM/Subscriber) to the IoT SIM.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM.

iccid
required
string

ICCID of the target IoT SIM. For IoT SIMs that do not support eUICC, the ICCID and SIM ID are the same.

Request Body schema: application/json
enable
boolean

In the case of additional subscriptions, specify whether to activate the additional subscription as soon as it has been downloaded. The default is true.

  • true: Activate immediately.
  • false: Keep inactive. Additional subscription will be activated at the next network registration or session registration.

Note that in the case of a virtual SIM/Subscriber, it is ignored.

subscription
required
string
Enum: "planP1" "planX1" "planX2" "planX3" "plan-US-max" "planArc01"

Name of the secondary subscription to be added.

  • planP1, planX1, planX2, planX3, plan-US-max: Additional Subscription
  • planArc01: Virtual SIM/Subscriber
tag
string <= 64 characters ^[a-zA-Z0-9\-_:]+$

Tag to set on the OTA scripts generated for this operation. If not specified, the default tag {operatorId}:addSubscription is used.

  • Only alphanumeric characters, hyphens (-), underscores (_), and colons (:) are allowed.
  • Maximum length is 64 characters.
type
string
Enum: "virtual" "cellular"
  • virtual: When subscription is planArc01.
  • cellular: When subscription is other than planArc01.

Responses

Request samples

Content type
application/json
Example
{
  • "enable": true,
  • "subscription": "planX3",
  • "type": "cellular"
}

Response samples

Content type
application/json
{
  • "arcClientPeerPrivateKey": "string",
  • "arcClientPeerPublicKey": "string",
  • "iccid": "string",
  • "otaSupported": true,
  • "primaryImsi": "string",
  • "subscribers": {
    }
}

Cancel the OTA to the subscription container for an additional subscription

Cancel the OTA of the additional subscription before the OTA starts. Note that once the IoT SIM goes online and the OTA begins, it cannot be canceled.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

The SIM ID of the target SIM.

iccid
required
string

The ICCID of the target subscription container.

imsi
required
string <IMSI>

The IMSI of the target additional subscription.

Responses

Response samples

Content type
application/json
{
  • "containers": [
    ],
  • "countryMapping": {
    }
}

Terminates subscription container

Terminates subscription container. Currently this API supports only for virtual SIM/Subscribers for Soracom Arc.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target subscription container.

iccid
required
string

ICCID of the target subscription container.

imsi
required
string <IMSI>

IMSI of the target subscription container.

Responses

Registers an IoT SIM to an operator

Registers an IoT SIM to an operator.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM.

Request Body schema: application/json
required

A SIM registration request.

groupId
string
registrationSecret
required
string

PUK or PASSCODE on SIM card

object (TagSet)

An object which always contains at least one property "name" with a string value. If you give a subscriber/SIM a name, the name will be returned as the value of the "name" property. If the subscriber/SIM does not have a name, an empty string "" is returned. In addition, if you create any custom tags for the subscriber/SIM, each custom tag will appear as additional properties in the object.

Responses

Request samples

Content type
application/json
{
  • "groupId": "string",
  • "registrationSecret": "string",
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "activeProfileId": "string",
  • "arcSessionStatus": {
    },
  • "capabilities": {
    },
  • "createdTime": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "imeiLock": {
    },
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "localInfo": {
    },
  • "moduleType": "mini",
  • "operatorId": "string",
  • "otaSerialNumber": "string",
  • "pcapEndTime": 0,
  • "pcapStartTime": 0,
  • "previousSession": {
    },
  • "profiles": {
    },
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "testmodeExhaustedTime": 0,
  • "type": "euicc"
}

Gets SIM local information report

Gets SIM local information report.

Alert: One SMS will be sent to the IoT device per request for SIM local information report. Sending SMS to IoT devices is charged. For more information on fees, refer to the following page

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target SIM.

Responses

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Send an SMS to an IoT SIM

Sends an SMS to the specified IoT SIM.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target SIM to which the SMS will be sent. The SIM ID can be obtained from the Sim:listSims API.

Request Body schema: application/json
required
encodingType
integer
Default: 2

Encoding type of the message body. Default is 2 (DCS_UCS2).

  • 1: Send in GSM 7-bit that only supports standard alphabet. Kanji, Cyrillic, and Arabic characters cannot be sent. Maximum 160 characters (maximum 140 bytes).

    Example: {"encodingType": 1, "payload": "Test message."}

  • 2: Send in UCS-2, which supports Kanji, Cyrillic, Arabic, etc. Maximum 70 characters.

    Example: {"encodingType": 2, "payload": "テストメッセージ"}

payload
string

Responses

Request samples

Content type
application/json
{
  • "encodingType": 2,
  • "payload": "Test message"
}

Response samples

Content type
application/json
{
  • "messageId": "string"
}

Creates a Soracom Arc session

Creates a Soracom Arc session. If the session already exists, re-create it.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target SIM.

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "arcAllowedIPs": [
    ],
  • "arcClientPeerIpAddress": "string",
  • "arcClientPeerPublicKey": "string",
  • "arcServerEndpoint": "string",
  • "arcServerPeerPublicKey": "string"
}

Sets expiry time of IoT SIM

Sets the expiration date and action for the specified IoT SIM.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target SIM. The SIM ID can be obtained from the Sim:listSims API.

Request Body schema: application/json
required

Expiration date (UNIX time in milliseconds) and action after the update.

expiryAction
string or null
Enum: "doNothing" "deleteSession" "deactivate" "suspend" "terminate" "(null value)"

Action at expiration. Specify one of the following Please refer to Soracom Air Expiration Function for more detail. You have to disable termination protection if you want to specify terminate as an action.

If omitted, a null value is set.

  • doNothing : do nothing
  • deleteSession : delete session of the SIM if any
  • deactivate : change the SIM status to Inactive
  • suspend : change the SIM status to Suspended
  • terminate : forcibly end any existing connections, and terminate the SIM
  • null value : not set (It works the same as doNothing)
expiryTime
required
integer <int64>

Timestamp of date and time set using the Expiration function (UNIX time in milliseconds)

Responses

Request samples

Content type
application/json
{
  • "expiryAction": "deactivate",
  • "expiryTime": 1893423600000
}

Response samples

Content type
application/json
{
  • "activeProfileId": "string",
  • "arcSessionStatus": {
    },
  • "capabilities": {
    },
  • "createdTime": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "imeiLock": {
    },
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "localInfo": {
    },
  • "moduleType": "mini",
  • "operatorId": "string",
  • "otaSerialNumber": "string",
  • "pcapEndTime": 0,
  • "pcapStartTime": 0,
  • "previousSession": {
    },
  • "profiles": {
    },
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "testmodeExhaustedTime": 0,
  • "type": "euicc"
}

Adds a SIM to a SIM group

Adds a SIM to a SIM group.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

ID of the target SIM. The SIM ID can be obtained using the Sim:listSims API.

Request Body schema: application/json
required
groupId
string

Group ID. The group ID can be obtained using the Group:listGroups API.

Responses

Request samples

Content type
application/json
{
  • "groupId": "string"
}

Response samples

Content type
application/json
{
  • "activeProfileId": "string",
  • "arcSessionStatus": {
    },
  • "capabilities": {
    },
  • "createdTime": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "imeiLock": {
    },
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "localInfo": {
    },
  • "moduleType": "mini",
  • "operatorId": "string",
  • "otaSerialNumber": "string",
  • "pcapEndTime": 0,
  • "pcapStartTime": 0,
  • "previousSession": {
    },
  • "profiles": {
    },
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "testmodeExhaustedTime": 0,
  • "type": "euicc"
}

Sets IMEI lock configuration for the SIM

Sets IMEI that the SIM should be locked to.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM.

Request Body schema: application/json

IMEI lock configuration for the SIM. (IMEI can be left blank for locking to the current IMEI of an online SIM.)

imei
string

IMEI of the target device. If you want to establish a session even when the IMEI is temporarily not reported, append |ANONYMOUS to the IMEI value.

For example, if the IMEI specified is 123456789012345, specifying 123456789012345|ANONYMOUS as the parameter value will allow a session to be established even when the IMEI is temporarily not reported.

Responses

Request samples

Content type
application/json
{
  • "imei": "string"
}

Response samples

Content type
application/json
{
  • "activeProfileId": "string",
  • "arcSessionStatus": {
    },
  • "capabilities": {
    },
  • "createdTime": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "imeiLock": {
    },
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "localInfo": {
    },
  • "moduleType": "mini",
  • "operatorId": "string",
  • "otaSerialNumber": "string",
  • "pcapEndTime": 0,
  • "pcapStartTime": 0,
  • "previousSession": {
    },
  • "profiles": {
    },
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "testmodeExhaustedTime": 0,
  • "type": "euicc"
}

Set SIM to standby mode.

Changes status of specified SIM to "standby".

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target SIM. The SIM ID can be obtained from the Sim:listSims API.

Responses

Response samples

Content type
application/json
{
  • "activeProfileId": "string",
  • "arcSessionStatus": {
    },
  • "capabilities": {
    },
  • "createdTime": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "imeiLock": {
    },
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "localInfo": {
    },
  • "moduleType": "mini",
  • "operatorId": "string",
  • "otaSerialNumber": "string",
  • "pcapEndTime": 0,
  • "pcapStartTime": 0,
  • "previousSession": {
    },
  • "profiles": {
    },
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "testmodeExhaustedTime": 0,
  • "type": "euicc"
}

List IoT SIM status operation history

List IoT SIM status operation history. Status operation history entry records what status operations were performed for which IMSI and which subscriptions, along with the operation time. It includes speed class, group ID, IoT SIM status, etc. If the total number of status operation history entry does not fit in one page, a URL for accessing the next page is returned in the link header of the response.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM.

query Parameters
from
integer

Start time of the status operation history entry to be searched (UNIX time in milliseconds). If not specified, from is set to the oldest status operation history entry time of the target IoT SIM.

to
integer

End time of the status operation history entry to be searched (UNIX time in milliseconds). If not specified, to is set to the current time.

last_evaluated_key
string

The value of the x-soracom-next-key header from the previous response. Specify this to retrieve the next page.

sort
string
Default: "desc"
Enum: "desc" "asc"

Sort order of status operation history entry. Either descending (latest data entry first) or ascending (oldest data entry first).

limit
integer [ 1 .. 100 ]
Default: 30

Maximum number of items to retrieve in one request. The response may contain fewer items than the specified limit.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Suspend SIM

Changes status of specified SIM to "suspended".

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target SIM. The SIM ID can be obtained from the Sim:listSims API.

Responses

Response samples

Content type
application/json
{
  • "activeProfileId": "string",
  • "arcSessionStatus": {
    },
  • "capabilities": {
    },
  • "createdTime": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "imeiLock": {
    },
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "localInfo": {
    },
  • "moduleType": "mini",
  • "operatorId": "string",
  • "otaSerialNumber": "string",
  • "pcapEndTime": 0,
  • "pcapStartTime": 0,
  • "previousSession": {
    },
  • "profiles": {
    },
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "testmodeExhaustedTime": 0,
  • "type": "euicc"
}

Bulk Add or Update tags for an IoT SIM

Adds or updates tags for the specified IoT SIM.

The name of the IoT SIM is registered as a tag with the key name.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM. The SIM ID can be obtained from the Sim:listSims API.

Request Body schema: application/json
required

Array of tags to be added or updated.

Array
tagName
required
string
tagValue
required
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "activeProfileId": "string",
  • "arcSessionStatus": {
    },
  • "capabilities": {
    },
  • "createdTime": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "imeiLock": {
    },
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "localInfo": {
    },
  • "moduleType": "mini",
  • "operatorId": "string",
  • "otaSerialNumber": "string",
  • "pcapEndTime": 0,
  • "pcapStartTime": 0,
  • "previousSession": {
    },
  • "profiles": {
    },
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "testmodeExhaustedTime": 0,
  • "type": "euicc"
}

Deletes a tag from the specified SIM

Deletes a tag from the specified IoT SIM.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM. The SIM ID can be obtained from the Sim:listSims API.

tag_name
required
string

Tag name to be deleted. This will be part of a URL path, so it needs to be percent-encoded. In JavaScript, specify the name after it has been encoded using encodeURIComponent().

Warning: If you are using Soracom CLI, do not use URL encoding (percent-encoding).

Responses

Terminate an IoT SIM

Terminates the specified IoT SIM. Please use the Sim:enableSimTermination API in advance to enable termination (remove termination protection).

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string <SimId>

SIM ID of the target SIM. The SIM ID can be obtained from the Sim:listSims API.

Responses

Response samples

Content type
application/json
{
  • "activeProfileId": "string",
  • "arcSessionStatus": {
    },
  • "capabilities": {
    },
  • "createdTime": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "imeiLock": {
    },
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "localInfo": {
    },
  • "moduleType": "mini",
  • "operatorId": "string",
  • "otaSerialNumber": "string",
  • "pcapEndTime": 0,
  • "pcapStartTime": 0,
  • "previousSession": {
    },
  • "profiles": {
    },
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "testmodeExhaustedTime": 0,
  • "type": "euicc"
}

Get usage of IoT SIM in testing status

Retrieves the usage information of "testing" status of the IoT SIM. Data can only be retrieved while the IoT SIM is in "testing" status.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target IoT SIM.

Responses

Response samples

Content type
application/json
{
  • "endedTime": 0,
  • "startedTime": 0,
  • "usage": {
    },
  • "usageLimit": {
    }
}

Deletes expiry time of the SIM

Deletes expiry time of specified SIM and changes it to indefinite.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM. The SIM ID can be obtained from the Sim:listSims API.

Responses

Response samples

Content type
application/json
{
  • "activeProfileId": "string",
  • "arcSessionStatus": {
    },
  • "capabilities": {
    },
  • "createdTime": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "imeiLock": {
    },
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "localInfo": {
    },
  • "moduleType": "mini",
  • "operatorId": "string",
  • "otaSerialNumber": "string",
  • "pcapEndTime": 0,
  • "pcapStartTime": 0,
  • "previousSession": {
    },
  • "profiles": {
    },
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "testmodeExhaustedTime": 0,
  • "type": "euicc"
}

Removes a SIM from a SIM group

Removes a SIM from a SIM group.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

ID of the target SIM. The SIM ID can be obtained using the Sim:listSims API.

Responses

Response samples

Content type
application/json
{
  • "activeProfileId": "string",
  • "arcSessionStatus": {
    },
  • "capabilities": {
    },
  • "createdTime": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "imeiLock": {
    },
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "localInfo": {
    },
  • "moduleType": "mini",
  • "operatorId": "string",
  • "otaSerialNumber": "string",
  • "pcapEndTime": 0,
  • "pcapStartTime": 0,
  • "previousSession": {
    },
  • "profiles": {
    },
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "testmodeExhaustedTime": 0,
  • "type": "euicc"
}

Unsets IMEI lock of SIM

Unsets the IMEI lock of the specified SIM.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM.

Responses

Response samples

Content type
application/json
{
  • "activeProfileId": "string",
  • "arcSessionStatus": {
    },
  • "capabilities": {
    },
  • "createdTime": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "imeiLock": {
    },
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "localInfo": {
    },
  • "moduleType": "mini",
  • "operatorId": "string",
  • "otaSerialNumber": "string",
  • "pcapEndTime": 0,
  • "pcapStartTime": 0,
  • "previousSession": {
    },
  • "profiles": {
    },
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "testmodeExhaustedTime": 0,
  • "type": "euicc"
}

Updates the IoT SIM speed class

Updates the IoT SIM speed class.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM.

Request Body schema: application/json
required

The speed class of the IoT SIM.

speedClass
required
string
Enum: "s1.minimum" "s1.slow" "s1.standard" "s1.fast" "s1.4xfast" "s1.8xfast" "u1.standard" "u1.slow"

Speed class. Specify one of the following. Please specify the speed class that matches the subscription.

  • For plan01s, plan01s - Low Data Volume, planX3 (X3-5MB), planP1, plan-D (without bundle), plan-D (D-500MB), plan-K2 (K2-500MB), plan-K:
    • s1.minimum
    • s1.slow
    • s1.standard
    • s1.fast
    • s1.4xfast
  • For plan-US:
    • s1.minimum
    • s1.slow
    • s1.standard
    • s1.fast
    • s1.4xfast
    • s1.8xfast
  • For plan-DU:
    • u1.standard
    • u1.slow

Warning: Speed class for plan-KM1 and virtual SIM/Subscriber cannot be changed as there is only one speed class available.

Responses

Request samples

Content type
application/json
{
  • "speedClass": "s1.minimum"
}

Response samples

Content type
application/json
{
  • "activeProfileId": "string",
  • "arcSessionStatus": {
    },
  • "capabilities": {
    },
  • "createdTime": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "imeiLock": {
    },
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "localInfo": {
    },
  • "moduleType": "mini",
  • "operatorId": "string",
  • "otaSerialNumber": "string",
  • "pcapEndTime": 0,
  • "pcapStartTime": 0,
  • "previousSession": {
    },
  • "profiles": {
    },
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "testmodeExhaustedTime": 0,
  • "type": "euicc"
}

SimProfileOrder

eSIM profiles

List eSIM profile orders

Returns a list of eSIM profile orders. If the total number of orders does not fit in one page, a URL for accessing the next page is returned in the link header of the response.

Authorizations:
(api_keyapi_token)
query Parameters
limit
integer [ 1 .. 100 ]
Default: 100

Maximum number of eSIM profile orders to retrieve. However, the number of eSIM profile orders returned may be less than the specified value.

last_evaluated_key
string

The ID of the last eSIM profile order retrieved on the previous page. By repeating the API call while specifying this parameter, the next page of eSIM profile orders will be returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new eSIM profile order

Creates a new eSIM profile order without confirming it. An unconfirmed order is valid for 1 day, after which it is automatically canceled. Use the SimProfileOrder:confirmProfileOrder API to confirm the order.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
bundles
Array of strings <= 1 items
Items Enum: "X3-5MB" "US-1MB" "US-3MB" "US-10MB" "US-20MB" "US-50MB" "US-100MB" "US-300MB" "US-500MB" "US-1GB" "US-3GB" "US-5GB" "US-10GB"

Bundles of the eSIM profile to be ordered. Specify one of the following. Please specify the bundle that matches the subscription.

  • For planX3:
    • X3-5MB
  • For plan-US:
    • US-1MB
    • US-3MB
    • US-10MB
    • US-20MB
    • US-50MB
    • US-100MB
    • US-300MB
    • US-500MB
    • US-1GB
    • US-3GB
    • US-5GB
    • US-10GB
description
string <= 100 characters

The description of the order. You can use this to identify the order in the order history.

quantity
required
integer <int32> [ 1 .. 100 ]

The quantity of the eSIM profile to be ordered.

Info: A maximum of 20 eSIM profiles may be purchased per order. If you would like to purchase more, please contact us.

speedClass
string
Enum: "s1.minimum" "s1.slow" "s1.standard" "s1.fast" "s1.4xfast" "s1.8xfast"

The speed class of the eSIM profile to be ordered. Specify one of the following. Please specify the speed class that matches the subscription.

  • For plan01s, planP1, planX1, planX2, planX3:
    • s1.minimum
    • s1.slow
    • s1.standard
    • s1.fast
    • s1.4xfast
  • For plan-US:
    • s1.minimum
    • s1.slow
    • s1.standard
    • s1.fast
    • s1.4xfast
    • s1.8xfast
subscription
required
string

The subscription of the eSIM profile to be ordered.

  • plan01s
  • planP1
  • planX1
  • planX2
  • planX3: Only available for customers located in the European Union and United Kingdom.
  • plan-US: Only available for customers located in in the United States and Canada.

Responses

Request samples

Content type
application/json
{
  • "description": "This is a test order",
  • "quantity": 10,
  • "speedClass": "s1.4xfast",
  • "subscription": "plan01s"
}

Response samples

Content type
application/json
{
  • "bundles": [ ],
  • "description": "This is a test order",
  • "orderedTime": 1718756585000,
  • "profileOrderId": "01902ddd-1cf3-77d9-afc0-fe8d410cadb1",
  • "quantity": 10,
  • "speedClass": "s1.4xfast",
  • "status": "DRAFT",
  • "subscription": "plan01s"
}

Cancel an eSIM profile order

Cancels an unconfirmed eSIM profile order.

Authorizations:
(api_keyapi_token)
path Parameters
profile_order_id
required
string

The ID of the eSIM profile order.

Responses

Get an eSIM profile order

Get an eSIM profile order.

Authorizations:
(api_keyapi_token)
path Parameters
profile_order_id
required
string

The ID of the eSIM profile order.

Responses

Response samples

Content type
application/json
{
  • "bundles": [ ],
  • "description": "This is a test order",
  • "orderedTime": 1718756585000,
  • "profileOrderId": "01902ddd-1cf3-77d9-afc0-fe8d410cadb1",
  • "quantity": 10,
  • "speedClass": "s1.4xfast",
  • "status": "DRAFT",
  • "subscription": "plan01s"
}

Confirm an eSIM profile order

Confirms an unconfirmed eSIM profile order and completes the order. Once confirmed, an eSIM profile order cannot be canceled.

Authorizations:
(api_keyapi_token)
path Parameters
profile_order_id
required
string

The ID of the eSIM profile order.

Responses

Response samples

Content type
application/json
{
  • "bundles": [ ],
  • "confirmedTime": 1718756585000,
  • "description": "This is a test order",
  • "orderedTime": 1718756585000,
  • "profileOrderId": "01902ddd-1cf3-77d9-afc0-fe8d410cadb1",
  • "quantity": 10,
  • "speedClass": "s1.4xfast",
  • "status": "CONFIRMED",
  • "subscription": "plan01s"
}

List eSIM profiles created by the eSIM profile order

Returns a list of eSIM profiles created by the specified eSIM profile order.

Authorizations:
(api_keyapi_token)
path Parameters
profile_order_id
required
string

The ID of the eSIM profile order.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Soralet

Soracom Orbit Soralet

List Soralets

Returns a list of Soralets.

Authorizations:
(api_keyapi_token)
query Parameters
sort
string
Default: "asc"
Enum: "asc" "desc"

Sort order of the data entries. Either descending (latest data entry first) or ascending (oldest data entry first).

limit
integer

The maximum number of items in a response.

last_evaluated_key
string

The identifier of the last Soralet retrieved on the current page. By specifying this parameter, you can continue to retrieve the list from the next Soralet onward.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a Soralet

Create a Soralet.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

request

description
string
soraletId
required
string

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "soraletId": "string"
}

Delete Soralet

Delete the specified Soralet.

Authorizations:
(api_keyapi_token)
path Parameters
soralet_id
required
string

The identifier of Soralet.

Responses

Get a Soralet

Returns a Soralet.

Authorizations:
(api_keyapi_token)
path Parameters
soralet_id
required
string

The identifier of Soralet.

Responses

Response samples

Content type
application/json
{
  • "createdTime": 0,
  • "description": "string",
  • "operatorId": "string",
  • "soraletId": "string",
  • "updatedTime": 0
}

Get log messages from Soralet

Returns a list of log messages from the specified Soralet.

Authorizations:
(api_keyapi_token)
path Parameters
soralet_id
required
string

The identifier of Soralet.

query Parameters
sort
string
Default: "desc"
Enum: "asc" "desc"

Sort order of the data entries. Either descending (latest data entry first) or ascending (oldest data entry first).

limit
integer

The maximum number of items in a response.

last_evaluated_key
string

The identifier of the last log message retrieved on the current page. By specifying this parameter, you can continue to retrieve the list from the next log message onward.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Execute Soralet with arguments

Execute the specified Soralet with the specified arguments.

Authorizations:
(api_keyapi_token)
path Parameters
soralet_id
required
string

The identifier of Soralet.

Request Body schema: application/json
required

Execution request.

contentType
required
string
direction
required
string
Enum: "uplink" "downlink"
encodingType
string
Enum: "text" "binary"
payload
required
string
required
object
userdata
string
version
required
string

Responses

Request samples

Content type
application/json
{
  • "contentType": "string",
  • "direction": "uplink",
  • "encodingType": "text",
  • "payload": "string",
  • "source": {
    },
  • "userdata": "string",
  • "version": "string"
}

Response samples

Content type
application/json
{
  • "body": "string",
  • "contentType": "string",
  • "encodingType": "string",
  • "resultCode": 0
}

List versions of Soralet

Returns a list of Soralet versions.

Authorizations:
(api_keyapi_token)
path Parameters
soralet_id
required
string

The identifier of Soralet.

query Parameters
sort
string
Default: "desc"
Enum: "asc" "desc"

Sort order of the data entries. Either descending (latest data entry first) or ascending (oldest data entry first).

limit
integer

The maximum number of items in a response.

last_evaluated_key
string

The identifier of the last version retrieved on the current page. By specifying this parameter, you can continue to retrieve the list from the next version onward.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Upload code and create a new version

Upload code and create a new version.

Authorizations:
(api_keyapi_token)
path Parameters
soralet_id
required
string

The identifier of Soralet.

header Parameters
content-type
string

Content type of the file to upload. When uploading .wasm files, please specify application/json.

Request Body schema: application/json
required

Contents of the file you wish to upload.

string <binary>

Responses

Request samples

Content type
application/json
"string"

Response samples

Content type
application/json
{
  • "createdTime": 0,
  • "hash": "string",
  • "operatorId": "string",
  • "size": 0,
  • "soraletId": "string",
  • "srn": "string",
  • "version": 0
}

Delete a Soralet version

Delete the specified Soralet version.

Authorizations:
(api_keyapi_token)
path Parameters
soralet_id
required
string

The identifier of Soralet.

version
required
integer

Soralet version.

Responses

Stats

Data usage history retrieval

Get Air Usage Report of a Group.

Retrieves the usage report aggregating all SIMs that belong to the specified Group.

Authorizations:
(api_keyapi_token)
path Parameters
group_id
required
string

Group ID

query Parameters
from
required
integer

Specify the start month/day of the period to be aggregated in UNIX time in seconds.

to
required
integer

Specify the end month/day of the period to be aggregated in UNIX time in seconds.

period
required
string
Enum: "month" "day"

Unit of aggregation.

  • month: Monthly.

    The from and to should be UNIX time (in seconds) from 3 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 on the first day of the month, including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the last day of the month containing the specified UNIX time (in seconds).

  • day: Daily

    The from and to should be UNIX time (in seconds) from 7 days before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 of the day including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the day including the specified UNIX time (in seconds).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Air Usage Report of an Operator.

Retrieves the usage report aggregating all SIMs that belong to the specified Operator.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

query Parameters
from
required
integer

Specify the start month/day of the period to be aggregated in UNIX time in seconds.

to
required
integer

Specify the end month/day of the period to be aggregated in UNIX time in seconds.

period
required
string
Enum: "month" "day"

Unit of aggregation.

  • month: Monthly.

    The from and to should be UNIX time (in seconds) from 3 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 on the first day of the month, including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the last day of the month containing the specified UNIX time (in seconds).

  • day: Daily

    The from and to should be UNIX time (in seconds) from 7 days before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 of the day including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the day including the specified UNIX time (in seconds).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Export Air Usage Report of All Subscribers

Download the Air Data Traffic Actual Data CSV file that contains the usage report of all the IoT SIMs for the specified operator.

Warning: If there is no data usage during the specified period, a CSV file with only a header row will be output. Info: You can also check the data usage of terminated IoT SIMs.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID. The operator ID can be obtained from the Operator:getOperator API.

query Parameters
export_mode
string
Enum: "async" "sync"

Specify how to obtain the URL to download the Air Data Usage Report CSV.

  • async: Get the exportedFieldId without waiting for the URL to be issued on the Soracom platform. Specify this exportedFieldId in Files:getExportedFile API to get the URL. If the file size of the Air Data Usage Report CSV is huge, specify async.
  • sync (default): Wait for the URL to be issued on the Soracom platform. However, if the file size of the Air Data Usage Report CSV is huge, it may time out and the URL cannot be retrieved. If the timeout occurs, specify async.
Request Body schema: application/json
required

Period and aggregation unit of the data to be exported.

from
integer <int64>

Specify the start month/day/minute of the period to be aggregated in UNIX time in seconds.

period
string
Enum: "month" "day" "minutes"

Unit of aggregation.

  • month: Aggregate by month.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 on the first day of the month, including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the last day of the month containing the specified UNIX time (in seconds).

  • day: Aggregate by day.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 of the day including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the day including the specified UNIX time (in seconds).

  • minutes: Aggregate by approximately every 5 minutes.

    The from and to must be between 32 days before the current time and the UNIX time (in seconds) of the current time. The actual period to be aggregated is not the time specified by from and to.

    Item Description
    Actual Start Time Start time of approximately 5 minutes including the specified UNIX time (seconds).
    Actual End Time End time of approximately 5 minutes including the specified UNIX time (seconds).
to
integer <int64>

Specify the end month/day/minute of the period to be aggregated in UNIX time in seconds.

Responses

Request samples

Content type
application/json
{
  • "from": 1709218800,
  • "period": "month",
  • "to": 1714402800
}

Response samples

Content type
application/json
Example

By specifying this exportedFieldId in the Files:getExportedFile API, you can obtain the URL for downloading. Access the URL and download the CSV file.

{
  • "exportedFileId": "fe_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  • "exportedFilePath": "//files/exported/fe_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Get Air Usage Report of SIM.

Retrieves the usage report for the SIM specified by the SIM ID.

Warning: The data traffic of the terminated IoT SIM cannot be confirmed.

Authorizations:
(api_keyapi_token)
path Parameters
sim_id
required
string

SIM ID of the target SIM. The SIM ID can be obtained from the Sim:listSims API.

query Parameters
from
required
integer

Specify the start month/day/minute of the period to be aggregated in UNIX time in seconds.

to
required
integer

Specify the end month/day/minute of the period to be aggregated in UNIX time in seconds.

period
required
string
Enum: "month" "day" "minutes"

Unit of aggregation.

  • month: Aggregate by month.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 on the first day of the month, including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the last day of the month containing the specified UNIX time (in seconds).

  • day: Aggregate by day.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 of the day including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the day including the specified UNIX time (in seconds).

  • minutes: Aggregate by approximately every 5 minutes.

    The from and to must be between 32 days before the current time and the UNIX time (in seconds) of the current time. The actual period to be aggregated is not the time specified by from and to.

    Item Description
    Actual Start Time Start time of approximately 5 minutes including the specified UNIX time (seconds).
    Actual End Time End time of approximately 5 minutes including the specified UNIX time (seconds).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Air Usage Report of Subscriber.

Retrieves the usage report for the subscriber specified by the IMSI.

Warning: The data traffic of the terminated IoT SIM cannot be confirmed.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

The target IMSI. The IMSI can be obtained from the Sim:listSims API.

query Parameters
from
required
integer

Specify the start month/day/minute of the period to be aggregated in UNIX time in seconds.

to
required
integer

Specify the end month/day/minute of the period to be aggregated in UNIX time in seconds.

period
required
string
Enum: "month" "day" "minutes"

Unit of aggregation.

  • month: Aggregate by month.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 on the first day of the month, including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the last day of the month containing the specified UNIX time (in seconds).

  • day: Aggregate by day.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 of the day including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the day including the specified UNIX time (in seconds).

  • minutes: Aggregate by approximately every 5 minutes.

    The from and to must be between 32 days before the current time and the UNIX time (in seconds) of the current time. The actual period to be aggregated is not the time specified by from and to.

    Item Description
    Actual Start Time Start time of approximately 5 minutes including the specified UNIX time (seconds).
    Actual End Time End time of approximately 5 minutes including the specified UNIX time (seconds).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Export Beam Usage Report of All Subscribers

Retrieves a file containing the Soracom Beam usage report of all subscribers for the specified operator. The report data range is specified with from, to in unixtime. The report contains monthly data. The file output destination is AWS S3. The file output format is CSV.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

query Parameters
export_mode
string
Enum: "async" "sync"

export_mode (async, sync)

Request Body schema: application/json
required

Export time period.

from
integer <int64>

Specify the start month/day/minute of the period to be aggregated in UNIX time in seconds.

period
string
Enum: "month" "day" "minutes"

Unit of aggregation.

  • month: Aggregate by month.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 on the first day of the month, including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the last day of the month containing the specified UNIX time (in seconds).

  • day: Aggregate by day.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 of the day including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the day including the specified UNIX time (in seconds).

  • minutes: Aggregate by approximately every 5 minutes.

    The from and to must be between 32 days before the current time and the UNIX time (in seconds) of the current time. The actual period to be aggregated is not the time specified by from and to.

    Item Description
    Actual Start Time Start time of approximately 5 minutes including the specified UNIX time (seconds).
    Actual End Time End time of approximately 5 minutes including the specified UNIX time (seconds).
to
integer <int64>

Specify the end month/day/minute of the period to be aggregated in UNIX time in seconds.

Responses

Request samples

Content type
application/json
{
  • "from": 1709218800,
  • "period": "month",
  • "to": 1714402800
}

Response samples

Content type
application/json
{
  • "exportedFileId": "string",
  • "exportedFilePath": "string",
  • "url": "string"
}

Get Beam Usage Report of Subscriber

Retrieves the Soracom Beam usage report for the subscriber specified by the IMSI.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

imsi

query Parameters
from
required
integer

Specify the start month/day/minute of the period to be aggregated in UNIX time in seconds.

to
required
integer

Specify the end month/day/minute of the period to be aggregated in UNIX time in seconds.

period
required
string
Enum: "month" "day" "minutes"

Unit of aggregation.

  • month: Aggregate by month.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 on the first day of the month, including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the last day of the month containing the specified UNIX time (in seconds).

  • day: Aggregate by day.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 of the day including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the day including the specified UNIX time (in seconds).

  • minutes: Aggregate by approximately every 5 minutes.

    The from and to must be between 32 days before the current time and the UNIX time (in seconds) of the current time. The actual period to be aggregated is not the time specified by from and to.

    Item Description
    Actual Start Time Start time of approximately 5 minutes including the specified UNIX time (seconds).
    Actual End Time End time of approximately 5 minutes including the specified UNIX time (seconds).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Export Funk Usage Report of All Subscribers

Retrieves a file containing the Soracom Funk usage report of all subscribers for the specified operator. The report data range is specified with from, to in unixtime. The report contains monthly data. The file output destination is AWS S3. The file output format is CSV.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

query Parameters
export_mode
string
Enum: "async" "sync"

export_mode (async, sync)

Request Body schema: application/json
required

Export time period.

from
integer <int64>

Specify the start month/day/minute of the period to be aggregated in UNIX time in seconds.

period
string
Enum: "month" "day" "minutes"

Unit of aggregation.

  • month: Aggregate by month.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 on the first day of the month, including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the last day of the month containing the specified UNIX time (in seconds).

  • day: Aggregate by day.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 of the day including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the day including the specified UNIX time (in seconds).

  • minutes: Aggregate by approximately every 5 minutes.

    The from and to must be between 32 days before the current time and the UNIX time (in seconds) of the current time. The actual period to be aggregated is not the time specified by from and to.

    Item Description
    Actual Start Time Start time of approximately 5 minutes including the specified UNIX time (seconds).
    Actual End Time End time of approximately 5 minutes including the specified UNIX time (seconds).
to
integer <int64>

Specify the end month/day/minute of the period to be aggregated in UNIX time in seconds.

Responses

Request samples

Content type
application/json
{
  • "from": 1709218800,
  • "period": "month",
  • "to": 1714402800
}

Response samples

Content type
application/json
{
  • "exportedFileId": "string",
  • "exportedFilePath": "string",
  • "url": "string"
}

Get Funk Usage Report of Subscriber

Retrieves the Soracom Funk usage report for the subscriber specified by the IMSI.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

imsi

query Parameters
from
required
integer

Specify the start month/day/minute of the period to be aggregated in UNIX time in seconds.

to
required
integer

Specify the end month/day/minute of the period to be aggregated in UNIX time in seconds.

period
required
string
Enum: "month" "day" "minutes"

Unit of aggregation.

  • month: Aggregate by month.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 on the first day of the month, including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the last day of the month containing the specified UNIX time (in seconds).

  • day: Aggregate by day.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 of the day including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the day including the specified UNIX time (in seconds).

  • minutes: Aggregate by approximately every 5 minutes.

    The from and to must be between 32 days before the current time and the UNIX time (in seconds) of the current time. The actual period to be aggregated is not the time specified by from and to.

    Item Description
    Actual Start Time Start time of approximately 5 minutes including the specified UNIX time (seconds).
    Actual End Time End time of approximately 5 minutes including the specified UNIX time (seconds).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Export Funnel Usage Report of All Subscribers

Retrieves a file containing the Soracom Funnel usage report of all subscribers for the specified operator. The report data range is specified with from, to in unixtime. The report contains monthly data. The file output destination is AWS S3. The file output format is CSV.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

query Parameters
export_mode
string
Enum: "async" "sync"

export_mode (async, sync)

Request Body schema: application/json
required

Export time period.

from
integer <int64>

Specify the start month/day/minute of the period to be aggregated in UNIX time in seconds.

period
string
Enum: "month" "day" "minutes"

Unit of aggregation.

  • month: Aggregate by month.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 on the first day of the month, including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the last day of the month containing the specified UNIX time (in seconds).

  • day: Aggregate by day.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 of the day including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the day including the specified UNIX time (in seconds).

  • minutes: Aggregate by approximately every 5 minutes.

    The from and to must be between 32 days before the current time and the UNIX time (in seconds) of the current time. The actual period to be aggregated is not the time specified by from and to.

    Item Description
    Actual Start Time Start time of approximately 5 minutes including the specified UNIX time (seconds).
    Actual End Time End time of approximately 5 minutes including the specified UNIX time (seconds).
to
integer <int64>

Specify the end month/day/minute of the period to be aggregated in UNIX time in seconds.

Responses

Request samples

Content type
application/json
{
  • "from": 1709218800,
  • "period": "month",
  • "to": 1714402800
}

Response samples

Content type
application/json
{
  • "exportedFileId": "string",
  • "exportedFilePath": "string",
  • "url": "string"
}

Get Funnel Usage Report of Subscriber

Retrieves the Soracom Funnel usage report for the subscriber specified by the IMSI.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

imsi

query Parameters
from
required
integer

Specify the start month/day/minute of the period to be aggregated in UNIX time in seconds.

to
required
integer

Specify the end month/day/minute of the period to be aggregated in UNIX time in seconds.

period
required
string
Enum: "month" "day" "minutes"

Unit of aggregation.

  • month: Aggregate by month.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 on the first day of the month, including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the last day of the month containing the specified UNIX time (in seconds).

  • day: Aggregate by day.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 of the day including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the day including the specified UNIX time (in seconds).

  • minutes: Aggregate by approximately every 5 minutes.

    The from and to must be between 32 days before the current time and the UNIX time (in seconds) of the current time. The actual period to be aggregated is not the time specified by from and to.

    Item Description
    Actual Start Time Start time of approximately 5 minutes including the specified UNIX time (seconds).
    Actual End Time End time of approximately 5 minutes including the specified UNIX time (seconds).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get 'Harvest usage report' for the specified operator.

Retrieves the Soracom Harvest usage report for the operator.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID

query Parameters
year_month
string

Specify the year and month from 18 months before the current time to the current time in the YYYYMM format.

Responses

Response samples

Content type
application/json
{
  • "exportedBytes": 0,
  • "yearMonth": "string"
}

Export Harvest Data Write Counts Report of all IoT SIMs

Download the Harvest Data Write Count Results Data CSV file that contains the usage report of all the IoT SIMs for the specified operator.

Info: You can also check the Harvest Data write counts of the terminated IoT SIM.

Authorizations:
(api_keyapi_token)
path Parameters
operator_id
required
string

Operator ID.

query Parameters
export_mode
string
Enum: "async" "sync"

Specify how to obtain the URL to download the Harvest Data Write Count Results Data CSV.

  • async: Get the exportedFieldId without waiting for the URL to be issued on the Soracom platform. Specify this exportedFieldId in Files:getExportedFile API to get the URL for downloading. If the file size of the Harvest Data Write Count Results Data CSV is huge, specify async.
  • sync (default): Wait for the URL for downloading to be issued on the Soracom platform. However, if the file size of the Harvest Data Write Count Results Data CSV is huge, it may time out and the URL cannot be retrieved. If the timeout occurs, specify async.
Request Body schema: application/json
required

Export time period.

from
integer <int64>

Specify the start month/day/minute of the period to be aggregated in UNIX time in seconds.

period
string
Enum: "month" "day" "minutes"

Unit of aggregation.

  • month: Aggregate by month.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 on the first day of the month, including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the last day of the month containing the specified UNIX time (in seconds).

  • day: Aggregate by day.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 of the day including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the day including the specified UNIX time (in seconds).

  • minutes: Aggregate by approximately every 5 minutes.

    The from and to must be between 32 days before the current time and the UNIX time (in seconds) of the current time. The actual period to be aggregated is not the time specified by from and to.

    Item Description
    Actual Start Time Start time of approximately 5 minutes including the specified UNIX time (seconds).
    Actual End Time End time of approximately 5 minutes including the specified UNIX time (seconds).
to
integer <int64>

Specify the end month/day/minute of the period to be aggregated in UNIX time in seconds.

Responses

Request samples

Content type
application/json
{
  • "from": 1709218800,
  • "period": "month",
  • "to": 1714402800
}

Response samples

Content type
application/json
{
  • "exportedFileId": "string",
  • "exportedFilePath": "string",
  • "url": "string"
}

Get Harvest Usage Report of Subscriber

Retrieves the Soracom Harvest usage report for the subscriber specified by the IMSI.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

imsi

query Parameters
from
required
integer

Specify the start month/day/minute of the period to be aggregated in UNIX time in seconds.

to
required
integer

Specify the end month/day/minute of the period to be aggregated in UNIX time in seconds.

period
required
string
Enum: "month" "day" "minutes"

Unit of aggregation.

  • month: Aggregate by month.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 on the first day of the month, including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the last day of the month containing the specified UNIX time (in seconds).

  • day: Aggregate by day.

    The from and to should be UNIX time (in seconds) from 18 months before the current time to the current time. The actual period of interest is not the time specified by from and to.

    Item Description
    Actual start time 00:00:00 of the day including the specified UNIX time (in seconds).
    Actual end time 24:00:00 of the day including the specified UNIX time (in seconds).

  • minutes: Aggregate by approximately every 5 minutes.

    The from and to must be between 32 days before the current time and the UNIX time (in seconds) of the current time. The actual period to be aggregated is not the time specified by from and to.

    Item Description
    Actual Start Time Start time of approximately 5 minutes including the specified UNIX time (seconds).
    Actual End Time End time of approximately 5 minutes including the specified UNIX time (seconds).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Napter audit logs' monthly exported data stats.

Get Napter audit logs' monthly exported data stats.

Authorizations:
(api_keyapi_token)
query Parameters
year_month
string

Specify the year and month from 18 months before the current time to the current time in the YYYYMM format.

Responses

Response samples

Content type
application/json
{
  • "exportedBytes": 0,
  • "yearMonth": "string"
}

Subscriber

Soracom Air for Cellular SIM information, operations, and cancellation

List Subscribers.

Returns a list of subscribers that match certain criteria. If the total number of subscribers does not fit in one page, a URL for accessing the next page is returned in the link header of the response.

Authorizations:
(api_keyapi_token)
query Parameters
tag_name
string

Tag name for filtering the search (exact match).

tag_value
string

Tag search string for filtering the search. Required when tag_name has been specified.

tag_value_match_mode
string
Default: "exact"
Enum: "exact" "prefix"

Tag match mode.

status_filter
string

Status for filtering the search. Can specify multiple values delimited by |. Valid values include: active, inactive, ready, instock, shipped, suspended, and terminated.

speed_class_filter
string

Speed class for filtering the search. Can specify multiple values delimited by |. Valid values include:

  • s1.minimum
  • s1.slow
  • s1.standard
  • s1.fast
  • s1.4xfast
  • s1.8xfast
  • u1.standard
  • u1.slow
  • t1.standard
  • arc.standard
serial_number_filter
string

Serial number for filtering the search. Can specify multiple values delimited by |. Returns subscribers with serial number starting with the specified value(s).

limit
integer [ 1 .. 100 ]

Maximum number of subscribers to retrieve (value range is 1 to 100). However, the number of subscribers returned may be less than the specified value.

last_evaluated_key
string

The IMSI of the last subscriber retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next subscriber onward.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Subscriber.

Returns information about the specified subscriber.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

IMSI of the target subscriber.

Responses

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Activate Subscriber.

Activates status of specified subscriber.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string <IMSI>

IMSI of the target subscriber.

Responses

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Set Bundles to Subscriber.

Sets bundles to the specified subscriber.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

IMSI of the target subscriber. The IMSI can be obtained from the Sim:listSims API.

Request Body schema: application/json
required

Array of bundles to set for the subscriber.

Array
string
Enum: "D-500MB" "DU-10GB" "DU-50GB" "DU-100GB" "US-1MB" "US-3MB" "US-10MB" "US-20MB" "US-50MB" "US-100MB" "US-300MB" "US-500MB" "US-1GB" "US-3GB" "US-5GB" "US-10GB"

Bundle to set. Specify a bundle supported by the subscription. The bundle name prefix (excluding size suffixes such as -xxMB or -xxGB) is as follows for each subscription:

  • plan-D: D
  • plan-DU: DU
  • plan-US: US

Example: For subscription plan-US, you can set US-300MB.

Warning: Bundles for plan-K2 (K2-500MB), plan-D (D-500MB), planX3, and planX3-EU cannot be changed.

Responses

Request samples

Content type
application/json
[
  • "D-500MB"
]

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Get data sent from a subscriber to Harvest Data.

Returns a list of data entries sent to Harvest Data from a subscriber that match certain criteria. If the total number of data entries does not fit in one page, a URL for accessing the next page is returned in the link header of the response.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

IMSI of the target subscriber that generated data entries.

query Parameters
from
integer

Start time for the data entries search range (UNIX time in milliseconds).

to
integer

End time for the data entries search range (UNIX time in milliseconds).

sort
string
Default: "desc"
Enum: "desc" "asc"

Sort order of the data entries. Either descending (latest data entry first) or ascending (oldest data entry first).

limit
integer [ 1 .. 1000 ]

Maximum number of data entries to retrieve (value range is 1 to 1000). The default is 10.

last_evaluated_key
string

Key in the last data entry retrieved in the previous page. The key for data entries in this API is ${UNIX time in milliseconds}_${IMSI}. By specifying this parameter, you can continue to retrieve the list from the next page onward.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Deactivate Subscriber.

Deactivates specified subscriber.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string <IMSI>

IMSI of the target subscriber.

Responses

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Delete Session

Deletes session for the specified subscriber.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

IMSI of the target subscriber.

Responses

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Disable Termination of Subscriber.

Disables termination of specified subscriber.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string <IMSI>

IMSI of the target subscriber.

Responses

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Send ping requests to a subscriber.

Send ICMP ping requests to a subscriber.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string <IMSI>

IMSI of the target subscriber.

Request Body schema: application/json
required

ping options

numberOfPingRequests
integer <= 5
Default: 1

The number of attempt ping.

timeoutSeconds
integer <= 3
Default: 1

The timeout duration of each ping.

Responses

Request samples

Content type
application/json
{
  • "numberOfPingRequests": 1,
  • "timeoutSeconds": 1
}

Response samples

Content type
application/json
{
  • "rtt": "string",
  • "stat": "string",
  • "success": true
}

Enable Termination of Subscriber.

Enables termination of specified subscriber.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string <IMSI>

IMSI of the target subscriber.

Responses

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

List Session Events.

Returns the event history of session creation/modification/disconnection on the specified subscriber in the last 32 days. If the total number of events does not fit in one page, a URL for accessing the next page is returned in the link header of the response.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

IMSI of the target subscriber.

query Parameters
from
integer

Start time for the events search range (UNIX time in milliseconds).

to
integer

End time for the events search range (UNIX time in milliseconds).

limit
integer

Maximum number of events to retrieve.

last_evaluated_key
string

The time stamp of the last event retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next event onward.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Register Subscriber.

Registers a subscriber.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

IMSI of the target subscriber.

Request Body schema: application/json
required

subscriber

groupId
string
registrationSecret
required
string

PUK or PASSCODE for SIM.

object (TagSet)

An object which always contains at least one property "name" with a string value. If you give a subscriber/SIM a name, the name will be returned as the value of the "name" property. If the subscriber/SIM does not have a name, an empty string "" is returned. In addition, if you create any custom tags for the subscriber/SIM, each custom tag will appear as additional properties in the object.

Responses

Request samples

Content type
application/json
{
  • "groupId": "string",
  • "registrationSecret": "string",
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Triggers Subscriber to report SIM local info.

Triggers Subscriber to report SIM local info.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string <IMSI>

IMSI of the target subscriber.

Responses

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Send SMS to Subscriber

Send SMS to the specified subscriber.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string <IMSI>

IMSI of the target subscriber.

Request Body schema: application/json
required

SMS forwarding request that contains message body and its encoding type.

encodingType
integer
Default: 2

Encoding type of the message body. Default is 2 (DCS_UCS2).

  • 1: Send in GSM 7-bit that only supports standard alphabet. Kanji, Cyrillic, and Arabic characters cannot be sent. Maximum 160 characters (maximum 140 bytes).

    Example: {"encodingType": 1, "payload": "Test message."}

  • 2: Send in UCS-2, which supports Kanji, Cyrillic, Arabic, etc. Maximum 70 characters.

    Example: {"encodingType": 2, "payload": "テストメッセージ"}

payload
string

Responses

Request samples

Content type
application/json
{
  • "encodingType": 2,
  • "payload": "string"
}

Response samples

Content type
application/json
{
  • "messageId": "string"
}

Update Expiry Time of Subscriber.

Updates expiry time of specified subscriber.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string <IMSI>

IMSI of the target subscriber.

Request Body schema: application/json
required

Expiration date (UNIX time in milliseconds) and action after the update.

expiryAction
string or null
Enum: "doNothing" "deleteSession" "deactivate" "suspend" "terminate" "(null value)"

Action at expiration. Specify one of the following Please refer to Soracom Air Expiration Function for more detail. You have to disable termination protection if you want to specify terminate as an action.

If omitted, a null value is set.

  • doNothing : do nothing
  • deleteSession : delete session of the SIM if any
  • deactivate : change the SIM status to Inactive
  • suspend : change the SIM status to Suspended
  • terminate : forcibly end any existing connections, and terminate the SIM
  • null value : not set (It works the same as doNothing)
expiryTime
required
integer <int64>

Timestamp of date and time set using the Expiration function (UNIX time in milliseconds)

Responses

Request samples

Content type
application/json
{
  • "expiryAction": "doNothing",
  • "expiryTime": 0
}

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Adds a SIM to a SIM group

Adds a SIM to a SIM group.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

IMSI of the target SIM. The IMSI can be obtained using the Sim:listSims API.

Request Body schema: application/json
required
groupId
string

Group ID. The group ID can be obtained using the Group:listGroups API.

Responses

Request samples

Content type
application/json
{
  • "groupId": "string"
}

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Set IMEI lock configuration for Subscriber.

Set IMEI that the subscriber should be locked to.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

IMSI of the target subscriber.

Request Body schema: application/json

IMEI lock configuration for the subscriber. (IMEI can be left blank for locking to the current IMEI of an online subscriber.)

imei
string

IMEI of the target device. If you want to establish a session even when the IMEI is temporarily not reported, append |ANONYMOUS to the IMEI value.

For example, if the IMEI specified is 123456789012345, specifying 123456789012345|ANONYMOUS as the parameter value will allow a session to be established even when the IMEI is temporarily not reported.

Responses

Request samples

Content type
application/json
{
  • "imei": "string"
}

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Set Subscriber to standby mode.

Set the specified subscriber to standby mode.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string <IMSI>

IMSI of the target subscriber.

Responses

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Suspend Subscriber.

Suspends the specified subscriber.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string <IMSI>

IMSI of the target subscriber.

Responses

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Bulk Insert or Update Subscriber Tags.

Inserts/updates tags for the specified subscriber.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

IMSI of the target subscriber.

Request Body schema: application/json
required

Array of tags to be inserted/updated.

Array
tagName
required
string
tagValue
required
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Delete Subscriber Tag.

Deletes a tag from the specified subscriber.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

IMSI of the target subscriber.

tag_name
required
string

Tag name to be deleted. (This will be part of a URL path, so it needs to be percent-encoded. In JavaScript, specify the name after it has been encoded using encodeURIComponent().)

Responses

Terminate Subscriber.

Terminates the specified subscriber

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string <IMSI>

IMSI of the target subscriber.

Responses

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Delete Expiry Time of Subscriber.

Deletes expiry time of specified subscriber and changes it to indefinite.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

IMSI of the target subscriber.

Responses

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Removes a SIM from a SIM group

Removes a SIM from a SIM group.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

IMSI of the target SIM. The IMSI can be obtained using the Sim:listSims API.

Responses

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Unset IMEI lock configuration for Subscriber.

Remove any existing IMEI lock configuration for the subscriber.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

IMSI of the target subscriber.

Responses

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Update Subscriber speed class.

Changes the speed class of the specified subscriber.

Authorizations:
(api_keyapi_token)
path Parameters
imsi
required
string

IMSI of the target subscriber.

Request Body schema: application/json
required

speed_class

speedClass
required
string
Enum: "s1.minimum" "s1.slow" "s1.standard" "s1.fast" "s1.4xfast" "s1.8xfast" "u1.standard" "u1.slow"

Speed class. Specify one of the following. Please specify the speed class that matches the subscription.

  • For plan01s, plan01s - Low Data Volume, planX3 (X3-5MB), planP1, plan-D (without bundle), plan-D (D-500MB), plan-K2 (K2-500MB), plan-K:
    • s1.minimum
    • s1.slow
    • s1.standard
    • s1.fast
    • s1.4xfast
  • For plan-US:
    • s1.minimum
    • s1.slow
    • s1.standard
    • s1.fast
    • s1.4xfast
    • s1.8xfast
  • For plan-DU:
    • u1.standard
    • u1.slow

Warning: Speed class for plan-KM1 and virtual SIM/Subscriber cannot be changed as there is only one speed class available.

Responses

Request samples

Content type
application/json
{
  • "speedClass": "s1.minimum"
}

Response samples

Content type
application/json
{
  • "apn": "string",
  • "bundles": [
    ],
  • "createdAt": 0,
  • "createdTime": 0,
  • "expiredAt": 0,
  • "expiryAction": "doNothing",
  • "expiryTime": 0,
  • "groupId": "string",
  • "iccid": "string",
  • "imeiLock": {
    },
  • "imsi": "string",
  • "ipAddress": "string",
  • "lastModifiedAt": 0,
  • "lastModifiedTime": 0,
  • "lastPortMappingCreatedTime": 0,
  • "locationRegistrationStatus": {
    },
  • "moduleType": "mini",
  • "msisdn": "string",
  • "operatorId": "string",
  • "packetCaptureSessions": [
    ],
  • "plan": 0,
  • "previousSession": {
    },
  • "registeredTime": 0,
  • "renewalFeeStatusSetTime": 0,
  • "serialNumber": "string",
  • "sessionStatus": {
    },
  • "simId": "string",
  • "speedClass": "string",
  • "status": "ready",
  • "subscription": "string",
  • "tags": {
    },
  • "terminationEnabled": true,
  • "type": "string"
}

Export all subscribers.

Export all subscribers as a CSV file.

Authorizations:
(api_keyapi_token)
query Parameters
export_mode
string
Default: "sync"
Enum: "async" "sync"

export mode (async, sync)

Responses

Response samples

Content type
application/json
{
  • "exportedFileId": "string",
  • "exportedFilePath": "string",
  • "url": "string"
}

Send SMS to Subscriber by MSISDN

Send SMS to a subscriber specified with MSISDN.

Authorizations:
(api_keyapi_token)
path Parameters
msisdn
required
string

MSISDN of the target subscriber.

Request Body schema: application/json
required

SMS forwarding request that contains message body and its encoding type.

encodingType
integer
Default: 2

Encoding type of the message body. Default is 2 (DCS_UCS2).

  • 1: Send in GSM 7-bit that only supports standard alphabet. Kanji, Cyrillic, and Arabic characters cannot be sent. Maximum 160 characters (maximum 140 bytes).

    Example: {"encodingType": 1, "payload": "Test message."}

  • 2: Send in UCS-2, which supports Kanji, Cyrillic, Arabic, etc. Maximum 70 characters.

    Example: {"encodingType": 2, "payload": "テストメッセージ"}

payload
string

Responses

Request samples

Content type
application/json
{
  • "encodingType": 2,
  • "payload": "string"
}

Response samples

Content type
application/json
{
  • "messageId": "string"
}

Cancel the transfer of Ready status SIMs (Invalidate the transfer token)

Invalidate the transfer token for SIMs and cancels the transfer of all SIMs associated with the transfer token. To use this API, you need an API key and token issued with the source operator.

Authorizations:
(api_keyapi_token)
path Parameters
token
required
string

Transfer token. The transfer token can be obtained from Subscriber:issueSubscriberTransferToken.

Responses

Initiate the transfer of Ready status SIMs (Issue a transfer token)

Initiates the transfer of Ready status SIMs. To use this API, you need an API key and token issued with the source operator. When this API is executed, a transfer token is issued and sent to the destination operator via email. For more information about SIM transfers, please refer to Transferring Ready Status SIMs.

  • To cancel a transfer, cancel each transfer token individually. If there is a possibility of canceling SIMs one by one, specify only one IMSI. To cancel, use the Subscriber:deleteSubscriberTransferToken API.
  • When this API is executed, the status of the SIMs will change to "Transferring".

Warning: Do not change the status of SIMs that are in the "Transferring" status. If the status is changed, the SIMs can no longer be transferred using this procedure. For the procedure to transfer SIMs whose status has been changed, refer to Transferring Other Status SIMs.

Info: The information of the destination operator can be confirmed by logging in to the Soracom User Console with the destination operator.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

Email address and Operator ID of the destination operator, and the IMSIs of the SIMs to be transferred.

transferDestinationOperatorEmail
required
string

Primary email address of the destination operator. Please confirm with the owner of the destination operator.

transferDestinationOperatorId
required
string

Operator ID of the destination operator. Please confirm with the owner of the destination operator.

transferImsi
required
Array of strings

IMSI of the SIM to be transferred. The IMSI can be obtained from the Sim:listSims API.

If there is a possibility of canceling SIMs one by one, please specify only one IMSI.

Responses

Request samples

Content type
application/json
{
  • "transferDestinationOperatorEmail": "transfer-destination-XX@example.com",
  • "transferDestinationOperatorId": "OPXXXXXXXXXX",
  • "transferImsi": [
    ]
}

Response samples

Content type
application/json
{
  • "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Accept the transfer of Ready status SIMs (Verify the transfer token)

Verifies the transfer token for SIMs and accepts the transfer. To use this API, you need an API key and token issued with the destination operator.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

Transfer token. The transfer token is sent via email.

token
required
string

Transfer token. When a transfer token is issued using the Subscriber:issueSubscriberTransferToken API, it is sent to the primary email address of the destination operator.

Responses

Request samples

Content type
application/json
{
  • "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Response samples

Content type
application/json
{
  • "transferredImsi": [
    ]
}

VirtualPrivateGateway

List Virtual Private Gateways

Returns a list of VPGs.

Authorizations:
(api_keyapi_token)
query Parameters
tag_name
string

Tag name of the VPG. Filters through all VPGs that exactly match the tag name. When tag_name is specified, tag_value is required.

tag_value
string

Tag value of the VPG.

tag_value_match_mode
string
Default: "exact"
Enum: "exact" "prefix"

Tag match mode.

limit
integer

Maximum number of results per response page.

last_evaluated_key
string

The last VPG ID retrieved on the current page. By specifying this parameter, you can continue to retrieve the list from the next VPG onward.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Virtual Private Gateway

Create a new VPG.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required

Request containing information for the new VPG to be created.

deviceSubnetCidrRange
string
Default: "10.128.0.0/9"
object
object
object (TagSet)

An object which always contains at least one property "name" with a string value. If you give a subscriber/SIM a name, the name will be returned as the value of the "name" property. If the subscriber/SIM does not have a name, an empty string "" is returned. In addition, if you create any custom tags for the subscriber/SIM, each custom tag will appear as additional properties in the object.

type
required
integer
Enum: 14 15 242

VPG Type.

  • 14 : Type-E
  • 15 : Type-F
  • 242 : Type-F2
useInternetGateway
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "deviceSubnetCidrRange": "10.128.0.0/9",
  • "placement": {
    },
  • "soracomTransitGateway": {
    },
  • "tags": {
    },
  • "type": 14,
  • "useInternetGateway": true
}

Response samples

Content type
application/json
{
  • "allowedOperators": [
    ],
  • "createdTime": 0,
  • "customerRoutes": {
    },
  • "deviceSubnetCidrRange": "string",
  • "enableSimBasedRouting": true,
  • "fixedIpAddressesEnabled": true,
  • "fixedPublicIpAddresses": [
    ],
  • "gateOpened": true,
  • "gatePrivacySeparatorEnabled": true,
  • "gateVxlanId": 0,
  • "implicitTerminationProtected": true,
  • "inspection": {
    },
  • "junctionEnabled": true,
  • "lastModifiedTime": 0,
  • "mirroring": {
    },
  • "offsetId": 0,
  • "operatorId": "string",
  • "placement": {
    },
  • "primaryServiceName": "string",
  • "redirection": {
    },
  • "routingFilterEntries": [
    ],
  • "sessionStats": {
    },
  • "simBasedRoutingConfig": {
    },
  • "size": "string",
  • "soracomTransitGateway": {
    },
  • "soracomTransitGatewayPeeringConnections": {
    },
  • "soracomTransitGatewayVpcAttachments": {
    },
  • "status": "running",
  • "tags": {
    },
  • "transitGatewayAttachments": {
    },
  • "type": 12,
  • "ueSubnetCidrRange": "string",
  • "useInternetGateway": true,
  • "virtualInterfaces": {
    },
  • "vpcPeeringConnections": {
    },
  • "vpgId": "string",
  • "vpgSubnetCidrRange": "string",
  • "vpnConnections": {
    }
}

Get Virtual Private Gateway

Retrieves information about the specified VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

Responses

Response samples

Content type
application/json
{
  • "allowedOperators": [
    ],
  • "createdTime": 0,
  • "customerRoutes": {
    },
  • "deviceSubnetCidrRange": "string",
  • "enableSimBasedRouting": true,
  • "fixedIpAddressesEnabled": true,
  • "fixedPublicIpAddresses": [
    ],
  • "gateOpened": true,
  • "gatePrivacySeparatorEnabled": true,
  • "gateVxlanId": 0,
  • "implicitTerminationProtected": true,
  • "inspection": {
    },
  • "junctionEnabled": true,
  • "lastModifiedTime": 0,
  • "mirroring": {
    },
  • "offsetId": 0,
  • "operatorId": "string",
  • "placement": {
    },
  • "primaryServiceName": "string",
  • "redirection": {
    },
  • "routingFilterEntries": [
    ],
  • "sessionStats": {
    },
  • "simBasedRoutingConfig": {
    },
  • "size": "string",
  • "soracomTransitGateway": {
    },
  • "soracomTransitGatewayPeeringConnections": {
    },
  • "soracomTransitGatewayVpcAttachments": {
    },
  • "status": "running",
  • "tags": {
    },
  • "transitGatewayAttachments": {
    },
  • "type": 12,
  • "ueSubnetCidrRange": "string",
  • "useInternetGateway": true,
  • "virtualInterfaces": {
    },
  • "vpcPeeringConnections": {
    },
  • "vpgId": "string",
  • "vpgSubnetCidrRange": "string",
  • "vpnConnections": {
    }
}

Create routing table entry

Creates a routing table entry for the specified VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

Request Body schema: application/json
required
destinationCidr
required
string

Destination CIDR block

ignoreDeviceSubnetCidrRangeOverlap
boolean
ignoreDeviceSubnetcidrRangeOverlap
any

A boolean flag to ignore device subnet CIDR range overlap with the destination CIDR range

target
required
string

Transit Gateway ID

Responses

Request samples

Content type
application/json
{
  • "destinationCidr": "string",
  • "ignoreDeviceSubnetCidrRangeOverlap": true,
  • "ignoreDeviceSubnetcidrRangeOverlap": null,
  • "target": "string"
}

Response samples

Content type
application/json
{
  • "destinationCidr": "string",
  • "id": "string",
  • "target": "string",
  • "type": "static"
}

Delete routing table entry

Deletes a routing table entry from the specified VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

route_id
required
string

Target route ID

Responses

Update routing table entry

Updates a routing table entry for the specified VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

route_id
required
string

Target route ID

Request Body schema: application/json
required
target
required
string

Responses

Request samples

Content type
application/json
{
  • "target": "string"
}

Response samples

Content type
application/json
{
  • "destinationCidr": "string",
  • "id": "string",
  • "target": "string",
  • "type": "static"
}

Disable the fixed global IP address option for the VPG

Disables the fixed global IP address option for the VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Responses

Response samples

Content type
application/json
{
  • "allowedOperators": [
    ],
  • "createdTime": 0,
  • "customerRoutes": {
    },
  • "deviceSubnetCidrRange": "string",
  • "enableSimBasedRouting": true,
  • "fixedIpAddressesEnabled": true,
  • "fixedPublicIpAddresses": [
    ],
  • "gateOpened": true,
  • "gatePrivacySeparatorEnabled": true,
  • "gateVxlanId": 0,
  • "implicitTerminationProtected": true,
  • "inspection": {
    },
  • "junctionEnabled": true,
  • "lastModifiedTime": 0,
  • "mirroring": {
    },
  • "offsetId": 0,
  • "operatorId": "string",
  • "placement": {
    },
  • "primaryServiceName": "string",
  • "redirection": {
    },
  • "routingFilterEntries": [
    ],
  • "sessionStats": {
    },
  • "simBasedRoutingConfig": {
    },
  • "size": "string",
  • "soracomTransitGateway": {
    },
  • "soracomTransitGatewayPeeringConnections": {
    },
  • "soracomTransitGatewayVpcAttachments": {
    },
  • "status": "running",
  • "tags": {
    },
  • "transitGatewayAttachments": {
    },
  • "type": 12,
  • "ueSubnetCidrRange": "string",
  • "useInternetGateway": true,
  • "virtualInterfaces": {
    },
  • "vpcPeeringConnections": {
    },
  • "vpgId": "string",
  • "vpgSubnetCidrRange": "string",
  • "vpnConnections": {
    }
}

Enable the fixed global IP address option for the VPG

Enables the fixed global IP address option for the VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Responses

Response samples

Content type
application/json
{
  • "allowedOperators": [
    ],
  • "createdTime": 0,
  • "customerRoutes": {
    },
  • "deviceSubnetCidrRange": "string",
  • "enableSimBasedRouting": true,
  • "fixedIpAddressesEnabled": true,
  • "fixedPublicIpAddresses": [
    ],
  • "gateOpened": true,
  • "gatePrivacySeparatorEnabled": true,
  • "gateVxlanId": 0,
  • "implicitTerminationProtected": true,
  • "inspection": {
    },
  • "junctionEnabled": true,
  • "lastModifiedTime": 0,
  • "mirroring": {
    },
  • "offsetId": 0,
  • "operatorId": "string",
  • "placement": {
    },
  • "primaryServiceName": "string",
  • "redirection": {
    },
  • "routingFilterEntries": [
    ],
  • "sessionStats": {
    },
  • "simBasedRoutingConfig": {
    },
  • "size": "string",
  • "soracomTransitGateway": {
    },
  • "soracomTransitGatewayPeeringConnections": {
    },
  • "soracomTransitGatewayVpcAttachments": {
    },
  • "status": "running",
  • "tags": {
    },
  • "transitGatewayAttachments": {
    },
  • "type": 12,
  • "ueSubnetCidrRange": "string",
  • "useInternetGateway": true,
  • "virtualInterfaces": {
    },
  • "vpcPeeringConnections": {
    },
  • "vpgId": "string",
  • "vpgSubnetCidrRange": "string",
  • "vpnConnections": {
    }
}

Close SORACOM Gate.

Close Soracom Gate on the specified VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

Responses

Disables Soracom Gate's privacy separator feature on the specified VPG

Disables Soracom Gate's privacy separator feature on the specified VPG and enables the Gate D2D feature.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string <VpgId>

VPG ID

Responses

Response samples

Content type
application/json
{
  • "allowedOperators": [
    ],
  • "createdTime": 0,
  • "customerRoutes": {
    },
  • "deviceSubnetCidrRange": "string",
  • "enableSimBasedRouting": true,
  • "fixedIpAddressesEnabled": true,
  • "fixedPublicIpAddresses": [
    ],
  • "gateOpened": true,
  • "gatePrivacySeparatorEnabled": true,
  • "gateVxlanId": 0,
  • "implicitTerminationProtected": true,
  • "inspection": {
    },
  • "junctionEnabled": true,
  • "lastModifiedTime": 0,
  • "mirroring": {
    },
  • "offsetId": 0,
  • "operatorId": "string",
  • "placement": {
    },
  • "primaryServiceName": "string",
  • "redirection": {
    },
  • "routingFilterEntries": [
    ],
  • "sessionStats": {
    },
  • "simBasedRoutingConfig": {
    },
  • "size": "string",
  • "soracomTransitGateway": {
    },
  • "soracomTransitGatewayPeeringConnections": {
    },
  • "soracomTransitGatewayVpcAttachments": {
    },
  • "status": "running",
  • "tags": {
    },
  • "transitGatewayAttachments": {
    },
  • "type": 12,
  • "ueSubnetCidrRange": "string",
  • "useInternetGateway": true,
  • "virtualInterfaces": {
    },
  • "vpcPeeringConnections": {
    },
  • "vpgId": "string",
  • "vpgSubnetCidrRange": "string",
  • "vpnConnections": {
    }
}

Enables Soracom Gate privacy separator feature on the specified VPG

Enables Soracom Gate's privacy separator feature on the specified VPG and disables the Gate D2D feature.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string <VpgId>

VPG ID

Responses

Response samples

Content type
application/json
{
  • "allowedOperators": [
    ],
  • "createdTime": 0,
  • "customerRoutes": {
    },
  • "deviceSubnetCidrRange": "string",
  • "enableSimBasedRouting": true,
  • "fixedIpAddressesEnabled": true,
  • "fixedPublicIpAddresses": [
    ],
  • "gateOpened": true,
  • "gatePrivacySeparatorEnabled": true,
  • "gateVxlanId": 0,
  • "implicitTerminationProtected": true,
  • "inspection": {
    },
  • "junctionEnabled": true,
  • "lastModifiedTime": 0,
  • "mirroring": {
    },
  • "offsetId": 0,
  • "operatorId": "string",
  • "placement": {
    },
  • "primaryServiceName": "string",
  • "redirection": {
    },
  • "routingFilterEntries": [
    ],
  • "sessionStats": {
    },
  • "simBasedRoutingConfig": {
    },
  • "size": "string",
  • "soracomTransitGateway": {
    },
  • "soracomTransitGatewayPeeringConnections": {
    },
  • "soracomTransitGatewayVpcAttachments": {
    },
  • "status": "running",
  • "tags": {
    },
  • "transitGatewayAttachments": {
    },
  • "type": 12,
  • "ueSubnetCidrRange": "string",
  • "useInternetGateway": true,
  • "virtualInterfaces": {
    },
  • "vpcPeeringConnections": {
    },
  • "vpgId": "string",
  • "vpgSubnetCidrRange": "string",
  • "vpnConnections": {
    }
}

Open Soracom Gate

Open Soracom Gate on the specified VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

Request Body schema: application/json

Optional configuration parameters for Gate.

privacySeparatorEnabled
boolean
Default: false
vxlanId
integer <int32>
Default: 10

Responses

Request samples

Content type
application/json
{
  • "privacySeparatorEnabled": false,
  • "vxlanId": 10
}

List VPG Gate Peers

List Gate Peers registered in the Virtual Private Gateway.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Register VPG Gate Peer

Register a host as a Gate Peer in the Virtual Private Gateway.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

Request Body schema: application/json
required
innerIpAddress
string

An IP address within the device subnet range (inner IP address).

outerIpAddress
required
string

Responses

Request samples

Content type
application/json
{
  • "innerIpAddress": "string",
  • "outerIpAddress": "string"
}

Response samples

Content type
application/json
{
  • "innerIpAddress": "string",
  • "netmask": "string",
  • "outerIpAddress": "string",
  • "ownedByCustomer": true
}

Unregister VPG Gate Peer

Unregister a Gate Peer from the Virtual Private Gateway.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

outer_ip_address
required
string

ID of the target node.

Responses

Disable SIM-Based Routing

Disables SIM-Based Routing.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

Responses

Enable SIM-Based Routing

Enables SIM-Based Routing.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

Responses

Associate a router's LAN IP address range with its SIM ID

Associates a router's LAN IP address range with its SIM ID.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

Request Body schema: application/json
required

Specify the LAN IP address range of the router to associate with a SIM ID.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "YOUR_SIM_ID_1": "192.0.2.0/24",
  • "YOUR_SIM_ID_2": "192.0.2.128/25"
}

Set VXLAN ID for Gate

Set VXLAN ID for Gate.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string
Request Body schema: application/json
required
vxlanId
required
integer

VXLAN ID. Specify a range between 1 and 16777215.

Responses

Request samples

Content type
application/json
{
  • "vxlanId": 0
}

List VPG IP address map entries

Retrieves the list of IP address map entries for the specified VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

query Parameters
limit
integer

The maximum number of IP address map entries to retrieve. The response may contain fewer entries than the specified value.

last_evaluated_key
string

The last IP address retrieved in the previous page. Use this parameter to retrieve the next page of IP address map entries.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Adds or updates an entry in VPG IP address map

Adds or updates an IP address map entry for the specified VPG.

Warning: The VirtualPrivateGateway:listVirtualPrivateGatewayIpAddressMapEntries API response includes entries that are automatically assigned to Gate Peers and the VPG, but these cannot be added or updated using the VirtualPrivateGateway:putVirtualPrivateGatewayIpAddressMapEntry API.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

Request Body schema: application/json
required
ipAddress
required
string

IP address to assign to the specified key.

key
required
string

IMSI of the IoT SIM to assign the fixed IP address to.

Responses

Request samples

Content type
application/json
{
  • "ipAddress": "string",
  • "key": "string"
}

Response samples

Content type
application/json
{
  • "hostId": "string",
  • "ipAddress": "string",
  • "key": "string",
  • "lastUpdatedAt": 0,
  • "type": "static"
}

Delete VPG IP address map entry

Deletes an entry from the IP address map of the specified VPG.

Warning: The VirtualPrivateGateway:listVirtualPrivateGatewayIpAddressMapEntries API response includes automatically assigned entries for Gate Peers and the VPG. These entries cannot be deleted using the VirtualPrivateGateway:deleteVirtualPrivateGatewayIpAddressMapEntry API.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

key
required
string

Identifier of the IP address map entry to delete (IMSI of the IoT SIM).

Responses

Adds node in the list of Junction mirroring peers

Adds node in the list of Junction mirroring peers.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

VPG ID

Request Body schema: application/json
required

Mirroring peer

description
string
enabled
boolean
Default: false
ipAddress
string
protocol
string
Value: "gre"

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "enabled": false,
  • "ipAddress": "string",
  • "protocol": "gre"
}

Remove peer from the list of Junction mirroring peers

Remove peer from the list of Junction mirroring peers.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

VPG ID

ipaddr
required
string

IP address of mirroring peer

Responses

Updates a Junction mirroring peer

Updates a Junction mirroring peer.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

VPG ID

ipaddr
required
string

Mirroring peer IP address

Request Body schema: application/json
required

List of attributes to update

Array
key
string
value
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Sets configuration for Junction inspection feature

Sets configuration for Junction inspection feature.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

VPG ID

Request Body schema: application/json
required

Inspection configuration

enabled
boolean
Default: false
object (FunnelConfiguration)

Responses

Request samples

Content type
application/json
{
  • "enabled": false,
  • "report": {
    }
}

Sets configuration for Junction redirection feature

Sets configuration for Junction redirection feature.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

VPG ID

Request Body schema: application/json
required

Redirection configuration

description
string
enabled
boolean
gateway
string

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "enabled": true,
  • "gateway": "string"
}

Unset configuration for Junction inspection feature

Unset configuration for Junction inspection feature.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

VPG ID

Responses

Unset configuration for Junction redirection feature

Unset configuration for Junction redirection feature.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

VPG ID

Responses

List Packet Capture Sessions associated with the VPG

List packet capture sessions associated with the VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

VPG ID

query Parameters
last_evaluated_key
string
Default: "null"

ID of the last packet capture session in the previous page. By specifying this parameter, you can continue to retrieve the list from the next packet capture session onward.

limit
integer <int32>
Default: 10

Max number of results in a response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a packet capture session associated with the VPG

Create a packet capture session associated with the VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

VPG ID

Request Body schema: application/json
required

A packet capture session request

duration
required
integer <int32> [ 30 .. 86400 ]
prefix
string^[0-9A-Za-z_\-]{0,100}$

Responses

Request samples

Content type
application/json
{
  • "duration": 30,
  • "prefix": "string"
}

Response samples

Content type
application/json
{
  • "createdTime": "2019-08-24T14:15:22Z",
  • "duration": 0,
  • "endedTime": "2019-08-24T14:15:22Z",
  • "failedReason": "string",
  • "prefix": "string",
  • "sessionId": "string",
  • "startedTime": "2019-08-24T14:15:22Z",
  • "status": "REQUESTED",
  • "url": "http://example.com"
}

Delete a packet capture session associated with the VPG

Delete a packet capture session associated with the VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

VPG ID

session_id
required
string

Packet capture session ID

Responses

Response samples

Content type
application/json
{
  • "createdTime": "2019-08-24T14:15:22Z",
  • "duration": 0,
  • "endedTime": "2019-08-24T14:15:22Z",
  • "failedReason": "string",
  • "prefix": "string",
  • "sessionId": "string",
  • "startedTime": "2019-08-24T14:15:22Z",
  • "status": "REQUESTED",
  • "url": "http://example.com"
}

Get a packet capture session associated with the VPG

Get a packet capture session associated with the VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

VPG ID

session_id
required
string

Packet capture session ID

Responses

Response samples

Content type
application/json
{
  • "createdTime": "2019-08-24T14:15:22Z",
  • "duration": 0,
  • "endedTime": "2019-08-24T14:15:22Z",
  • "failedReason": "string",
  • "prefix": "string",
  • "sessionId": "string",
  • "startedTime": "2019-08-24T14:15:22Z",
  • "status": "REQUESTED",
  • "url": "http://example.com"
}

Stop a packet capture session associated with the VPG

Stop a packet capture session associated with the VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

VPG ID

session_id
required
string

Packet capture session ID

Responses

Response samples

Content type
application/json
{
  • "createdTime": "2019-08-24T14:15:22Z",
  • "duration": 0,
  • "endedTime": "2019-08-24T14:15:22Z",
  • "failedReason": "string",
  • "prefix": "string",
  • "sessionId": "string",
  • "startedTime": "2019-08-24T14:15:22Z",
  • "status": "REQUESTED",
  • "url": "http://example.com"
}

Sets Virtual Private Gateway outbound routing filter

Sets Virtual Private Gateway outbound routing filter.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

Request Body schema: application/json
required

List of routing filter entries

Array
action
required
string
Enum: "allow" "deny"

Whether to allow or deny the outbound packets with a destination in the specified range

ipRange
required
string

IPv4 address range in CIDR format, e.g. a.b.c.d/x

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Update VPG tags

Adds/updates tags of the specified VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string
Request Body schema: application/json
required
Array
tagName
required
string
tagValue
required
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Delete a VPG Tag

Deletes a tag from the specified VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string
tag_name
required
string

Responses

Terminate Virtual Private Gateway

Terminates the specified VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

Responses

Create transit gateway peering connection

Creates a transit gateway peering connection for the specified VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

Request Body schema: application/json
required
customerAwsAccountId
required
string

AWS account ID of the peer transit gateway

customerRegion
required
string

AWS region of the peer transit gateway

customerTransitGatewayId
required
string

AWS transit gateway ID of the peer transit gateway

name
string

A name used to identify the peering connection

Responses

Request samples

Content type
application/json
{
  • "customerAwsAccountId": "string",
  • "customerRegion": "string",
  • "customerTransitGatewayId": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "allowedOperators": [
    ],
  • "createdTime": 0,
  • "customerRoutes": {
    },
  • "deviceSubnetCidrRange": "string",
  • "enableSimBasedRouting": true,
  • "fixedIpAddressesEnabled": true,
  • "fixedPublicIpAddresses": [
    ],
  • "gateOpened": true,
  • "gatePrivacySeparatorEnabled": true,
  • "gateVxlanId": 0,
  • "implicitTerminationProtected": true,
  • "inspection": {
    },
  • "junctionEnabled": true,
  • "lastModifiedTime": 0,
  • "mirroring": {
    },
  • "offsetId": 0,
  • "operatorId": "string",
  • "placement": {
    },
  • "primaryServiceName": "string",
  • "redirection": {
    },
  • "routingFilterEntries": [
    ],
  • "sessionStats": {
    },
  • "simBasedRoutingConfig": {
    },
  • "size": "string",
  • "soracomTransitGateway": {
    },
  • "soracomTransitGatewayPeeringConnections": {
    },
  • "soracomTransitGatewayVpcAttachments": {
    },
  • "status": "running",
  • "tags": {
    },
  • "transitGatewayAttachments": {
    },
  • "type": 12,
  • "ueSubnetCidrRange": "string",
  • "useInternetGateway": true,
  • "virtualInterfaces": {
    },
  • "vpcPeeringConnections": {
    },
  • "vpgId": "string",
  • "vpgSubnetCidrRange": "string",
  • "vpnConnections": {
    }
}

Delete transit gateway peering connection

Deletes a transit gateway peering connection from the specified VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

soracom_tgw_peering_attachment_id
required
string

Transit gateway peering connection ID

Responses

Create transit gateway VPC attachment

Creates a transit gateway VPC attachment for the specified VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

Request Body schema: application/json
required
customerAwsAccountId
required
string

AWS account ID of the VPC to be attached

customerVpcId
required
string

AWS VPC ID of the VPC to be attached

name
string

A name used to identify the VPC attachment

Responses

Request samples

Content type
application/json
{
  • "customerAwsAccountId": "string",
  • "customerVpcId": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "allowedOperators": [
    ],
  • "createdTime": 0,
  • "customerRoutes": {
    },
  • "deviceSubnetCidrRange": "string",
  • "enableSimBasedRouting": true,
  • "fixedIpAddressesEnabled": true,
  • "fixedPublicIpAddresses": [
    ],
  • "gateOpened": true,
  • "gatePrivacySeparatorEnabled": true,
  • "gateVxlanId": 0,
  • "implicitTerminationProtected": true,
  • "inspection": {
    },
  • "junctionEnabled": true,
  • "lastModifiedTime": 0,
  • "mirroring": {
    },
  • "offsetId": 0,
  • "operatorId": "string",
  • "placement": {
    },
  • "primaryServiceName": "string",
  • "redirection": {
    },
  • "routingFilterEntries": [
    ],
  • "sessionStats": {
    },
  • "simBasedRoutingConfig": {
    },
  • "size": "string",
  • "soracomTransitGateway": {
    },
  • "soracomTransitGatewayPeeringConnections": {
    },
  • "soracomTransitGatewayVpcAttachments": {
    },
  • "status": "running",
  • "tags": {
    },
  • "transitGatewayAttachments": {
    },
  • "type": 12,
  • "ueSubnetCidrRange": "string",
  • "useInternetGateway": true,
  • "virtualInterfaces": {
    },
  • "vpcPeeringConnections": {
    },
  • "vpgId": "string",
  • "vpgSubnetCidrRange": "string",
  • "vpnConnections": {
    }
}

Delete transit gateway VPC attachment

Deletes a transit gateway VPC attachment from the specified VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

customer_tgw_vpc_attachment_id
required
string

Transit gateway VPC attachment ID

Responses

Accept transit gateway VPC attachment connection request

Accepts the specified transit gateway VPC attachment connection request.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

customer_tgw_vpc_attachment_id
required
string

Transit gateway VPC attachment ID

Responses

Create VPC Peering Connection

Creates a VPC peering connection for the specified VPG.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

Request Body schema: application/json
required

VPC peering connection to be created.

destinationCidrBlock
string
peerOwnerId
string
peerRegion
string
peerVpcId
string

Responses

Request samples

Content type
application/json
{
  • "destinationCidrBlock": "string",
  • "peerOwnerId": "string",
  • "peerRegion": "string",
  • "peerVpcId": "string"
}

Response samples

Content type
application/json
{
  • "destinationCidrBlock": "string",
  • "id": "string",
  • "peerOwnerId": "string",
  • "peerRegion": "string",
  • "peerVpcId": "string"
}

Delete VPC Peering Connection

Deletes the specified VPC peering connection.

Authorizations:
(api_keyapi_token)
path Parameters
vpg_id
required
string

Target VPG ID.

pcx_id
required
string

VPC peering connection ID to be deleted.

Responses

Batch

Batch processing

List batch groups.

Returns a list of batch groups.

Authorizations:
(api_keyapi_token)
query Parameters
limit
integer <int32>
Example: limit=10

Maximum number of batch groups to retrieve. The number of batch groups returned may be less than the specified value.

last_evaluated_key
string

The value of the x-soracom-next-key header returned in the response to the last request. Specify this to retrieve the next page of batch groups.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create batch group.

Create a new batch group for organizing and managing batch jobs. To create a batch job, use the Batch:createBatchJob instead.

Authorizations:
(api_keyapi_token)
Request Body schema: application/json
required
batchGroupName
required
string <= 100 characters

Batch group name.

description
string <= 500 characters

Description of the batch group.

Responses

Request samples

Content type
application/json
{
  • "batchGroupName": "Monthly SIM Tag Update",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "batchGroupId": "aaaa1111",
  • "batchGroupName": "Monthly SIM Tag Update",
  • "createdTime": 1704067200,
  • "description": "string",
  • "updatedTime": 1704153600
}

Delete batch group.

Delete the specified batch group. Batch groups can only be deleted if there are no running batch jobs in the group.

Authorizations:
(api_keyapi_token)
path Parameters
batch_group_id
required
string

Batch group ID.

Responses

Get batch group.

Returns details of the specified batch group.

Authorizations:
(api_keyapi_token)
path Parameters
batch_group_id
required
string

Batch group ID.

Responses

Response samples

Content type
application/json
{
  • "batchGroupId": "aaaa1111",
  • "batchGroupName": "Monthly SIM Tag Update",
  • "createdTime": 1704067200,
  • "description": "string",
  • "updatedTime": 1704153600
}

Update batch group.

Updates the name or description of the specified batch group.

Authorizations:
(api_keyapi_token)
path Parameters
batch_group_id
required
string

Batch group ID.

Request Body schema: application/json
required
batchGroupName
string <= 100 characters

Batch group name.

description
string <= 500 characters

Description of the batch group.

Responses

Request samples

Content type
application/json
{
  • "batchGroupName": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "batchGroupId": "aaaa1111",
  • "batchGroupName": "Monthly SIM Tag Update",
  • "createdTime": 1704067200,
  • "description": "string",
  • "updatedTime": 1704153600
}

List batch jobs.

Returns a list of batch jobs in the specified batch group.

Authorizations:
(api_keyapi_token)
path Parameters
batch_group_id
required
string

Batch group ID.

query Parameters
limit
integer <int32>
Example: limit=10

Maximum number of batch jobs to retrieve. The number of batch jobs returned may be less than the specified value.

last_evaluated_key
string

The value of the x-soracom-next-key header returned in the response to the last request. Specify this to retrieve the next page of batch jobs.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create and run batch job.

Create a new batch job and run it. A batch job consists of multiple tasks, each representing an API operation to be performed. Tasks are executed using the permissions of the user that created the batch job API. Batch job information is retained for 32 days.

System Limits:

  • Each batch job is limited to a single API action. Mixing different APIs in the same job is not supported.
  • Each batch job is limited to a maximum of 10,000 tasks.
  • Only one batch job per API action can be created and processed at a time.
  • Batch jobs may be delayed or restricted if system load is high. If this occurs, please wait and try again later.
Authorizations:
(api_keyapi_token)
path Parameters
batch_group_id
required
string

Batch group ID.

Request Body schema: application/json
required
abortOnFailure
boolean

Whether to immediately abort upon encountering an error during batch job execution.

description
string <= 500 characters

Description of the batch job.

jobName
string <= 100 characters

Batch job name.

required
Array of objects (BatchTaskRequest)

List of tasks to be executed in the batch job.

Supported Soracom APIs:

Specify the API request path, HTTP method, and body in the request field according to the Soracom API specification. For example, to call the Sim:activateSim API, specify as follows:

{
  "request": {
    "path": "/v1/sims/8981100001234567890/activate",
    "method": "POST",
    "body": {
      "sim_id": "8981100001234567890"
    }
  }
}

Responses

Request samples

Content type
application/json
{
  • "abortOnFailure": false,
  • "description": "string",
  • "jobName": "July 16th 2025 Set group",
  • "tasks": [
    ]
}

Response samples

Content type
application/json
{
  • "abortOnFailure": true,
  • "batchGroupId": "aaaa1111",
  • "createdTime": 1704067200,
  • "description": "string",
  • "errorMessage": "string",
  • "finishedTime": 1704240000,
  • "jobId": "bbbb2222",
  • "jobName": "July 16th 2025 Set group",
  • "status": "pending",
  • "summary": {
    },
  • "updatedTime": 1704153600
}

Get batch job.

Returns information about the specified batch job.

Authorizations:
(api_keyapi_token)
path Parameters
batch_group_id
required
string

Batch group ID.

job_id
required
string

Batch job ID.

Responses

Response samples

Content type
application/json
{
  • "abortOnFailure": true,
  • "batchGroupId": "aaaa1111",
  • "createdTime": 1704067200,
  • "description": "string",
  • "errorMessage": "string",
  • "finishedTime": 1704240000,
  • "jobId": "bbbb2222",
  • "jobName": "July 16th 2025 Set group",
  • "status": "pending",
  • "summary": {
    },
  • "updatedTime": 1704153600
}

List tasks.

Returns a list of tasks in the specified batch job. Each task represents an individual API operation executed as part of the batch job.

Authorizations:
(api_keyapi_token)
path Parameters
batch_group_id
required
string

Batch group ID.

job_id
required
string

Batch job ID.

query Parameters
limit
integer <int32>
Example: limit=10

Maximum number of tasks to retrieve. The number of tasks returned may be less than the specified value.

status
string
Enum: "pending" "success" "error"

Filter by task status.

last_evaluated_key
string

The value of the x-soracom-next-key header returned in the response to the last request. Specify this to retrieve the next page of tasks.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

ResourceSummary

Get the resource summary identified by resource_summary_type

Obtain a resource summary information identified by resource_summary_type.

Authorizations:
(api_keyapi_token)
path Parameters
resource_summary_type
required
string
Value: "simsPerStatus"

The type of the resource summary.

  • simsPerStatus: The number of IoT SIMs per status.

Responses

Response samples

Content type
application/json
{
  • "resourceSummaryItems": [
    ],
  • "resourceSummaryType": "simsPerStatus"
}