Transactions API
PHP

Introduction

This API provides insight into all individual messages send through your account. A lot of details about every message are available, like deliverytime and the message content.

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.0/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

Envelope

The resultset is encapsulated in an envolope with 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

pagination

This object holds pagination information

  • currentPage
  • totalPages
  • pageSize

summary

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

  • startDate
  • endDate
  • totalTransactions

result

This array holds the resultset

Transaction object (out)

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

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

http status content-type description
200 application/json {
  • "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"
    • }
    ]
  • }

curl -i https://api.cmtelecom.com/v1.0/transactions/
     -G
     -H "X-CM-PRODUCTTOKEN: 0000000-0000-0000-0000-000000000000"
     -d startdate=2017-02-01
     -d enddate=2017-02-02
$headers = @{"X-CM-PRODUCTTOKEN"="my-cm-producttoken"}

$filters = @{
	startdate = "2017-02-22T17:00"
	enddate = "2017-02-22T18:00"
}

Invoke-RestMethod -Uri "https://api.cmtelecom.com/v1.0/transactions/"`
	-Method Get`
	-Headers $headers`
	-Body $filters

Transaction object (in)

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

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

http status content-type description
200 application/json {
  • "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"
    • }
    ]
  • }

curl -i https://api.cmtelecom.com/v1.0/transactions/
     -G
     -H "X-CM-PRODUCTTOKEN: 0000000-0000-0000-0000-000000000000"
     -d startdate=2017-02-01
     -d enddate=2017-02-02
     -d direction=in
$headers = @{"X-CM-PRODUCTTOKEN"="my-cm-producttoken"}

$filters = @{
	startdate = "2017-02-22T17:00"
	enddate = "2017-02-22T18:00"
	direction = "in"
}

Invoke-RestMethod -Uri "https://api.cmtelecom.com/v1.0/transactions/"`
	-Method Get`
	-Headers $headers`
	-Body $filters

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

Filtering transactions per Channel is possible through the Channel filter.

channel=SMS

channels

  • SMS
  • PUSH
Converted

use converted to filter by converted messages

converted=true

accepts a boolean value

Converted

  • converted=true
  • converted=false
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
Direction

Use the direction parameter to get transactions from a certain direction.

direction=out
direction=in

Available values

  • out (default)
  • in

OUT will filter outgoing messages (MT)

IN will filter incoming messages (MO)

Errorcode

use errorcode to filter by errorcodes as returned by this api

errorcode=5

accepts a comma separated list of integers

MCC MNC

use mccmnc to filter by recipients at specific operators

mccmnc=20404

accepts a comma separated list of operator identification codes

mccmnc?

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

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 some timeconsuming operations and speed up the response.

omit=totalprice,totaltariff

accepts a comma separated list of values

  • totalprice : the price calculation for the resultset
  • totaltariff : the tariff sum calculation for the resultset

These properties are in the summary property of the JSON.

Since these operations can take quite some time for big resultsets, you can choose to omit these if you do not need them.

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 yout want te 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

[ { "id": 19, "description": "Sent" }, ... ]