Introduction

This API provides insight into every individual message sent through your account. A lot of details about every message are available, like deliverytime and the delivery status.

Authentication

You can authenticate your calls to this API endpoint by using your producttoken or with the CM SSO cookie.

https://api.cmtelecom.com/v1.2/transactions/

For authenticating with your Producttoken provide the header X-CM-PRODUCTTOKEN with your producttoken as value.

For CM SSO authentication send your cookie along with the request.

Response

All requests to the Transactions API are GET requests.

enveloppe

The resultset is encapsulated in an envelope which contains information about the resultset.

status
1 for successful request processing
message
Ok , when nothing exceptional happened
There are no transactions available with these parameters , when an empty resultset is returned

summary

This object holds all applied filtering information, and some aggregate information

startDate
endDate
direction
totalTransactions
totalPrice
priceCurrency
localPrice
localCurrency
totalTariff

pagination

This object holds pagination information

currentPage
totalPages
pageSize

result

This array holds the resultset

Transaction object (out)

https://api.cmtelecom.com/v1.2/transactions/
Try

OUT is the default direction for transactions in this API. These are messages send to a mobilephone.

JSON example

{  
"status": 1,  
"message": "Ok",  
"pagination":  
{  
"currentPage": 1,  
"totalPages": 1,  
"pageSize": 1000  
},  
"summary": {  
"startDate": "2017-02-01T00:00:00+01:00",  
"endDate": "2017-02-02T00:00:00+01:00",  
"direction": "out",  
"totalTransactions": 1  
},  
"result": [  
{  
"sender": "3669",  
"recipient": "0031601234567",  
"message": "Super Short Message",  
"standarderror": null,  
"errordescription": "",  
"status": 20,  
"statusdescription": "Delivered",  
"created": "2017-02-01T23:58:25+01:00",  
"countryiso": "NL",  
"countryname": "Netherlands",  
"mccmnc": "20404",  
"operatorname": "NL - Vodafone",  
"deliverytime": 5,  
"datacodingscheme": 0,  
"userdataheader": "",  
"channel": "SMS",  
"multipart": {  
"identifer": "B300554E"  
"part": 1  
"parts": 2  
},  
"price": 0.08,  
"tariff": 0,  
"premium": false,  
"customgrouping": null,  
"customgrouping2": null,  
"customgrouping3": null,  
"reference": "6419616239",  
"converted": null,  
"direction": "out"  
}  
]  
} 

Transaction object (in)

https://api.cmtelecom.com/v1.2/transactions/?direction=in
Try

IN is the other direction for transactions in this API. These are messages send from a mobilephone.

{
"status": 1,
"message": "Ok",
"pagination":
{
"currentPage": 1,
"totalPages": 1,
"pageSize": 1000
},
"summary": {
"startDate": "2017-02-01T00:00:00+01:00",
"endDate": "2017-02-02T00:00:00+01:00",
"direction": "in",
"totalTransactions": 1
},
"result": [
{
"sender": "0031601234567",
"recipient": "3669",
"message": "Please send me a super short message",
"status": null,
"created": "2017-02-01T23:58:20+01:00",
"countryiso": "NL",
"countryname": "Netherlands",
"mccmnc": "20404",
"operatorname": "NL - Vodafone",
"datacodingscheme": 0,
"userdataheader": "",
"channel": "SMS",
"price": 0,
"tariff": 0,
"premium": false,
"customgrouping": null,
"customgrouping2": null,
"customgrouping3": null,
"reference": "510661747",
"direction": "in"
}
]
}
 

Required filters

Daterange

filter for a date range with these parameters :

startdate={ISO8601}
enddate={ISO8601}
These are the only required parameters for calls to this API.

When the Time is omitted in the startdate or enddate it will be filled out with zeroes. 2017-05-05 will be treated as 2017-05-05T00:00:00.

A maximum range of 1 month is allowed.

Optional filters

Analyticserror

use the analyticserror parameter to filter by errorcode used in the analytics api for readable errors

analyticserror=3
accepts comma separated list of integers

analyticserrors list

0 = Unknown recipient
1 = Unknown failure
2 = Too many messages to recipient
3 = Recipient temporarily unavailable
4 = Recipient blacklisted
5 = Message rejected by operator
6 = Message malformed
7 = Handset issue
8 = Recipient has no credit
9 = Age verification failed
10 = Deliverytime expired

Channel

use channel for filtering transactions per Channel.

channel=SMS
available channels

SMS
PUSH
Voice
RCS
Viber
WhatsApp
iMessage
Line

Converted

use converted to filter by converted messages

converted=true
accepts a boolean value

CountryISO

use countryiso to filter by recipients in specific countries

countryiso=nl
accepts a comma separated list of country iso codes

