POST /sms

This API allows the customer to send application-originated (AO) SMS to devices with either Verizon US eSIM profile or global eSIM profile.

Bulk operation: Supported (The callback would be one for each profile). 

eSIM profiles: Both Verizon US and Global.

Contents

Uses and Requirements

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.

Request

HTTP Request

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

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.

Request Body

The request body identifies the devices that the message is sent to, and the message itself.

* You can either specify up to 10,000 individual devices with the devices parameter, or you can 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 Device

{
  "deviceIds": [
    {
      "id": "20-digit ICCID",
      "kind": "iccid"
    }
  ],
  "smsMessage": "Can you hear me now?"
}

Send an SMS Message to All Devices with a Specified Service Plan

{
  "servicePlan": "service plan name",
  "smsMessage": "The rain in Spain stays mainly in the plain."
}

Success Responses

Status 200

Example Success Response

{
  "requestId": "d1f08526-5443-4054-9a29-4456490ea9f8"
}

Example Success Callback Response

SendSmsMessage Callback Messages

Per-Device Message

{  
  "username":"user's login (callback registration)",
  "password":"user's password",
  "requestId":"d1f08526-5443-4054-9a29-4456490ea9f8",
  "deviceIds":[  
    {  
      "id":"20-digit ICCID",
      "kind":"Iccid"
    },
    {  
      "id":"10-digit phone number",
      "kind":"Mdn"
    },
    {  
      "id":"15-digit IMEI",
      "kind":"Imei"
    },
    {  
      "id":"1+ 10-digit phone number (can be up to 15 digits)",
      "kind":"Msisdn"
    }
  ],
  "comment":"SendSmsMessage,Performed action on device.",
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

Request Complete Message

{  
  "username":"user's login (callback registration)",
  "password":"user's password",
  "requestId":"d1f08526-5443-4054-9a29-4456490ea9f8",
  "comment":"SendSmsMessage,Request Completed Processing."
  "summary": {
    "devicesRequested": 2
  }
}

SmsDeliveryConfirmation Callback Messages

Success after device acknowledgement

{  
  "username":"user's login (callback registration)",
  "password":"user's password",
  "requestId":"d1f08526-5443-4054-9a29-4456490ea9f8",
  "deviceIds":[  
    {  
      "id":"10-digit phone number",
      "kind":"Mdn"
    }
  ],
  "deviceResponse":{  
    "smsDeliveryResponse":{  
      "confirmation":"Delivered"
    }
  }
}

Undelivered, such as for messages sent to suspended devices

{  
  "username":"user's login (callback registration)",
  "password":"user's password",
  "requestId":"d1f08526-5443-4054-9a29-4456490ea9f8",
  "deviceIds":[  
    {  
      "id":"10-digit phone number",
      "kind":"Mdn"
    }
  ],
  "deviceResponse":{  
    "smsDeliveryResponse":{  
      "confirmation":"Undelivered"
    }
  }
}

Expired, when a message could not be delivered within 5 days

{  
  "username":"user's login (callback registration)",
  "password":"user's password",
  "requestId":"d1f08526-5443-4054-9a29-4456490ea9f8",
  "deviceIds":[  
    {  
      "id":"10-digit phone number",
      "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":"user's login (callback registration)",
  "password":"user's password",
  "requestId":"d1f08526-5443-4054-9a29-4456490ea9f8",
  "deviceIds":[  
    {  
      "id":"10-digit phone number",
      "kind":"Mdn"
    }
  ],
  "deviceResponse":{  
    "smsDeliveryResponse":{  
      "confirmation":"Rejected"
    }
  }
}

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.