4.0 Provisioning
This is the reference documentation for the Provisioning 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:
title: Provisioning
description: '<p>Activate a subscriber and assign a tariff.<p><strong>Note:</strong> If you want to perform bulk activations, you must use the platform''s user interface.</p></p><p>You can use these endpoints to:</p> <ul> <li>View a list of tariffs that you can assign to a stock subscriber</li> <li>Activate a stock subscriber and assign a tariff</li> </ul> <p>Stock refers to subscribers (physical devices or virtual profiles) that are available (''in stock'') and not yet activated. The provisioning endpoints apply only to subscribers with a status of stock. For any other subscriber state, such as active or terminated, the endpoints return an error.</p> <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><strong>Note:</strong> You should allow between 24 and 48 hours for the network operator to process activation requests.</p>'
version: 4.0.0
servers:
- url: 'https://api.iot-x.com'
paths:
'/provisioning/{physicalId}':
post:
summary: Activates the specified stock subscriber.
tags:
- Provisioning
description: '<p>The following requirements apply to this endpoint:</p><ul><li>You can only activate a ''stock'' subscriber (available in your inventory and not yet activated).</li><li>You must provide the subscriber''s <em>physicalId</em> as a parameter in the request. This value varies depending on the subscriber type:</li><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><li>In the request body, you must provide the <em>productSetId</em> for the tariff you want to assign.</li><li>For a satellite subscriber, you must also provide the Iridium type and target values.</li><li>To use this endpoint, your user account must have the <strong>Activate a Single Subscriber</strong> and <strong> Perform Bulk Subscriber Activations</strong> permissions enabled.</li></ul>'
operationId: activate subscriber
parameters:
- name: physicalId
in: path
description: The unique subscriber identifier.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/activationRequestBody'
responses:
'200':
description: Success - returns the newly activated subscriber details.
content:
application/json:
schema:
properties:
content:
$ref: '#/components/schemas/activationResponse'
'400':
description: Error - invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'404':
description: Error - resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'500':
description: Error - an internal server error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
get:
summary: Returns a list of the available tariffs for the specified stock subscriber.
tags:
- Provisioning
description: '<p>The following requirements apply to this endpoint:</p><ul><li>You can only query the tariffs for a ''stock'' subscriber (available in your inventory and not yet activated). The endpoint returns an error if you query an active subscriber.</li><li>You must provide the subscriber''s <em>physicalId</em> as a parameter in the request. This value varies depending on the subscriber type:</li><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></li><li>To use this endpoint, your user account must have the <strong>View All Tariffs</strong> and <strong>Lets User View Tariff Information</strong> permissions enabled.</li></ul>'
operationId: get available tariffs
parameters:
- name: physicalId
in: path
description: The unique subscriber identifier.
required: true
schema:
type: string
responses:
'200':
description: Success - returns a list of the available tariffs for the specified stock subscriber.
content:
application/json:
schema:
type: object
properties:
content:
type: array
items:
$ref: '#/components/schemas/getTariffSuccessfulResponse'
examples:
exampleGetTariffResponse:
value: |-
[ 'OperatorCode' => [
tariffName => 'TARIFF ABC',
productSetID => 1,
lineRentalPrice => 1000
], [
tariffName => 'TARIFF XYZ',
productSetID => 2,
lineRentalPrice => 2000
]
]
'400':
description: Error - invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'404':
description: Error - resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
components:
schemas:
errorResponse:
required:
- error
properties:
error:
$ref: '#/components/schemas/errorResponseBody'
errorResponseBody:
required:
- children
- code
- message
properties:
children:
description: Any child errors that are related to the request.
example: '[]'
type: string
code:
description: The error code.
example: BAD_REQUEST
type: integer
message:
description: The error message.
example: 'Unable to find :resourceName with identifier :resourceId.'
type: string
activationRequestBody:
required:
- productSetId
properties:
productSetId:
type: integer
description: 'The tariff identifier, unique within your company.'
example: 99
deviceNickname:
type: string
description: The subscriber nickname.
example: Example Nickname
imei:
type: string
description: The subscriber IMEI (for a satellite subscriber).
example: 990000862471854
zipCode:
description: The location at which the subscriber is registered (used for US MNOs).
type: string
example: '78701'
iridium:
type: array
items:
$ref: '#/components/schemas/iridiumTarget'
iridiumTarget:
required:
- type
- target
properties:
type:
type: string
description: 'The type of Iridium endpoint, either TCP or email.'
example: email
target:
type: string
description: The TCP or email address to which Iridium messages are forwarded.
example: Example@examples.com
example:
- type: tcp
target: 8.8.8.8
- type: email
target: Example@examples.com
activationResponse:
required:
- dataNumber
- physicalId
- imsi
- ip
- status
- subscriberId
properties:
physicalId:
description: '<p>The unique <em>physical</em> subscriber identifier:</p><ul><li><em>Cellular</em> - the ICCID</li><li><em>Non-IP</em> - the EUI</li><li><em>Satellite</em> - the IMEI</li></ul>'
type: string
example: '8944000000000000001'
subscriberId:
description: '<p>The unique <em>network</em> subscriber identifier:</p><ul><li>Cellular subscriber - the MSISDN</li><li>Non-IP subscriber - the Device EUI</li><li>Satellite subscriber - the Subscription ID</li></ul>'
type: string
example: '447000000001'
dataNumber:
description: 'If the subscriber uses Circuit Switched Data (CSD), this field displays its data number. If the subscriber does not use CSD, this field is null.'
type: string
example: '9999'
ip:
description: The subscriber IP address.
type: string
example: 172.0.0.1
imsi:
description: The subscriber IMSI.
type: string
example: '234150000000001'
getTariffSuccessfulResponse:
required:
- '{operatorName}'
properties:
'{operatorName}':
description: An array of tariff objects named by the operator.
type: array
items:
$ref: '#/components/schemas/tariffObject'
tariffObject:
required:
- lineRentalPrice
- productSetID
- tariffName
properties:
tariffName:
description: The tariff name.
type: string
example: TARIFF ABC
productSetID:
description: 'The tariff identifier, unique within your company.'
example: 1
type: integer
lineRentalPrice:
description: The cost of line rental for the tariff expressed in pence (or in the smallest unit of the tariff currency).
type: number
example: 1000