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

Calls to the API endpoint are authenticated by your producttoken.

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

Provide the header X-CM-PRODUCTTOKEN with your producttoken as value.

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",
    • "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
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
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)
Statuscode

use statuscode to filter by statuscode as returned by this api

statuscode=20

accepts comma separated list of integers

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