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.

Contents

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.

Request Components

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

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

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.