Visit our new API Documentation portal.
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:
Parameter name: “ts”, value: current unix timestamp of the call.
Parameter name: “api_login”, value: your buyer login in TCXC.
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
Endpoint | https://api.telecomsxchange.com/number/market |
Controller Name | dids_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 Name | Is Required | Description |
---|---|---|
“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” |
“seller” | optional | allows to search for DIDs only of selected seller, example ”Nexmo” |
“voice” | optional | May contain value 0 or 1 to search for DIDs with capability “VOICE” |
“sms" | optional | May contain value 0 or 1 to search for DIDs with capability “SMS” |
“fax” | optional | May contain value 0 or 1 to search for DIDs with capability “Video” |
“video” | optional | May contain value 0 or 1 to search for DIDs with capability “fax” |
“did_type" | optional | May 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 name | purchase_did |
Allows to purchase a certain DID number using certain billing account and point it to SIP/SMPP contact.
Supported parameters:
Parameter Name | Is required | Description |
“i_did” | Yes | ID of the did you want to purchase |
“billing_i_account” | Yes | id 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
Endpoint | https://api.telecomsxchange.com/numbes/list |
Controller Name | c_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
Endpoint | https://api.telecomsxchange.com/number/unsubscribe |
Controller Name | c_dids |
Description: “unsubscribe” (required) i_did identifier of the DID number to unsubscribe from.
Allows to unsubscibe from certain DID number.
Parameters :
Parameter Name | Required | Description |
---|---|---|
"I_did" | Yes | Allows 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
Endpoint | https://api.telecomsxchange.com/number/update |
Controller Name | c_dids |
Allows to update contact/smpp_contact of the purchased DID number.
Supported parameters:
Paramater Name | Is required | Description |
---|---|---|
"edit" | Yes | i_did identifier of the DID number to be edited |
"contact" | Yes | SIP contact for the DID number to be sent to, example “sip:12345abc@sip.domain.com:5060” |
“smpp_contact” | Yes | 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 $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." }