Standard APIsConnectivity ManagementAPI EndpointsConnectivity CallbacksRegister Callback
API Reference
Register a Callback Listener URL
POST /callbacks/{accountName}
Registers a URL at which an account receives asynchronous responses and other messages from a ThingSpace Platform callback service. The messages are REST messages. Users are responsible for creating and running a listening process on a server at that URL to receive and parse the messages.
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.
| 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. |
Uses and Requirements
All Verizon callbacks originate from one of these IP addresses:
- 3.87.163.45
- 3.91.119.203
- 54.197.62.209
- 35.165.205.14
- 54.200.43.232
- 34.216.81.234
- 137.117.33.109
- 168.62.173.153
When registering a callback, Verizon only allows the following ports:
- 80
- 443
- 9001-9006
- 50551-50559
- 28200-28220
HTTP Request
POST https://thingspace.verizon.com/api/m2m/v1/callbacks/{accountname}
Request Parameters
The account name must be included in the path.
| Parameter Name | Data Type | Description |
|---|---|---|
| accountName (required) | string | The name of the billing account to receive callback messages. An account name is usually numeric, and must include any leading zeros. |
Note: Use “TestAccount-2” when trying this request with the simulator.
Request Body
The body specifies the callback service being subscribed to and the URL where the listening service is running.
| Parameter Name | Data Type | Description |
|---|---|---|
| name (required) | string | The name of the callback service to subscribe to. Set this to one of the following values: Fota - This callback service delivers messages for Software Management (Firmware-Over-The-Air or FOTA). AlertService - Callback messages sent when trigger conditions are met. CarrierService - Asynchronous responses for all requests that change a device’s state and metadata, including: activate, suspend, restore, and deactivate. Note: the Assign and Unassign SIM Secure APIs will respond on this callback service. DevicePRLInformation - Asynchronous responses containing current device PRL values, in response to POST /devices/actions/prl/list requests.DeviceProfileService - Asynchronous responses for all requests that change a device’s profile status, including download, enable, disable, and delete. DeviceService - Asynchronous responses to POST /devices/availability/actions/list and POST /devices/actions/upload requests.DeviceSuspensionStatus - Asynchronous responses containing information about suspended devices in response to POST /devices/suspension/status requests.DeviceUsage - Asynchronous responses about device usage in response to POST /devices/usage/actions/list/aggregate requests.DiagnosticsService - Asynchronous responses for all requests that allow registering, status check for Service Capabilities Exposure Function (SCEF) devices for notifications when there is a change in device’s state (awake/sleep). EnhancedConnectivityService - This callback service provides two types of messages: The contents of SMS messages sent from your devices to 750075007500 or to 900060005010. Notification of when messages sent through POST /sms requests are sent by the network to devices.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 or Change MDN. IntelligenceService - Receive callback notifications from the ThingSpace Intelligence service such as real-time network conditions, static coverage, FWA coverage, site proximity and device experience score. NiddService - Asynchronous responses (second callback) for all requests that change a device’s state and metadata, including: activate, suspend, restore, deactivate, changedeviceserviceplan and NIDD Configuration success/failure (for NB-IoT devices only). Asynchronous responses for all requests that allow sending Non-IP Data Delivery (NIDD) data (mobile terminating or MT) to the device; and asynchronous callbacks for the NIDD data messages (mobile originating or MO) coming from the device. 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. ResumeTrackingNotification - Receive callback messages to notify about suspended devices that are automatically returned to active status. ThingSpace sends a callback message 7 days before a suspended device will auto-resume. SMSDeliveryConfirmation - Indicates that an SMS Message sent from a POST /sms request was received and acknowledged by the device.StateService - Aynchronous responses from PUT /devices/actions/gotostate requests. Note: A callback service cannot be registered through the REST API if the same callback service has been registered through the SOAP API.SubscriptionNotificationService - Notification that data will be partially or completely "Throttled". |
| url (required) | string | The address on the designated server where a listening service for callback messages has been enabled. Specify a URL that is reachable from the Verizon data centers. If the service is running on HTTPS, a one-way authentication certificate should be used with a white-listed IP address. In most cases, registration of each service type should be to a unique a URL address. When registering a callback, Verizon only allows the following ports: 80, 443, 9000-9006, 50551-50559 and 28200-28220. |
| username (optional) | string | The user name that the M2M Platform should return in the callback messages. If handling multiple accounts for the same callback address, use this credential to identify the account that a particular message is associated with. Pass an empty element if including a username for this account and service type is not required. Do not use a UWS/M2M username, or any other username that should remain private or secret. 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 a password for this account and service type is not required to be included. Do not use the UWS/M2M password or any other password that should remain private or secret. Note: Must be 40 characters or fewer. |
Request Body Example
{
"name": "CarrierService",
"url": "http://10.120.102.183:50559/CallbackListener/CarrierServiceMessages.asmx"
}Success Responses
Status 200 Example Success Response:
{
"accountName": "0000123456-00001",
"serviceName": "CarrierService"
}Success Parameters
| Parameter Name | Data Type | Description |
|---|---|---|
| accountName | string | The name of the billing account for which callback messages are sent. |
| serviceName | string | The name of the callback service, which identifies the type and format of messages that are sent to the registered URL. |
Failure Responses
All error messages are returned in this format:
{
"errorCode": "error code string",
"errorMessage": "error message string"
}Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions.