Introduction

This API provides insight into every individual message sent through your account. You can use this to get all details on your sent and received message.

Authentication

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

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

For authenticating with your product token provide the header X-CM-PRODUCTTOKEN with your product token 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 result set is encapsulated in an envelope which contains information about the result set.

📘

There are no transactions available with these parameters , when an empty result set is returned

summary

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

pagination

This object holds pagination information

result

This array holds the result set

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": "2024-10-22T08:30:00+02:00",
        "endDate": "2024-10-22T09:00:00+02:00",
        "direction": "out",
        "totalTransactions": 3,
        "totalPrice": 0,
        "priceCurrency": "EUR",
        "localPrice": 0,
        "localCurrency": "USD",
        "totalTariff": 0
    },
    "result": [
        {
            "sender": "009190000000",
            "recipient": "009190000000",
            "message": "",
            "standarderror": null,
            "errordescription": "",
            "status": 20,
            "statusdescription": "Delivered",
            "created": "2024-10-22T08:51:55+02:00",
            "countryiso": "IN",
            "countryname": "India",
            "mccmnc": "404997",
            "operatorname": "IN - Unspecified operator",
            "deliverytime": 7,
            "datacodingscheme": 0,
            "userdataheader": "",
            "channel": "WhatsApp",
            "price": 0,
            "currency": "EUR",
            "localPrice": 0,
            "localCurrency": "USD",
            "tariff": 0,
            "premium": false,
            "customgrouping": null,
            "customgrouping2": null,
            "customgrouping3": null,
            "reference": "47ce194c-7f83-4c05-ad1a-46697dd86a3e",
            "converted": null,
            "direction": "out",
            "multipart": null,
            "readbyrecipient": "2024-10-22T09:22:31+02:00"
        },
        {
            "sender": "0096500000000",
            "recipient": "0096500000000",
            "message": "",
            "standarderror": null,
            "errordescription": "",
            "status": 20,
            "statusdescription": "Delivered",
            "created": "2024-10-22T08:37:33+02:00",
            "countryiso": "KW",
            "countryname": "Kuwait",
            "mccmnc": "419997",
            "operatorname": "KW - Unspecified operator",
            "deliverytime": 4,
            "datacodingscheme": 0,
            "userdataheader": "",
            "channel": "WhatsApp",
            "price": 0,
            "currency": "EUR",
            "localPrice": 0,
            "localCurrency": "USD",
            "tariff": 0,
            "premium": false,
            "customgrouping": null,
            "customgrouping2": null,
            "customgrouping3": null,
            "reference": "caea1acb-ae28-414d-916b-3a208c8dd983",
            "converted": null,
            "direction": "out",
            "multipart": null,
            "readbyrecipient": "2024-10-22T18:40:49+02:00"
        },
        {
            "sender": "0096500000000",
            "recipient": "0096500000000",
            "message": "",
            "standarderror": null,
            "errordescription": "",
            "status": 20,
            "statusdescription": "Delivered",
            "created": "2024-10-22T08:33:50+02:00",
            "countryiso": "KW",
            "countryname": "Kuwait",
            "mccmnc": "419997",
            "operatorname": "KW - Unspecified operator",
            "deliverytime": 5,
            "datacodingscheme": 0,
            "userdataheader": "",
            "channel": "WhatsApp",
            "price": 0,
            "currency": "EUR",
            "localPrice": 0,
            "localCurrency": "USD",
            "tariff": 0,
            "premium": false,
            "customgrouping": null,
            "customgrouping2": null,
            "customgrouping3": null,
            "reference": "bf350100-12d0-499f-b1ea-3478c53cba6c",
            "converted": null,
            "direction": "out",
            "multipart": null,
            "readbyrecipient": "2024-10-22T08:34:03+02:00"
        }
    ]
}

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.

