API Docs

Retrieve SMS Event History for a Device

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.

`POST /devices/sms/history/actions/list`

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.

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`.

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/devices/sms/history/actions/list

Request Parameters

The request body identifies the device identifier and specifies a time frame for which SMS events should be returned.

Parameter	Data Type	Description
deviceId (optional)	object	An identifier for a single device.
kind (required for `deviceId`)	string	The type of device identifier. This can be: 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
id (required for `deviceId`)	string	The value of the device identifier.
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.

Request Body

Example Request:

{   "deviceId":{      "id":"20-digit ICCID",      "kind":"iccid"   },   "earliest":"2019-05-01T00:00:01Z",   "latest":"2019-06-01T00:00:01Z"}

Success Response

Status 200 A successful response returns a requestId. Example Response:

{   "requestId":"595f5c44-eeee-ffff-gggg-020a1545a84d"}

Success Parameters

Parameter	Data Type	Description
requestId	string	A unique string (UUID) 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.

Failure Responses

Example Response:

{  "errorCode": "The 3-digit HTML error code",  "errorMessage": "string"}

Callback Response

DeviceService sends a callback that contains an array of a maximum of 500 SmsEvents objects, that contain detailed information about each event. Example callback response:

{   "username":"string",   "password":"string",   "requestId":"595f5c44-eeee-ffff-gggg-020a1545a84d",   "deviceResponse":{      "smsEventHistoryResponse":{         "deviceId":{            "id":"1+ 10-digit phone number",            "kind":"msisdn"         },         "smsEvents":[            {               "timestamp":"2020-02-28T17:52:17+0000",               "smsType":"MoSms",               "sentFrom":"10-digit phone number",               "message":"?{h??",               "encoding":"US-ASCII",               "deliveryStatus":"Delivered"            },            {               "timestamp":"2020-03-03T17:42:53+0000",               "smsType":"MtSms",               "sentTo":"10-digit phone number",               "message":"labttqhfvn",               "encoding":"US-ASCII",               "deliveryStatus":"Scheduled"            },            {               "timestamp":"2020-03-09T14:58:08+0000",               "smsType":"MtSms",               "sentTo":"10-digit phone number",               "message":"lryuchiedd",               "encoding":"US-ASCII",               "deliveryStatus":"Delivered"            },            {               "timestamp":"2020-03-09T16:55:16+0000",               "smsType":"MtSms",               "sentTo":"10-digit phone number",               "message":"ygpcmzbrhn",               "encoding":"US-ASCII",               "deliveryStatus":"Scheduled"            },            {               "timestamp":"2020-03-10T16:26:24+0000",               "smsType":"MtSms",               "sentTo":"10-digit phone number",               "message":"iqiqhwjkmu",               "encoding":"US-ASCII",               "deliveryStatus":"Delivered"            },            {               "timestamp":"2020-03-10T16:28:55+0000",               "smsType":"MtSms",               "sentTo":"10-digit phone number",               "message":"evgnmtcuhj",               "encoding":"US-ASCII",               "deliveryStatus":"Delivered"            },            {               "timestamp":"2020-03-10T16:35:06+0000",               "smsType":"MtSms",               "sentTo":"10-digit phone number",               "message":"zdskemrpsg",               "encoding":"US-ASCII",               "deliveryStatus":"Delivered"            },            {               "timestamp":"2020-03-10T16:43:37+0000",               "smsType":"MtSms",               "sentTo":"10-digit phone number",               "message":"xxfkjlinyz",               "encoding":"US-ASCII",               "deliveryStatus":"Delivered"            },            {               "timestamp":"2020-03-10T17:00:36+0000",               "smsType":"MtSms",               "sentTo":"10-digit phone number",               "message":"nxlhfceybs",               "encoding":"US-ASCII",               "deliveryStatus":"Scheduled"            },            {               "timestamp":"2020-03-10T17:05:56+0000",               "smsType":"MtSms",               "sentTo":"10-digit phone number",               "message":"czbsvpekzb",               "encoding":"US-ASCII",               "deliveryStatus":"Scheduled"            },            {               "timestamp":"2020-03-12T13:26:38+0000",               "smsType":"MtSms",               "sentTo":"10-digit phone number",               "message":"gfdvidznli",               "encoding":"US-ASCII",               "deliveryStatus":"Delivered"            },            {               "timestamp":"2020-03-12T15:21:14+0000",               "smsType":"MtSms",               "sentTo":"10-digit phone number",               "message":"hrnbhdiygu",               "encoding":"US-ASCII",               "deliveryStatus":"Scheduled"            },            {               "timestamp":"2020-03-12T15:29:59+0000",               "smsType":"MtSms",               "sentTo":"10-digit phone number",               "message":"uxcikgvinz",               "encoding":"US-ASCII",               "deliveryStatus":"Delivered"            },            {               "timestamp":"2020-03-12T15:32:29+0000",               "smsType":"MtSms",               "sentTo":"10-digit phone number",               "message":"ksbsrcgkfb",               "encoding":"US-ASCII",               "deliveryStatus":"Delivered"            },            {               "timestamp":"2020-03-16T15:14:14+0000",               "smsType":"MtSms",               "sentTo":"10-digit phone number",               "message":"vxaghtkpeb",               "encoding":"US-ASCII",               "deliveryStatus":"Delivered"            },            {               "timestamp":"2020-03-16T15:41:14+0000",               "smsType":"MtSms",               "sentTo":"10-digit phone number",               "message":"zxnckzabzw",               "encoding":"US-ASCII",               "deliveryStatus":"Scheduled"            }         ]      }   },   "callbackCount":1,   "maxCallbackThreshold":4}

Callback Parameters

Parameter	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 (UUID) 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 response objects.
smsEventHistoryResponse	array	An array of device identifiers and `smsEvents`.
kind	string	The type of device identifier. This can be: 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
id	string	The value of the device identifier.
SmsEvents	array	An array of `SmsEvent` objects.
TimeStamp	string ($dateTime)	The date and time that the message was sent or received.
SmsType	string	The type of SMS message. 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.

# Retrieve SMS Event History for a Device 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. ### `POST /devices/sms/history/actions/list` ## 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/resources/documentation/connectivity/API_Reference/Register_Callback_Listener/) callback service to receive the callback response. ## 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/connectivity-management/guides/getting-started/introduction-to-the-connectivity-management-api). |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/m2m/v1/devices/sms/history/actions/list](/docs/standard-apis/global-iot-orchestration/api-endpoints/retrieve-sms-event-history-for-a-device-2/listsmsmessagehistory) ## Request Parameters The request body identifies the device identifier and specifies a time frame for which SMS events should be returned. | Parameter | Data Type | Description | | --------------- | ----------------- | ------------------- | | **deviceId** *(optional)* | object | An identifier for a single device. | **kind** *(required for `deviceId`)* | string | The type of device identifier. This can be: 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 | | **id** *(required for `deviceId`)* | string | The value of the device identifier. | | **earliest** *(optional)* | string | Only include `smsEvents` that occurred after this [date and time](https://thingspace.verizon.com/resources/documentation/connectivity/Working_with_Verizon_Wireless/Data_Types_and_Units_of_Measure/). | | **latest** *(optional)* | string | Only include `smsEvents` that occurred before this [date and time](https://thingspace.verizon.com/resources/documentation/connectivity/Working_with_Verizon_Wireless/Data_Types_and_Units_of_Measure/). | ## Request Body Example Request: ```json { "deviceId":{ "id":"20-digit ICCID", "kind":"iccid" }, "earliest":"2019-05-01T00:00:01Z", "latest":"2019-06-01T00:00:01Z" } ``` ## Success Response **Status 200** A successful response returns a `requestId`. Example Response: ```json { "requestId":"595f5c44-eeee-ffff-gggg-020a1545a84d" } ``` ## Success Parameters | Parameter | Data Type | Description | | ---------- | -------- | ----------- | | **requestId** | string | A unique string (UUID) that associates the request with the results that are sent via a [callback message](https://thingspace.verizon.com/resources/documentation/connectivity/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. | ## Failure Responses Example Response: ```json { "errorCode": "The 3-digit HTML error code", "errorMessage": "string" } ``` ## Callback Response **DeviceService** sends a callback that contains an array of a maximum of 500 `SmsEvents` objects, that contain detailed information about each event. Example callback response: ```json { "username":"string", "password":"string", "requestId":"595f5c44-eeee-ffff-gggg-020a1545a84d", "deviceResponse":{ "smsEventHistoryResponse":{ "deviceId":{ "id":"1+ 10-digit phone number", "kind":"msisdn" }, "smsEvents":[ { "timestamp":"2020-02-28T17:52:17+0000", "smsType":"MoSms", "sentFrom":"10-digit phone number", "message":"?{h??", "encoding":"US-ASCII", "deliveryStatus":"Delivered" }, { "timestamp":"2020-03-03T17:42:53+0000", "smsType":"MtSms", "sentTo":"10-digit phone number", "message":"labttqhfvn", "encoding":"US-ASCII", "deliveryStatus":"Scheduled" }, { "timestamp":"2020-03-09T14:58:08+0000", "smsType":"MtSms", "sentTo":"10-digit phone number", "message":"lryuchiedd", "encoding":"US-ASCII", "deliveryStatus":"Delivered" }, { "timestamp":"2020-03-09T16:55:16+0000", "smsType":"MtSms", "sentTo":"10-digit phone number", "message":"ygpcmzbrhn", "encoding":"US-ASCII", "deliveryStatus":"Scheduled" }, { "timestamp":"2020-03-10T16:26:24+0000", "smsType":"MtSms", "sentTo":"10-digit phone number", "message":"iqiqhwjkmu", "encoding":"US-ASCII", "deliveryStatus":"Delivered" }, { "timestamp":"2020-03-10T16:28:55+0000", "smsType":"MtSms", "sentTo":"10-digit phone number", "message":"evgnmtcuhj", "encoding":"US-ASCII", "deliveryStatus":"Delivered" }, { "timestamp":"2020-03-10T16:35:06+0000", "smsType":"MtSms", "sentTo":"10-digit phone number", "message":"zdskemrpsg", "encoding":"US-ASCII", "deliveryStatus":"Delivered" }, { "timestamp":"2020-03-10T16:43:37+0000", "smsType":"MtSms", "sentTo":"10-digit phone number", "message":"xxfkjlinyz", "encoding":"US-ASCII", "deliveryStatus":"Delivered" }, { "timestamp":"2020-03-10T17:00:36+0000", "smsType":"MtSms", "sentTo":"10-digit phone number", "message":"nxlhfceybs", "encoding":"US-ASCII", "deliveryStatus":"Scheduled" }, { "timestamp":"2020-03-10T17:05:56+0000", "smsType":"MtSms", "sentTo":"10-digit phone number", "message":"czbsvpekzb", "encoding":"US-ASCII", "deliveryStatus":"Scheduled" }, { "timestamp":"2020-03-12T13:26:38+0000", "smsType":"MtSms", "sentTo":"10-digit phone number", "message":"gfdvidznli", "encoding":"US-ASCII", "deliveryStatus":"Delivered" }, { "timestamp":"2020-03-12T15:21:14+0000", "smsType":"MtSms", "sentTo":"10-digit phone number", "message":"hrnbhdiygu", "encoding":"US-ASCII", "deliveryStatus":"Scheduled" }, { "timestamp":"2020-03-12T15:29:59+0000", "smsType":"MtSms", "sentTo":"10-digit phone number", "message":"uxcikgvinz", "encoding":"US-ASCII", "deliveryStatus":"Delivered" }, { "timestamp":"2020-03-12T15:32:29+0000", "smsType":"MtSms", "sentTo":"10-digit phone number", "message":"ksbsrcgkfb", "encoding":"US-ASCII", "deliveryStatus":"Delivered" }, { "timestamp":"2020-03-16T15:14:14+0000", "smsType":"MtSms", "sentTo":"10-digit phone number", "message":"vxaghtkpeb", "encoding":"US-ASCII", "deliveryStatus":"Delivered" }, { "timestamp":"2020-03-16T15:41:14+0000", "smsType":"MtSms", "sentTo":"10-digit phone number", "message":"zxnckzabzw", "encoding":"US-ASCII", "deliveryStatus":"Scheduled" } ] } }, "callbackCount":1, "maxCallbackThreshold":4 } ``` ## Callback Parameters | Parameter | 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 (UUID) 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 response objects. | | **smsEventHistoryResponse** | array | An array of device identifiers and `smsEvents`. | | **kind** | string | The type of device identifier. This can be: 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 | | **id** | string | The value of the device identifier. | | **SmsEvents** | array | An array of `SmsEvent` objects. | | **TimeStamp** | string ($dateTime) | The date and time that the message was sent or received. | | **SmsType** | string | The type of SMS message. 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. |

Verizon 5G Edge API Portal

API Reference

Retrieve SMS Event History for a Device

`POST /devices/sms/history/actions/list`

Uses and Requirements

Header Parameters

HTTP Request

Request Parameters

Request Body

Success Response

Success Parameters

Failure Responses

Callback Response

Callback Parameters

On this page

Retrieve SMS Event History for a Device

`POST /devices/sms/history/actions/list`

Uses and Requirements

Header Parameters

HTTP Request

Request Parameters

Request Body

Success Response

Success Parameters

Failure Responses

Callback Response

Callback Parameters