DID Exchange

TCXC DID Exchange, enables modern communication providers (buyers/sellers) to programmatically buy and/or sell virtual phone numbers on the exchange after pointng them via SIP/SMPP protocols.

The DID exchange APIs are critical in a modern digitized communication provider(s).

The API enables:

Buyers:

  • Search Available DIDs
  • Buyer/Purchase DIDs
  • List purchased DIDs
  • Unsubscribe/Canel purchased DID(s)

Seller:

  • List/Filter DID(s)
  • Update existing DIDs record (change price, change billing interval, etc..)
  • Sell new voice and SMS enabled DID number(s)
  • Control status/visbility of DIDs on the market
  • Control capabilities and capacity of DID(s)
Base URLhttps://apiv2.telecomsxchange.com
AuthenticationHTTP Digest

Selling DIDs

This API set allows seller to sell/add a new voice or sms enabled phone number and list it for sale on the public exchange.

#Add / Sell New DID Number

POSThttps://apiv2.telecomsxchange.com/sellers/did/add

This API endpoint allows authenticated sellers to sell a new DID/Phone number on the exchange.

Prerequisites:

  • Point your voice DID(s) via SIP protocol to sip01.telecomsxchange.com
  • Point your SMS DID(s) via SMPP v.5.x or v.3.x to smpp01.telecomsxchange.com port:2776

Body parameters

application/x-www-form-urlencoded
numberintegerrequired

Unique DID Number ( Virtual Phone Number ) being sold for the first time

Example 19542405099

price_1numberrequired

Incoming Voice call price in USD per minute

Example 0.001

interval_1integerrequired

Billing Interval - Seconds or Minutes (60 for minutes and 1 for seconds)

Example 60

monthly_feeintegerrequired

Monthly reccuring DID charge

Example 10

setup_feenumberrequired

One time setup fee - charges once on purchase

Example 1.00

did_typestringrequired

the phone number type (national, mobile, toll free or grey)

Example mobile

voiceintegerrequired

Voice enabled (1 for yes and 0 for no)

Example 1

smsintegerrequired

