This document covers API access to TCXC buyers functions related to Call Detail Records (CDRs)


The API users can: List call history for buyer account. 


API Authentication



Each API access call must be authenticated. In this API , there are 3 (three) HTTPS parameters are required to be supplied to verify the authenticity of the API caller:


  1. Parameter name: “ts”, value: current unix timestamp of the call.

  2. Parameter name: “api_login”, value: your buyer login in TCXC.

  3. Parameter name: “signature”, value: signature of the request which is a SHA256 hash of the concatenated string of the controller name, the API key  is generated from TCXC portal under preferences option, the TCXC buyer login and the string value of the unxi timestamp associated with the request. 



Generating signature (PHP example):

$signature = hash( 'sha256', $controller .  $api_key   . $api_login  . $ts);




Sample Signature Error API Response:


:{
    "error": "Wrong signature",
    "status": "fail"
}




If you have any issues with this secure API Authentication method, please contact us.



API Parameters

Are to be supplied as HTTP POST/GET parameters.



Is provided in JSON format. Each call returns “status” parameter indicating either “success” or “error” for the requested operation and “message” containing human readable description of the operation status. Response may contain other parameters depending on the call.


Success

{
    "status": "success",
}


incase of error:

server_output:{
    "status": "error",
    "message": "There was an error."
} 




API Methods.

Each API method has its controller name which is used for authentication. Method should be called using GET or POST method, but you may also use GET if the size of parameters allows you to:



Endpointhttps://api.telecomsxchange.com/buyers/callhistory


Controller Namec_cdrs



Supported parameters:



Parameter NameIs RequiredDescription 
“prefix”optionalmay contain search prefix, for example “44” for listing only CDRs for destination U.K, leave empty to get all CDRs
“show”Yes *required*
"all" will show all success and failed CDRs, default value is "all"
"date_from"optionalStarting Date, e.g 2018-09-24 17:49:30
“date_to”
optionalEnd Date, e.g 2019-09-24 00:00:00


"pager", "off"Yes *required*

“pager” is a limit of the numbers to be returned.

"off"yes *required*

“off” (should be set or unset) allow to limit and paginate results. “pager” is a limit of the numbers to be returned, “off” is offset.





Success Response:





Incase of any error:


server_output:{
    "status": "error",
    "message": "There was an error."
} 





Quick Start Script

<?php

// TCXC BUYER LOGIN
$api_login ="YOUR BUYER LOGIN";

//TCXC Buyer API KEY
$api_key = "KEY";


// initialising CURL
$ch = curl_init();

//controller is a script name, so in case lookup.php controller is lookup
$controller = "c_cdrs";

//unix timestamp to ensure that signature will be valid temporary
$ts = time();


//compose signature concatenating controller api_key api_login and unix timestamp
$signature = hash( 'sha256', $controller .  $api_key   . $api_login  . $ts);


$params = array(
                'ts' => $ts,  //Provide TS
                'signature' => $signature,
                'api_login' => $api_login,
                'prefix' => '',          //Country Prefix
                'show' => 'all',       // Show Success and Failed
                'date_from' => '2018-09-24 17:49:30', // DATE FROM
                'date_to' => '2019-09-25 17:49:30'.    // DATE TO
                );


curl_setopt($ch, CURLOPT_URL,"https://api.telecomsxchange.com/buyers/callhistory");

curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_VERBOSE, true);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$server_output = curl_exec ($ch);
echo "server_output:$server_output \nparams:".http_build_query($params);


?>


Sample Response:


 {
            "i_cdr": "77",
            "CLD": "12014705652", // Destination Number
            "CLI": "18552334464", // Caller ID
            "call_id": "31491e97655c19c10c70981c33635a19", // SIP Call-ID
            "duration": "0",
            "billed_duration": null,
            "connect_time": "2019-08-27 17:45:11",
            "disconnect_time": "2019-08-27 17:45:11",
            "setup_time": "2019-08-27 17:45:11",
            "billing_prefix": "1201470565",
            "billing_price_1": 0.004987,
            "billing_price_n": 0.004987,
            "billing_interval_1": "6",
            "billing_interval_n": "6",
            "customer_amount": "0.000000",
            "i_customer": "1",
            "i_account": "10",
            "i_vendor": "13",
            "i_connection": "0",
            "i_purchased_route": "0",
            "disconnect_code": "16",
            "customer_ip": "",
            "i_rate": "0",
            "vendor_name": "IDT",
            "account_name": "SBC-3001",
            "connection_name": null,
            "disconnect_reason": "Normal Call Clearing",
            "country_name": "United States of America",
            "description": "Fixed - ROC"
        },