API Reference

SMS messages are queued on the ThingSpace Platform and sent as soon as possible, but they may be delayed due to traffic and routing considerations. You can register for the EnhancedConnectivityService callback service to be notified when the messages have actually been sent to the devices, and for the SMSDeliveryConfirmation callback service to verify that the devices receive the messages.

The Verizon Wireless network attempts to deliver a message for five days (120 hours) from the date of receipt. Messages not delivered within five days are deleted, and an “expired” notification is sent via the SMSDeliveryConfirmation callback service.

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/sms

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 devices that the message is sent to, and the message itself.

Parameter Name	Data Type	Description
deviceIds optional	array of device identifiers	The devices that you want to send the message to, specified by device identifier. You only need to provide one identifier per device. Do not use accountName, groupName, or customFields if you use this parameter.
kind, id required for deviceIds	strings	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 MSISDN - decimal, 11 digits
accountName optional	string	The name of a billing account. This parameter is always required. An account name is usually numeric, and must include any leading zeros.
groupName optional	string	The name of a device group, if you want to send the SMS message to all devices in the device group.
servicePlan optional	string	The name of a service plan, if you want to only include devices that have that service plan. You can use GET /plans to get a list of all service plans in the account.
customFields optional*	array	The names and values of custom fields, if you want to only include devices that have matching custom fields.
key required for customFields	string	The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5.
value required for customFields	string	The value of the custom field. The value is not case-sensitive, but other than that it must match exactly with the value set for a device. Wildcards and partial matches are not supported.
dataEncoding optional	string	The SMS message encoding, which can be: 7-bit (default) 8-bit-ASCII 8-bit-UTF-8 8-bit-DATA Note: All 8-bit SMS messages require the message contents to be base64 encoded.
smsMessage required	string	The contents of the SMS message. The SMS message is limited to 160 characters in 7-bit format, or 140 characters in 8-bit format.
timeToLive (optional)	string	A period of time the message remains valid or an end date for the message. For more information, please review section 5.2.16 (validity period) and 7.1 (time definitions) in the SMPP Standards document

Either specify up to 10,000 individual devices with the devices parameter, or use any combination of groupName, servicePlan, and customFields to run the request on all devices that match all criteria.

Example Request Body

Send an SMS Message to single or multiple Device ID(s):

{
  "accountName": "0000123456-00001",
  "customFields": [
    {
      "key": "CustomField1",
      "value": "value of the field"
    }
  ],
  "dataEncoding": "optional 7 or 8-bit encoding",
  "deviceIds": [
    {
      "id": "20-digit ICCID",
      "kind": "iccid"
    }
  ],
  "smsMessage": "the body or text of the message itself",
  "timeToLive": "000000010000000R"
}

Send an SMS Message to All Devices with a specified service plan or group name:

{
  "accountName": "0000123456-00001",
  "customFields": [
    {
      "key": "ANR5XG3Ud",
      "value": "r0QngIFUIQ1BatSsN"
    }
  ],
  "dataEncoding": "optional 7 or 8-bit encoding",
  "groupName": "the name of the group the device is in",
  "servicePlan": "the service plan the device is using",
  "smsMessage": "the body or text of the message itself",
  "timeToLive": "000000010000000R"
}

Success Responses

Status 200

Parameter Name	Data Type	Description
requestId	string	A unique string (UUID) that associates the request with the results that are sent via a callback service. The ThingSpace Platform sends a separate callback message for each device that matched the request criteria, indicating whether the operation succeeded for that device and containing any requested information. All related callback messages have the same `requestId`.

Example Success Response

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

Example Callback Response

SendSmsMessage Callback Messages:

Per-Device Message:

