### Overview The ThingSpace Connectivity Management API uses callback services (also called webhooks) to send messages to your application. There are three broad categories of callback messages: - [Asynchronous API Responses](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/guides/working-with-verizon-wireless/overview) - Messages that contain the status or requested information from API requests that take time to process, such as activating devices. - [ThingSpace Notifications](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/guides/working-with-verizon-wireless/overview) - Messages sent to notify your application about a change that was made outside of the API interface, such as a manual change made through a Verizon portal, the expiration of a promotional code for a device, or an upcoming date when a suspended device will automatically be returned to active status. - [Device Messages](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/guides/working-with-verizon-wireless/overview) - SMS messages sent by devices through ThingSpace to your application. ### Subscribing to Callback Services To receive callback messages, you will need to create and deploy a web service that can validate and process REST messages that conform to the [Callback JSON schema](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/guides/working-with-verizon-wireless/overview). You then need to [register the URL of your web service](/docs/standard-apis/connectivity-management/api-endpoints/connectivity-callbacks/register-callback/registercallback) through the Connectivity Management API so that it knows where to send the callback messages. You can run multiple callback listening services on a single server, but your application will be more robust if you use a separate port for each type of callback message that you plan to receive. You only need to register once for each type of callback message that you want to receive. You do not need to subscribe to all messages – only to those that are applicable to your needs. **NOTE**: You will have to provide a way through your firewalls for the callback messages, such as by whitelisting the IP addresses used by the Verizon ThingSpace servers. The IP addresses are: - `137.117.33.109` - `168.62.173.153` - `3.87.163.45` - `3.91.119.203` - `54.197.62.209` - `35.165.205.14` - `54.200.43.232` - `34.216.81.234` **NOTE**: To test your callback listening services in a non-production environment, you must have an external URL for the computer or server that is hosting the web services. The ThingSpace Platform cannot send callback messages to a system that does not have a URL. ### Resource Path and Query Parameters The account name must be included in the path. | Parameter Name | Data Type | Description | |---------------------|---------|---------------------------------------| | **accountname** *(required)* | string | The name of the billing account for which you want to receive callback messages. An account name is numeric, and must include any leading zeros. <br> **Note**: Use “TestAccount-2” when trying this request with the simulator. | ### 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 Format The body specifies the callback service that you are subscribing to and the URL where the listening service is running. | Parameter Name | Data Type | Description | |------------------|---------|----------------------------------| | **name** *(required)* | string | The name of the callback service being subscribed to. Set this to one of the following values: <br> **AlertService** - Callback messages sent when trigger conditions are met. <br> **CarrierService** - Asynchronous responses for all requests that change a device’s state and metadata, including: `activate`, `suspend`, `restore`, and `deactivate`. <br> **Note**: the Assign and Unassign SIM Secure APIs will respond on this callback service. <br> **DevicePRLInformation** - Asynchronous responses containing current device PRL values, in response to `POST /devices/actions/prl/list` requests. <br> **DeviceProfileService** - Asynchronous responses for all requests that change a device’s profile status. Including: `download`, `enable`, `disable` and `delete`. <br> **DeviceService** - Asynchronous responses to `POST /devices/availability/actions/list` and `POST /devices/actions/upload` requests. <br> **DeviceSuspensionStatus** - Asynchronous responses containing information about suspended devices in response to `POST /devices/suspension/status` requests. <br> **DeviceUsage** - Asynchronous responses about device usage in response to `POST /devices/usage/actions/list/aggregate` requests. <br> **DiagnosticsService** - Asynchronous responses for all requests that allow registering, status check for SCEF devices for notifications when there is a change in device’s state (awake/sleep). <br> **EnhancedConnectivityService** - This callback service provides two types of messages: <br> - The contents of SMS messages sent from your devices to 750075007500 or to 900060005010. <br> - Notification of when messages sent through `POST /sms` requests are sent by the network to devices. <br> **ExternalProvisioningChanges** - Receive callback messages when provisioning changes are made outside of the ThingSpace APIs, such as when a user performs one of the following provisioning actions from an interactive Verizon system: `Activate`, `Deactivate`, `Suspend`, `Resume`, `Change ESN`, `Change MEID`, `Change MDN`. <br> **IntelligenceService** - Receive callback notifications from the Intelligence service such as real-time network conditions, static coverage, FWA coverage, site proximity and device experience score. <br> **NiddService** - Asynchronous responses (second callback) for all requests that change a device’s state and metadata, including: `activate`, `suspend`, `restore`, `deactivate` and `changedeviceserviceplan`, for Nidd Configuration success/failure (for NB-IoT devices only). Asynchronous responses for all requests that allow sending NIDD data (MT) to the device and asynchronous callbacks for the NIDD data messages (MO) coming from the device. <br> **PromoChanges** - Receive unsolicited callbacks for changes to promotional codes. A `PromoChange` callback message is sent shortly after the end of a device’s billing cycle if a promotional package was removed during the billing cycle. <br> **ResumeTrackingNotification** - Receive callback messages to notify you about suspended devices that are automatically returned to active status. ThingSpace sends a callback message 7 days before a suspended device will auto-resume. <br> **SMSDeliveryConfirmation** - Indicates that an SMS Message sent from a `POST /sms` request was received and acknowledged by the device. <br> **StateService** - Asynchronous responses from `PUT /devices/actions/gotostate` requests. <br> **Note**: You cannot register a callback service through the REST API if the same callback service has been registered through the SOAP API. <br> **SubscriptionNotificationService** - Notification that data will be partially or completely "Throttled". | | **url** *(required)* | string | The address on your server where a listening service for callback messages has been enabled. Specify a URL that is reachable from the Verizon data centers. If your service is running on HTTPS, you should use a one-way authentication certificate with a white-listed IP address. In most cases, you should register each service type to a unique a URL address. When you register a callback, Verizon only allows the following ports: `80`, `443`, `9000-9006`, `50551-50559`, `28200-28220`. | | **username** *(optional)* | string | The user name that the M2M Platform should return in the callback messages. If you are handling multiple accounts and you want them to use the same callback address, you can use this credential to identify the account that a particular message is associated with. Pass an empty element if you don’t want to include a username for this account and service type. Do not use your UWS/M2M username, or any other username that you want to remain private or secret. <br> **Note**: Must be 40 characters or fewer. | | **password** *(optional)* | string | The password that the M2M Platform should return in the callback messages. Pass an empty element if you don’t want to include a password for this account and service type. Do not use your UWS/M2M password, or any other password that you want to remain private or secret. <br> **Note**: Must be 40 characters or fewer. | #### An example of a callback service being linked to a URL ```json { "name": "CarrierService", "url": "http://10.120.102.183:50559/CallbackListener/CarrierServiceMessages.asmx" } ``` ### Callback Security When you register to receive any type of callback messages, you can specify a username and/or password that you want ThingSpace to include in each message. It will include the username and password as plain text in the callback messages. ThingSpace will not interact with any sort of authentication system. It will include the username and password as plain text in the callback message, like this: ```json "password": "string", "username": "string" ``` To increase security when receiving callback messages from ThingSpace, you can implement these protocols: - Enable white-listing on your firewall or front-end server and add the ThingSpace IP addresses to the white list. This will allow your servers to reject requests from other IP addresses. - Install a one-way certificate and enable HTTPS. You must use a certificate from a third-party certificate service; a self-signed certificate will not work. ThingSpace will check the validity of the certificate at the start of every session. ### Callback Reliability Your callback listener web service must acknowledge receipt of a callback message by sending back a 2xx status code. Callback messages that are not acknowledged by your application will be resent by ThingSpace three more times at 5 minute intervals, for a total of 4 attempts to send the message. Failed (unacknowledged) callback messages are archived for 30 days. During the 30 day period, you can contact support with the Request ID of failed callbacks and ask for them to be resent. ### Receiving Asynchronous API Callbacks For API service requests that require significant processing time, such as provisioning service for a device or changing a service plan, the Connectivity Management API replies first with a synchronous response that simply acknowledges the request and allows your application to continue processing. Later, the API sends an asynchronous callback message, reporting the results of the request.  The synchronous response contains a unique Request ID. The callback message will contain the same Request ID so that you can associate the callback with the original API request. Below are the callback services that return asynchronous API responses: | Callback Service | Description | | --------------------------- | --------------------------------------- | | **CarrierService** | Asynchronous responses from all requests that change device states and metadata. For example: activate, suspend, restore, deactivate, move, change cost center and change service plan. | | **DevicePRLInformation** | Callback messages containing current device PRL values, in response to `POST /devices/prl/actions/list` requests. | | **DeviceProfileService** | Asynchronous responses for all requests that change a device’s profile status, including download, enable, disable, and delete. | | **DevicePromoUsage** | reserved for future use | | **DeviceService** | Callback messages about devices from `POST /devices/actions/upload` requests. | | **DeviceSuspensionStatus** | Callback messages containing information about the suspended status of devices, in response to `POST /devices/suspension/status` requests. | | **DeviceUsage** | Callback messages about device usage from `POST /devices/usage/actions/list/aggregate` requests. | | **DiagnosticsService** | Asynchronous responses for all requests that allow registering, status check for SCEF devices for notifications when there is a change in device’s state (awake/sleep). | | **EnhancedConnectivityService** | Callback messages from `POST /sms` to let you know when your messages have been sent to devices. (This callback service is also used to receive SMS messages sent from devices to your application.) | | **PmecService** | reserved for future use | | **SMSDeliveryConfirmation** | Indicates that an SMS Message sent through `POST /sms` was received and acknowledged by the device. | | **StateService** | Asynchronous responses from `PUT /devices/actions/gotostate` requests. | | VIPCallbackSerivce | reserved for future use | ### Receiving ThingSpace Notification Callbacks You can subscribe to these services to receive notifications about device changes that were not initiated through ThingSpace APIs. You can use these messages to keep any information that your application stores in sync with the actual status. The table below lists the callback services that provide notifications about external changes: | Callback Service | Description | | ------------------------------- | ------------------------ | | **AlertService** | Callback messages sent when trigger conditions are met. | | **ExternalProvisioningChanges** | Non-API-initiated provisioning transactions. For example, ThingSpace would send a message if a Verizon business portal user made any of these changes: `Activate`, `Deactivate`, `Suspend`, `Restore`, `Change ESN`, `Change MEID`, `Change MDN` | | **ResumeTrackingNotification** | Messages to notify about suspended devices that will automatically return to active status. ThingSpace will send a callback message 7 days before a suspended device will auto-resume. | | **SubscriptionNotificationService** | Notification to alert the user that data services will be "Throttled" either partially or completely. | ### Receiving Device Message Callbacks Sophisticated IoT applications often need to process information sent from devices so that appropriate actions can be taken. You can use the callback service listed below to receive messages that are originated by devices. | Callback Service | Description | | --------------------------- | --------------------------------| | **EnhancedConnectivityService** | This callback service provides two types of messages: <br> - The contents of SMS messages sent by your devices to `750075007500` or to `900060005010` and <br> - Notification of when `POST /sms` messages are sent to devices. | ### Callback Best Practices To see more information about best practices for callbacks, please visit [Callback Best Practices](/docs/standard-apis/connectivity-management/guides/callbacks/about-callback-services). ### Callback Examples #### CarrierService ##### Activate ```json { "username": "", "password": "", "requestId": "2c90bd28-ece4-42ef-9f02-7e3bd4fbff33", "deviceIds": [ { "id": "352452060026934", "kind": "IMEI" } ], "deviceResponse": { "activateResponse": { "deviceIds": [ { "id": "10-digit phone number", "kind": "mdn" }, { "id": "15-digit IMSI", "kind": "imsi" }, { "id": "20-digit ICCID", "kind": "iccId" }, { "id": "1+ 10-digit phone number", "kind": "msisdn" }, { "id": "10-digit MIN", "kind": "min" } ], "ipAddress": "10.224.48.88", "state": "Active", "servicePlan": "84638", "featureCodes": [], "deviceCredential": { "username": "{10-digit MDN}@vzw3g.com", "password": "{password}" } } }, "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` ##### Suspend ```json { "username": "", "password": "", "requestId": "5b645698-162f-4897-889d-c61275ab1afc", "deviceIds": [ { "id": "14-character MEID", "kind": "MEID" }, { "id": "10-digit phone number", "kind": "MDN" } ], "deviceResponse": { "suspendResponse": { "expectedResumeDate": "05/25/2018", "maxSuspendDaysAllowed": 180, "numDaysSuspendedLast12Months": 93, "numDaysSuspendAllowedCurrent12Months": 87 } }, "comment": "Device Suspended - Applicable Charges Will Continue", "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` ##### Restore ```json { "username": "", "password": "", "requestId": "52288eff-c306-44f0-9e73-0c3143ea9e7b", "deviceIds": [ { "id": "15-digit IMEI", "kind": "imei" }, { "id": "20-digit ICCID", "kind": "iccid" } ], "deviceResponse": { "restoreResponse": { "restored": true } }, "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` ##### Deactivate ```json { "username": "", "password": "", "requestId": "eb3406b0-15fc-4473-8e84-b92cfb67f22d", "deviceIds": [ { "id": "15-digit IMEI", "kind": "imei" }, { "id": "20-digit ICCID", "kind": "iccid" } ], "deviceResponse": { "deactivateResponse": { "deactivated": true } }, "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` ##### Change Device Contact Info ```json { "username": "", "password": "", "requestId": "24da9f9a-d110-4a54-86b4-93fb76aab83c", "deviceIds": [ { "kind": "ESN", "id": "11-digit ESN" }, { "kind": "ESN", "id": "11-digit ESN" } ], "deviceResponse": { "contactInfoResponse": { "accountName": "0000123456-00001" } }, "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` ##### Change Device Cost Center ```json { "username": "", "password": "", "requestId": "3e4a42ca-6dfa-460e-9803-f677b069a694", "deviceIds": [ { "id": "14-character MEID", "kind": "Meid" } ], "deviceResponse": { "deviceCostCenterResponse": { "costCenterCode": "VZW103", "primaryPlaceOfUse": { "address": { "addressLine1": "9808", "addressLine2": "Scranton Road", "city": "San Diego", "state": "CA", "country": "US", "zip": "92121", "zip4": "01234", "phone": "{10-digit phone number}", "phoneType": "M", "emailAddress": "zaffod@theinternet.com" }, "customerName": { "firstName": "Zaffod", "lastName": "Beeblebrox", "middleName": "Q", "title": "President", "suffix": "I" } } } }, "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` ##### Change Device Custom Fields ```json { "username": "", "password": "", "requestId": "c8de7c1d-59b9-4cf3-b969-db76cb2ce509", "deviceIds": [ { "id": "10-digit phone number", "kind": "mdn" } ], "deviceResponse": {}, "comment": "Success", "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` ##### Change Device Identifier ```json { "username": "", "password": "", "requestId": "a28892ea-6503-4aa7-bfa2-4cd45d42f61b", "deviceIds": [ { "id": "11-digit ESN", "kind": "ESN" } ], "deviceResponse": { "changeIdentifierResponse": { "deviceIds": [ { "id": "14-character MEID", "kind": "Meid" } ], "servicePlan": "M2M_4G" } }, "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` ##### Change Device Service Plan ```json { "username": "", "password": "", "requestId": "c8de7c1d-59b9-4cf3-b969-db76cb2ce509", "deviceIds": [ { "id": "10-digit phone number", "kind": "mdn" } ], "deviceResponse": { "deviceChangeServicePlanResponse": { "servicePlan": "M2M5GB", "effectiveDate": "12/25/2017 12:00:00 AM" } }, "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` ##### Move Device ```json { "username": "", "password": "", "requestId": "ec682a8b-e288-4806-934d-24e7a59ed889", "deviceIds": [ { "id": "11-digit ESN", "kind": "Esn" } ], "deviceResponse": { "usageResponse": [], "moveDeviceResponse": { "deviceIds": [ { "id": "11-digit ESN", "kind": "Esn" } ], "accountName": "0000123456-00001" } }, "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` #### DeviceService ##### Check Device Availability ```json { "username": "", "password": "", "requestId": "595f5c44-c31c-4552-8670-020a1545a84d", "deviceResponse": { "checkDeviceAvailabilityResponse": { "deviceInfo": [ { "device": [ { "id": "15-digit IMEI", "kind": "IMEI", "deviceSku": "VZW090000450004", "productType": "Modem", "deviceFound": true }, { "id": "20-digit ICCID", "kind": "ICCID", "deviceFound": true } ], "associatedWithMTN": true, "deviceSimPair": true } ], "accountName": "0000123456-00001" } }, "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` ##### DevicePRLInformation ```json { "username": "", "password": "", "requestId": "5b645698-162f-4897-889d-c61275ab1afc", "deviceIds": [ { "id": "14-character MEID", "kind": "MEID" }, { "id": "10-digit phone number", "kind": "MDN" } ], "deviceResponse": { "prlInformationResponse": { "prlVersion": "523310" } }, "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` ##### DeviceSuspensionStatus ```json { "username": "", "password": "", "requestId": "904dcdc6-a590-45e4-ac76-403306f6d883", "deviceResponse": { "deviceSuspensionStatusResponse": [ { "deviceIds": [ { "id": "15-digit IMEI", "kind": "imei" } ], "state": "suspend", "suspendDate": "2017-12-21 00:00:00", "expectedResumeDate": "2018-03-20", "daysRemainingAutoResume": "90", "maxSuspendDaysAllowed": "180", "numDaysSuspendedLast12Months": "0", "numDaysSuspendAllowedCurrent12Months": "91", "timesSuspendedLast12Months": "1" }, { "deviceIds": [ { "id": "20-digit ICCID", "kind": "iccid" } ], "state": "suspend", "suspendDate": "2017-12-21 00:00:00", "expectedResumeDate": "2018-03-20", "daysRemainingAutoResume": "90", "maxSuspendDaysAllowed": "180", "numDaysSuspendedLast12Months": "0", "numDaysSuspendAllowedCurrent12Months": "91", "timesSuspendedLast12Months": "1" } ] }, "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` ##### DeviceUsage ```json { "username": "", "password": "", "requestId": "24da9f9a-d110-4a54-86b4-93fb76aab83c", "deviceResponse": { "prlInformationResponse": {}, "smsDeliveryResponse": {}, "usageResponse": [ {}, { "deviceIds": [ { "id": "10-digit phone number", "kind": "Mdn" }, { "id": "14-character MEID", "kind": "Meid" } ], "dataUsage": "0", "smsUsage": "0", "startDate": "2014-02-02T00:00:00.0000000", "endDate": "2014-02-25T00:00:00.0000000" } ] }, "comment": "Request Completed Processing", "summary": { "devicesRequested": 0 }, "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` ##### UploadDevices ```json { "username": "", "password": "", "requestId": "595f5c44-c31c-4552-8670-020a1545a84d", "deviceResponse": { "deviceUploadResponse": { "devices": [ { "deviceIds": [ { "id": "20-digit ICCID", "kind": "Iccid" }, { "id": "15-digit IMEI", "kind": "Imei" } ], "lineStatus": "Device upload successful." }, { "deviceIds": [ { "id": "20-digit ICCID", "kind": "Iccid" }, { "id": "15-digit IMEI", "kind": "Imei" } ], "lineStatus": "Device upload successful" }, { "deviceIds": [ { "id": "20-digit ICCID", "kind": "Iccid" }, { "id": "15-digit IMEI", "kind": "Imei" } ], "lineStatus": "SIM Id is invalid" } ], "accountName": "0000123456-00001", "deviceSku": "VZW123456", "totalLineCount": "3", "failedLineCount": "1", "successLineCount": "2" } }, "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` #### EnhancedConnectivityService ##### SendSMSMessage ###### Per-Device Message ```json { "username": "", "password": "", "requestId": "2c90bd28-ece4-42ef-9f02-7e3bd4fbff33", "deviceIds": [ { "id": "20-digit ICCID", "kind": "Iccid" }, { "id": "10-digit phone number", "kind": "Mdn" }, { "id": "15-digit IMEI", "kind": "Imei" }, { "id": "1+ 10-digit phone number", "kind": "Msisdn" } ], "comment": "SendSmsMessage,Performed action on device.", "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` ###### Request Complete Message ```json { "username":"", "password":"", "requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33", "comment":"SendSmsMessage,Request Completed Processing." "summary": { "devicesRequested": 2 }, "callbackCount": 1, "maxCallbackThreshold": 4 } ``` ##### SmsDeliveryConfirmation Callback Messages ###### Success after device acknowledgement ```json { "username": "", "password": "", "requestId": "2c90bd28-ece4-42ef-9f02-7e3bd4fbff33", "deviceIds": [ { "id": "10-digit phone numer", "kind": "Mdn" } ], "deviceResponse": { "smsDeliveryResponse": { "confirmation": "Delivered" } } } ``` #### SMS Message from Device ```json { { "messages": [ { "deviceIds": [ { "id": "11-digit ESN", "kind": "esn" } ], "message": "testmessage1", "timestamp": "2016-01-01T12:29:49-08:00" }, { "deviceIds": [ { "id": "11-digit ESN", "kind": "esn" } ], "message": "testmessage2", "timestamp": "2016-01-01T12:31:02-08:00" } ] }, "hasMoreData": false } ``` #### ExternalProvisioningChanges This is an example of an ExternalProvisioningChanges callback message sent when a system other than the Wireless Network Services API or ThingSpace Connectivity Management API activates a line of service for a device. ```json { "username": "", "password": "", "requestId": "24da9f9a-d110-4a54-86b4-93fb76aab83c", "deviceIds": [ { "id": "15-digit IMEI", "kind": "Imei" } ], "deviceResponse": { "externalProvisioningChangeResponse": { "change": "Activate", "deviceInfo": { "accountName": "0000123456-00001", "billingCycleEndDate": "2017-11-30T00:00:00.0000000Z", "carrierInformations": [ { "carrierName": "Verizon Wireless", "servicePlan": "M2M5GB", "state": "active" } ], "connected": true, "createdAt": "2017-11-27T14:03:21.0000000Z", "deviceIds": [ { "id": "10-digit phone number", "kind": "mdn" }, { "id": "15-digit IMSI", "kind": "imsi" }, { "id": "15-digit IMEI", "kind": "imei" }, { "id": "20-digit ICCID", "kind": "iccId" }, { "id": "1+ 10-digit phone number", "kind": "msisdn" }, { "id": "10-digit MIN", "kind": "min" } ], "groupNames": ["Default: West coast trucks"], "ipAddress": "1.1.29.169", "lastActivationBy": "User Verizon", "lastActivationDate": "2017-11-27T14:13:37.0000000Z" } } }, "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` #### Device Detection ```json { "username": null, "password": null, "requestId": "c19051aa-eeee-ffff-gggg-6a95731029e5", "deviceIds": [ { "id": "15-digit IMEI", "kind": "imei", "deviceFound": false } ], "status": null, "callbackCount": 1, "maxCallbackThreshold": 4, "deviceResponse": { "externalProvisioningChangeResponse": { "change": "Device Detection", "deviceInfo": { "deviceIds": [ { "id": "5001234567", "kind": "mdn", "deviceFound": false }, { "id": "15-digit IMSI", "kind": "imsi", "deviceFound": false }, { "id": "15-digit IMEI", "kind": "imei", "deviceFound": false }, { "id": "20-digit ICCID", "kind": "iccId", "deviceFound": false }, { "id": "15001234567", "kind": "msisdn", "deviceFound": false }, { "id": "5001234567", "kind": "min", "deviceFound": false } ], "associatedWithMTN": false, "deviceSimPair": false, "accountName": "0000123456-00001", "billingCycleEndDate": "2024-10-01T00:00:00.0000000Z", "carrierInformations": [ { "carrierName": "Verizon Wireless", "servicePlan": "Plan Name", "state": "active" } ], "connected": false, "createdAt": "2024-09-25T17:45:21.0000000Z", "groupNames": [ "Default: 0000123456-00001" ], "ipAddress": "1.2.3.4", "lastActivationBy": "user", "lastActivationDate": "2024-09-25T17:45:48.0000000Z" } } } } ``` #### DevicePrimaryPlaceOfuseUpdate ```json { "requestId": "99e78bab-eeee-ffff-gggg-e4aecb85a108", "deviceIds": [ { "id": "5775551234", "kind": "MDN" } ], "deviceResponse": { "externalProvisioningChangeResponse": { "change": "DevicePrimaryPlaceOfuseUpdate", "deviceInfo": { "preIMEI": "900000000000007", "accountName": "0000123456-00001", "billingCycleEndDate": "2024-12-10T00:00:00.0000000Z", "carrierInformations": [ { "carrierName": "Verizon Wireless", "servicePlan": "M2M150MB", "state": "active" } ], "connected": false, "createdAt": "2024-11-12T21:11:46.0000000Z", "deviceIds": [ { "id": "5775551234", "kind": "mdn" }, { "id": "15-digit IMSI", "kind": "imsi" }, { "id": "15-digit IMEI", "kind": "imei" }, { "id": "20-digit ICCID", "kind": "iccId" }, { "id": "15775551234", "kind": "msisdn" }, { "id": "5775551234", "kind": "min" } ], "groupNames": [ "Default: 0000123456-00001" ], "ipAddress": "0.0.0.0", "lastActivationBy": "User Name", "lastActivationDate": "2024-11-12T21:20:46.0000000Z", "lastConnectionDate": "2024-11-16T00:24:22.0000000Z", "primaryPlaceOfUse": { "address": { "addressLine1": "1922 STREET NAME", "city": "ALLEN", "zip": "75013" }, "customerName": { "firstName": "FIRST", "lastName": "LAST" } } } } }, "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` #### GoToState ```json { "username": "", "password": "", "requestId": "595f5c44-c31c-4552-8670-020a1545a84d", "deviceIds": [ { "id": "20-digit ICCID", "kind": "Iccid" }, { "id": "15-digit IMEI", "kind": "Imei" } ], "deviceResponse": { "usageResponse": [], "goToStateResponse": { "deviceIds": [ { "id": "20-digit ICCID", "kind": "Iccid" }, { "id": "15-digit IMEI", "kind": "Imei" } ], "serviceName": "WAM", "stateName": "WAM Activate" } }, "status": "Success", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` #### PromoChanges ThingSpace sends messages when there are changes to the promotional codes for a line of service, such as when a promotional code expires. ThingSpace sends a PromoChange callback message shortly after the end of a device’s billing cycle if a promotional package was removed during the billing cycle. **NOTE**: You can use the [POST /devices/actions/list](/docs/standard-apis/connectivity-management/api-endpoints/device-management/list-devices-information/listdevicesinformation) to see all active promotional codes for a device and the scheduled end date for each one. ```json { "username": "", "password": "", "requestId": "90682b54-66ad-4c1f-a0f2-f3bb77ea298b", "deviceIds": [ { "id": "15-digit IMEI", "kind": "IMEI" } ], "deviceResponse": { "promoChangeResponse": { "change": "PromoCode Dropped.", "changeDate": "12/15/2017 12:00:00 AM" } } } ``` #### ResumeTrackingNotification ```json { "username": "", "password": "", "requestId": "24da9f9a-d110-4a54-86b4-93fb76aab83c", "deviceResponse": { "deviceIds": [ { "id": "10-digit phone number", "kind": "Mdn" }, { "id": "14-character MEID", "kind": "Meid" } ], "comment": "Device will be auto resumed on - 12/15/2018 12:00:00 AM" } } ``` #### SubscriptionNotificationService ```json { "requestId": "535a2d96-33d9-4b36-8246-31058ffd0ff1", "deviceIds": [ { "id": "10-digit phone number", "kind": "Mdn" }, { "id": "15-digit IMEI", "kind": "Imei" }, { "id": "20-digit ICCID", "kind": "Iccid" }, { "id": "32-digit EID", "kind": "Eid" }, { "id": "1+ 10-digit phone number", "kind": "Msisdn" } ], "deviceResponse": { "subscriptionNotification": [ { "accountName": "0000123456-00001", "timeStamp": "2019-10-28 05:41:39", "throttlingPercentage": "100%", "usage": "12348646456.000000", "usageUnits": "BYT" } ] }, "callbackCount": 1, "maxCallbackThreshold": 4 } ```