Specialized APIsThingSpace Connection PlannerRetrieve Windows for Connection Planner
API Reference
Get Device Window for Connection Planner
POST /v1/intelligence/device/connection-planner
Use this API endpoint to get device windows based on Radio Access Network Key Performance Indicators (RAN KPI).
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 how to obtain tokens .
| 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/v1/intelligence/device/connection-planner
Request Parameters
| Parameter | Data Type | Description |
|---|---|---|
| accountNumber (required) | string | The numeric name of the account, including leading zeros. |
| filter (optional) | string | When to schedule using RAN KPI data. Valid values are: All - All 24 windows for each day Best - Top 3 for each day Worst - Lowest 3 for each day |
| devices (required) | array | An array of deviceId values. |
| deviceIds (required) | array | An array of kind/id pairs used to identify devices on the account. |
| kind (required) | string | The kind of device identifier. The example uses International Mobile Equipment Identifier (IMEI). |
| id (required) | string | The value of the kind used. |
Request Body
Example Request:
{
"accountNumber": "0000123456-00001",
"filter": "All or Best or Worst",
"devices": [
{
"deviceIds": [
{
"kind": "imei",
"id": "15-digit IMEI value"
}
]
}
]
}Success Response
Status 200
A successful request returns the UUID of a requestId.
Example Response:
{
"requestId": "d24cc6e4-eeee-ffff-gggg-0ffbb091c076"
}Success Parameters
| Parameter | Data Type | Description |
|---|---|---|
| requestId | string | A unique identifier (UUID) of the request made. |
Failure Responses
Example Response:
{
"errorCode": "string",
"errorMessage": "string",
"errorUrl": "string"
}Callback Response
These endpoints send responses asynchronously. In order to read the results a callback is required. To learn more about callbacks, please visit About Callback Services. Example callback responses:
{
"username": "",
"password": "",
"requestId": "d24cc6e4-eeee-ffff-gggg-0ffbb091c076",
"connectionPlannerResponse": {
"deviceWindowsResponse" : [
{
"deviceIds": [
{
"id": "15-digit IMEI",
"kind": "IMEI"
}
],
"status": "SUCCESS",
"reason": "Device Data Found",
"deviceWindows": [
{
"day": "Monday",
"windows": [
{
"hour": "12",
"score": "54",
"confident": "poor"
}
]
},
{
"day": "Tuesday",
"windows": [
{
"hour": "10",
"score": "87",
"confident": "strong"
}
]
}
]
},
{
"deviceIds": [
{
"id": "15-digit IMEI",
"kind": "IMEI"
}
],
"status": "Failure",
"reason": "Device Data NOT Found"
}
]
},
"status": "SUCCESS",
"callbackCount": 1,
"maxCallbackThreshold": 4
}Callback Parameters
| Parameter | Data Type | Description |
|---|---|---|
| username | string | This will be the user name making the request, the user name that registered the callback listener or it will be blank. |
| password | string | The password of the user name. If the username value is blank, this will be blank as well. |
| requestId | string | A unique identifier (UUID) of the request made. |
| connectionPlannerResponse | object | The callback message returned. |
| deviceWindowsResponse | object | The payload of teh callback message containing the details of the response. |
| deviceIds | array | The id/kind pair responding. |
| id | string | The value of the type of identifier. |
| kind | string | The type of identifier. The example uses International Mobile Equipment Id (IMEI) |
| status | string | The status of the device response. This will be SUCCESS or failure |
| reason | string | A brief message to add more status detail. |
| deviceWindows | array | An array of objects detailing the device's availablity. |
| day | string | A day of the week (Sunday, Monday, Tuesday, etc) that there is RAN KPI data for. NOTE: if there is no data for that day of the week, the day will not be listed. |
| hour | string | A hour of the day, from 1 to 24. |
| score | string | A numeric score from 1 to 100 of the device's availability. |
| confident | string | A rating of the device's availablity based on the RAN KPI score. This will be strong for good availability or poor for less than ideal availability. |
| status | string | The status of the connectionPlannerResponse. |
| callbackCount | string | The number of attempts for connectionPlannerResponse. |
| maxCallbackThreshold | string | The maximum number of attempts allowed for connectionPlannerResponse. |