4.0 Subscriber products
This is the reference documentation for the Subscriber products 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: Subscriber products
description: <p>Manage an active subscriber's functionality and services (<em>products</em>).</p><p>You can use these endpoints to retrieve a list of:</p><ul><li>Attached products (associated with the subscriber's tariff and enabled)</li><li>Available products (associated with the subscriber's tariff but not yet enabled)</li></ul><p>You can also use these endpoints to enable or disable an active subscriber's products.</p><p><em>Products</em> are functional options, such as:</p><ul><li>Network access</li><li>SMS services</li><li>Voice services</li></ul><p>The available products vary depending on the subscriber's tariff, and changing a subscriber's products can incur additional fees.</p>
version: 4.0.0
servers:
- url: 'https://api.iot-x.com'
paths:
/subscribers/{physicalId}/products/active:
get:
summary: Returns a list of products that are attached to the specified subscriber.
description: 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 must be assigned with the <strong>View Subscriber Products</strong> permission.
tags:
- Subscribers
operationId: get-active-products
responses:
200:
description: Successful response - this either returns an array of the products that are attached to the subscriber, or an empty array (meaning no products are attached).
content:
application/json:
schema:
$ref: '#/components/schemas/ValidResponse'
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'
parameters:
- name: physicalId
in: path
description: The unique subscriber identifier.
required: true
schema:
type: string
/subscribers/{physicalId}/products/available:
get:
summary: Returns a list of products that can be attached to the specified subscriber.
description: 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 must be assigned with the <strong>View Subscriber Products</strong> permission.
tags:
- Subscribers
operationId: get-available-products
responses:
200:
description: Successful response - this either returns an array of the products that can be attached to the subscriber or an empty array (meaning no products are available to be attached).
content:
application/json:
schema:
$ref: '#/components/schemas/ValidResponse'
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'
parameters:
- name: physicalId
in: path
description: The unique subscriber identifier.
required: true
schema:
type: string
/subscribers/{physicalId}/products:
patch:
tags:
- Subscribers
summary: Enables or disables products that are attached to a specified subscriber.
description: |
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>You specify the product to enable or disable in the request body's <em>product</em> field. This value must be identical to the value returned in the <em>product</em> field of the /subscribers/{physicalId}/products/active endpoint's response body.<p><br>You can only enable and disable products when the subscriber is in an active state. <p><br>To use this endpoint, your user must be assigned with the <strong>Add a Product to a Subscriber</strong> and <strong>Remove a Product From a Subscriber</strong> permissions.
operationId: enable-or-disable-products
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EnableDisableRequestBody'
examples:
Example Enable/Disable Request Body:
summary: An example request body.
description: both keys and values are required.
value: '[service => Product Name 1, action => enable]'
required: true
responses:
204:
description: Successful response - the product has been successfully enabled or disabled for the given subscriber.
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'
parameters:
- name: physicalId
in: path
description: The unique subscriber identifier.
required: true
schema:
type: string
components:
schemas:
ValidResponse:
required:
- content
properties:
content:
description: The response to a valid request is either an array of the subscriber's attached products or an empty array (meaning no products are attached to the subscriber).
type: array
items:
$ref: '#/components/schemas/SubscriberProduct'
SubscriberProduct:
required:
- description
- enabled
- product
properties:
product:
description: The product's name.
type: string
example: 'Product Name'
description:
description: The product's description.
example: 'This product allows subscribers to ...'
type: string
enabled:
description: Whether the product is enabled on the subscriber.
type: boolean
example: 'true'
ErrorResponse:
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorResponseBody'
description: Key name of the error body
ErrorResponseBody:
required:
- message
- code
- children
properties:
message:
description: The error message.
type: string
example: 'Unable to find :resourceName with identifier :resourceId.'
code:
description: The error's code.
type: integer
example: 'BAD_REQUEST'
children:
description: Any child errors that are related to the request.
type: string
example: '[]'
EnableDisableRequestBody:
required:
- service
- action
properties:
product:
description: The name of the product to be enabled or disabled.
example: 'Product Name'
type: string
action:
description: The action to perform on the product. This can either be 'enable' or 'disable'.
type: string
example: 'enable'
tags:
- name: Subscribers