# 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](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/guides/working-with-verizon-wireless/about-callback-services) callback service to receive the callback response. ## HTTP Request [POST https://thingspace.verizon.com/api/m2m/v1/devices/sms/history/actions/list](/docs/standard-apis/global-iot-orchestration/api-endpoints/get-sms-messages/getsmsmessages) ## 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](https://thingspace.verizon.com/documentation/api-documentation.html#/http/session-management/guides/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 ```json { "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](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/guides/working-with-verizon-wireless/about-callback-services). 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 ```json { "requestId":"d1f08526-5443-4054-9a29-4456490ea9f8" } ``` ## Callback Responses The [DeviceService](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/guides/working-with-verizon-wireless/about-callback-services) 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 ```json { "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: ```json { "errorCode":"error code string", "errorMessage":"error message string" } ``` Error codes and messages are listed on the [Error Messages](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/guides/error-messages/overview) page, along with explanations and suggestions for corrective actions.