# 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](thingspace.verizon.com/documentation/api-documentation.html/#/http/guided-walkthroughs/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](/docs/specialized-apis/thingspace-connection-planner/retrieve-windows-for-connection-planner/setconnectionplanner) ## 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: <br> **All** - All 24 windows for each day <br> **Best** - Top 3 for each day <br> **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: ```json { "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: ```json { "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: ```json { "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](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/guides/working-with-verizon-wireless/about-callback-services). Example callback responses: ```json { "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. <br> **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`. |