Create a QoS Subscription

`POST /api/m2m/v1/device/actions/enhanceQoS`

Use this endpoint to start the ThingSpace Quality of Service API subscription to receive data and to elevate quality of service specified.

Header Parameters

The request header must set the content-type to JSON, contain a current ThingSpace authorization token and a current VZ-M2M session token. For more details on how to get these tokens, visit Getting Started.

Parameter Name	Data Type	Description
Authorization (required)	string	HTTP Authorization request header containing a valid Bearer token: `Authorization: Bearer {token}`
VZ-M2M-Token (required)	string	A valid session token returned by a Connectivity Management `POST /session/login` request.
Content-Type (required)	string	Must be `application/json`.

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/device/actions/enhanceQoS

Request Parameters

Parameter Name	Data Type	Description
accountName (required)	string	The name of a billing account. This value is numeric and must include any leading zeroes.
deviceInfo (required)	array	An array of device information containing the deviceId, flowInfo and deviceIPv6Addr.
deviceId (required)	object	Contains the identifier value and type of identifier.
id (required)	string	The device identifier value.
kind (required)	string	The type of the identifier. This will be one of the following: IMEI, MDN, MSISDN or ICCID. Note: the `kind` value has to be the same across the `deviceInfo` array, mixed `kind` is not currently supported.
deviceIPv6Addr (optional)	string	The IPv6 IP address of the device. Note: port should not be specified in this field.
flowInfo (required)	array	An array of `flowInfo` elements.
flowServer (required)	string	The customer Server's IP address and port. The port value is optional but if not specified the elevation will be applied to any port on the requested IP address. This field will support IPv4 or IPv6 but the format must be consistant for `flowServer` and `flowDevice`, meaning if IPv6 is chosen for one, it must be used for both. The same rule applies for IPv4. Note: The IPv6 address must be in brackets if a port is specified.
flowDevice (required)	string	The device's IP address and port. The port value is optional but if not specified the elevation will be applied to any port on the requested IP address. This field will support IPv4 or IPv6 but the format must be consistant for `flowServer` and `flowDevice`, meaning if IPv6 is chosen for one, it must be used for both. The same rule applies for IPv4. Note: The IPv6 address must be in brackets if a port is specified.
flowDirection (required)	string	This will be either: UPLINK - from the device, DOWNLINK - To the device or BIDIRECTION - measuring to and from the device.
flowProtocol (required)	string	This the data protocol used and will be either: UDP, TCP or IP.
qciOption (required)	string	The quality level to elevate to. Only these options are supported: Premium or Standard.

Request Body

Example Request

