Create the ThingSpace Quality of Service API 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.

Request Components

HTTP Request

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

Resource Path and Query Parameters

None.

Header Parameters

The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token, and must set the content-type to JSON.

Parameter Name Data Type Description
Authorization
required		 string HTTP Authorization bearer token.
VZ-M2M-Token
required		 string A valid session token returned by POST /session/login.
Content-Type
required		 string Must be application/json.

Request Body

Request body parameters. All parameters listed are required unless marked "optional".

Parameter Name Data Type Description
accountName string The name of a billing account. This value is numeric and must include any leading zeroes.
deviceInfo array An array of device information containing:
  • deviceId
  • flowInfo
  • deviceIPv6Addr
     deviceId object Contains the identifier value and type of identifier.
         id string The device identifier value.

         kind

 string

The type of the identifier. This will be one of the following:

  • IMEI
  • MDN
  • MSISDN
  • 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

 array An array of flowInfo elements.

         flowServer

 string

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  

 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   

 string

This will be either:

  • UPLINK
  • DOWNLINK
  • BIDIRECTION

         flowProtocol  

 string

This will be either:

  • UDP
  • TCP
  • IP

         qciOption

 string

The quality level to elevate to: only these options are supported:

  • Premium
  • Standard

Example Request

{
  "accountName": "0000123456-00001",
  "deviceInfo": [
    {
      "deviceId": {
        "id": "10-digit phone number",
        "kind": "MDN"
      },
      "deviceIPv6Addr": "IPv6 address",
      "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-0a9a-4367-93ab-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-0a9a-4367-93ab-0af6c4ed256a",
  "deviceIds": [
    {
      "id": "10-digit phone number",
      "kind": "MDN"
    }
  ],
  "deviceResponse": {
    "qoS": [
      {
        "accountName": "0000123456-00001",
        "qosSubscriptionId": "QoS subscription ID",
        "reportedTime": "2023-02-17T18:56:52.795",
        "qosEvent": "QoSChangeReqAck",
        "status": "SUCCESS"
      }
    ]
  },
  "callbackCount": 1,
  "maxCallbackThreshold": 4

Or, if the request fails:

{
  "requestId": "be36accb-0a9a-4367-93ab-0af6c4ed256a",
  "deviceIds": [
    {
      "id": "10-digit phone number",
      "kind": "MDN"
    }
  ],
  "deviceResponse": {
    "qoS": [
      {
        "accountName": "0000123456-00001",
        "reportedTime": "2023-02-17T18:56:52.795",
        "qosEvent": "QoSChangeFailed",
        "status": "FAILED",
        "reason": "Device not found"
      }
    ]
  },
  "callbackCount": 1,
  "maxCallbackThreshold": 4
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
  • 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 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)
  • QoSChangeFailed
        status         string

This will show either:

  • SUCCESS
  • FAILED
        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 (deliver QoS Change Events)

{
  "username": "User Name",
  "password": "Password for the User Name",
  "requestId": "be36accb-0a9a-4367-93ab-0af6c4ed256a",
  "deviceResponse": {
    "qoS": [
      {
        "accountName": "0000123456-00001",
        "qosSubscriptionId": "QoS subscription ID",
        "reportedTime": "2023-02-17 18:57:48.627",
        "qosEvent": "QosChangeOn"
      }
    ]
  },
  "callbackCount": 1,
  "maxCallbackThreshold": 4
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
  • 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

Status 400

All error messages are returned in this format:

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