All API resources

Accounts

A buyer account is how traffic reaches TelecomsXchange: a SIP trunk authorised by IP or digest login, an SMPP bind, or an IoT (MQTT) login. Each account has its own balance (or uses another account's), its own purchased routes and its own alerts. Create accounts, change their credentials and authorise extra IP addresses.

POSTCreate a buyer account
POSTUpdate a buyer account
POSTAdd an extra IP to an account

Create a buyer account

POST/buyers/account/add

Creates a buyer account: a voice SIP trunk authorised by IP address, SIP login or both (smpp=0), an SMPP bind (smpp=1) or an IoT MQTT login (smpp=2). Returns the new i_account. For voice and SMPP accounts TCXC emails you, and texts you if an SMS number is on file, that a new origination IP or login was registered. Free.

Send every field in the form body; fields in the query string are ignored.

Parameters

namestringform fieldRequired
Account name, unique among your accounts.
ExampleNorthwind-SIP
smppintegerform fieldOptional
Account type: 0 voice (SIP), 1 SMPP, 2 IoT (MQTT).
One of012
Default0
ip_addressstringform fieldOptional
IPv4 or IPv6 address your traffic comes from. Voice accounts need ip_address, voip_login or both. An IP used for IP-only authentication cannot be shared with another account.
Example203.0.113.25
voip_loginstringform fieldOptional
SIP username (voice), SMPP system_id (required when smpp=1) or MQTT username (smpp=2; must start with your customer ID zero-padded to 10 digits, such as 0000001014). Must be unique.
Examplenw_sip_01
voip_passwordstringform fieldOptional
SIP, SMPP or MQTT password for voip_login.
Examplepw-Xr83kq2L
use_balanceintegerform fieldOptional
i_account of another of your accounts whose balance this account should spend. 0 gives the account its own balance.
Default0
subscribe_all_printegerform fieldOptional
Voice accounts only: 1 adds every unblocked route your other accounts have bought to the new account, with the same ASR and ACD alert and block thresholds.
One of01
Default0

Errors

Message	When
`"You have to specify IP Address or voip_login or both"`	a voice account (smpp=0) has neither ip_address nor voip_login
`"IP should be IP address, say 1.2.3.4"`	ip_address is given but is not a valid IPv4 or IPv6 address
`"IP is not unique"`	a voice account without voip_login uses an IP already authorised for IP-only authentication on the exchange
`"This IP address is already being authenticated"`	a voice account without voip_login uses an IP that another voice account already has
`"Wrong Prefix for login"`	smpp=2 and voip_login does not start with your 10-digit zero-padded customer ID
`"This Login is not unique"`	smpp=2 and voip_login is already in use
`"Empty SMPP system Id not allowed:"`	smpp=1 and voip_login is empty
`"Name is not unique, choose another name"`	you already have an account with this name
`"Empty name not allowed"`	name is empty
`"voip_login is not unique, choose another voip_login<voip_login>"`	a voice account's voip_login is already taken; the login follows the message with no space
`"voip_login is not unique om the ip, choose another voip_login or ip"`	an SMPP account with the same system_id and IP already exists

POST/buyers/account/add

curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/account/add" \
  -d name=Northwind-SIP \
  -d smpp=0 \
  -d ip_address=203.0.113.25 \
  -d voip_login=nw_sip_01 \
  -d voip_password=pw-Xr83kq2L \
  -d use_balance=0 \
  -d subscribe_all_pr=1

import os
import requests
from requests.auth import HTTPDigestAuth

resp = requests.post(
    "https://apiv2.telecomsxchange.com/buyers/account/add",
    auth=HTTPDigestAuth(os.environ["TCXC_USERNAME"], os.environ["TCXC_API_KEY"]),
    data={"name": "Northwind-SIP", "smpp": 0, "ip_address": "203.0.113.25", "voip_login": "nw_sip_01", "voip_password": "pw-Xr83kq2L", "use_balance": 0, "subscribe_all_pr": 1},
)
print(resp.json())

$ch = curl_init("https://apiv2.telecomsxchange.com/buyers/account/add");
curl_setopt_array($ch, [
    CURLOPT_HTTPAUTH => CURLAUTH_DIGEST,
    CURLOPT_USERPWD => getenv('TCXC_USERNAME') . ':' . getenv('TCXC_API_KEY'),
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => http_build_query(['name' => "Northwind-SIP", 'smpp' => 0, 'ip_address' => "203.0.113.25", 'voip_login' => "nw_sip_01", 'voip_password' => "pw-Xr83kq2L", 'use_balance' => 0, 'subscribe_all_pr' => 1]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);

Response

{
  "status": "success",
  "message": "Account has been added",
  "new_i_account": 2088
}

Update a buyer account

POST/buyers/account/edit/{i_account}

Replaces the settings of one of your accounts: name, IP, login and password, which balance it spends, low-balance alert, block flag and, for SMPP accounts, the default route or routing group. This is a full update: optional fields you leave out are reset, so blocked becomes 0, notification_balance is cleared, and smpp_rate_limit, default_routing_group and subspace become 0. If the IP address or login changes, TCXC emails you, and texts you if an SMS number is on file. Free.

Send every field in the form body; fields in the query string are ignored. Send the account's current values for any setting you don't want to change.

Parameters

i_accountintegerpathRequired
The account to update.
Example1022
namestringform fieldRequired
Account name.
ExampleNorthwind
use_balanceintegerform fieldRequired
i_account of the account whose balance this one spends, or 0 for its own balance.
Example0
ip_addressstringform fieldOptional
IPv4 or IPv6 address. Voice accounts need ip_address, voip_login or both.
Example203.0.113.10
voip_loginstringform fieldOptional
SIP username, SMPP system_id (required for SMPP accounts) or MQTT username.
voip_passwordstringform fieldOptional
New password. Leave empty to keep the current one.
blockedintegerform fieldOptional
Send this field, with any value, to block the account; omit it to leave the account unblocked. A blocked account cannot send traffic.
notification_balancenumberform fieldOptional
Send a low-balance alert when the balance falls below this amount. Empty switches the alert off.
Example1000
smpp_rate_limitintegerform fieldOptional
SMPP accounts: messages-per-second limit for the bind; 0 sets no limit.
Default0
default_routing_groupintegerform fieldOptional
SMPP accounts: i_routing_group to use by default; must be one of your routing groups. Setting it clears the default purchased route.
Default0
smpp_defaultintegerform fieldOptional
SMPP accounts: i_purchased_route of one of this account's routes to make the default; clears default_routing_group.
subspaceintegerform fieldOptional
1 authenticates calls from the Subspace network by its special header instead of the source IP.
One of01
Default0

Errors

Message	When
`"Unexpected DB error"`	i_account is not one of your accounts; returned as plain text, not JSON
`"You have to specify IP Address or voip_login or both"`	a voice or IoT account has neither ip_address nor voip_login
`"IP should be either IP address, say 1.2.3.4 or host:port like 1.2.3.4:5060"`	ip_address is not a valid IPv4 or IPv6 address (host:port is not accepted)
`"IP is not unique"`	a voice account without voip_login uses an IP already authorised for IP-only authentication on another account
`"'notification_balance' parameter expects numeric"`	notification_balance is not empty and not a number
`"This IP address is already being authenticated"`	a voice account without voip_login uses an IP that another voice account has
`"Empty SMPP system Id not allowed"`	an SMPP account's voip_login is empty
`"rouing group not found"`	an SMPP account's default_routing_group is not one of your routing groups
`"'use_balance' parameter expects integer"`	use_balance is missing or not a number
`"voip_login is not unique, choose another voip_login"`	a voice account's voip_login is used by another account
`"voip_login is not unique on the ip, choose another voip_login"`	another SMPP account has the same system_id and IP
`"Empty name not allowed"`	name is empty

POST/buyers/account/edit/{i_account}

curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/account/edit/1022" \
  -d name=Northwind \
  -d use_balance=0 \
  -d ip_address=203.0.113.10 \
  -d voip_login='' \
  -d voip_password='' \
  -d notification_balance=1000 \
  -d smpp_rate_limit=0 \
  -d default_routing_group=0 \
  -d subspace=0

import os
import requests
from requests.auth import HTTPDigestAuth

resp = requests.post(
    "https://apiv2.telecomsxchange.com/buyers/account/edit/1022",
    auth=HTTPDigestAuth(os.environ["TCXC_USERNAME"], os.environ["TCXC_API_KEY"]),
    data={"name": "Northwind", "use_balance": 0, "ip_address": "203.0.113.10", "voip_login": "", "voip_password": "", "notification_balance": 1000, "smpp_rate_limit": 0, "default_routing_group": 0, "subspace": 0},
)
print(resp.json())

$ch = curl_init("https://apiv2.telecomsxchange.com/buyers/account/edit/1022");
curl_setopt_array($ch, [
    CURLOPT_HTTPAUTH => CURLAUTH_DIGEST,
    CURLOPT_USERPWD => getenv('TCXC_USERNAME') . ':' . getenv('TCXC_API_KEY'),
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => http_build_query(['name' => "Northwind", 'use_balance' => 0, 'ip_address' => "203.0.113.10", 'voip_login' => "", 'voip_password' => "", 'notification_balance' => 1000, 'smpp_rate_limit' => 0, 'default_routing_group' => 0, 'subspace' => 0]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);

Response

{
  "status": "success",
  "message": "Account has been updated"
}

Add an extra IP to an account

POST/buyers/account/additional_ip_add/{i_account}

Authorises one more source IP address for one of your accounts, so traffic from the main IP or any additional IP is accepted for it. Returns the ID of the new IP entry. Free.

Send ip_address in the form body; it is ignored in the query string.

Parameters

i_accountintegerpathRequired
The account to add the IP to.
Example1022
ip_addressstringform fieldRequired
IPv4 or IPv6 address to authorise.
Example198.51.100.40

Errors

Message	When
`"Missing i_account"`	the path has no i_account, or it is 0
`"i_account not found"`	the account is not one of yours
`"IP should be IP address, say 1.2.3.4"`	ip_address is missing or not a valid IPv4 or IPv6 address
`"The IP is already used up"`	the account has no voip_login and the IP is already authorised for IP-only authentication on the exchange

POST/buyers/account/additional_ip_add/{i_account}

curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/account/additional_ip_add/1022" \
  -d ip_address=198.51.100.40

import os
import requests
from requests.auth import HTTPDigestAuth

resp = requests.post(
    "https://apiv2.telecomsxchange.com/buyers/account/additional_ip_add/1022",
    auth=HTTPDigestAuth(os.environ["TCXC_USERNAME"], os.environ["TCXC_API_KEY"]),
    data={"ip_address": "198.51.100.40"},
)
print(resp.json())

$ch = curl_init("https://apiv2.telecomsxchange.com/buyers/account/additional_ip_add/1022");
curl_setopt_array($ch, [
    CURLOPT_HTTPAUTH => CURLAUTH_DIGEST,
    CURLOPT_USERPWD => getenv('TCXC_USERNAME') . ':' . getenv('TCXC_API_KEY'),
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => http_build_query(['ip_address' => "198.51.100.40"]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);

Response

{
  "status": "success",
  "message": "IP has been added",
  "new_i_remote_ip_auth": 311
}