DID Exchange application programming interface (API) documentation for buyers.


This document covers API access to TCXC buyers functions related to DID numbers. 


The API users can: View DIDs, Purchase DIDs, List purchased DID, Unsubscribe from purchased DIDs. 


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.


Example with success:


{
    "status": "success",
    "message": "DID entry has been updated."
}



Example with errors:




{
    "status": "error",
    "message": "This DID can not be purchased, it has been already sold"
}


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 POST method, but you may also use GET if the size of parameters allows you to:


View DIDs market


Endpointhttps://api.telecomsxchange.com/number/market
Controller Namedids_market


POST /number/market 


Returns DID numbers available for purchase along with detailed information for each DID number in “dids” array of the response.


Supported parameters:



Parameter NameIs RequiredDescription 
“prefix”optionalmay contain search prefix, for example “44” for UK numbers.
“country”optionalmay contain country name to search for, for example “UNITED ARAB EMIRATES”
“description”optionalmay contain description for the area of the number, i.e. “Mobile - Etisalat”
“seller”
optionalallows to search for DIDs only of selected seller, example ”Nexmo
“voice”optionalMay contain value 0 or 1 to search for DIDs with capability “VOICE”
“sms"optionalMay contain value 0 or 1 to search for DIDs with capability “SMS”
“fax”optionalMay contain value 0 or 1 to search for DIDs with capability “Video”
“video”optionalMay contain value 0 or 1 to search for DIDs with capability “fax”
“did_type"optionalMay contain special values “any” for any numbers, “national” for National numbers, “mobile” for Mobile DIDs, “tollfree” for Toll Free numbrs, “unknown” for Grey numbers.
"pager", "off"required

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




Sample Successful Response:

DID Exchange API Response:

:{
            "status": "success",
            "dids": [
                {
                    "country": "US",
                    "msisdn": "19542374274",
                    "cost": "0.90",
                    "type": "mobile-lvn",
                    "features": [
                        "VOICE",
                        "SMS"
                    ],
                    "monthly_fee": "2.1944",
                    "number": "19542374274",
                    "smpp_price": "0.0069",
                    "price_1": "0.0055",
                    "setup_fee": "0.0000",
                    "capacity": 50,
                    "voice": 1,
                    "sms": 1,
                    "video": 0,
                    "fax": 0,
                    "verification_required": 0,
                    "interval_1": 60,
                    "interval_n": 60,
                    "did_type": "mobile",
                    "vendor_name": "Nexmo",
                    "is_nexmo": 1,
                    "country_code": "us",
                    "country_name": "United States of America",
                    "description": "Mobile - T-Mobile",
                    "price_n": "0.0055"
                },


P.S: When verification required = 1, the DID provided must receive verification documents from buyer before the DID is activate and ready for use.


PHP Sample Script:


<?php

// My login in TCXC - Your TCXC username
$api_login ="AcmeInc";

//My API key - Generated from TCXC Portal
$api_key = "{ENTER YOUR API-KEY}";
// initialising CURL

// initialising CURL
$ch = curl_init();

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

//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);

$prefix = '380';
$did_type = 'any';

$params = array(
                'ts' => $ts,  //Provide TS
                'signature' => $signature,
                'webapi' => '1',   //required field by tcxc api
                'api_login' => $api_login,
                'searchform' => '1',  //required field
                'did_type' => $did_type,
                'prefix' => $prefix
                );


//Query against api. URL

curl_setopt($ch, CURLOPT_URL,"http://api.telecomsxchange.com/$controller.php");

//api.telecomsxchange.com
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);




?>




Purchase DID




Endpoint:https://api.telecomsxchange.com/number/purchase
Controller namepurchase_did 


Allows to purchase a certain DID number using certain billing account and point it to SIP/SMPP contact.


Supported parameters:


Parameter NameIs required Description
“i_did”
YesID of the did you want to purchase
“billing_i_account”Yesid of your billing account on file, found under Accounts page in portal
“contact”Yes(required for VOICE, VIDEO, FAX enabled DIDs) SIP contact for the DID number to be sent to, example “sip:12345abc@sip.domain.com:5060”
“smpp_contact”Yes (only for sms enabled numbers)

SMPP contact for the DID number to be sent to, example “smpp:login:pass:12345abc@smpp.domain.com:2776”




PHP Code Example:


<?php

// My login in TCXC - Your TCXC username
$api_login ="AcmeInc";

//My API key - Generated from TCXC Portal
$api_key = "{ENTER YOUR API-KEY}";

// initialising CURL

// initialising CURL
$ch = curl_init();

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

//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);

$i_did = '10';
$billing_i_account = 1 ;
$contact = "sip:380673333333@192.168.3.1:5060";
$smpp_contact = "smpp:login:password:380673333333@192.168.3.1:2776";

$params = array(
                'ts' => $ts,  //Provide TS
                'signature' => $signature,
                'webapi' => '1',   //required field by tcxc api
                'api_login' => $api_login,
                'add' => '1',  //required field
                'i_did' => $i_did,
                'billing_i_account' => $billing_i_account,
                'contact' => $contact,
                'smpp_contact' => $smpp_contact
                );


//query against api. URL

curl_setopt($ch, CURLOPT_URL,"http://members.telecomsxchange.com/$controller.php");
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);


