4.0 Tags

This is the reference documentation for the Tags 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.

components: schemas: Tag: properties: tagName: minLength: 1 type: string description: The tag name. example: 'Example Tag' required: - tagName type: object TagWithCount: properties: tagName: type: string description: The tag name. example: 'Example Tag' numberOfSubscribers: type: integer description: The number of subscribers associated with the specified tag. example: 10 required: - tagName - numberOfSubscribers type: object Subscriber: properties: physicalId: maxLength: 25 type: string minLength: 1 description: <p>The subscriber's <em>physicalId</em>.</p><p>This value varies depending on the subscriber type&#58;</p><ul><li><em>Cellular</em> - the ICCID</li><li><em>Non-IP</em> - the Device EUI</li><li><em>Satellite</em> - the IMEI</li></ul> example: '894000000000001' required: - physicalId type: object info: title: Tags version: 4.0.0 description: |- <p>Manage the subscriber tags for your company.</p><p>Tags provide a way to identify and search for subscribers. For example, you might want to create tags that identify subscribers by project, network or location. <p><strong>Note</strong>&#58; If you want to restrict access to a group of subscribers, use a <em>Subscriber group</em> rather than a tag.</p> <p>You can use these endpoints to&#58;</p> <ul> <li>Retrieve a list of all the tags associated with your company</li> <li>Retrieve a list of all the tags associated with a subscriber</li> <li>Retrieve a list of all the subscribers associated with a tag</li> <li>Add a tag to a subscriber</li> <li>Remove a tag from a subscriber</li> </ul> <p><strong>Note&#58;</strong> Some endpoints require you to pass the subscriber <em>physicalId</em> parameter in the request. This value varies depending on the subscriber type&#58;</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> openapi: 3.0.0 paths: '/tags': get: operationId: TagListController.getAllTags responses: '200': content: application/json: schema: type: object properties: content: type: array items: $ref: '#/components/schemas/TagWithCount' description: Success - returns a list of all the tags associated with your company. summary: Returns a list of all the tags associated with your company. tags: - Tags parameters: - name: offset in: query description: <p>Offsets the returned results to begin at a particular record count.</p><p>For example, setting this to 10 causes the query to skip the first ten records in the data set.</p> schema: type: number default: 0 - name: limit in: query description: 'Specifies the upper limit of the number of results to return. This filter has an upper limit of 100.<p>For example, setting this to 10 limits the query to returning a maximum of ten records.</p>If no limit is set, the query will return a maximum of 25 records.</p>' schema: type: number maximum: 100 default: 25 description: <p>Returns a list of your company tags and the total number of subscribers identified by each tag.</p><p><br>To use this endpoint, your user account must have the <strong>View Subscriber</strong> permission enabled.</p> '/subscribers/{physicalId}/tags': get: operationId: TagListController.getAllTagsFromSubscriber parameters: - in: path name: physicalId description: The unique subscriber identifier. required: true schema: type: string - name: offset in: query description: 'Offsets the returned results to begin at particular record count. <p>For example, setting this to 10 causes the query to skip the first ten records in the data set.</p>' schema: type: number default: 0 - name: limit in: query description: 'Specifies the upper limit of the number of results to return. This filter has an upper limit of 100.<p>For example, setting this to 10 limits the query to returning a maximum of ten records.</p>If no limit is set, the query will return a maximum of 25 records.</p>' schema: type: number maximum: 100 default: 25 responses: '200': content: application/json: schema: type: object properties: content: type: array items: $ref: '#/components/schemas/Tag' description: Success - returns a list of the tags associated with the specified subscriber. '400': content: application/json: schema: type: object properties: error: type: object properties: message: type: string code: type: string description: Error - invalid request. summary: Returns a list of the tags associated with the specified subscriber. tags: - Tags description: <p>You must provide the subscriber's <em>physicalId</em> as a parameter in this request. This value varies depending on the subscriber type&#58;</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>View Subscriber</strong> permission enabled.</p> '/{tagName}/subscribers': get: operationId: TagListController.getAllSubscribersFromTag parameters: - in: path name: tagName description: The tag name. required: true schema: type: string - name: offset in: query description: 'Offsets the returned results to begin at particular record count. <p>For example, setting this to 10 causes the query to skip the first ten records in the data set.</p>' schema: type: number default: 0 - name: limit in: query description: 'Specifies the upper limit of the number of results to return. This filter has an upper limit of 100.<p>For example, setting this to 10 limits the query to returning a maximum of ten records.</p>If no limit is set, the query will return a maximum of 25 records.</p>' schema: type: number maximum: 100 default: 25 responses: '200': content: application/json: schema: type: object properties: content: type: array items: $ref: '#/components/schemas/Subscriber' description: Success - returns a list of the subscribers associated with the specified tag. '400': content: application/json: schema: type: object properties: error: type: object properties: message: type: string code: type: string description: Error - invalid request. summary: Returns a list of the subscribers associated with the specified tag. tags: - Tags description: <p>You must provide the <em>tagName</em> as a parameter in this request.</p><p><br>To use this endpoint, your user account must have the <strong>View Subscriber</strong> permission enabled. '/subscribers/{physicalId}': post: operationId: TagListController.addTagToSubscriber parameters: - in: path name: physicalId description: The unique subscriber identifier. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/Tag' description: Tag required: false responses: '204': content: application/json: {} description: Success - the tag has been added to the specified subscriber. '400': content: application/json: schema: type: object properties: error: type: object properties: message: type: string code: type: string description: Error - invalid request. '404': content: application/json: schema: type: object properties: error: type: object properties: message: type: string code: type: string description: Error - resource not found. summary: Adds a tag to a subscriber. tags: - Tags description: <p>The following requirements apply to this endpoint&#58;</p><ul><li>You must provide the subscriber's <em>physicalId</em> as a parameter in this request. This value varies depending on the subscriber type&#58;<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>You must provide the tag name you want to assign in the <em>tagName</em> field of the request body.</li><li>To use this endpoint, your user account must have the <strong>View Subscriber</strong> and <strong>Update the Details of a Subscriber</strong> permissions enabled. '/{tagName}/subscribers/{physicalId}': delete: operationId: TagListController.removeTagFromSubscriber parameters: - in: path name: tagName description: The tag name. required: true schema: type: string - in: path name: physicalId description: The unique subscriber identifier. required: true schema: type: string responses: '204': content: application/json: {} description: Success - the specified tag has been deleted. '400': content: application/json: schema: type: object properties: error: type: object properties: message: type: string code: type: string description: Error - invalid request. '404': content: application/json: schema: type: object properties: error: type: object properties: message: type: string code: type: string description: Error - resource not found. summary: Removes a tag from a subscriber. tags: - Tags description: <p>You must provide the <em>tagName</em> and the subscriber's <em>physicalId</em> as parameters in this request. This value varies depending on the subscriber type&#58;</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>View Subscriber</strong> and the <strong>Update the Details of a Subscriber</strong> permissions enabled.</p> servers: - url: 'https://api.iot-x.com'