SMS API

SMS API Descriptions
Plum offers four services for its SMS REST API:
Method
Service
Description
POST
sms/queue
Queues an SMS message and returns an SMS message resource
GET
sms/status
Returns a single SMS message resource
GET
sms/messages
Returns a filtered list of SMS message resources
GET
sms/conversation
Returns SMS messages exchanged between two defined phone numbers
Please note that each of these SMS REST APIs use HTTP AUTH for authentication. The username/password to be used for authentication are the same as your standard Plum DEV login credentials.
All of the SMS REST APIs have the same return format that includes a status (success or failure), error message and the result data.
Sample Responses
XML (success)
XML (failure)
JSON (success)
 JSON (failure)
JSON (invalid phone number)
XML (success)
<sample>
  <status>success</status>
  <error/>
  <result>
    <!-- SAMPLE RESULT DATA -->
  </result>
</sample>
XML (failure)
<sample>
  <status>failure</status>
  <error>Unauthorized access to sample service</error>
</sample>
JSON (success)
{
  "status":"success",
  "error":"",
  "result": {
    // SAMPLE RESULT DATA
  }
}
 JSON (failure)
{
  "status":"failure",
  "error":"Unauthorized access to sample service",
}
JSON (invalid phone number)
{
  "status":"failure",
  "error":"Invalid 'to' phone number",
}
Sending SMS
post
Queue SMS
https://hosting.plumvoice.com/ws/sms/{resource_type}
Queues an SMS message to be sent
Request
Response
Request
Path Parameters
resource_type
required
string
queue.xml or queue.json
Headers
Content-type
required
string
application/x-www-form-urlencoded
Accept
optional
string
application/xml, application/json
Form Data Parameters
to
required
string
Phone number that the SMS message will be sent to
Note: you must include a '1' before the 10 digit phone number.
from
required
string
Phone number that the SMS will appear from
Note: this phone number must appear as an “SMS Number” on the “Account Configuration” page in your Plum DEV account. Any attempt to send an SMS using a number not listed as an “SMS Number” in your account will fail. 
body
required
string
SMS message to be sent
Note: messages larger than 160 characters will be split into multiple messages.
result_url
optional
string
URL for tracking the SMS result status
Note: after the SMS is sent this URL will receive a POST with the following variables: 'sms_message_id' and 'status'. This should be used to get the status of an SMS message rather than polling the status REST service. 
Response
200: OK
JSON
XML
JSON
{
  "status":"success",
  "error":"",
  "result": {
    "sms_messages": [
      {
        "sms_message_id":"e7f41fdc813d481081ec2840d68838b5",
        "to":"19998881234",
        "from":"2435678910",
        "body":"This is a notification",
        "request_timestamp":1330464356,
        "result_url":"http://myserver.com/storesmsresults.php",
        "status":"queued"
      }
    ]
  }
}
XML
<queue>
  <status>success</status>
  <error/>
  <result>
    <sms_messages>
      <sms_message>
        <sms_message_id>e7f41fdc813d481081ec2840d68838b5</sms_message_id>
        <to>19998881234</to>
        <from>2435678910</from>
        <body>This is a notification</body>
        <request_timestamp>1330464356</request_timestamp>
        <result_url>http://myserver.com/storesmsresults.php<result_url>
        <status>queued</status>
      </sms_message>
    </sms_messages>
  </result>
