Standard APIsGlobal IoT OrchestrationAPI EndpointsRetrieve SMS Event History for a Device
API Reference
Retrieve SMS Event History for a Device
POST /devices/sms/history/actions/list
Returns the history of mobile-originated/mobile-terminated SMS messages for a single device that were sent or received via ThingSpace, within a specified time period.
Bulk operation: Not Supported. eSIM profiles: Both Verizon US and Global.
Uses and Requirements
The following limitations apply to retrieving the SMS event history:
A maximum of 500 SmsEvent records can be returned in a single request. To obtain more records, you can call the API multiple times, adjusting the earliest and latest parameters each time to start where the previous request ended. ThingSpace persists historical SMS messages for up to 3 months.
You must register for the DeviceService callback service to receive the callback response.
HTTP Request
POST https://thingspace.verizon.com/api/m2m/v1/devices/sms/history/actions/list
Resource Path and Query Parameters
None.
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 bearer token: Authorization: Bearer {token} |
| VZ-M2M-Token (required) | string | A valid session token: VZ-M2M-Token: {M2Mtoken} |
| Content-Type (required) | string | Must be application/json Content-Type: application/json |
| Parameter Name | Data Type | Description |
|---|---|---|
| deviceId (required) | deviceId object | An identifier for a single device. |
| kind, id | string | The type and value of the device identifier. ESN - decimal, 11 digits, ICCID - decimal, up to 20 digits, IMEI - decimal, up to 15 digits, MDN - decimal, 10 digits, MEID - hexadecimal, 14 hex digits, MSISDN - decimal, 11 digits (up to 15 digits for Global profiles) |
| earliest (optional) | string | Only include smsEvents that occurred after this date and time. |
| latest (optional) | string | Only include smsEvents that occurred before this date and time. |
Example Request Body
{
"deviceId":{
"id":"20-digit ICCID",
"kind":"iccid"
},
"earliest":"2019-05-01T00:00:01Z",
"latest":"2019-06-01T00:00:01Z"
}Success Response
Status 200
| Parameter Name | Data Type | Description |
|---|---|---|
| requestId | string | A unique string that associates the request with the results that are sent via a callback message. ThingSpace sends a separate callback message for each device that was in the request indicating whether the operation succeeded for that device. All of the callback messages have the same requestId. |
Example Success Response
{
"requestId":"d1f08526-5443-4054-9a29-4456490ea9f8"
}Callback Responses
The DeviceService sends a callback that contains an array of a maximum of 500 SmsEvents objects, that contain detailed information about each event.
| Parameter Name | Data Type | Description |
|---|---|---|
| username | string | The username defined when a URL was registered for the callback service, or an empty element if no username was defined. |
| password | string | The password defined when a URL was registered for the callback service, or an empty element if no password was defined. |
| requestId | string | A unique string that matches the requestId returned in the synchronous response to the original API request. A separate callback message is sent for each device that matched the request criteria, indicating whether the operation succeeded for that device. All of the callback messages have the same requestId. |
| deviceResponse | array | An array of objects. |
| smsEventHistoryResponse | array | Array of device identifiers and smsEvents objects. |
| deviceId | deviceId object | An identifier for a single device. |
| kind, id | string | The type and value of the device identifier: ESN - decimal, 11 digits, ICCID - decimal, up to 20 digits, IMEI - decimal, up to 15 digits, MDN - decimal, 10 digits (phone number), MEID - hexadecimal, 14 hex digits, MSISDN - decimal, 11 digits (1+ a phone number) |
| smsEvents | array | Array of smsEvent objects. |
| timeStamp | dateTime | The date and time that the message was sent or received. |
| smsType | string | Valid values include: MoSms - mobile originated, MtSms - mobile terminated |
| sentTo | string | The identifier to which the message was sent. |
| sentFrom | string | The identifier from where the message was sent. |
| message | string | The contents of the message. |
| encoding | string | The type of message encoding that was used to send the message. |
| deliveryStatus | string | The status of the message. Valid values include: Scheduled, Enroute, Delivered, Expired, Deleted, Undeliverable, Accepted, Unknown, Rejected, Skipped, Failed |
| callbackCount | integer | The number of times this callback message has been sent. |
| maxCallbackThreshold | integer | The maximum number of times this callback message is sent if it is not correctly acknowledged. |
Example Success Response
{
"username":"user's login (callback registration)",
"password":"user's password",
"requestId":"d1f08526-5443-4054-9a29-4456490ea9f8",
"deviceResponse":{
"smsEventHistoryResponse":{
"deviceId":{
"id":"1+ 10-digit phone number (up to 15 digits)",
"kind":"msisdn"
},
"smsEvents":[
{
"timestamp":"2020-02-28T17:52:17+0000",
"smsType":"MoSms",
"sentFrom":"msisdn",
"message":"?{h??",
"encoding":"US-ASCII",
"deliveryStatus":"Delivered"
},
{
"timestamp":"2020-03-03T17:42:53+0000",
"smsType":"MtSms",
"sentTo":"mdn",
"message":"labttqhfvn",
"encoding":"US-ASCII",
"deliveryStatus":"Scheduled"
},
{
"timestamp":"2020-03-09T14:58:08+0000",
"smsType":"MtSms",
"sentTo":"mdn",
"message":"lryuchiedd",
"encoding":"US-ASCII",
"deliveryStatus":"Delivered"
},
{
"timestamp":"2020-03-09T16:55:16+0000",
"smsType":"MtSms",
"sentTo":"mdn",
"message":"ygpcmzbrhn",
"encoding":"US-ASCII",
"deliveryStatus":"Scheduled"
},
{
"timestamp":"2020-03-10T16:26:24+0000",
"smsType":"MtSms",
"sentTo":"mdn",
"message":"iqiqhwjkmu",
"encoding":"US-ASCII",
"deliveryStatus":"Delivered"
},
{
"timestamp":"2020-03-10T16:28:55+0000",
"smsType":"MtSms",
"sentTo":"mdn",
"message":"evgnmtcuhj",
"encoding":"US-ASCII",
"deliveryStatus":"Delivered"
},
{
"timestamp":"2020-03-10T16:35:06+0000",
"smsType":"MtSms",
"sentTo":"mdn",
"message":"zdskemrpsg",
"encoding":"US-ASCII",
"deliveryStatus":"Delivered"
},
{
"timestamp":"2020-03-10T16:43:37+0000",
"smsType":"MtSms",
"sentTo":"mdn",
"message":"xxfkjlinyz",
"encoding":"US-ASCII",
"deliveryStatus":"Delivered"
},
{
"timestamp":"2020-03-10T17:00:36+0000",
"smsType":"MtSms",
"sentTo":"mdn",
"message":"nxlhfceybs",
"encoding":"US-ASCII",
"deliveryStatus":"Scheduled"
},
{
"timestamp":"2020-03-10T17:05:56+0000",
"smsType":"MtSms",
"sentTo":"mdn",
"message":"czbsvpekzb",
"encoding":"US-ASCII",
"deliveryStatus":"Scheduled"
},
{
"timestamp":"2020-03-12T13:26:38+0000",
"smsType":"MtSms",
"sentTo":"mdn",
"message":"gfdvidznli",
"encoding":"US-ASCII",
"deliveryStatus":"Delivered"
},
{
"timestamp":"2020-03-12T15:21:14+0000",
"smsType":"MtSms",
"sentTo":"mdn",
"message":"hrnbhdiygu",
"encoding":"US-ASCII",
"deliveryStatus":"Scheduled"
},
{
"timestamp":"2020-03-12T15:29:59+0000",
"smsType":"MtSms",
"sentTo":"mdn",
"message":"uxcikgvinz",
"encoding":"US-ASCII",
"deliveryStatus":"Delivered"
},
{
"timestamp":"2020-03-12T15:32:29+0000",
"smsType":"MtSms",
"sentTo":"mdn",
"message":"ksbsrcgkfb",
"encoding":"US-ASCII",
"deliveryStatus":"Delivered"
},
{
"timestamp":"2020-03-16T15:14:14+0000",
"smsType":"MtSms",
"sentTo":"mdn",
"message":"vxaghtkpeb",
"encoding":"US-ASCII",
"deliveryStatus":"Delivered"
},
{
"timestamp":"2020-03-16T15:41:14+0000",
"smsType":"MtSms",
"sentTo":"mdn",
"message":"zxnckzabzw",
"encoding":"US-ASCII",
"deliveryStatus":"Scheduled"
}
]
}
},
"callbackCount":1,
"maxCallbackThreshold":4
}Failure Responses
Status 400
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.