Search SMS

Description

Returns a list of SMS message IDs associated with a particular account during a specified time period. Optionally, you can restrict the search to a specific device.

The function returns messages between Control Center and a device. You cannot get information about messages exchanged between a device and a non-Control Center SMS client.

Users with Essential accounts must purchase the Essential SMS Service package in order to use this API.

Resource URL

GET rws/api/v{apiVersion}/smsMessages

Request Parameters

Request Parameters and Descriptions
Parameter Description
apiVersion

The version number for this API. The current version for all functions is 1.

accountId

(Optional) Unique identifier for the account associated with the messages you want to retrieve.

iccid (Optional) Restricts the list of returned messages to just those messages sent or received by a particular device. This device must be owned by the specified account.
fromDate A date and time using the ISO 8601 format (see Date Formats). The function returns any messages that were sent or received on or after this date.
toDate (Optional) A date and time using the ISO 8601 format (see Date Formats). Use this parameter to specify a particular period of time for the messages. If you do not specify a toDate, Control Center returns all messages up to the current date and time.
msgType (Optional) Indicates whether the message was sent by the device (MO, mobile-originated) or received by the device (MT, mobile-terminated).
pageSize

(Optional) Specifies the number of records returned in each response page. The maximum value is 50. The value defaults to 50.

pageNumber

(Optional) Specifies the number of response pages to return. This value defaults to 1.

Response Parameters

The function returns an array of SMS message IDs. Records are sorted by modification date in ascending order with the oldest message listed first.

Return Values and Descriptions
Return Value Description
smsMsgIds An array of message identifiers. You must use the Get SMS Details API to retrieve the content of each message.

pageNumber

An integer specifying the number of the current page.

lastPage

A true or false value indicating whether the current page is the last in the series.

Request Example

Make sure to use your own user credentials. See Authentication for information about creating an authorization header.

json
Copycurl -X GET --header "Accept: application/json" --header "Authorization: Basic <YOUR-ENCRYPTED-CREDENTIALS>" "https://rws-jpotest.jasper.com/rws/api/v1/smsMessages"

Response Example

json
Copy{
	"smsMsgIds": [
		106184,
		105025
	],
	"pageNumber": 1,
	"lastPage": true
}

Code Samples

Make sure to use the Control Center sandbox URL and your own user credentials.

python
javascript
ruby
Copyimport requests 
import json 
import base64 
import pprint 

cobrandURL=input("Cobrand URL: ")						
url = 'https://'+input("Cobrand URL: ")+'/rws/api/v1/smsMessages?accountId='+input("Account ID: ")+'&fromDate=2016-04-18T17%3A31%3A34%2B00%3A00&pageSize=50&pageNumber=1' 
myResponse = requests.get(url,auth=(input("username: "),input("api_key: ")))
# For successful API call, response code will be 200 (OK)
if(myResponse.ok):
    # Loading the response data into a dict variable
    # json.loads takes in only binary or string variables so using content to fetch binary content
    # Loads (Load String) takes a Json file and converts into python data structure (dict or list, depending on JSON)
    jData = json.loads(myResponse.content)
    pp=pprint.PrettyPrinter(indent=4) 
    pp.pprint(jData) 
else:
    # If response code is not ok (200), print the resulting http error code with description
    print("Failure")
    myResponse.raise_for_status()
Copyvar request = require('request');
var body = [];
request.get('https://<your-base-URL>/rws/api/v1/devices/smsMessages?accountId=147060908&fromDate=2016-04-18T17%3A31%3A34%2B00%3A00&pageSize=50&pageNumber=1').auth('username', 'password', false)
    .on('error', function(error){
        console.log('Error:', error);
    })
    .on('response', function(response) {
        console.log(response.statusCode); // return statusCode
        console.log(response.headers['content-type']); // return contentType
    })
    .on('data',function(chunk){
        body.push(chunk);
    })
    .on('end',function(){
        body = Buffer.concat(body).toString();
        console.log(body);
    });
Copy#!/usr/bin/ruby -w
require 'rest-client'
require 'json'
  
url = 'https://<your-base-URL>/rws/api/v1/smsMessages?accountId=147060908&fromDate=2016-04-18T17%3A31%3A34%2B00%3A00&pageSize=50&pageNumber=1'
response = RestClient::Request.execute(
 method: :get,
 url: url,
 user: 'username',
 password: 'password',
 :headers => {:accept => :json}
)
puts JSON.pretty_generate(JSON.parse(response))

Errors

Error Codes, HTTP Codes, and Descriptions
Error Code HTTP Code Error Message
10000001 401

Invalid credentials.

Description: Control Center uses this error message when the API credentials are invalid or when the IP address is not within the allowed range.

10000002 400 AccoundId is required.
10000004 400 Invalid accountId.
10000006 400 Invalid pageSize.
10000007 400 Invalid pageNumber.
10000012 400 Invalid date format.
10000021 400 Invalid iccid.
10000022 400 FromDate is required.
10000024 400 Invalid apiVersion.
10000027 400 ToDate must be after fromDate.
30000001 500 Unknown server error.
101000022 400 Invalid message type.