</queue>
Sample Code
queuesms.php
storesmsresults.php
CURL (command line)
queuesms.php
<?php
header("Content-type: text/xml");
​
$params['to'] = "19998881234";
$params['from'] = "2435678910";
$params['body'] = "This is a notification.";
$params['result_url'] = "http://myserver.com/storesmsresults.php";
​
// initialize curl
$ch = curl_init();
​
// set necessary curl options
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_URL, "https://hosting.plumvoice.com/ws/sms/queue.xml");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");
​
echo(curl_exec($ch));
​
curl_close($ch);
?>
storesmsresults.php
<?php
// make sure the log file has read/write permissions from the web server
$logfile = "logs/smsresults.log"
if (!is_readable($logfile) || !is_writable($logfile)) {
  die("Unable to write to log file.");
}
​
if (isset($_POST['sms_message_id'], $_POST['status'])) {
  if ($fp = fopen($logfile, 'a+')) {
    $date = date("r");
    $message_id = $_POST['sms_message_id'];
    $status = $_POST['status'];
    fwrite($fp, "$date $message_id $status\n");
    fclose($fp);
  }
}
?>
CURL (command line)
curl -u username:password -d to=19998881234 -d from=2435678910 -d body='This is a notification' https://hosting.plumvoice.com/ws/sms/queue.xml
Receiving SMS
get
SMS Status
https://hosting.plumvoice.com/ws/sms/{resource_type}/{sms_message_id}
Returns the status of an SMS message
Request
Response
Request
Path Parameters
resource_type
required
string
status.xml or status.json
sms_message_id
required
string
Unique 128-bit hexidecimal identifier for this SMS message
Note: this value is provided in the result of a queued SMS message
Headers
content-type
optional
string
application/x-www-form-urlencoded
accept
optional
string
application/json, application/xml
Response
200: OK
JSON
XML
JSON
{
  "status":"success",
  "error":"",
  "result": {
    "sms_message_id":"e7f41fdc813d481081ec2840d68838b5",
    "to":"19998881234",
    "from":"2435678910",
    "body":"This is a notification",
    "request_timestamp":"1330464356",
    "response_timestamp":"1330464357",
    "status":"sent",
    "delivery_status":"delivered"
  }
}
XML
<status>
  <status>success</status>
  <error/>
  <result>
    <sms_message_id>e7f41fdc813d481081ec2840d68838b5</sms_message_id>
    <to>19998881234</to>
    <from>2435678910</from>
    <body>This is a notification</body>
    <request_timestamp>1330464356</request_timestamp>
    <response_timestamp>1330464357</response_timestamp>
    <status>sent</status>
    <delivery_status>delivered</delivery_status>
  </result>