Direction

direction=out (default) , countrycode of the recipient
direction=in , countrycode of the sender

Customgrouping

use the customgrouping parameters to filters on all provided customgroupings

customgrouping=some-kind-of-reference
customgrouping2=some-kind-of-reference
customgrouping3=some-kind-of-reference
accepts a comma separated string of custom groupings at any level

Errorcode

use errorcode to filter by errorcodes as returned by this api

errorcode=5
accepts a comma separated list of integers

MCC MNC

it stands for Mobile Country Code Mobile Network Code, 204 identifies the country (the Netherlands) and 04 identifies the operator (Vodafone) in this example

use mccmnc to filter by recipients at specific operators

mccmnc=20404
accepts a comma separated list of operator identification codes

Message

use the message parameter to filter for specific messages, works in both directions

message=This very specific message
accepts * for wildcard in the message

Multipart

Messages may consist of multiple parts, for example when the SMS text is over 160 characters. In this case the message object has a multipart property set, containing an identifier and a part number.

For your viewing pleasure it is possible to filter the message list to show only messages consisting of one part and only the first part of messages consisting of multiple parts. This way you get an overview of your "Full Messages".

multipart=firstpartonly
You can also get all parts of a specific multipart message by filtering for a specific identifier. It is adviced to use the Recipient filter in combination with this filter, since the multipart identifier are not universally unique.

multipart={multipart.identifier}

Omit

use omit to skip specific properties that are of no use in the applicable context.

omit=totalprice,totaltariff,result
accepts a comma separated list of values

totalprice : the price calculation for the resultset
totaltariff : the tariff calculation for the resultset
result : the paginated list of messages for the resultset
Omitting some of these properties can result in smaller and faster responses.

Recipient

use recipient to filter by receiver of a transaction

recipient=0031601234567
accepts a comma separated list of recipients

direction=out (default) , recipient usually is a mobile phonenumber (msisdn)
direction=in , recipient usually is a shortcode or longcode
Reference
use reference to filter by customer provided reference

reference=customer-known-identifier
accepts comma separated list of references

Sender

use sender to filter by sendername of a transaction

sender=3669
sender=0031601234567
accepts comma separated list of senders

direction=out (default) , sender is usually a companyname, shortcode or longcode
direction=in , sender is usually a mobile phonenumber (msisdn)

SMSCampaign

Getting all transactions that belong to a certain SMS-Campaign can be filtered using this parameter.

smscampaign={smscampaign.identifier}
Your SMS Campaign identifier is a GUID, which you can find in the URL of the campaign-edit-view before hand, and in the CustomGrouping property of messages that are sent out (and in) for a specific campaign.

Statuscode

use statuscode to filter by statuscode as returned by this api

statuscode=20
accepts comma separated list of integers

analyticserrors list

19 = Sent To Operator
20 = Delivered
21 = Failed
22 = Cancelled
37 = Accepted By Operator
40 = Rejected By Operator

Pagination

Pagesize

use pagesize to set the pageSize property in the pagination object

pagesize=10
default value : 1000
maximum value : 7500

Startat

use startat to set the currentPage property in the pagination object

startat=7
default value : 1
use the pagination object to determine the max value

Negate

use negate to invert a filter

negate=statuscode
accepts a comma separated list of parameter keys

For example, to filter for all messages to recipients outside The Netherlands, supply the countryiso parameter with the value you want to negate, and supply the negate parameter with that parameter-key.

?startdate=...&endate=...&countryiso=nl&negate=countryiso

Extra Resources

On this API there is not only a /transactions/ resource available, but also a few extra resources to help you out with getting values for a few filters.

Countries

In this resource you can find all known countries with their ISO code for us in the country filters

/transactions/countries
[ { "iso": "AD", "name": "Andorra" }, ... ]

Errorcodes

All errorcodes to filter on.

/transactions/errorcodes
[ { "id": 0, "description": "Unknown recipient" }, ... ]

Mediums

All known Mediums aka Channels

/transactions/mediums
[ { "id": 1, "name": "SMS" }, ... ]

Operators

All known Operators with their MCC MNC

/transactions/operators
[ { "iso": "US", "mccmnc": "200053", "name": "Virgin Mobile" }, ... ]

Statuscodes

All known Status codes

/transactions/statuscodes
It currently produces this list of status codes

[ {  
    "id": 19,  
    "description": "Sent"  
},  
{  
    "id": 20,  
    "description": "Delivered"  
},  
{  
    "id": 21,  
    "description": "Failed"  
},  
{  
    "id": 22,  
    "description": "Cancelled"  
},  
{  
    "id": 37,  
    "description": "Accepted"  
},  
{  
    "id": 40,  
    "description": "Rejected"  
}]