{
  "accountName": "0000123456-00001",
  "deviceInfo": [
    {
      "deviceId": {
        "id": "10-digit phone number",
        "kind": "MDN"
      },
      "deviceIPv6Addr": "IPv6 address", ### Empty if using IPv4
      "flowInfo": [
        {
          "flowServer": "[IPv6 address]:port", ### IPv4:port if using IPv4
          "flowDevice": "[IPv6 address]:port", ### IPv4:port if using IPv4
          "flowDirection": "UPLINK",
          "flowProtocol": "UDP",
          "qciOption": "Premium"
        }
      ]
    }
  ]

Success Responses

Status 201

{
"requestId": "be36accb-eeee-ffff-gggg-0af6c4ed256a"
}

Callback examples

ThingSpace Quality of Service API Callback body (the first callback to deliver the result of a ThingSpace Quality of Service API Request)

{
  "requestId": "be36accb-eeee-ffff-gggg-0af6c4ed256a",
  "deviceIds": [
    {
      "id": "10-digit phone number",
      "kind": "MDN"
    }
  ],
  "deviceResponse": {
    "qoS": [
      {
        "accountName": "0000123456-00001",
        "qosSubscriptionId": "QoS subscription ID",
        "reportedTime": "2024-08-29T18:56:52.795Z",
        "qosEvent": "QoSChangeReqAck",
        "status": "SUCCESS"
      }
    ]
  },
  "callbackCount": 1,
  "maxCallbackThreshold": 4

Or, if the request fails:

{
  "requestId": "be36accb-eeee-ffff-gggg-0af6c4ed256a",
  "deviceIds": [
    {
      "id": "10-digit phone number",
      "kind": "MDN"
    }
  ],
  "deviceResponse": {
    "qoS": [
      {
        "accountName": "0000123456-00001",
        "reportedTime": "2024-08-29T18:56:52.795Z",
        "qosEvent": "QoSChangeFailed",
        "status": "FAILED",
        "reason": "Device not found"
      }
    ]
  },
  "callbackCount": 1,
  "maxCallbackThreshold": 4

Callback parameters

Parameter Name	Data Type	Description
requestId	string	This is the same `requestId` in the response to the original request.
deviceIds	array	An array of the device ID values.
id	string	The device identifier value.
kind	string	The type of the identifier. This will be one of the following: IMEI, MDN, MSISDN or ICCID. Note: the kind value has to be the same across the `deviceInfo` array, mixed kind is not currently supported.
deviceResponse	object	The device response object.
qoS	array	The array containing the QoS status for this subscription and account.
accountName	string	The name of a billing account. This value is numeric and must include any leading zeroes.
qosSubscriptionId	string	The subscription id of the QoS request. This value can be used for a subsequent call to cancel the subscription (for example). This field should be present in every QoS callback notification unless the callback fails.
reportedTime	string ($datetime)	Identifies the absolute time at which the reachability report is received from the Service Capability Exposure Function (SCEF). The format is aligned with RFC3339.
qosEvent	string	This will show either: QoSChangeReqAck (request acknowledged) or QoSChangeFailed.
status	string	This will show either: SUCCESS or FAILED depending on the callback state.
reason	string	This line will have a reason or description of why the request failed. If the `status` is "SUCCESS", this line will not be output.
callbackCount	integer	The number of responses in the callback request.
maxCallbackThreshold	integer	The maximum number of callback responses allowed for this request.

QoS Event Callback body (delivers QoS Change Events)

{
  "username": "User Name",
  "password": "Password for the User Name",
  "requestId": "be36accb-eeee-ffff-gggg-0af6c4ed256a",
  "deviceResponse": {
    "qoS": [
      {
        "accountName": "0000123456-00001",
        "qosSubscriptionId": "QoS subscription ID value",
        "reportedTime": "2024-08-T18:57:48.627Z",
        "qosEvent": "QosChangeOn"
      }
    ]
  },
  "callbackCount": 1,
  "maxCallbackThreshold": 4

Event Callback Parameters

Parameter Name	Data Type	Description
username	string	The user name recieving the callback response.
password	string	The password of the user recieving the callback response.
requestId	string	This is the same `requestId` in the response to the original request.
deviceResponse	object	The device response object.
qoS	array	The array containing the QoS status for this subscription and account.
accountName	string	The name of a billing account. This value is numeric and must include any leading zeroes.
qosSubscriptionId	string	The subscription id of the QoS request.
reportedTime	string ($datetime)	Identifies the absolute time at which the reachability report is received from the Service Capability Exposure Function (SCEF). The format is aligned with RFC3339.
qosEvent	string	This will show either: QoSChangeOn (requested QoS elevation is functioning), QoSChangeFailed or QoSChangeTerminated (requested QoS elevation has been stopped).
callbackCount	integer	The number of responses in the callback request.
maxCallbackThreshold	integer	The maximum number of callback responses allowed for this request.

Failure Responses

All error messages are returned in this format:

    {
      "errorCode": "error code string",
      "errorMessage": "error message string"
    }

POST /api/m2m/v1/device/actions/enhanceQoSCopy Anchor Link

Header ParametersCopy Anchor Link

HTTP RequestCopy Anchor Link

Request ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Success ResponsesCopy Anchor Link

Callback examplesCopy Anchor Link

Callback parametersCopy Anchor Link

QoS Event Callback body (delivers QoS Change Events)Copy Anchor Link

Event Callback ParametersCopy Anchor Link

Failure ResponsesCopy Anchor Link

On this page