</status>
This method with return result status as queued, sent, received, or failed. When the value of status is sent, then the method will also return a result delivery_status as delivered or undelivered.
Statuses Explained
Message Status Types:
Queued: your message has been added to the queue to be sent.
Sent: your message has been sent.
Received: you have received an incoming message.
Failed: your message could not be sent. Failed messages can happen for a variety of reasons including queue overflows, account suspensions, etc.
Delivery Status Types:
Delivered: your message has been successfully delivered to your recipient.
Undelivered: your message was not delivered. There are many reasons why this may occur including, destination number is not a mobile number, carrier content filtering, the availability of the destination number, etc.
Please be advised! The delivery status will only be available up to 7 days after the SMS message was sent.
Sample Code
checkstatus.php
CURL (command line)
checkstatus.php
<?php
header("Content-type: text/xml");
​
// for this example, our sms_message_id is e7f41fdc813d481081ec2840d68838b5
$sms_message_id = 'e7f41fdc813d481081ec2840d68838b5';
​
// initialize curl
$ch = curl_init();
​
// set necessary curl options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");
curl_setopt($ch, CURLOPT_URL, "https://hosting.plumvoice.com/ws/sms/status.xml/".$sms_message_id);
​
echo(curl_exec($ch));
​
curl_close($ch);
?>
CURL (command line)
curl -u username:password https://hosting.plumvoice.com/ws/sms/status.json/e7f41fdc813d481081ec2840d68838b5
get
SMS Messages
https://hosting.plumvoice.com/ws/sms/{resource_type}
Lists SMS messages that have been sent and/or received.
Request
Response
Request
Path Parameters
resource_type
required
string
messages.xml or messages.json
Query Parameters
offset
optional
integer
Number of SMS messages to skip before returning results.
limit
optional
integer
Maximum number of SMS messages to return.
Note: minimum limit is 50, maximum limit is 1000.
start_timestamp
optional
integer
Start timestamp to begin searching for SMS messages.
end_timestamp
optional
integer
End timestamp to stop searching for SMS messages.
msg_type
optional
string
Type of messages to be returned.
Note: Accepted values are 'inbound', 'outbound', 'all' (for both inbound and outbound), or blank.
phone_number
optional
integer
The phone number to filter results on.
number_type
required
string
Available and required only when message type is inbound or outbound AND a phone number is provided.
Note: accepted values are 'account' (your SMS phone number) and 'customer' (your end user's SMS phone number) 
Response
200: OK
JSON
XML
JSON
{
  "status":"success",
  "error":"",
  "result": {
    "offset":0,
    "limit":50,
    "total":"2",
    "sms_messages": [
      {
        "sms_message_id":"e7f41fdc813d481081ec2840d68838b5",
        "to":"19998881234",
        "from":"2435678910",
        "body":"This is a notification",
        "request_timestamp":"1330464356",
        "response_timestamp":"1330464357",
        "result_url":"",
        "status":"sent"
      },
      {
        "sms_message_id":"bf811cfb5e864a2793d9b6b81ec2185f",
        "to":"19998881234",
        "from":"2435678910",
        "body":"Resending notification",
        "request_timestamp":"1330464386",
        "response_timestamp":"1330464387",
        "result_url":"",
        "status":"sent"
      }
    ]
  }
}
XML
<messages>
  <status>success</status>
  <error/>
  <result>
    <offset>0</offset>
    <limit>50</limit>
    <total>2</total>
    <sms_messages>
      <sms_message>
        <sms_message_id>e7f41fdc813d481081ec2840d68838b5</sms_message_id>
        <to>19998881234</to>
        <from>2435678910</from>
        <body>This is a notification</body>
        <request_timestamp>1330464356</request_timestamp>
        <response_timestamp>1330464357</response_timestamp>
        <result_url/>
        <status>sent</status>
      </sms_message>
      <sms_message>
        <sms_message_id>bf811cfb5e864a2793d9b6b81ec2185f</sms_message_id>
        <to>19998881234</to>
        <from>2435678910</from>
        <body>Resending notification</body>
        <request_timestamp>1330464386</request_timestamp>
        <response_timestamp>1330464387</response_timestamp>
        <result_url/>
        <status>sent</status>
      </sms_message>
    </sms_messages>
  </result>
</messages>
Sample Code
getmessages.php
CURL (command line)
getmessages.php
<?php
header("Content-type: text/xml");
​
// initialize curl
$ch = curl_init();
​
// set necessary curl options
curl_setopt($ch, CURLOPT_URL, "https://hosting.plumvoice.com/ws/sms/messages.xml?offset=0&limit=50&start_timestamp=0&end_timestamp=0&msg_type=inbound&phone_number=xxxxxxxxxx&number_type=account");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");
​
echo(curl_exec($ch));
​
curl_close($ch);
?>
CURL (command line)
curl -u username:password "https://hosting.plumvoice.com/ws/sms/messages.json/?offset=0&limit=50&start_timestamp=0&end_timestamp=0&msg_type=inbound&phone_number=xxxxxxxxxx&number_type=account"
get
SMS Conversation
https://hosting.plumvoice.com/ws/sms/{resource_type}
Lists messages between two phone numbers
Request
Response
Request
Path Parameters
resource_type
required
string
conversation.xml or  conversation.json
Query Parameters
offset
optional
integer
Number of SMS messages to skip before returning results.
limit
optional
integer
Maximum number of SMS messages to return.
Note: minimum limit is 50, maximum limit is 1000.
start_timestamp
optional
integer
Start timestamp to begin searching for SMS messages.
end_timestamp
optional
integer
End timestamp to stop searching for SMS messages.
phone_number1
required
integer
First phone number to filter on for the returned conversation.
phone_number2
required
integer
Second phone number to filter on for the returned conversation.
Response
200: OK
JSON
XML
JSON
{
  "status":"success",
  "error":"",
  "result":{
    "offset":"0",
    "limit":"50",
    "total":"4",
    "sms_messages":[
      {
        "sms_message_id":"b84b2dbfadcc49e1a697aabfdb1f2730",
        "to":"19998881234",
        "from":"2435678910",
        "body":"GREAT",
        "request_timestamp":"1594662275",
        "response_timestamp":"1594662276",
        "result_url":"",
        "type":"inbound",
        "status":"received"
      },
      {
        "sms_message_id":"4beb4b8ace954ff694bdadb8cca99ac9",
        "to":"2435678910",
        "from":"19998881234",
        "body":"Thanks for visiting us today! Tell us how we did. Reply back with \"OK\", \"GOOD\", \"GREAT\" or \"EXCELLENT\".",
        "request_timestamp":"1594662276",
        "response_timestamp":"1594662279",
        "result_url":"",
        "type":"outbound",
        "status":"sent"
      },
      {
        "sms_message_id":"dd2ee079413f48b49e45879241af09d4",
        "to":"19998881234",
        "from":"2435678910",
        "body":"CONFIRM",
        "request_timestamp":"1594662276",
        "response_timestamp":"1594662276",
        "result_url":"",
        "type":"inbound",
        "status":"received"
      },
      {
        "sms_message_id":"6b8e2bd2e9e5485d9123ec929f462efd",
        "to":"2435678910",
        "from":"19998881234",
        "body":"This is a notification of your appointment tomorrow. Please reply with \"CONFIRM\", to confirm your appointment.",
        "request_timestamp":"1594662313",
        "response_timestamp":"1594662314",
        "result_url":"",
        "type":"outbound",
        "status":"sent"
      }
    ]
  }
}
XML
<conversation>
    <status>success</status>
    <error></error>
    <result>
        <offset>0</offset>
        <limit>50</limit>
        <total>4</total>
        <sms_messages>
            <sms_message>
                <sms_message_id>b84b2dbfadcc49e1a697aabfdb1f2730</sms_message_id>
                <to>19998881234</to>
                <from>2435678910</from>
                <body>GREAT</body>
                <request_timestamp>1594662275</request_timestamp>
                <response_timestamp>1594662276</response_timestamp>
                <result_url></result_url>
                <type>inbound</type>
                <status>received</status>
            </sms_message>
            <sms_message>
                <sms_message_id>4beb4b8ace954ff694bdadb8cca99ac9</sms_message_id>
                <to>2435678910</to>
                <from>19998881234</from>
                <body>Thanks for visiting us today! Tell us how we did. Reply back with "OK", "GOOD", "GREAT" or "EXCELLENT".</body>
                <request_timestamp>1594662276</request_timestamp>
                <response_timestamp>1594662279</response_timestamp>
                <result_url></result_url>
                <type>outbound</type>
                <status>sent</status>
            </sms_message>
            <sms_message>
                <sms_message_id>dd2ee079413f48b49e45879241af09d4</sms_message_id>
                <to>19998881234</to>
                <from>2435678910</from>
                <body>CONFIRM</body>
                <request_timestamp>1594662276</request_timestamp>
                <response_timestamp>1594662276</response_timestamp>
                <result_url></result_url>
                <type>inbound</type>
                <status>received</status>
            </sms_message>
            <sms_message>
                <sms_message_id>6b8e2bd2e9e5485d9123ec929f462efd</sms_message_id>
                <to>2435678910</to>
                <from>19998881234</from>
                <body>This is a notification of your appointment tomorrow. Please reply with "CONFIRM", to confirm your appointment.</body>
                <request_timestamp>1594662313</request_timestamp>
                <response_timestamp>1594662314</response_timestamp>
                <result_url></result_url>
                <type>outbound</type>
                <status>sent</status>
            </sms_message>
        </sms_messages>
    </result>
</conversation>
Be sure to filter based on your Plum-provided SMS number and the end-user's phone number to yield the correct results. Use the phone_number1 or phone_number2 parameters with either filtered number.
Sample Code
getconversation.php
CURL (command line)
getconversation.php
<?php
header("Content-type: text/xml");
​
// initialize curl
$ch = curl_init();
​
// set necessary curl options
curl_setopt($ch, CURLOPT_URL, "https://hosting.plumvoice.com/ws/sms/conversation.xml?offset=0&limit=50&start_timestamp=0&end_timestamp=0&phone_number1=xxxxxxxxxx&phone_number2=xxxxxxxxxx");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");
​
echo(curl_exec($ch));
​
curl_close($ch);
?>
CURL (command line)
curl -u username:password "https://hosting.plumvoice.com/ws/sms/messages.json/?offset=0&limit=50&start_timestamp=0&end_timestamp=0&phone_number1=xxxxxxxxxxx&phone_number2=xxxxxxxxxx"
Legacy and Miscellaneous Notes
Next - Plum DEV APIs
Call Logs API
Last updated 4 days ago
Method	Service	Description
POST	sms/queue	Queues an SMS message and returns an SMS message resource
GET	sms/status	Returns a single SMS message resource
GET	sms/messages	Returns a filtered list of SMS message resources
GET	sms/conversation	Returns SMS messages exchanged between two defined phone numbers
SMS API

SMS API Descriptions

Sample Responses

Sending SMS

postQueue SMS

Receiving SMS

getSMS Status

Statuses Explained

Message Status Types:

Delivery Status Types:

getSMS Messages

getSMS Conversation

post
Queue SMS

get
SMS Status

get
SMS Messages

get
SMS Conversation
