Soracom Event Handler API
Configure event handlers (rules + actions) on SIM, data, and billing events; manage the Credentials Store; and deploy Orbit Soralets (WebAssembly inline payload transforms).
OpenAPI Specification
openapi: 3.0.0
info:
title: Soracom Event Handler API
description: Define event handlers, rule sets, and actions to drive workflows on SIM, billing, and data events; manage credentials
and Soralets.
version: 20250903-043502
servers:
- description: Japan coverage production API endpoint
url: https://api.soracom.io/v1
- description: Global coverage production API endpoint
url: https://g.api.soracom.io/v1
paths:
/event_handlers:
get:
description: Returns a list of event handlers.
operationId: listEventHandlers
parameters:
- description: The event handler target (the target for executing events).
in: query
name: target
required: false
schema:
enum:
- operator
- imsi
- sim
- group
type: string
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/EventHandlerModel'
type: array
description: OK.
security:
- api_key: []
api_token: []
summary: List Event Handlers
tags:
- EventHandler
x-soracom-cli:
- event-handlers list
post:
description: Creates a new event handler. Please see also https://developers.soracom.io/en/docs/air/event-handler/.
operationId: createEventHandler
requestBody:
content:
application/json:
examples:
(01) Execute multiple actions when a subscriber's monthly data traffic volume exceeds a certain limit.:
value:
actionConfigList:
- properties:
executionDateTimeConst: IMMEDIATELY
speedClass: s1.minimum
type: ChangeSpeedClassAction
- properties:
executionDateTimeConst: BEGINNING_OF_NEXT_MONTH
speedClass: s1.standard
type: ChangeSpeedClassAction
- properties:
message: 'Target IoT SIM: ${imsi}
The monthly data traffic volume of the IoT SIM has reached 1024 MiB, and the communication speed has
been limited to "s1.minimum".'
title: Notification of Speed Limitation
type: SendMailToOperatorAction
- properties:
message: 'Target IoT SIM: ${imsi}
Since the speed limitation period has ended, the communication speed has been set to "s1.standard".'
title: Notification of Speed Limitation Release
type: SendMailToOperatorAction
description: Sample description
name: Event handler
ruleConfig:
properties:
inactiveTimeoutDateConst: BEGINNING_OF_NEXT_MONTH
limitTotalTrafficMegaByte: 1024
type: SubscriberMonthlyTrafficRule
status: active
targetOperatorId: OP0000000000
(02) Notify on Slack when the speed class of an IoT SIM changes.:
value:
actionConfigList:
- properties:
body: '{"text":"${imsi} speed class changed from ${oldSpeedClass} to ${newSpeedClass}"}'
contentType: application/json
executionDateTimeConst: IMMEDIATELY
headers: '{"contentType":"application/json; charset=utf-8"}'
httpMethod: POST
url: https://hooks.slack.com/services/XXXX
type: ExecuteWebRequestAction
name: SpeedClass
ruleConfig:
properties:
inactiveTimeoutDateConst: IMMEDIATELY
type: SimSpeedClassAttributeRule
status: active
targetOperatorId: OP0000000000
(03) If the daily data traffic volume exceeds 100 MiB, limit the speed for 24 hours and send an email notification.:
value:
actionConfigList:
- properties:
executionDateTimeConst: IMMEDIATELY
speedClass: s1.slow
type: ChangeSpeedClassAction
- properties:
executionDateTimeConst: AFTER_ONE_DAY
speedClass: s1.fast
type: ChangeSpeedClassAction
- properties:
executionDateTimeConst: IMMEDIATELY
message: Speed limitation will be implemented as the daily data traffic volume has reached 100 MiB.
title: Notification from Soracom
to: notify@exmaple.com
type: SendMailAction
- properties:
executionDateTimeConst: AFTER_ONE_DAY
message: Speed limitation will be released
title: Notification from Soracom
to: notify@exmaple.com
type: SendMailAction
description: Limit speed for 24 hours if daily data traffic volume exceeds 100 MiB.
name: 100 MiB Limit
ruleConfig:
properties:
inactiveTimeoutDateConst: AFTER_ONE_DAY
limitTotalTrafficMegaByte: '100'
type: SubscriberDailyTrafficRule
status: active
targetImsi: xxxxxxxxxxxx
(04) Call AWS Lambda when the cumulative data traffic volume reaches 3000 MiB.:
description: 'For cumulative events, `inactiveTimeoutDateConst` is set to `NEVER` (not re-evaluated).
'
value:
actionConfigList:
- properties:
credentialsId: '{Authentication ID}'
endpoint: https://lambda.ap-northeast-1.amazonaws.com
executionDateTimeConst: IMMEDIATELY
functionName: '{Lambda function name}'
parameter1: param1
parameter2: param2
parameter3: param3
type: InvokeAWSLambdaAction
description: Call AWS Lambda when cumulative data traffic volume reaches 3000 MiB.
name: 3000 MiB Limit
ruleConfig:
properties:
inactiveTimeoutDateConst: NEVER
limitTotalTrafficMegaByte: '3000'
type: SimCumulativeTotalTrafficRule
status: active
targetOperatorId: OP0000000000
(05) Save history in AWS Lambda when changing speed class.:
description: 'The idea is to send the before and after speed classes to AWS Lambda using variables available
in the speed class change rule (`${newSpeedClass}` and `${oldSpeedClass}`), and save the history in a database
or similar in AWS Lambda.
'
value:
actionConfigList:
- properties:
credentialsId: '{Authentication ID}'
endpoint: https://lambda.ap-northeast-1.amazonaws.com
executionDateTimeConst: IMMEDIATELY
functionName: '{Lambda function name}'
parameter1: ${oldSpeedClass}
parameter2: ${newSpeedClass}
type: InvokeAWSLambdaAction
description: Save history in AWS Lambda when changing speed class.
name: SpeedClass Change
ruleConfig:
properties:
inactiveTimeoutDateConst: IMMEDIATELY
targetSpeedClass: null
type: SubscriberSpeedClassAttributeRule
status: active
targetOperatorId: OP0000000000
(06) Send a request to a specified URL when the data traffic volume of a subscriber is recorded for the first time.:
value:
actionConfigList:
- properties:
body: '{"text":"${imsi} speed class changed from ${oldSpeedClass} to ${newSpeedClass}"}'
contentType: application/json
executionDateTimeConst: IMMEDIATELY
headers: '{"contentType":"application/json; charset=utf-8"}'
httpMethod: POST
url: https://hooks.slack.com/services/XXXX
type: ExecuteWebRequestAction
description: Sample description
name: Event handler
ruleConfig:
properties:
inactiveTimeoutDateConst: NEVER
type: SubscriberFirstTrafficRule
status: active
targetOperatorId: OP0000000000
(07) Send an email when a subscriber's daily data traffic volume exceeds a certain limit.:
value:
actionConfigList:
- properties:
executionDateTimeConst: IMMEDIATELY
message: 'IMSI: ${imsi} daily data traffic volume has reached 10 MiB.'
title: Notification from SORACOM
to: notify@exmaple.com
type: SendMailAction
description: Sample description
name: Event handler
ruleConfig:
properties:
inactiveTimeoutDateConst: BEGINNING_OF_NEXT_DAY
inactiveTimeoutOffsetMinutes: '5'
limitTotalTrafficMegaByte: '10'
type: SubscriberDailyTrafficRule
status: active
targetOperatorId: OP0000000000
(08) Change the speed class of an IoT SIM when a subscriber's monthly data traffic volume exceeds a certain limit.:
value:
actionConfigList:
- properties:
executionDateTimeConst: IMMEDIATELY
speedClass: s1.minimum
type: ChangeSpeedClassAction
description: Sample description
name: Event handler
ruleConfig:
properties:
inactiveTimeoutDateConst: BEGINNING_OF_NEXT_MONTH
limitTotalTrafficMegaByte: '1024'
type: SubscriberMonthlyTrafficRule
status: active
targetOperatorId: OP0000000000
? (09) Change the status of an IoT SIM when the cumulative data traffic volume from the start of use exceeds
a certain limit.
: value:
actionConfigList:
- properties:
executionDateTimeConst: IMMEDIATELY
type: SuspendAction
description: Sample description
name: Event handler
ruleConfig:
properties:
inactiveTimeoutDateConst: NEVER
limitTotalTrafficMegaByte: '10240'
type: SubscriberCumulativeTrafficRule
status: active
targetOperatorId: OP0000000000
(10) Send a request to a specified URL when the status of an IoT SIM changes.:
value:
actionConfigList:
- properties:
body: '{"text":"${imsi} status changed from ${oldStatus} to ${newStatus}"}'
contentType: application/json
executionDateTimeConst: IMMEDIATELY
headers: '{"contentType":"application/json; charset=utf-8"}'
httpMethod: POST
url: https://hooks.slack.com/services/XXXX
type: ExecuteWebRequestAction
description: Sample description
name: Event handler
ruleConfig:
properties:
inactiveTimeoutDateConst: NEVER
sourceStatus: ready
targetStatus: active
type: SimStatusAttributeRule
status: active
targetOperatorId: OP0000000000
(11) Call AWS Lambda when the speed class of an IoT SIM changes.:
value:
actionConfigList:
- properties:
credentialsId: '{Authentication ID}'
endpoint: https://lambda.ap-northeast-1.amazonaws.com
executionDateTimeConst: IMMEDIATELY
functionName: '{Lambda function name}'
parameter1: param1
parameter2: param2
parameter3: param3
type: InvokeAWSLambdaAction
description: Sample description
name: Event handler
ruleConfig:
properties:
inactiveTimeoutDateConst: IMMEDIATELY
targetSpeedClass: s1.4xfast
type: SimSpeedClassAttributeRule
status: active
targetOperatorId: OP0000000000
(12) Send an email to the operator's primary email address when the validity period of an IoT SIM expires.:
value:
actionConfigList:
- properties:
executionDateTimeConst: IMMEDIATELY
message: 'IMSI: ${imsi}''s validity period has expired.'
title: Notification from Soracom
type: SendMailToOperatorAction
description: Sample description
name: Event handler
ruleConfig:
properties:
inactiveTimeoutDateConst: BEGINNING_OF_NEXT_MONTH
type: SubscriberExpiredRule
status: active
targetOperatorId: OP0000000000
(13) Call AWS Lambda when an IoT SIM fails to connect due to an IMEI lock.:
value:
actionConfigList:
- properties:
credentialsId: '{Authentication ID}'
endpoint: https://lambda.ap-northeast-1.amazonaws.com
executionDateTimeConst: IMMEDIATELY
functionName: '{Lambda function name}'
parameter1: param1
parameter2: param2
parameter3: param3
type: InvokeAWSLambdaAction
description: Sample description
name: Event handler
ruleConfig:
properties:
inactiveTimeoutDateConst: AFTER_ONE_DAY
type: SubscriberImeiMismatchedRule
status: active
targetOperatorId: OP0000000000
? (14) Send an email when the total daily data traffic volume of all subscribers linked to an IoT SIM exceeds
a certain limit.
: value:
actionConfigList:
- properties:
executionDateTimeConst: IMMEDIATELY
message: 'SIM ID: ${simId}''s total daily data traffic volume has reached 10 MiB.'
title: Notification from Soracom
to: notify@exmaple.com
type: SendMailAction
description: Sample description
name: Event handler
ruleConfig:
properties:
inactiveTimeoutDateConst: BEGINNING_OF_NEXT_DAY
inactiveTimeoutOffsetMinutes: '5'
limitTotalTrafficMegaByte: '10'
runOnceAmongTarget: 'true'
type: SimDailyTotalTrafficRule
status: active
targetOperatorId: OP0000000000
? (15) Change the speed class of an IoT SIM when the total monthly data traffic volume of all subscribers linked
to it exceeds a certain limit.
: value:
actionConfigList:
- properties:
executionDateTimeConst: IMMEDIATELY
speedClass: s1.minumum
type: ChangeSpeedClassAction
description: Sample description
name: Event handler
ruleConfig:
properties:
inactiveTimeoutDateConst: BEGINNING_OF_NEXT_MONTH
limitTotalTrafficMegaByte: '1024'
runOnceAmongTarget: 'true'
type: SimMonthlyTotalTrafficRule
status: active
targetOperatorId: OP0000000000
? (16) Change the status of an IoT SIM when the total cumulative data traffic volume from the start of use of
all linked subscribers exceeds a certain limit.
: value:
actionConfigList:
- properties:
executionDateTimeConst: IMMEDIATELY
type: SuspendAction
description: Sample description
name: Event handler
ruleConfig:
properties:
inactiveTimeoutDateConst: NEVER
limitTotalTrafficMegaByte: '10240'
runOnceAmongTarget: 'true'
type: SimCumulativeTotalTrafficRule
status: active
targetOperatorId: OP0000000000
(17) Call AWS Lambda when a subscription is added to an IoT SIM.:
value:
actionConfigList:
- properties:
credentialsId: '{Authentication ID}'
endpoint: https://lambda.ap-northeast-1.amazonaws.com
executionDateTimeConst: IMMEDIATELY
functionName: '{Lambda function name}'
parameter1: param1
parameter2: param2
parameter3: param3
type: InvokeAWSLambdaAction
description: Sample description
name: Event handler
ruleConfig:
properties:
inactiveTimeoutDateConst: NEVER
runOnceAmongTarget: 'false'
targetOtaStatus: started
type: SimSubscriptionStatusRule
status: active
targetOperatorId: OP0000000000
? (18) Send an email to the operator's primary email address when the total daily data traffic volume of all
IoT SIMs linked to the operator exceeds a certain limit.
: value:
actionConfigList:
- properties:
executionDateTimeConst: IMMEDIATELY
message: The total daily data traffic volume of all IoT SIMs linked to the operator has exceeded 1024
MiB.
title: Notification from Soracom
type: SendMailToOperatorAction
description: Sample description
name: Event handler
ruleConfig:
properties:
inactiveTimeoutDateConst: BEGINNING_OF_NEXT_DAY
limitTotalTrafficMegaByte: '1024'
runOnceAmongTarget: 'false'
type: DailyTotalTrafficRule
status: active
targetOperatorId: OP0000000000
? (19) Change the speed class of IoT SIMs when the total monthly data traffic volume of all IoT SIMs linked
to an operator exceeds a certain limit.
: value:
actionConfigList:
- properties:
executionDateTimeConst: IMMEDIATELY
speedClass: s1.minumum
type: ChangeSpeedClassAction
description: Sample description
name: Event handler
ruleConfig:
properties:
inactiveTimeoutDateConst: BEGINNING_OF_NEXT_MONTH
limitTotalTrafficMegaByte: '10240'
runOnceAmongTarget: 'false'
type: MonthlyTotalTrafficRule
status: active
targetOperatorId: OP0000000000
(20) Change the status of IoT SIMs when this month's usage fee exceeds a set amount.:
value:
actionConfigList:
- properties:
executionDateTimeConst: IMMEDIATELY
type: SuspendAction
description: Sample description
name: Event handler
ruleConfig:
properties:
inactiveTimeoutDateConst: BEGINNING_OF_NEXT_MONTH
limitTotalAmount: '10000'
type: MonthlyChargeRule
status: active
targetOperatorId: OP0000000000
schema:
$ref: '#/components/schemas/CreateEventHandlerRequest'
description: Event handler settings.
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/EventHandlerModel'
description: Created.
security:
- api_key: []
api_token: []
summary: Create Event Handler
tags:
- EventHandler
x-soracom-cli:
- event-handlers create
/event_handlers/{handler_id}:
delete:
description: Deletes the specified event handler.
operationId: deleteEventHandler
parameters:
- description: Event handler ID.
in: path
name: handler_id
required: true
schema:
type: string
responses:
'204':
description: OK.
'404':
description: Event Handler not found.
security:
- api_key: []
api_token: []
summary: Delete Event Handler
tags:
- EventHandler
x-soracom-cli:
- event-handlers delete
get:
description: Returns information about the specified event handler.
operationId: getEventHandler
parameters:
- description: Event handler ID.
in: path
name: handler_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EventHandlerModel'
description: OK.
'404':
description: Event Handler not found.
security:
- api_key: []
api_token: []
summary: Get Event Handler
tags:
- EventHandler
x-soracom-cli:
- event-handlers get
put:
description: Updates the specified event handler. Please see also https://developers.soracom.io/en/docs/air/event-handler/.
operationId: updateEventHandler
parameters:
- description: Event handler ID.
in: path
name: handler_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEventHandlerRequest'
description: Event handler settings.
required: true
responses:
'200':
description: OK.
'400':
description: Invalid event handler ID.
security:
- api_key: []
api_token: []
summary: Update Event Handler
tags:
- EventHandler
x-soracom-cli:
- event-handlers update
/event_handlers/{handler_id}/subscribers/{imsi}/ignore:
delete:
description: Deletes the setting for ignoring the specified event handler of the specified IMSI.
operationId: deleteIgnoreEventHandler
parameters:
- description: IMSI.
in: path
name: imsi
required: true
schema:
type: string
- description: Event handler ID.
in: path
name: handler_id
required: true
schema:
type: string
responses:
'204':
description: OK.
'404':
description: Event Handler not found.
security:
- api_key: []
api_token: []
summary: Delete Ignore Event Handler
tags:
- EventHandler
x-soracom-cli:
- event-handlers unignore
post:
description: Adds a setting for ignoring the specified event handler of the specified IMSI.
operationId: setIgnoreEventHandler
parameters:
- description: IMSI.
in: path
name: imsi
required: true
schema:
type: string
- description: Event handler ID.
in: path
name: handler_id
required: true
schema:
type: string
responses:
'200':
description: OK.
security:
- api_key: []
api_token: []
summary: Ignore Event Handler
tags:
- EventHandler
x-soracom-cli:
- event-handlers ignore
/event_handlers/subscribers/{imsi}:
get:
description: Returns a list of event handlers related to the specified IMSI.
operationId: listEventHandlersBySubscriber
parameters:
- description: IMSI.
in: path
name: imsi
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/EventHandlerModel'
type: array
description: OK.
'404':
description: Event Handler not found.
security:
- api_key: []
api_token: []
summary: List Event Handlers related to Subscriber
tags:
- EventHandler
x-soracom-cli:
- event-handlers list-for-subscriber
/credentials:
get:
description: Returns a list of credential sets.
operationId: listCredentials
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/CredentialsModel'
type: array
description: OK.
security:
- api_key: []
api_token: []
summary: List credential sets
tags:
- Credential
x-soracom-cli:
- credentials list
/credentials/{credentials_id}:
delete:
description: Deletes a credential set.
operationId: deleteCredential
parameters:
- description: Credential set ID.
in: path
name: credentials_id
required: true
schema:
type: string
responses:
'204':
description: Credential set has been deleted.
'404':
description: Not Found.
security:
- api_key: []
api_token: []
summary: Delete a credential set
tags:
- Credential
x-soracom-cli:
- credentials delete
post:
description: Creates a new credential set.
operationId: createCredential
parameters:
- description: Credential set ID.
in: path
name: credentials_id
required: true
schema:
type: string
requestBody:
content:
application/json:
examples:
API Token credentials:
$ref: '#/components/examples/APITokenCredentials'
AWS IAM Role credentials:
$ref: '#/components/examples/IAMRoleCredentials'
AWS credentials:
$ref: '#/components/examples/AWSCredentials'
Asteria Platio credentials:
$ref: '#/components/examples/InfoteriaPlatioCredentials'
Azure IoT credentials:
$ref: '#/components/examples/AzureIoTCredentials'
Azure credentials:
$ref: '#/components/examples/AzureCredentials'
Esri Japan ArcGIS Online credentials:
$ref: '#/components/examples/EsrijCredentials'
Google Cloud IoT Core credentials:
$ref: '#/components/examples/GoogleIoTCredentials'
Google Service Account (JSON):
$ref: '#/components/examples/GoogleServiceAccountJson'
Kii Thing-IF credentials:
$ref: '#/components/examples/KiiThingifCredentials'
LANDLOG credentials:
$ref: '#/components/examples/LandlogCredentials'
OPTiM Cloud IoT OS credentials:
$ref: '#/components/examples/OptimCloudCredentials'
Pre-Shared Key:
$ref: '#/components/examples/PreSharedKey'
PubNub credentials:
$ref: '#/components/examples/PubnubCredentials'
SensorCorpus credentials:
$ref: '#/components/examples/SensorcorpusCredentials'
Username password credentials:
$ref: '#/components/examples/UsernamePasswordCredentials'
WingArc1st MotionBoard credentials:
$ref: '#/components/examples/MotionboardCredentials'
X.509 certificate:
$ref: '#/components/examples/X509Certificate'
YE DIGITAL MMCloud credentials:
$ref: '#/components/examples/MmcloudCredentials'
schema:
$ref: '#/components/schemas/CreateAndUpdateCredentialsModel'
description: Credential set.
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/CredentialsModel'
description: Credential set has been created.
security:
- api_key: []
api_token: []
summary: Create a credential set
tags:
- Credential
x-soracom-cli:
- credentials create
put:
description: Updates a credential set.
operationId: updateCredential
parameters:
- description: Credential set ID.
in: path
name: credentials_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAndUpdateCredentialsModel'
description: Credential set.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CredentialsModel'
description: OK.
'400':
description: There was an error in the request or the specified token has already expired. (In the latter case,
you will need to use the /auth API to do authentication once again.)
security:
- api_key: []
api_token: []
summary: Update a credential set
tags:
- Credential
x-soracom-cli:
- credentials update
/soralets:
get:
description: Returns a list of Soralets.
operationId: listSoralets
parameters:
- description: Sort order of the data entries. Either descending (latest data entry first) or ascending (oldest data
entry first).
in: query
name: sort
required: false
schema:
default: asc
enum:
- asc
- desc
type: string
- description: The maximum number of items in a response.
in: query
name: limit
required: false
schema:
ty
# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/soracom/refs/heads/main/openapi/soracom-event-handler-api-openapi.yml