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."
}

TelecomsXChange Support

DID Buyers API

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

API Authentication

API Parameters

API Methods.

View DIDs market

Purchase DID

List Purchased DID numbers

Unsubscribe from DID

Update DID

DID Buyers API

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

API Authentication

API Parameters

API Methods.

View DIDs market

Purchase DID

List Purchased DID numbers

Unsubscribe from DID

Update DID

Related Articles