?>






List Purchased DID numbers


Endpointhttps://api.telecomsxchange.com/numbes/list
Controller Namec_dids


Allows to list purchased DID numbers.


Supported parameters:

  • “prefix” (optional) may contain search prefix, for example “44” for UK numbers.

  • “country” (optional) may contain country name to search for, for example “UNITED ARAB EMIRATES”

  • “description” (optional) may contain description for the area of the number, i.e. “Mobile - Etisalat”

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


PHP Code Example:


<?php

// My login in TCXC - Your TCXC username
$api_login ="AcmeInc";

//My API key - Generated from TCXC Portal
$api_key = "{ENTER YOUR API-KEY}";
// initialising CURL

// initialising CURL
$ch = curl_init();

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

//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);

$prefix = '380';

$params = array(
                'ts' => $ts,  //Provide TS
                'signature' => $signature,
                'webapi' => '1',   //required field by tcxc api
                'api_login' => $api_login,
                'searchform' => '1',  //required field
                'prefix' => $prefix
                );


//query against api. URL
curl_setopt($ch, CURLOPT_URL,"http://members.telecomsxchange.com/$controller.php");

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 Successful Response:


server_output:{
    "status": "success",
    "dids": [
        {
            "i_did": "1",
            "number": "380671234567",
            "price_1": "0.1430",
            "price_n": "0.2640",
            "interval_1": "60",
            "interval_n": "60",
            "monthly_fee": "21.9890",
            "setup_fee": "6.6000",
            "i_vendor": "9",
            "status": "purchased",
            "contact": "sip:380671234568@12.23.34.12:5060",
            "smpp_contact": "smpp:login:password:380671234567@12.23.34.12:2776",
            "notes": "note for this DID",
            "billed_to": "2019-09-15 12:55:19",
            "monthly_start_ts": "2019-09-15 12:55:19",
            "voice": "1",
            "sms": "1",
            "fax": "1",
            "video": "1",
            "capacity": "2",
            "did_type": "unknown",
            "verification_required": "0",
            "documents_verified": "0",
            "smpp_price": "0.1100",
            "is_nexmo": "0",
            "account_name": "Demo",
            "vendor_name": "Acme",
            "country_code": "ua",
            "country_name": "UKRAINE",
            "description": "Mobile - Kyivstar"
        },
        {
            "i_did": "60",
            "number": "380678888888",
            "price_1": "0.1100",
            "price_n": "0.1100",
            "interval_1": "1",
            "interval_n": "1",
            "monthly_fee": "1.1000",
            "setup_fee": "1.1000",
            "i_vendor": "9",
            "status": "purchased",
            "contact": "sip:380671234568@12.23.34.12:5060",
            "smpp_contact": "smpp:perftest:perftest:380677777777@108.61.167.86:2776",
            "notes": "",
            "billed_to": "2019-09-15 13:11:39",
            "monthly_start_ts": "2019-09-15 13:11:39",
            "voice": "1",
            "sms": "1",
            "fax": "0",
            "video": "0",
            "capacity": "2",
            "did_type": "unknown",
            "verification_required": "1",
            "documents_verified": "1",
            "smpp_price": "0.0330",
            "is_nexmo": "0",
            "account_name": "Demo",
            "vendor_name": "Acme",
            "country_code": "ua",
            "country_name": "UKRAINE",
            "description": "Mobile - Kyivstar"
        }
    ]
} 


