4.0 Subscriber actions
This is the reference documentation for the Subscriber actions endpoints.
Note
You can generate an example call for each endpoint using the Try It Out button.
This call will not trigger any action on your account unless you add your authentication token to it.
openapi: 3.0.0
info:
version: 4.0.0
title: Subscriber actions
description: |-
<p>Perform troubleshooting actions for your subscribers.</p><p>You can use these endpoints to:</p><ul>
<li>View a list of available actions</li>
<li>Refresh the subscriber services that are currently running (SIM refresh) </li>
<li>Disconnect/reconnect a subscriber (forces a new connection)</li>
<li>Perform a SIM swap between two subscribers to transfer products, services and tariff details from one SIM to another</li></ul><p>The subscriber actions you can perform depend on the subscriber type and network.</p><p><strong>Note -</strong> Some endpoints require you to pass the subscriber <em>physicalId</em> parameter in the request. This value varies depending on the subscriber type:</p><ul><li><em>Cellular</em> - use the ICCID</li><li><em>Non-IP</em> - use the Device EUI</li><li><em>Satellite</em> - use the IMEI</li></ul>
servers:
- url: 'https://api.iot-x.com'
paths:
'/subscriber-actions-api/subscribers/{physicalId}/actions':
get:
summary: Returns a list of actions you can perform for the specified subscriber.
description: '<p>You must provide the subscriber''s <em>physicalId</em> as a parameter in the request. This value varies depending on the subscriber type:</p><ul><li><em>Cellular</em> - use the ICCID</li><li><em>Non-IP</em> - use the Device EUI</li><li><em>Satellite</em> - use the IMEI</li></ul><p>To use this endpoint, your user account must have the <strong>Perform Troubleshooting Actions on a Subscriber</strong> permission enabled.'
tags:
- Actions
parameters:
- name: physicalId
in: path
description: The unique subscriber identifier.
required: true
allowEmptyValue: false
schema:
type: string
example: '89400000001'
responses:
'200':
description: Success - returns a list of actions that you can perform for the specified subscriber.
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/SubscriberActionsResponse'
'/subscriber-actions-api/subscribers/{physicalId}/actions/{actionName}':
post:
summary: Performs the specified subscriber action.
description: '<p>The <em>actionName</em> and <em>physicalId</em> are required parameters in the request.</p><br><p>The <em>physicalID</em> value depends on the subscriber type:</p><ul><li><em>Cellular</em> - use the ICCID</li><li><em>Non-IP</em> - use the Device EUI</li><li><em>Satellite</em> - use the IMEI</li></ul><p><p>The available <em>actionNames</em> include</p><ul><li>refresh</li><li>disconnectReconnect, and</li><li>view_swap.</li></ul><p>To perform a SIM swap between a faulty SIM and a new SIM, you must:</p><ul><li>provide the subscriber <em>physicalId</em> of both the faulty SIM (path parameter) and the new SIM (in the request body), and</li><li>make sure that the new SIM is unactivated and belongs to the same operator as the faulty SIM.</li></ul><p>To use this endpoint, your user account must have the <strong>Perform Troubleshooting Actions on a Subscriber</strong> permission enabled.</p>'
tags:
- Actions
parameters:
- name: physicalId
in: path
description: The unique subscriber identifier.
required: true
allowEmptyValue: false
schema:
type: string
example: '89400000001'
- name: actionName
in: path
description: The name of the action you want to perform.
required: true
allowEmptyValue: false
schema:
type: string
enum:
- refresh
- disconnectReconnect
- view_swap
example: refresh
requestBody:
description: 'For the view_swap action, you must provide the physical ID of the new SIM (<em>newPhysicalId</em>) in the request body.'
required: false
content:
application/json:
schema:
type: string
example: '{ "newPhysicalId": "8944200000000000002" }'
$ref: '#/components/schemas/actionPostBody'
responses:
'204':
description: Success - the action was performed.
'400':
description: Error - invalid request.
'404':
description: Error - resource not found.
components:
schemas:
SubscriberAction:
properties:
name:
type: string
description: The action name.
example: refresh
description:
type: string
description: A description of the action.
example: Sends an instruction to refresh the services on the subscriber's SIM.
SubscriberActionsResponse:
properties:
content:
type: array
description: Returns a list of actions that you can perform for the specified subscriber.
items:
$ref: '#/components/schemas/SubscriberAction'
actionPostBody:
properties:
newPhysicalId:
type: string
example: 8944200000000000000
description: The physical ID of the new target subscriber.
type: object
required:
- nickname