SMS enabled ( (1 for yes and 0 for no)

Example 0

curl --digest \
  -u "$TCXC_USERNAME:$TCXC_API_KEY" \
  -X POST \
  "https://apiv2.telecomsxchange.com/sellers/did/add" \
  -d "number=19542405099" \
  -d "price_1=0.001" \
  -d "interval_1=60" \
  -d "monthly_fee=10" \
  -d "setup_fee=1.00" \
  -d "did_type=mobile" \
  -d "voice=1" \
  -d "sms=0" \
  -d "fax=0" \
  -d "video=0" \
  -d "smpp_price=0.00" \
  -d "capacity=5" \
  -d "status=blocked"
Listing result
SuccessThe DID has been successfully added.
Rendered from the example response.

#List DIDs

POSThttps://apiv2.telecomsxchange.com/sellers/did/list

List the seller DIDs with optional POST parameter prefix for DIDs list

Query parameters

prefixintegeroptional

Optional prefix filter

Example 1

Body parameters

application/x-www-form-urlencoded
prefixintegerrequired

Optional - Filter DIDs by starting prefix

Example 380

curl --digest \
  -u "$TCXC_USERNAME:$TCXC_API_KEY" \
  -X POST \
  "https://apiv2.telecomsxchange.com/sellers/did/list" \
  -d "prefix=380"
Your numbers1 number
+380670493246idle
UKRAINE · Mobile - Kyivstar
$10.00/month$10.00setup$0.1000/min
voicesms
Rendered from the example response.

#Update DID Record

POSThttps://apiv2.telecomsxchange.com/sellers/did/edit/{i_did}

This API endpoint allows authenticated sellers to update an existing DID/Phone number on the exchange.

Path parameters

i_didintegerrequired

ID of the DID record to update, as returned by List DIDs.

Example 46

Body parameters

application/x-www-form-urlencoded
numberintegerrequired

Unique DID Number ( Virtual Phone Number ) being sold for the first time

Example 19542405099

price_1numberrequired

Incoming Voice call price in USD per minute

Example 0.001

interval_1integerrequired

Billing Interval - Seconds or Minutes (60 for minutes and 1 for seconds)

Example 60

monthly_feeintegerrequired

Monthly reccuring DID charge

Example 10

setup_feenumberrequired

One time setup fee - charges once on purchase

Example 1.00

did_typestringrequired

the phone number type (national, mobile, toll free or grey)

Example mobile

voiceintegerrequired

Voice enabled (1 for yes and 0 for no)

Example 1

smsintegerrequired

SMS enabled ( (1 for yes and 0 for no)

Example 0

curl --digest \
  -u "$TCXC_USERNAME:$TCXC_API_KEY" \
  -X POST \
  "https://apiv2.telecomsxchange.com/sellers/did/edit/46" \
  -d "number=19542405099" \
  -d "price_1=0.001" \
  -d "interval_1=60" \
  -d "monthly_fee=10" \
  -d "setup_fee=1.00" \
  -d "did_type=mobile" \
  -d "voice=1" \
  -d "sms=0" \
  -d "fax=0" \
  -d "video=0" \
  -d "smpp_price=0.00" \
  -d "capacity=5" \
  -d "status=blocked"
Update result
SuccessDID entry has been updated.
Rendered from the example response.

Buying DIDs

This API set allows buyers to search/buy/cancel DID numbers (aka. Virtual Numbers) from sellers (Modern Telecom Operators selling their phone numbers virtually)

#Search DID Market View

POSThttps://apiv2.telecomsxchange.com/number/market

This API lets you search for incoming local and/or toll-free phone numbers that are available for you to purchase.

Body parameters

application/x-www-form-urlencoded
prefixintegerrequired

The phone number, in E.164 (i.e. "1954") format.

Example 1954

countrystringrequired

The country name - string - (i.e. "Nigeria")

Example United Kingdom

descriptionstringrequired

The network description - string - (i.e. "MTN")

Example Mobile

sellerstringoptional

String - e.g "Nexmo"

Example Nexmo

voiceintegerrequired

May contain value 0 or 1 to search for DIDs with capability “VOICE”

Example 1

smsintegerrequired

May contain value 0 or 1 to search for DIDs with capability “SMS”

Example 1

faxintegerrequired

May contain value 0 or 1 to search for DIDs with capability “fax”

Example 0

videointegerrequired

May contain value 0 or 1 to search for DIDs with capability “Video”

Example 0

curl --digest \
  -u "$TCXC_USERNAME:$TCXC_API_KEY" \
  -X POST \
  "https://apiv2.telecomsxchange.com/number/market" \
  -d "prefix=1954" \
  -d "country=United Kingdom" \
  -d "description=Mobile" \
  -d "voice=1" \
  -d "sms=1" \
  -d "fax=0" \
  -d "video=0" \
  -d "did_type=any" \
  -d "pager=5" \
  -d "off=0"
Available numbers3 numbers
+441861020078idle
UNITED KINGDOM · Fixed - ROC
$5.50/month$1.10setup$0.0011/min
no capabilities set
+447523410070idle
UNITED KINGDOM · Mobile - Tismi · mobile
$5.00/month$5.00setup$0.1000/min
voicesms
+447913314252idle
UNITED KINGDOM · Mobile - O2 · mobile
$1.00/month$1.00setup$0.0200/min
voicesmsfaxvideo
Rendered from the example response.

#Purchase DID

POSThttps://apiv2.telecomsxchange.com/number/purchase

This method allows you to purchase phone numbers (DIDs).

Body parameters

application/x-www-form-urlencoded
i_didintegerrequired

ID of the did you want to purchase

Example 25

billing_i_accountintegerrequired

id of your billing account on file, found under Accounts page in portal, use List buyer accounts API to discover your billing i_account id.

Example 1022

contactstringrequired

Primary SIP Address e.g SIP: E.164@162.13.42.203

Example sip:12345abc@sip.domain.com:5060

contact2stringrequired

Failover SIP Address e.g SIP: E.164@162.13.42.203

Example sip:12345abc@sip.domain.com:5060

smpp_contactstringrequired

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

Example smpp:login:pass:12345abc@smpp.domain.com:2776

curl --digest \
  -u "$TCXC_USERNAME:$TCXC_API_KEY" \
  -X POST \
  "https://apiv2.telecomsxchange.com/number/purchase" \
  -d "i_did=25" \
  -d "billing_i_account=1022" \
  -d "contact=sip:12345abc@sip.domain.com:5060" \
  -d "contact2=sip:12345abc@sip.domain.com:5060" \
  -d "smpp_contact=smpp:login:pass:12345abc@smpp.domain.com:2776"
Purchase result
SuccessDID has been purchased
Rendered from the example response.

#List Purchased DIDs

POSThttps://apiv2.telecomsxchange.com/number/list

Retrieve the list of DID numbers purchased on your TCXC account, with optional pagination and filtering by status and other attributes.

Body parameters

application/x-www-form-urlencoded
prefixintegerrequired

Filter results starting with Country Code (Prefix) e.g 971 will show all numbers that start with 971

Example 44

countrystringrequired

Filter results starting with Country Name e.g United will show all numbers that start with United

Example United Kingdom

descriptionstringrequired

Filter results starting with description e.g Mobile will show all numbers that start with description Mobile

Example Mobile

pagerintegerrequired

Example 5

offintegerrequired

Example 0

curl --digest \
  -u "$TCXC_USERNAME:$TCXC_API_KEY" \
  -X POST \
  "https://apiv2.telecomsxchange.com/number/list" \
  -d "prefix=44" \
  -d "country=United Kingdom" \
  -d "description=Mobile" \
  -d "pager=5" \
  -d "off=0"
Your numbers2 numbers
+971501021800purchased
UNITED ARAB EMIRATES · Mobile - Etisalat · national
$0.00/month$0.00setup$0.0000/min
voicesms
+971500808365purchased
UNITED ARAB EMIRATES · Mobile - Etisalat · mobile
$20.00/month$20.00setup$0.2000/min
voicesms
Rendered from the example response.

#Update DID Entry

POSThttps://apiv2.telecomsxchange.com/number/update

This API allows you to update certain phone number SIP or SMPP configurations.

SIP DNS SRV Records

TCXC supports SIP DNS SRV records exlusivley for the Restcomm Cloud platform.

To point your DID number to Restcomm cloud using SIP SRV records, use below format:

contact: did_number@sip_udp{organization}.restcomm.com

Example:

1234567893@_sip_udp_telecomsxchange.com.restcomm.com

Body parameters

application/x-www-form-urlencoded
submit_editintegerrequired

required field by tcxc api

Example 1

editintegerrequired

this is the i_did value for e.g 380673333333

Example 1001

contactstringrequired

Primary SIP Address

Example sip:380673333333@192.168.3.2:5060

contact2stringrequired

Failover SIP Address

Example sip:380673333333@192.168.3.2:5060

smpp_contactstringrequired

SMPP contact details - system id, password, phone number , SMPP host and SMPP port.

Example smpp:did:did:380673333333@192.168.3.1:2776

curl --digest \
  -u "$TCXC_USERNAME:$TCXC_API_KEY" \
  -X POST \
  "https://apiv2.telecomsxchange.com/number/update" \
  -d "submit_edit=1" \
  -d "edit=1001" \
  -d "contact=sip:380673333333@192.168.3.2:5060" \
  -d "contact2=sip:380673333333@192.168.3.2:5060" \
  -d "smpp_contact=smpp:did:did:380673333333@192.168.3.1:2776"
Update result
SuccessDID entry has been updated.
Rendered from the example response.