# 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. ## 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](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/guides/getting-started/introduction-to-the-connectivity-management-api). |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](/docs/specialized-apis/automotive-oem/thingspace-quality-of-service/api-endpoints/thingspace-quality-of-service-api-actions/createathingspacequalityofserviceapisubscription) ## 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 ```json { "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** ```json { "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) ```json { "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: ```json { "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) ```json { "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: ```json { "errorCode": "error code string", "errorMessage": "error message string" } ```