{  
  "username":"",
  "password":"",
  "requestId":"595f5c44-eeee-ffff-gggg-020a1545a84d",
  "deviceIds":[  
    {  
      "id":"20-digit ICCID",
      "kind":"iccid"
    },
    {  
      "id":"3035551234",
      "kind":"mdn"
    },
    {  
      "id":"15-digit IMEI",
      "kind":"imei"
    },
    {  
      "id":"13035551234",
      "kind":"msisdn"
    }
  ],
  "comment":"SendSmsMessage,Performed action on device.",
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

Request Complete Message:

{  
  "username":"",
  "password":"",
  "requestId":"595f5c44-eeee-ffff-gggg-020a1545a84d",
  "comment":"SendSmsMessage,Request Completed Processing."
  "summary": {
    "devicesRequested": 2
  }
}

SmsDeliveryConfirmation Callback Messages:

Success after device acknowledgement:

{  
  "username":"",
  "password":"",
  "requestId":"595f5c44-eeee-ffff-gggg-020a1545a84d",
  "deviceIds":[  
    {  
      "id":"3035551234",
      "kind":"mdn"
    }
  ],
  "deviceResponse":{  
    "smsDeliveryResponse":{  
      "confirmation":"Delivered"
    }
  }
}

Undelivered, such as for messages sent to suspended devices:

{  
  "username":"",
  "password":"",
  "requestId":"595f5c44-eeee-ffff-gggg-020a1545a84d",
  "deviceIds":[  
    {  
      "id":"3035551234",
      "kind":"mdn"
    }
  ],
  "deviceResponse":{  
    "smsDeliveryResponse":{  
      "confirmation":"Undelivered"
    }
  }
}

Expired, when a message could not be delivered within 5 days or exceeded timeToLive :

{  
  "username":"",
  "password":"",
  "requestId":"595f5c44-eeee-ffff-gggg-020a1545a84d",
  "deviceIds":[  
    {  
      "id":"3035551234",
      "kind":"mdn"
    }
  ],
  "deviceResponse":{  
    "smsDeliveryResponse":{  
      "confirmation":"Expired"
    }
  }
}

Rejected, when a device’s message queue is full (the device already has 100 pending messages in queue):

{  
  "username":"",
  "password":"",
  "requestId":"595f5c44-eeee-ffff-gggg-020a1545a84d",
  "deviceIds":[  
    {  
      "id":"3035551234",
      "kind":"mdn"
    }
  ],
  "deviceResponse":{  
    "smsDeliveryResponse":{  
      "confirmation":"Rejected"
    }
  }
}

Callback Parameters

Parameter	Data Type	Description
username	string	The user name of the requestor.
password	string	The password of the user making the request.
requestId	string	The UUID of the request. A UUID is a 32 to 36-bit alphanumeric string.
deviceIds	array	An array of device identifier objects, each object containing a `kind` and `id`.
id	string	The value of the `kind` associated with the device.
kind	string	A description of what the parameter is and what valid data for the parameter is. This is usually the MDN - Mobile Device Number, which is a 10-digit phone number, but could also be: IMEI - International Mobile Equipment Identifier ICCID - Integrated Circuit Card Identifier MSISDN - Mobile Services International Subscriber Directory Number. In the United States, this is 1+ a 10-digit phone number.
deviceResponse	object	The object containing the response from the device that was sent an SMS.
smsDeliveryResponse	object	The object containing the confirmation message from the device.
confirmation	string	Confirmation of message delivery. This can be one of the following: DELIVERED: The message has successfully reached the recipient's device. EXPIRED: The message validity period has passed, and the Short Message Service Controller (SMSC) cannot deliver it. UNDELIVERABLE: The message could not be delivered for various reasons, such as an invalid number or a temporary mobile network outage. DELETED: The message was deleted by the SMSC or the recipient. REJECTED: The message was rejected by the SMSC. UNKNOWN: The status of the message is unknown.

Failure Responses

All error messages are returned in this format:

{
  "errorCode": "error code string",
  "errorMessage": "error message string"
}

Error response when the message sent is too long:

{
  "errorCode": "EnhancedConnectivityService.INPUT_INVALID.SmsMessage.TooLong",
  "errorMessage": "An 8-bit SMS message cannot be more than 188 characters long."
}

Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions.

HTTP RequestCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Example Request BodyCopy Anchor Link

Success ResponsesCopy Anchor Link

Example Success ResponseCopy Anchor Link

Example Callback ResponseCopy Anchor Link

Callback ParametersCopy Anchor Link

Failure ResponsesCopy Anchor Link

On this page