{
    "message": "Ok",
    "pagination": {
        "currentPage": 1,
        "pageSize": 1000,
        "totalPages": 1
    },
    "result": [
        {
            "channel": "SMS",
            "countryiso": "NL",
            "countryname": "Netherlands",
            "created": "2025-02-01T23:58:20+01:00",
            "customgrouping": null,
            "customgrouping2": null,
            "customgrouping3": null,
            "datacodingscheme": 0,
            "direction": "in",
            "mccmnc": "20404",
            "message": "I love CM.com's transaction API",
            "operatorname": "NL - Vodafone",
            "premium": false,
            "price": 0,
            "recipient": "3669",
            "reference": "510661747",
            "sender": "0031601234567",
            "status": null,
            "tariff": 0,
            "userdataheader": ""
        }
    ],
    "status": 1,
    "summary": {
        "direction": "in",
        "endDate": "2025-02-02T00:00:00+01:00",
        "startDate": "2025-02-01T00:00:00+01:00",
        "totalTransactions": 1
    }
}

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

Channel

use channel for filtering transactions per Channel.

Available Channels

Converted

use converted to filter by converted messages

CountryISO

use countryiso to filter by recipients in specific countries

Example

countryiso=NL,DE,FR (Netherlands, Germany, France)

Direction

Direction Values

• out (default): Country code of the recipient
• in: Country code of the sender

Customgrouping

use the customgrouping parameters to filters on all provided customgroupings

Example

customgrouping=reference1,reference2,reference3

Errorcode

use errorcode to filter by errorcodes as returned by this api

Example

errorcode=1,3,5 (Unknown failure, Recipient temporarily unavailable, Message rejected by operator)

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

Example

mccmnc=20404,20405 (Operator IDs for specific recipients)

Message

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

Example

message=This very specific message
message=This*message (Uses * as a wildcard)

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.

Example 1: Show only first part of multipart messages

multipart=firstpartonly

Example 2: Show all parts of a specific multipart message

multipart={multipart.identifier}
(Recommended to use in combination with the Recipient filter)

Omit

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

Example

omit=totalprice,totaltariff,result
Omit totalprice, totaltariff, and result for smaller, faster responses.

Property Descriptions:

• totalprice: The price calculation for the result set
• totaltariff: The tariff calculation for the result set
• result: The paginated list of messages for the result set

Recipient

use recipient to filter by receiver of a transaction

Example 1: Filtering by recipient

recipient=0031601234567,0031607654321

Example 2: Filtering by direction

direction=out (default, recipient is a mobile phone number)
direction=in (recipient is a shortcode or longcode)

Example 3: Filtering by reference

reference=customer-known-identifier1,customer-known-identifier2

Sender

use sender to filter by sendername of a transaction

Example 1: Filtering by sender

sender=3669,0031601234567

Example 2: Filtering by direction

direction=out (default, sender is usually a company name, shortcode, or longcode)
direction=in (sender is usually a mobile phone number (msisdn))

SMSCampaign

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

Example

smscampaign={smscampaign.identifier}
Your SMS Campaign identifier is a GUID, which can be found in the URL of the campaign-edit-view or in the CustomGrouping property of messages.

Statuscode

use statuscode to filter by statuscode as returned by this api

Example

statuscode=20,21,40 (Delivered, Failed, Rejected By Operator)

Status Codes

Pagination

Pagesize

use pagesize to set the pageSize property in the pagination object

Example

pagesize=10
(Default value is 1000, maximum value is 7500)

Startat

use startat to set the currentPage property in the pagination object

Example

startat=7
(Default value is 1, max value is determined by the pagination object)

Negate

use negate to invert a filter

Example

negate=statuscode
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=...&enddate=...&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

Example

You can use this resource to find all known countries with their ISO code for use in country filters:
/transactions/countries
Returns a list like:
[ { "iso": "AD", "name": "Andorra" }, ... ]

Errorcodes

All errorcodes to filter on.

/transactions/errorcodes

Example

You can use this resource to find all known error codes and their descriptions:
/transactions/errorcodes
Returns a list like:
[ { "id": 0, "description": "Unknown recipient" }, ... ]

Mediums

All known Mediums aka Channels

/transactions/mediums

Example

You can use this resource to find all available mediums:
/transactions/mediums
Returns a list like:
[ { "id": 1, "name": "SMS" }, ... ]

Operators

All known Operators with their MCC MNC

/transactions/operators

Example

You can use this resource to find all available operators:
/transactions/operators
Returns a list like:
[ { "iso": "US", "mccmnc": "200053", "name": "Virgin Mobile" }, ... ]

Statuscodes

All known Status codes

/transactions/statuscodes

Example

You can use this resource to find all available status codes:
/transactions/statuscodes

Returns this list:

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