P.S: documents_verified = 1 means that the DID provided has verified the buyers KYC documents and it's ready for use, if the value is 0, the DID is added to your list but is still waiting verification by seller before it become active and functional.



Unsubscribe from DID


Endpointhttps://api.telecomsxchange.com/number/unsubscribe
Controller Namec_dids


Description:  “unsubscribe” (required) i_did identifier of the DID number to unsubscribe from. 

Allows to unsubscibe from certain DID number.





Parameters :


Parameter NameRequiredDescription
"I_did"YesAllows to unsubscribe from individual DID number previously purchased




PHP Code Example:


<?php

// My login in TCXC - Your TCXC username
$api_login ="AcmeInc";

//My API key - Generated from TCXC Portal
$api_key = "{ENTER YOUR API-KEY}";

// initialising CURL
$ch = curl_init();

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

//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);

$unsubscribe = '60';

$params = array(
                'ts' => $ts,  //Provide TS
                'signature' => $signature,
                'webapi' => '1',   //required field by tcxc api
                'api_login' => $api_login,
                'unsubscribe' => $unsubscribe
                );


//query against api. URL

curl_setopt($ch, CURLOPT_URL,"https://api.telecomsxchange.com/$controller.php");
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 Successful Response:

server_output:{
    "status": "success",
    "message": "Unsubscribed successfully"
} 


P.S: This action is irreversible . As soon as you unsubscribed from purchased DID it will be back on the exchange and may be purchased by another buyer.


Sample Response with Error:

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




Update DID


Endpointhttps://api.telecomsxchange.com/number/update
Controller Namec_dids


Allows to update contact/smpp_contact of the purchased DID number.


Supported parameters:



Paramater NameIs requiredDescription
"edit"Yesi_did identifier of the DID number to be edited
"contact"YesSIP contact for the DID number to be sent to, example “sip:12345abc@sip.domain.com:5060”
“smpp_contact”YesSMPP contact for the DID number to be sent to, example “smpp:login:pass:12345abc@smpp.domain.com:2776”



 PHP Code Example:


<?php

// My login in TCXC - Your TCXC username

 $api_login ="AcmeInc";

//My API key - Generated from TCXC Portal

 $api_key = "{ENTER YOUR API-KEY}";

// initialising CURL
$ch = curl_init();

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

//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);

$edit = '1';     // this is the i_did value for 380673333333
$contact = "sip:380673333333@192.168.3.2:5060";   // sip contact details
$smpp_contact = "smpp:did:did:380673333333@192.168.3.1:2776"; // smpp contact details

$params = array(
                'ts' => $ts,  //Provide TS
                'signature' => $signature,
                'webapi' => '1',   //required field by tcxc api
                'api_login' => $api_login,
                'submit_edit' => 1, //required
                'edit' => $edit,
                'contact' => $contact,
                'smpp_contact' => $smpp_contact
                );


// Query against api. URL

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

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);


?>



Success Response:


{
    "status": "success",
    "message": "DID entry has been updated."
}


Incase of any error:


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