# TelecomsXChange (TCXC) API Reference > Canonical documentation: https://www.telecomsxchange.com/api-docs/reference. Base URL: https://apiv2.telecomsxchange.com. Authentication: HTTP Digest (username = TCXC username, password = API key). 54 endpoints across 12 groups. Generated 2026-09-22. ## Introduction Telecomsxchange's platfom application programming interfaces (APIs) empower you to automate significant operations in the telecom industry's wholesale buying and selling landscape. These operations range from establishing interconnections and overseeing carrier relationships to exploring market opportunities and handling support tickets. They also include managing communications, controlling traffic routing, offering ratings and reviews, and orchestrating financial settlements for voice, SMS, and virtual numbers. ## Overview To access and utilize this API, it is essential to have a valid TelecomsXChange buyer or seller account. If you don't have an account yet, you can easily sign up by clicking on the following link: [Signup Here](https://www.telecomsxchange.com). ## Authentication Find below the two API authentication methods supported by TCXC, you may use any of them to authenticate to the API **Digest Authentication** To authenticate using Digest Authentication, you need to pass on the following information: Username: {TCXC Username} Password: {TCXC API Key} For more information on Digest Authentication visit[this page](https://en.wikipedia.org/wiki/Digest_access_authentication) **Signature Based Authentication** [Warning: This method is more secure, but not developer friendly and may not work with tools like Postman.](#) 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, TCXC buyer login and the string value of the unxi timestamp associated with the request. ## Rate LIMIT TCXC API rate limits your requests to a specified hourly value based on your account. Contact us if you desire a higher rate limit. Users are also limited to a number of requests per second. If you exceed either limit you will receive an HTTP 429 error. ## Endpoints - [Voice Exchange](https://www.telecomsxchange.com/api-docs/reference/voice-exchange): 9 endpoints - [SMS Exchange](https://www.telecomsxchange.com/api-docs/reference/sms-exchange): 3 endpoints - [DID Exchange](https://www.telecomsxchange.com/api-docs/reference/did-exchange): 7 endpoints - [eSIM Exchange](https://www.telecomsxchange.com/api-docs/reference/esim-exchange): 7 endpoints - [Interconnect](https://www.telecomsxchange.com/api-docs/reference/interconnect): 3 endpoints - [Money](https://www.telecomsxchange.com/api-docs/reference/money): 4 endpoints - [Tools](https://www.telecomsxchange.com/api-docs/reference/tools): 4 endpoints - [Members Messaging](https://www.telecomsxchange.com/api-docs/reference/members-messaging): 10 endpoints - [Rates](https://www.telecomsxchange.com/api-docs/reference/rates): 2 endpoints - [HLR Lookups](https://www.telecomsxchange.com/api-docs/reference/hlr-lookups): 2 endpoints - [IoT](https://www.telecomsxchange.com/api-docs/reference/iot): 1 endpoints - [Reports](https://www.telecomsxchange.com/api-docs/reference/reports): 2 endpoints ## Voice Exchange Docs: https://www.telecomsxchange.com/api-docs/reference/voice-exchange **What is it ?** The voice exchange section of this API represents all the exposed APIs related to voice buying and selling. Developers use this section to integrate rates, cdrs, route testing with third party applications. Visit [Github repository for code examples](https://www.github.com/telecomsxchange) Don't have an account? [Signup here](https://www.telecomsxchange.com/buyerjoin) ### Market View **Overview** The Market Rates Lookup API from TelecomsXchange provides real-time access to voice wholesale termination rates from several sellers. The returned data includes a host of valuable information, including prefix, rates, ASR (Answer Seizure Ratio), ACD (Average Call Duration), ratings, reviews, seller payouts, and more. **Warning** Please note that the Market Rates Lookup API is primarily designed to facilitate price comparisons for specific destinations, and is not optimized for fetching extensive sets of results. Therefore, you might encounter performance issues if attempting to retrieve a large number of rates via this API. Should you need to sync a high volume of rate records simultaneously, we recommend using the Carrier Download Rates API feature, specifically designed for such use-cases. **Usage Constraints** While using the Market Rates Lookup API, ensure to structure your requests efficiently to maintain optimal performance and avoid potential slowdowns. **Returned Data** The returned data from this API call will include: - Prefix: The prefix corresponding to each rate. - Rates: The cost of voice wholesale termination. - ASR: The Answer Seizure Ratio. - ACD: The Average Call Duration. - Ratings: The ratings given by other users. - Reviews: User reviews for each seller. - Seller Payouts: The payout rates for each seller. - More: Additional information may also be provided. For more details on the data structure, response format, and potential error codes, please refer to the specific sections of the TelecomsXchange API documentation. #### Search Market View (Voice) `POST https://apiv2.telecomsxchange.com/marketview/search` Docs: https://www.telecomsxchange.com/api-docs/reference/voice-exchange#search-market-view-voice Search Voice termination partners rates, stats and reviews and other unique data usin this method. P.S: Daily minutes and stats (ASR/ACD) values show based on last rate update for the given prefix. **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `prefix` | integer | required | `1855` | Country Code , Area Code | | `searchform` | integer | required | `1` | same parameters as web portal accepts | | `type` | string | required | `CLI` | Route Type - cli, nocli , tdm, any | | `seller` | string | required | `Pure` | show sms rates only (optional) | | `pager` | integer | required | `100` | number of pages to return "pagination" | | `off` | integer | required | `0` | offset | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/marketview/search" \ -d "prefix=1855" \ -d "searchform=1" \ -d "type=CLI" \ -d "seller=Pure" \ -d "pager=100" \ -d "off=0" ``` **Example response: Search Market View (Voice) - BVI - Gold (HTTP 200)** ```json { "status": "success", "rates": [ { "prefix": "22789", "vendor_name": "BVI", "connection_name": "Gold", "i_tariff": "655", "daily_asr": 10.506757, "weekly_asr": 12.17703, "daily_acd": 25, "weekly_acd": 143, "daily_minutes": 97763, "weekly_minutes": 702993, "stats_time": "2020-06-12 03:05:27", "i_connection": "653", "effective_from": "06/06/20 9:54PM", "price_1": "0.162500", "price_n": "0.162500", "interval_1": "1", "interval_n": "1", "i_vendor": "299", "capacity_limit": "500", "i_rate": "143754804", "forbidden": "0", "discontinued": "0", "route_type": "TDM", "seller_registration_date": "2016-09-13 20:16:26", "vendor_short_memo": null, "connection_short_memo": "High performing retail quality routes.", "country_code": "ne", "country_name": "Niger", "description": "Mobile - Airtel", "commision_percent": "0", "mccmnc": "61402", "seller_avg_rating": 2, "seller_reviews": 4, "rateid": 143754804 } ] } ``` **Example response: Search Market View (Voice) (HTTP 200)** ```json { "status": "success", "rates": [ { "prefix": "22797", "vendor_name": "LowSIP", "connection_name": "Premium", "i_tariff": "1033", "daily_asr": 21.4286, "weekly_asr": 20.6897, "daily_acd": 60, "weekly_acd": 60, "daily_minutes": 5, "weekly_minutes": 5, "stats_time": "2019-08-05 05:04:49", "i_connection": "1031", "effective_from": "01/16/19 4:41AM", "price_1": "0.200200", "price_n": "0.200200", "interval_1": "1", "interval_n": "1", "i_vendor": "351", "capacity_limit": "3000", "i_rate": "89596941", "forbidden": "0", "discontinued": "0", "route_type": "CLI", "seller_registration_date": "2018-03-23 02:02:05", "country_code": "ne", "country_name": "Niger", "description": "Mobile - Airtel", "commision_percent": "0", "mccmnc": "61402", "seller_avg_rating": 5, "seller_reviews": 0, "rateid": 89596941 }, { "prefix": "22797", "vendor_name": "TCXC", "connection_name": "CLI", "i_tariff": "787", "daily_asr": 19.5134, "weekly_asr": 20.5202, "daily_acd": 126, "weekly_acd": 124, "daily_minutes": 1648, "weekly_minutes": 14489, "stats_time": "2019-11-03 02:58:23", "i_connection": "785", "effective_from": "10/18/19 1:14AM", "price_1": "0.217000", "price_n": "0.217000", "interval_1": "1", "interval_n": "1", "i_vendor": "264", "capacity_limit": "500", "i_rate": "116604515", "forbidden": "0", "discontinued": "0", "route_type": "CLI", "seller_registration_date": "2015-10-02 23:10:08", "country_code": "ne", "country_name": "Niger", "description": "Mobile - Airtel", "commision_percent": "0", "mccmnc": "61402", "seller_avg_rating": 5, "seller_reviews": 3, "rateid": 116604515 }, { "prefix": "22797", "vendor_name": "AirTel", "connection_name": "Gold", "i_tariff": "884", "daily_asr": 19.1384, "weekly_asr": 13.4146, "daily_acd": 134, "weekly_acd": 126, "daily_minutes": 1727, "weekly_minutes": 2202, "stats_time": "2019-11-03 02:59:09", "i_connection": "882", "effective_from": "08/21/19 10:08AM", "price_1": "0.217000", "price_n": "0.217000", "interval_1": "1", "interval_n": "1", "i_vendor": "287", "capacity_limit": "1500", "i_rate": "111373907", "forbidden": "0", "discontinued": "0", "route_type": "CLI", "seller_registration_date": "2016-03-23 08:55:40", "country_code": "ne", "country_name": "Niger", "description": "Mobile - Airtel", "commision_percent": "0", "mccmnc": "61402", "seller_avg_rating": 5, "seller_reviews": 1, "rateid": 111373907 }, "… 11 more items" ] } ``` **Example response: Search Market View (Voice) (HTTP 200)** ```json { "status": "success", "rates": [ { "prefix": "21369", "vendor_name": "AirTel", "connection_name": "Gold", "i_tariff": "884", "daily_asr": 100, "weekly_asr": 25, "daily_acd": 129, "weekly_acd": 135, "daily_minutes": 2, "weekly_minutes": 29, "stats_time": "2019-10-30 03:23:10", "i_connection": "882", "effective_from": "10/10/19 4:20PM", "price_1": "0.455000", "price_n": "0.455000", "interval_1": "1", "interval_n": "1", "i_vendor": "287", "capacity_limit": "1500", "i_rate": "115796765", "forbidden": "0", "discontinued": "0", "route_type": "CLI", "seller_registration_date": "2016-03-23 08:55:40", "country_code": "dz", "country_name": "Algeria", "description": "Mobile - Mobilis", "commision_percent": "0", "mccmnc": "60301", "seller_avg_rating": 5, "seller_reviews": 1, "rateid": 115796765 }, { "prefix": "21367", "vendor_name": "AirTel", "connection_name": "Gold", "i_tariff": "884", "daily_asr": 50, "weekly_asr": 22.3301, "daily_acd": 108, "weekly_acd": 40, "daily_minutes": 10, "weekly_minutes": 15, "stats_time": "2019-11-03 02:59:06", "i_connection": "882", "effective_from": "10/10/19 4:20PM", "price_1": "0.455000", "price_n": "0.455000", "interval_1": "1", "interval_n": "1", "i_vendor": "287", "capacity_limit": "1500", "i_rate": "115796764", "forbidden": "0", "discontinued": "0", "route_type": "CLI", "seller_registration_date": "2016-03-23 08:55:40", "country_code": "dz", "country_name": "Algeria", "description": "Mobile - Mobilis", "commision_percent": "0", "mccmnc": "60301", "seller_avg_rating": 5, "seller_reviews": 1, "rateid": 115796764 }, { "prefix": "21365", "vendor_name": "AirTel", "connection_name": "Gold", "i_tariff": "884", "daily_asr": 25, "weekly_asr": 16.6667, "daily_acd": 147, "weekly_acd": 150, "daily_minutes": 2, "weekly_minutes": 22, "stats_time": "2019-11-03 02:59:06", "i_connection": "882", "effective_from": "10/10/19 4:20PM", "price_1": "0.455000", "price_n": "0.455000", "interval_1": "1", "interval_n": "1", "i_vendor": "287", "capacity_limit": "1500", "i_rate": "115796762", "forbidden": "0", "discontinued": "0", "route_type": "CLI", "seller_registration_date": "2016-03-23 08:55:40", "country_code": "dz", "country_name": "Algeria", "description": "Mobile - Mobilis", "commision_percent": "0", "mccmnc": "60301", "seller_avg_rating": 5, "seller_reviews": 1, "rateid": 115796762 }, "… 97 more items" ] } ``` #### Carrier Rate Download (CSV) `POST https://apiv2.telecomsxchange.com/sellers/rates/{i_tariff}` Docs: https://www.telecomsxchange.com/api-docs/reference/voice-exchange#carrier-rate-download-csv **Overview** The Sell Rates Download API from TelecomsXchange enables you to retrieve and download the current sell rates for a specific seller in CSV format. It's particularly useful for integrating and syncing comprehensive rate decks directly into your billing systems. **Prerequisites** Before you begin, you must know the `i_tariff` value for the seller/connection rates you wish to retrieve. This value can be found using either the `Market View` API or the `List Seller IDs` API. For instance, the `i_tariff` value for the seller "PureTelephone" with the route "CLI" is 866. You may use this ID as an example to familiarize yourself with the process. **Ideal Usage** This API proves beneficial in cases where the full synchronization of rate decks into your billing system is required, offering a more efficient method to manage and analyze sell rates data. Please refer to the specific sections of the TelecomsXchange API documentation for details on request structure, response format, and handling potential error codes. **Path parameters** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `i_tariff` | integer | required | `866` | Tariff ID of the seller connection to download. Find it with Market View or List Sellers Route Information. | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/sellers/rates/866" ``` **Example response: Carrier Rate Download (CSV) - Seller PureTelephone (HTTP 200)** ``` Country,Description,Prefix,Effective from,Rate Id,Forbidden,Discontinued,Price 1,Price N,Interval 1,Interval N,Last Day ASR,Last Week ASR,Last Day ACD,Last Week ACD,Last Day Minutes,Last Week Minutes,Statistics Time UNITED STATES OF AMERICA,Fixed - Paid 800,1800,2018-04-10 20:13:28,59701437,0,0,0,0,1,1,100,100,133,133,4.4167,4.4167,2019-09-30 04:33:34 UNITED STATES OF AMERICA,Fixed - Paid 800,1833,2018-04-10 20:13:28,59701438,0,0,0,0,1,1,0,0,0,0,0,0,0000-00-00 00:00:00 UNITED STATES OF AMERICA,Fixed - Paid 800,1844,2018-04-10 20:13:28,59701439,0,0,0,0,1,1,0,0,0,0,0,0,0000-00-00 00:00:00 UNITED STATES OF AMERICA,Fixed - Paid 800,1855,2018-04-10 20:13:28,59701440,0,0,0,0,1,1,100,100,79,79,6.5833,6.5833,2018-06-11 05:51:08 UNITED STATES OF AMERICA,Fixed - Paid 800,1866,2018-04-10 20:13:28,59701441,0,0,0,0,1,1,0,0,0,0,0,0,0000-00-00 00:00:00 UNITED STATES OF AMERICA,Fixed - Paid 800,1877,2018-04-10 20:13:28,59701442,0,0,0,0,1,1,100,100,11,11,0.1833,0.1833,2018-10-22 03:29:10 UNITED STATES OF AMERICA,Fixed - Paid 800,1888,2018-04-10 20:13:28,59701443,0,0,0,0,1,1,0,0,0,0,0,0,0000-00-00 00:00:00 ``` #### Top Voice Destinations `GET https://apiv2.telecomsxchange.com/sellers/toproutes` Docs: https://www.telecomsxchange.com/api-docs/reference/voice-exchange#top-voice-destinations **Overview** The Top Destinations API from TelecomsXchange provides members with a way to fetch a list of the top (5, 10, 20) destinations that have seen the most traffic over a specific period (today, yesterday, this week, this month) and for a specific route type such as TDM, CLI, NCLI, NA. **Usage** This API is ideal for analyzing traffic patterns and understanding the most active destinations. The selectable timeframe and route type allow for flexible, targeted data retrieval, making it easier to monitor and adjust your traffic strategy accordingly. Please refer to the TelecomsXchange API documentation for more details about how to structure your requests, understand the response format, and handle any potential error codes. **Query parameters** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `type` | string | required | `CLI` | Route Type supported: CLI, TDM, NCLI, NA | | `smpp` | integer | optional | `1` | smpp: 0 or 1 or defaults to 0 | | `number` | integer | required | `5` | Expects integer values from 1 to 20 and defaults to 5 if not set. | | `period` | string | required | `today` | period: supported values are today, yesterday, week, month | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X GET "https://apiv2.telecomsxchange.com/sellers/toproutes?type=CLI&number=5&period=today" ``` **Example response: Top 5 Voice Destinations for last month (HTTP 200)** ```json { "status": "success", "top_routes": { "NIGER": { "routes": [ { "billing_prefix": "22797", "price": "0.191", "type": "CLI", "description": "Mobile - Airtel" }, { "billing_prefix": "22796", "price": "0.191", "type": "CLI", "description": "Mobile - Airtel" }, { "billing_prefix": "22799", "price": "0.191", "type": "CLI", "description": "Mobile - Airtel" }, "… 89 more items" ] }, "INDIA": { "routes": [ { "billing_prefix": "919", "price": "0.0047", "type": "CLI", "description": "Fixed - ROC" }, { "billing_prefix": "9194", "price": "0.0044", "type": "CLI", "description": "Mobile - BSNL" }, { "billing_prefix": "91", "price": "0.0044", "type": "CLI", "description": "Fixed - ROC" }, "… 2018 more items" ] }, "SUDAN": { "routes": [ { "billing_prefix": "24996", "price": "0.1179", "type": "CLI", "description": "Mobile - Zain" }, { "billing_prefix": "24990", "price": "0.1179", "type": "CLI", "description": "Mobile - Zain" }, { "billing_prefix": "24991", "price": "0.1179", "type": "CLI", "description": "Mobile - Zain" }, "… 35 more items" ] }, "NIGERIA": { "routes": [ { "billing_prefix": "234906", "price": "0.0761", "type": "CLI", "description": "Mobile - MTN" }, { "billing_prefix": "234816", "price": "0.0761", "type": "CLI", "description": "Mobile - MTN" }, { "billing_prefix": "234903", "price": "0.0761", "type": "CLI", "description": "Mobile - MTN" }, "… 131 more items" ] }, "EGYPT": { "routes": [ { "billing_prefix": "2010", "price": "0.0873", "type": "CLI", "description": "Mobile - Vodafone" }, { "billing_prefix": "2011", "price": "0.059", "type": "CLI", "description": "Mobile - Etisalat" }, { "billing_prefix": "2011", "price": "0.051", "type": "CLI", "description": "Mobile - Etisalat" }, "… 37 more items" ] } } } ``` **Example response: Top 10 Voice Destinations for last week (HTTP 200)** ```json { "status": "success", "top_routes": { "INDIA": { "routes": [ { "billing_prefix": "919", "price": "0.0047", "type": "CLI", "description": "Fixed - ROC" }, { "billing_prefix": "9194", "price": "0.0044", "type": "CLI", "description": "Mobile - BSNL" }, { "billing_prefix": "9199", "price": "0.0044", "type": "CLI", "description": "Fixed - ROC" }, "… 977 more items" ] }, "NIGERIA": { "routes": [ { "billing_prefix": "234906", "price": "0.0761", "type": "CLI", "description": "Mobile - MTN" }, { "billing_prefix": "234903", "price": "0.0761", "type": "CLI", "description": "Mobile - MTN" }, { "billing_prefix": "234906", "price": "0.0725", "type": "CLI", "description": "Mobile - MTN" }, "… 61 more items" ] }, "SUDAN": { "routes": [ { "billing_prefix": "24990", "price": "0.1179", "type": "CLI", "description": "Mobile - Zain" }, { "billing_prefix": "24996", "price": "0.1179", "type": "CLI", "description": "Mobile - Zain" }, { "billing_prefix": "24991", "price": "0.1179", "type": "CLI", "description": "Mobile - Zain" }, "… 7 more items" ] }, "NIGER": { "routes": [ { "billing_prefix": "22797", "price": "0.191", "type": "CLI", "description": "Mobile - Airtel" }, { "billing_prefix": "22798", "price": "0.191", "type": "CLI", "description": "Mobile - Airtel" }, { "billing_prefix": "22796", "price": "0.191", "type": "CLI", "description": "Mobile - Airtel" }, "… 17 more items" ] }, "UNITED KINGDOM": { "routes": [ { "billing_prefix": "44", "price": "0.0015", "type": "CLI", "description": "Fixed - ROC" }, { "billing_prefix": "447341", "price": "0.0079", "type": "CLI", "description": "Mobile - Vodafone" }, { "billing_prefix": "447798", "price": "0.007", "type": "CLI", "description": "Mobile - Vodafone" }, "… 439 more items" ] }, "UNITED STATES OF AMERICA": { "routes": [ { "billing_prefix": "1800", "price": "0", "type": "CLI", "description": "Fixed - Paid 800" }, { "billing_prefix": "1888", "price": "0", "type": "CLI", "description": "Fixed - Paid 800" }, { "billing_prefix": "1", "price": "0.024", "type": "CLI", "description": "Fixed - ROC" }, "… 699 more items" ] … ``` ### Buyers Accounts **Overview** The Sub-Accounts Listing API provided by TelecomsXchange allows authenticated buyers to retrieve a list of all their associated sub-accounts. This includes all SMPP (Short Message Peer-to-Peer), SIP (Session Initiation Protocol), and IoT (Internet of Things) sub-accounts. **Usage** This API is particularly useful for buyers needing to manage multiple sub-accounts, offering a unified view of all associated accounts within a single request. It assists with account organization and management across various protocols and services. Please refer to the TelecomsXchange API documentation for more details about how to structure your requests, understand the response format, and handle any potential error codes. #### List Buyer Accounts `POST https://apiv2.telecomsxchange.com/buyers/account/list` Docs: https://www.telecomsxchange.com/api-docs/reference/voice-exchange#list-buyer-accounts The Accounts Listing API provided by TelecomsXchange allows authenticated parent buyers to retrieve a comprehensive list of all their associated child accounts. **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/account/list" ``` **Example response: List Buyer Accounts (HTTP 200)** ```json { "status": "success", "accounts": [ { "i_account": "1855", "name": "A2P-TRAFFIC", "ip_address": "", "currency": "USD", "balance": "0.00", "use_balance": "1022", "credit_limit": "0", "i_customer": "1014", "blocked": "0", "notification_balance": null, "last_notification_status": "1", "capacity_limit": "0", "voip_login": "sip307104", "voip_password": "pw1505408830", "smpp": "1", "smpp_rate_limit": "0", "parent_balance": "4,035.45", "parent_name": "NORTHWIND" }, { "i_account": "1022", "name": "NORTHWIND", "ip_address": "203.0.113.10", "currency": "USD", "balance": "4,035.45", "use_balance": "0", "credit_limit": "60000", "i_customer": "1014", "blocked": "0", "notification_balance": "1000", "last_notification_status": "0", "capacity_limit": "1000", "voip_login": "", "voip_password": "", "smpp": "0", "smpp_rate_limit": "0", "parent_balance": "0.00", "parent_name": "" } ] } ``` ### Buyer Route Testing This folder contains test requests for validating buyer routing configurations on the TelecomsXChange (TCXC) platform. Use these requests to: - Authenticate as a TCXC buyer using environment variables for credentials - Retrieve available test numbers - Submit and validate test calls against purchased routes - Verify quality parameters (ASR, ACD, PDD) and routing behavior before moving traffic to production **Prerequisites** - A valid TCXC buyer account - An API key or token configured via Postman environment variables (no secrets hard-coded in requests) - The {{base_url}} variable pointing to the correct TCXC API environment (sandbox or production) #### Get Test Numbers `GET https://apiv2.telecomsxchange.com/buyers/tools/getnumbers` Docs: https://www.telecomsxchange.com/api-docs/reference/voice-exchange#get-test-numbers **Overview** The Global Phone Numbers API from TelecomsXchange enables users to retrieve valid phone numbers from any country worldwide, which can then be used to initiate voice and SMS tests. Designed with network operation centers in mind, this API is ideal for entities that require continuous access to working numbers in various countries for testing purposes. **Key Features and Use Cases** - Worldwide Access : Retrieve valid phone numbers from any country globally. - Limit Setting : Define a limit in the API call to control how many numbers you receive in each response. - Comprehensive Information : Along with phone numbers, get the country name, code, and description in the response. - Validity Check : Ensure that you only receive valid, usable numbers. - Randomization : On every API call, random numbers are provided to avoid duplicates. **Try the Demo App** A demo application is available for users who want to explore and understand the API before integrating it into their systems. [Try Demo App](https://tools.telecomsxchange.com) **Post-Retrieval Actions** Once you've retrieved the numbers, you can use the Route Test API to initiate test calls, enabling a full cycle of number acquisition and test execution. For further information on how to structure your requests, interpret the response format, and handle potential error codes, please consult the TelecomsXchange API documentation. **Query parameters** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `prefix` | integer | required | `91` | Country code + Area code | | `country` | string | required | `India` | Country name i.e. India | | `description` | string | required | `Airtel` | Network name . i.e. Airtel | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X GET "https://apiv2.telecomsxchange.com/buyers/tools/getnumbers?prefix=&country=&description=" ``` **Example response: Get Test Numbers (HTTP 200)** ```json { "status": "success", "cdrs": [ { "CLD": "201021634650", "billing_prefix": "2010", "country_code": "eg", "country_name": "Egypt", "description": "Mobile - Vodafone" }, { "CLD": "201023792381", "billing_prefix": "2010", "country_code": "eg", "country_name": "Egypt", "description": "Mobile - Vodafone" }, { "CLD": "201032091935", "billing_prefix": "2010", "country_code": "eg", "country_name": "Egypt", "description": "Mobile - Vodafone" }, "… 7 more items" ] } ``` **Example response: Get Test Numbers (Country + Description) (HTTP 200)** ```json { "status": "success", "cdrs": [ { "CLD": "919861533061", "billing_prefix": "9198", "country_code": "io", "country_name": "India", "description": "Mobile - Airtel" }, { "CLD": "919904184443", "billing_prefix": "9199", "country_code": "io", "country_name": "India", "description": "Mobile - Airtel" }, { "CLD": "919980697848", "billing_prefix": "9199", "country_code": "io", "country_name": "India", "description": "Mobile - Airtel" }, "… 7 more items" ] } ``` **Example response: Get Test Numbers** ``` "status": "success", "cdrs": [ { "CLD": "1954612330", "billing_prefix": "1", "country_code": "us", "country_name": "United States Of America", "description": "Florida" }, { "CLD": "19548333445", "billing_prefix": "1", "country_code": "us", "country_name": "United States Of America", "description": "Florida" }, { "CLD": "19542370957", "billing_prefix": "1", "country_code": "us", "country_name": "United States Of America", "description": "Florida" }, { "CLD": "19545395970", "billing_prefix": "1", "country_code": "us", "country_name": "United States Of America", "description": "Florida" }, { "CLD": "1954637168", "billing_prefix": "1", "country_code": "us", "country_name": "United States Of America", "description": "Florida" } ] ``` #### Initiate Route Test `POST https://apiv2.telecomsxchange.com/buyers/routetest` Docs: https://www.telecomsxchange.com/api-docs/reference/voice-exchange#initiate-route-test **Overview** The Route Test API from TelecomsXchange enables users to initiate testing on one or more routes using a single API request. This feature is designed to facilitate efficient and comprehensive testing processes for network routes. **Usage** This API is ideal for users who need to validate and test the functionality of multiple network routes simultaneously. By allowing a single API request to handle testing for more than one route, it streamlines the testing process and improves overall efficiency. For additional details on how to format your requests, understand the response format, and manage potential error codes, please refer to the TelecomsXchange API documentation. **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `i_account` | integer | required | `1022` | Billing Account ID | | `cld1` | integer | required | `962790326274` | The first phone number to dial | | `cli1` | integer | required | `18882874637` | The caller id to use when calling the first number or CLD1 | | `i_connection1` | integer | required | `315` | Carrier Route to use for the test call e.g 315 is IDT, You can find this infromation in Market View API. | | `cld2` | integer | required | `18882874637` | The second phone number to dial | | `cli2` | integer | required | `9542405411` | The second caller id to use when calling the second number or CLD 2 | | `i_connection2` | integer | required | `864` | Carrier Route to use for the test call on second number | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/routetest" \ -d "i_account=1022" \ -d "cld1=962790326274" \ -d "cli1=18882874637" \ -d "i_connection1=315" \ -d "cld2=18882874637" \ -d "cli2=9542405411" \ -d "i_connection2=864" ``` **Example response: Route Test (Success) (HTTP 200)** ```json { "status": "ok", "status_text": "Test call has been initiated" } ``` **Example response: Route Test (Error: Route Not Purchased) (HTTP 200)** ```json { "status": "ok", "status_text": "Selected account does not have a purchased for selected route(s), please choose other combination or purchase selected route(s) on this account" } ``` ### Buyer Live Calls Get Summary and Details of Active calls for the authenticated buyer account. e.g "total_rows": "100" means that there are 100 active calls in total at this time from your buyer account. the value includes traffic from all sub-accounts as well. #### List Active Calls `POST https://apiv2.telecomsxchange.com/buyers/livecalls` Docs: https://www.telecomsxchange.com/api-docs/reference/voice-exchange#list-active-calls return all currently active voice calls on the buyer’s account **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `prefix` | integer | required | `1` | optional - leave empty to show all or enter country code that you want to filter the active calls results for. | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/livecalls" \ -d "prefix=1" ``` **Example response: List ActiveCalls (HTTP 200)** ```json { "status": "success", "live_calls": [ { "i_live_call": "608114221", "call_id": "46a570fafe8c11e9a4880cc47ab0b860@198.51.100.10-b2b_1", "type": "Connected", "CLD": "18004362367", "CLI": "6002", "authorized_duration": "3600", "authorized_amount": 0, "connect_time": "2019-11-03 22:53:58", "setup_time": "2019-11-03 22:53:57", "interim_update_time": null, "i_account": "1022", "i_purchased_route": "90124", "i_vendor": "259", "i_connection": "776", "i_rate": "111788009", "billing_prefix": "1800", "billing_price_1": 0, "billing_price_n": 0, "billing_interval_1": "1", "billing_interval_n": "1", "cancel_flag": "0", "duration": "2294", "vendor_name": "Tollfreedollars", "account_name": "Northwind", "connection_name": "USA-TollFree", "route_type": "CLI", "country_name": "UNITED STATES OF AMERICA", "description": "Fixed - Paid 800", "country_code": "us" }, { "i_live_call": "608115502", "call_id": "2ba5cf262c5105041963eaaa7d16a7b9@192.0.2.10:5060-b2b_1-b2b_1", "type": "Connected", "CLD": "15595074769", "CLI": "19094149795", "authorized_duration": "3600", "authorized_amount": 0.20434, "connect_time": "2019-11-03 23:27:59", "setup_time": "2019-11-03 23:27:48", "interim_update_time": null, "i_account": "1022", "i_purchased_route": "90959", "i_vendor": "297", "i_connection": "862", "i_rate": "59701436", "billing_prefix": "1", "billing_price_1": 0.0034, "billing_price_n": 0.0034, "billing_interval_1": "6", "billing_interval_n": "6", "cancel_flag": "0", "duration": "253", "vendor_name": "PureTelephone", "account_name": "Northwind", "connection_name": "USA CLI (OVH)", "route_type": "CLI", "country_name": "UNITED STATES OF AMERICA", "description": "California", "country_code": "us" } ], "total_rows": "2" } ``` ### Buyer CDRs APis related to billing - such as CDRs (call detail records) for buyers. #### List CDRs `POST https://apiv2.telecomsxchange.com/buyers/callhistory/` Docs: https://www.telecomsxchange.com/api-docs/reference/voice-exchange#list-cdrs Search and filter Call Detailed Records. **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `show` | string | required | `good` | "good" for none zero duration, "bad" for zero duration, "all" for both failed and successfull calls. | | `date_from` | datetime | required | `2019-11-02 23:59:59` | Only show calls that started on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) | | `date_to` | datetime | required | `2019-11-05 23:59:59` | Only show calls that ended on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/callhistory/" \ -d "show=good" \ -d "date_from=2019-11-02 23:59:59" \ -d "date_to=2019-11-05 23:59:59" ``` **Example response: List CDRs (HTTP 200)** ```json { "status": "success", "cdrs": [ { "i_cdr": "524808155", "CLD": "982391383658", "CLI": "+971590908045", "call_id": "fc029128fe9411e9a3b6002590d192ea@203.0.113.11-b2b_1", "duration": "0", "billed_duration": null, "connect_time": "2019-11-03 23:52:25", "disconnect_time": "2019-11-03 23:52:25", "setup_time": "2019-11-03 23:52:24", "billing_prefix": "982", "billing_price_1": 0.029, "billing_price_n": 0.029, "billing_interval_1": "1", "billing_interval_n": "1", "customer_amount": "0.000000", "i_customer": "1014", "i_account": "1022", "i_vendor": "423", "i_connection": "1088", "i_purchased_route": "97967", "disconnect_code": "63", "customer_ip": "203.0.113.10", "i_rate": "114110752", "vendor_name": "dwci", "account_name": "Northwind", "connection_name": "TDM -HD", "disconnect_reason": "Service or option not available, unspecified", "country_name": "IRAN", "description": "Fixed - ROC" }, { "i_cdr": "524808152", "CLD": "982391383658", "CLI": "+971591834442", "call_id": "6aa9dc04fe9411e9a1710cc47ab0b860@198.51.100.10-b2b_1", "duration": "0", "billed_duration": null, "connect_time": "2019-11-03 23:52:14", "disconnect_time": "2019-11-03 23:52:14", "setup_time": "2019-11-03 23:52:13", "billing_prefix": "982", "billing_price_1": 0.029, "billing_price_n": 0.029, "billing_interval_1": "1", "billing_interval_n": "1", "customer_amount": "0.000000", "i_customer": "1014", "i_account": "1022", "i_vendor": "423", "i_connection": "1088", "i_purchased_route": "97967", "disconnect_code": "63", "customer_ip": "203.0.113.10", "i_rate": "114110752", "vendor_name": "dwci", "account_name": "Northwind", "connection_name": "TDM -HD", "disconnect_reason": "Service or option not available, unspecified", "country_name": "IRAN", "description": "Fixed - ROC" }, { "i_cdr": "524808139", "CLD": "201212650157", "CLI": "11656503", "call_id": "bfhbfgbaephlvi0023512@198.51.100.11-b2b_1-b2b_1", "duration": "0", "billed_duration": null, "connect_time": "2019-11-03 23:51:49", "disconnect_time": "2019-11-03 23:51:49", "setup_time": "2019-11-03 23:51:40", "billing_prefix": "2012", "billing_price_1": 0.089, "billing_price_n": 0.089, "billing_interval_1": "1", "billing_interval_n": "1", "customer_amount": "0.000000", "i_customer": "1014", "i_account": "1022", "i_vendor": "406", "i_connection": "1112", "i_purchased_route": "101673", "disconnect_code": "63", "customer_ip": "203.0.113.10", "i_rate": "117339531", "vendor_name": "Teltorhub", "account_name": "Northwind", "connection_name": "TDM", "disconnect_reason": "Service or option not available, unspecified", "country_name": "EGYPT", "description": "Mobile - Orange" }, "… 47 more items" ] } ``` **Example response: List CDRs (HTTP 200)** ```json { "status": "success", "cdrs": [ { "i_cdr": "524807884", "CLD": "982391383658", "CLI": "+971530335044", "call_id": "0edc2626fe9311e99c4f002590d192ea@203.0.113.11-b2b_1", "duration": "0", "billed_duration": null, "connect_time": "2019-11-03 23:38:37", "disconnect_time": "2019-11-03 23:38:37", "setup_time": "2019-11-03 23:38:37", "billing_prefix": "982", "billing_price_1": 0.029, "billing_price_n": 0.029, "billing_interval_1": "1", "billing_interval_n": "1", "customer_amount": "0.000000", "i_customer": "1014", "i_account": "1022", "i_vendor": "423", "i_connection": "1088", "i_purchased_route": "97967", "disconnect_code": "63", "customer_ip": "203.0.113.10", "i_rate": "114110752", "vendor_name": "dwci", "account_name": "Northwind", "connection_name": "TDM -HD", "disconnect_reason": "Service or option not available, unspecified", "country_name": "IRAN", "description": "Fixed - ROC" }, { "i_cdr": "524807881", "CLD": "982391383658", "CLI": "+971523456831", "call_id": "7c2301a6fe9211e996860cc47ab0b860@198.51.100.10-b2b_1", "duration": "0", "billed_duration": null, "connect_time": "2019-11-03 23:38:24", "disconnect_time": "2019-11-03 23:38:24", "setup_time": "2019-11-03 23:38:24", "billing_prefix": "982", "billing_price_1": 0.029, "billing_price_n": 0.029, "billing_interval_1": "1", "billing_interval_n": "1", "customer_amount": "0.000000", "i_customer": "1014", "i_account": "1022", "i_vendor": "423", "i_connection": "1088", "i_purchased_route": "97967", "disconnect_code": "63", "customer_ip": "203.0.113.10", "i_rate": "114110752", "vendor_name": "dwci", "account_name": "Northwind", "connection_name": "TDM -HD", "disconnect_reason": "Service or option not available, unspecified", "country_name": "IRAN", "description": "Fixed - ROC" }, { "i_cdr": "524807879", "CLD": "982391383658", "CLI": "+971512736219", "call_id": "00b466d0fe9311e99c3c002590d192ea@203.0.113.11-b2b_1", "duration": "0", "billed_duration": null, "connect_time": "2019-11-03 23:38:13", "disconnect_time": "2019-11-03 23:38:13", "setup_time": "2019-11-03 23:38:13", "billing_prefix": "982", "billing_price_1": 0.029, "billing_price_n": 0.029, "billing_interval_1": "1", "billing_interval_n": "1", "customer_amount": "0.000000", "i_customer": "1014", "i_account": "1022", "i_vendor": "423", "i_connection": "1088", "i_purchased_route": "97967", "disconnect_code": "63", "customer_ip": "203.0.113.10", "i_rate": "114110752", "vendor_name": "dwci", "account_name": "Northwind", "connection_name": "TDM -HD", "disconnect_reason": "Service or option not available, unspecified", "country_name": "IRAN", "description": "Fixed - ROC" }, "… 47 more items" ] } ``` #### Filter CDRs `POST https://apiv2.telecomsxchange.com/buyers/callhistory/` Docs: https://www.telecomsxchange.com/api-docs/reference/voice-exchange#filter-cdrs Fitering CDRs to a sepcific number or for calling starting with a specific prefix. **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `show` | string | required | `good` | "good" for none zero duration, "bad" for zero duration, "all" for both failed and successfull calls. | | `prefix` | string | required | `201%` | Enter Country Code or full number e.g 12262101683 | | `date_from` | datetime | required | `2019-11-02 23:59:59` | Only show calls that started on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) | | `date_to` | datetime | required | `2019-11-05 23:59:59` | Only show calls that ended on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/callhistory/" \ -d "show=good" \ -d "prefix=201%" \ -d "date_from=2019-11-02 23:59:59" \ -d "date_to=2019-11-05 23:59:59" ``` **Example response: Filter CDRs (HTTP 200)** ```json { "status": "success", "cdrs": [ { "i_cdr": "524808006", "CLD": "201061987074", "CLI": "308422", "call_id": "bfhbiajijwzsxd9703945@192.0.2.12-b2b_1-b2b_1", "duration": "0", "billed_duration": null, "connect_time": "2019-11-03 23:45:16", "disconnect_time": "2019-11-03 23:45:16", "setup_time": "2019-11-03 23:45:06", "billing_prefix": "2010", "billing_price_1": 0.089, "billing_price_n": 0.089, "billing_interval_1": "1", "billing_interval_n": "1", "customer_amount": "0.000000", "i_customer": "1014", "i_account": "1022", "i_vendor": "406", "i_connection": "1112", "i_purchased_route": "101673", "disconnect_code": "16", "customer_ip": "203.0.113.10", "i_rate": "117339532", "vendor_name": "Teltorhub", "account_name": "Northwind", "connection_name": "TDM", "disconnect_reason": "Normal call clearing", "country_name": "EGYPT", "description": "Mobile - Vodafone" }, { "i_cdr": "119081922", "CLD": "201061987074", "CLI": "308422", "call_id": "bfhbiajijwzrzg2034745@192.0.2.12-b2b_1-b2b_1", "duration": "9", "billed_duration": "9", "connect_time": "2019-11-03 23:42:29", "disconnect_time": "2019-11-03 23:42:38", "setup_time": "2019-11-03 23:42:16", "billing_prefix": "2010", "billing_price_1": 0.089, "billing_price_n": 0.089, "billing_interval_1": "1", "billing_interval_n": "1", "customer_amount": "0.013350", "i_customer": "1014", "i_account": "1022", "i_vendor": "406", "i_connection": "1112", "i_purchased_route": "101673", "disconnect_code": "16", "customer_ip": "203.0.113.10", "i_rate": "117339532", "vendor_name": "Teltorhub", "account_name": "Northwind", "connection_name": "TDM", "disconnect_reason": "Normal call clearing", "country_name": "EGYPT", "description": "Mobile - Vodafone" }, { "i_cdr": "524807872", "CLD": "201063551361", "CLI": "74122754", "call_id": "bfhbiajijwzqcb7586345@192.0.2.12-b2b_1-b2b_1", "duration": "0", "billed_duration": null, "connect_time": "2019-11-03 23:37:45", "disconnect_time": "2019-11-03 23:37:45", "setup_time": "2019-11-03 23:37:40", "billing_prefix": "2010", "billing_price_1": 0.089, "billing_price_n": 0.089, "billing_interval_1": "1", "billing_interval_n": "1", "customer_amount": "0.000000", "i_customer": "1014", "i_account": "1022", "i_vendor": "406", "i_connection": "1112", "i_purchased_route": "101673", "disconnect_code": "63", "customer_ip": "203.0.113.10", "i_rate": "117339532", "vendor_name": "Teltorhub", "account_name": "Northwind", "connection_name": "TDM", "disconnect_reason": "Service or option not available, unspecified", "country_name": "EGYPT", "description": "Mobile - Vodafone" }, "… 47 more items" ] } ``` **Example response: Filter CDRs (HTTP 200)** ```json { "status": "success", "cdrs": [ { "i_cdr": "524807872", "CLD": "201063551361", "CLI": "74122754", "call_id": "bfhbiajijwzqcb7586345@192.0.2.12-b2b_1-b2b_1", "duration": "0", "billed_duration": null, "connect_time": "2019-11-03 23:37:45", "disconnect_time": "2019-11-03 23:37:45", "setup_time": "2019-11-03 23:37:40", "billing_prefix": "2010", "billing_price_1": 0.089, "billing_price_n": 0.089, "billing_interval_1": "1", "billing_interval_n": "1", "customer_amount": "0.000000", "i_customer": "1014", "i_account": "1022", "i_vendor": "406", "i_connection": "1112", "i_purchased_route": "101673", "disconnect_code": "63", "customer_ip": "203.0.113.10", "i_rate": "117339532", "vendor_name": "Teltorhub", "account_name": "Northwind", "connection_name": "TDM", "disconnect_reason": "Service or option not available, unspecified", "country_name": "EGYPT", "description": "Mobile - Vodafone" }, { "i_cdr": "524807808", "CLD": "201090979267", "CLI": "9547322", "call_id": "bfhbfgbaephiee6682902@198.51.100.11-b2b_1-b2b_1", "duration": "0", "billed_duration": null, "connect_time": "2019-11-03 23:35:20", "disconnect_time": "2019-11-03 23:35:20", "setup_time": "2019-11-03 23:35:12", "billing_prefix": "2010", "billing_price_1": 0.089, "billing_price_n": 0.089, "billing_interval_1": "1", "billing_interval_n": "1", "customer_amount": "0.000000", "i_customer": "1014", "i_account": "1022", "i_vendor": "406", "i_connection": "1112", "i_purchased_route": "101673", "disconnect_code": "16", "customer_ip": "203.0.113.10", "i_rate": "117339532", "vendor_name": "Teltorhub", "account_name": "Northwind", "connection_name": "TDM", "disconnect_reason": "Normal call clearing", "country_name": "EGYPT", "description": "Mobile - Vodafone" }, { "i_cdr": "524807798", "CLD": "201011628378", "CLI": "7846319", "call_id": "bfhbiajijwzozh3143145@192.0.2.12-b2b_1-b2b_1", "duration": "0", "billed_duration": null, "connect_time": "2019-11-03 23:34:48", "disconnect_time": "2019-11-03 23:34:48", "setup_time": "2019-11-03 23:34:45", "billing_prefix": "2010", "billing_price_1": 0.089, "billing_price_n": 0.089, "billing_interval_1": "1", "billing_interval_n": "1", "customer_amount": "0.000000", "i_customer": "1014", "i_account": "1022", "i_vendor": "406", "i_connection": "1112", "i_purchased_route": "101673", "disconnect_code": "16", "customer_ip": "203.0.113.10", "i_rate": "117339532", "vendor_name": "Teltorhub", "account_name": "Northwind", "connection_name": "TDM", "disconnect_reason": "Normal call clearing", "country_name": "EGYPT", "description": "Mobile - Vodafone" }, "… 47 more items" ] } ``` ## SMS Exchange Docs: https://www.telecomsxchange.com/api-docs/reference/sms-exchange **What is it ?** The SMS exchange section of this API represents all the exposed APIs related to SMS buying and selling. Developers use this section to integrate rates, SDRs with third party applications. Visit [Github repository for code examples](https://www.github.com/telecomsxchange) Don't have an account? [Signup here](https://www.telecomsxchange.com/buyerjoin) ### Buyer SDRs **Overview** This folder contains SDR (SMS Detail Record) reporting endpoints for TCXC buyers. Use these requests to retrieve detailed information about your SMS traffic, including volumes, costs, and delivery performance per vendor or destination. The goal is to help your team monitor traffic in near real time, reconcile invoices, and debug routing or quality issues quickly. **What you can do with these endpoints** - List SDRs for a time range – pull all records for a given date/time window for billing, fraud detection, or reconciliation. - Filter SDRs by vendor, buyer account, or trunk – isolate traffic for a specific partner or interconnect. - Filter by call attributes – e.g., Sender, Destination, country, prefix, disconnect cause, or call result (answered, failed, no‑answer, etc.). - Summarize performance – build dashboards around Submitted, Delivered, traffic , and cost per destination. #### List SDRs `POST https://apiv2.telecomsxchange.com/buyers/smshistory` Docs: https://www.telecomsxchange.com/api-docs/reference/sms-exchange#list-sdrs This method allows you to pull SMS Detailed records from SMS exchange. **Query parameters** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `prefix` | integer | optional | `44` | | | `sent` | integer | optional | `1` | | | `date_from` | datetime | optional | `2020-09-24 17:49:30` | | | `date_to` | datetime | optional | `2017-09-24 17:49:30` | | **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `show` | string | required | `good` | "good" for successfully sunmitted messages, "bad" for failed to submit. | | `prefix` | integer | required | `44` | optional You can specify country code (prefix) or leave empty for all | | `sent` | integer | required | `1` | 1 for successfull messages, 0 for failed messages | | `date_from` | datetime | required | `2015-10-18 19:19:27` | Only show SMS messages that started on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32 | | `date_to` | datetime | required | `2020-10-24 17:49:30` | Only show SMS messages that ended on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/smshistory" \ -d "show=good" \ -d "prefix=44" \ -d "sent=1" \ -d "date_from=2015-10-18 19:19:27" \ -d "date_to=2020-10-24 17:49:30" ``` **Example response: List SDRs (HTTP 200)** ```json { "status": "success", "sms": [ { "i_message": "567878", "message_id": "5d309d43-d6b1-0810-c16e-6c844fa59aeb", "ts": "2019-11-03 15:47:12", "delivered": "0", "sent": "1", "i_account": "1855", "i_customer": "1014", "i_connection": "1160", "i_vendor": "436", "message_text": "Your test pin code is: 66644", "from_number": "12262403276", "to_number": "22961175098", "i_rate": "117989386", "delivered_in_sec": "0", "error_text": null, "billed_msgs_cnt": "1", "vendor_name": "NobelGlobe", "account_name": "A2P-Traffic", "connection_name": "PREMIUM", "country_name": "BENIN", "description": "Mobile - MTN", "billing_price_1": 0, "billing_price_n": 0, "customer_amount": 0.0137 }, { "i_message": "567877", "message_id": "5d309d43-3e0b-c381-8517-4f04714ea1a7", "ts": "2019-11-03 15:45:43", "delivered": "0", "sent": "1", "i_account": "1855", "i_customer": "1014", "i_connection": "1160", "i_vendor": "436", "message_text": "Your test pin code is: 66644", "from_number": "12262403276", "to_number": "22501251280", "i_rate": "117989442", "delivered_in_sec": "0", "error_text": null, "billed_msgs_cnt": "1", "vendor_name": "NobelGlobe", "account_name": "A2P-Traffic", "connection_name": "PREMIUM", "country_name": "IVORY COAST", "description": "Mobile - Moov", "billing_price_1": 0, "billing_price_n": 0, "customer_amount": 0.023 }, { "i_message": "567876", "message_id": "5d309d43-18f9-c010-54df-d6a69316599b", "ts": "2019-11-03 15:45:31", "delivered": "0", "sent": "1", "i_account": "1855", "i_customer": "1014", "i_connection": "1160", "i_vendor": "436", "message_text": "Your test pin code is: 66644", "from_number": "12262403276", "to_number": "22501159632", "i_rate": "117989442", "delivered_in_sec": "0", "error_text": null, "billed_msgs_cnt": "1", "vendor_name": "NobelGlobe", "account_name": "A2P-Traffic", "connection_name": "PREMIUM", "country_name": "IVORY COAST", "description": "Mobile - Moov", "billing_price_1": 0, "billing_price_n": 0, "customer_amount": 0.023 }, "… 47 more items" ] } ``` ### Market View (SMS) Lookup Market Rates in real time for SMS wholesale terminaiton from several sellers. the returned results include (prefix, rates, asr, acd, ratings, reviews and seller payouts and more) **Warning!** The lookup API allows you to compare prices for certain destinations and it is not intended to fetch too many results. therefore you may experience slowness when fetching too many rates using this API. If you're looking to sync high count of rates records at once, we would recommend you to use carrier download rates API feature. #### Search Market View (SMS) `POST https://apiv2.telecomsxchange.com/marketview/search` Docs: https://www.telecomsxchange.com/api-docs/reference/sms-exchange#search-market-view-sms Search Market View for SMS termination rates. **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `prefix` | integer | required | `447` | Country Code | | `searchform` | integer | required | `1` | *Required | | `smpp` | integer | required | `1` | *Required to filter SMS termination rates only | | `pager` | integer | required | `5` | *Required for pagination | | `off` | integer | required | `0` | *Required offset value (must be less than pager value) | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/marketview/search" \ -d "prefix=447" \ -d "searchform=1" \ -d "smpp=1" \ -d "pager=5" \ -d "off=0" ``` **Example response: Search MarketView (HTTP 200)** ```json { "status": "success", "rates": [ { "prefix": "447106", "vendor_name": "Mitto", "connection_name": "Premium", "i_tariff": "14", "daily_asr": 0, "weekly_asr": 0, "daily_acd": 0, "weekly_acd": 0, "daily_minutes": 0, "weekly_minutes": 0, "stats_time": "0000-00-00 00:00:00", "i_connection": "14", "effective_from": "02/27/19 2:35PM", "price_1": "0.020400", "price_n": "0.020400", "interval_1": "1", "interval_n": "1", "i_vendor": "4", "capacity_limit": "0", "i_rate": "197275", "forbidden": "0", "discontinued": "0", "route_type": "", "seller_registration_date": "2019-01-18 17:56:23", "country_code": "gb", "country_name": "United Kingdom", "description": "Mobile - O2", "commision_percent": "0", "mccmnc": "23411", "seller_avg_rating": 5, "seller_reviews": 0, "rateid": 197275 }, { "prefix": "447107", "vendor_name": "Mitto", "connection_name": "Premium", "i_tariff": "14", "daily_asr": 0, "weekly_asr": 0, "daily_acd": 0, "weekly_acd": 0, "daily_minutes": 0, "weekly_minutes": 0, "stats_time": "0000-00-00 00:00:00", "i_connection": "14", "effective_from": "02/27/19 2:35PM", "price_1": "0.020400", "price_n": "0.020400", "interval_1": "1", "interval_n": "1", "i_vendor": "4", "capacity_limit": "0", "i_rate": "197276", "forbidden": "0", "discontinued": "0", "route_type": "", "seller_registration_date": "2019-01-18 17:56:23", "country_code": "gb", "country_name": "United Kingdom", "description": "Mobile - O2", "commision_percent": "0", "mccmnc": "23411", "seller_avg_rating": 5, "seller_reviews": 0, "rateid": 197276 }, { "prefix": "447300", "vendor_name": "Mitto", "connection_name": "Premium", "i_tariff": "14", "daily_asr": 0, "weekly_asr": 0, "daily_acd": 0, "weekly_acd": 0, "daily_minutes": 0, "weekly_minutes": 0, "stats_time": "0000-00-00 00:00:00", "i_connection": "14", "effective_from": "02/27/19 2:35PM", "price_1": "0.060000", "price_n": "0.060000", "interval_1": "1", "interval_n": "1", "i_vendor": "4", "capacity_limit": "0", "i_rate": "197203", "forbidden": "0", "discontinued": "0", "route_type": "", "seller_registration_date": "2019-01-18 17:56:23", "country_code": "gb", "country_name": "United Kingdom", "description": "Mobile - Ee", "commision_percent": "0", "mccmnc": "23502", "seller_avg_rating": 5, "seller_reviews": 0, "rateid": 197203 }, "… 2 more items" ] } ``` #### Top SMS Destinations `GET https://apiv2.telecomsxchange.com/buyers/toproutes` Docs: https://www.telecomsxchange.com/api-docs/reference/sms-exchange#top-sms-destinations This API endpoint allows memvers to retreive a list of the top (5, 10, 20) destinations with SMS traffic for a specific period of time (today, yesterday, week, month) and specific route type such as TDM , CLI , NCLI, NA. **Query parameters** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `period` | string | required | `week` | period: supported values are today, yesterday, week, month | | `smpp` | integer | required | `1` | Required value for SMS | | `number` | integer | required | `10` | Expects integer values from 1 to 20 and defaults to 5 if not set. | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X GET "https://apiv2.telecomsxchange.com/buyers/toproutes?period=week&smpp=1&number=10" ``` **Example response: Top SMS Routes (For Buyers) (HTTP 200)** ```json { "status": "success", "top_routes": { "SPAIN": { "routes": [ { "billing_prefix": "34607", "price": "0.0255", "description": "Mobile - Vodafone" }, { "billing_prefix": "34635", "price": "0.0255", "description": "Mobile - Orange" }, { "billing_prefix": "34696", "price": "0.0255", "description": "Mobile - Movistar" }, "… 14 more items" ] }, "SAUDI ARABIA": { "routes": [ { "billing_prefix": "96650", "price": "0.0133", "description": "Mobile - Al Jawal" }, { "billing_prefix": "96655", "price": "0.0133", "description": "Mobile - Al Jawal" }, { "billing_prefix": "96656", "price": "0.0271", "description": "Mobile - Mobily" } ] }, "AUSTRALIA": { "routes": [ { "billing_prefix": "61425", "price": "0.0161", "description": "Mobile - Vodafone" } ] }, "NIGERIA": { "routes": [ { "billing_prefix": "234817", "price": "0.009", "description": "Mobile - 9mobile" }, { "billing_prefix": "234909", "price": "0.009", "description": "Mobile - 9mobile" } ] }, "KUWAIT": { "routes": [ { "billing_prefix": "9655", "price": "0.078", "description": "Mobile - VIVA" } ] }, "CHILE": { "routes": [ { "billing_prefix": "569880", "price": "0.0196", "description": "Mobile - Claro" } ] }, "ECUADOR": { "routes": [ { "billing_prefix": "593987", "price": "0.0738", "description": "Mobile - Movistar" } ] } } } ``` **Example response: Top SMS Routes (HTTP 200)** ```json { "status": "success", "top_routes": [ { "billing_prefix": "212638", "price": "0.0215", "country_name": "MOROCCO", "description": "Mobile - Inwi" }, { "billing_prefix": "212682", "price": "0.0262", "country_name": "MOROCCO", "description": "Mobile - Maroc Telecom" }, { "billing_prefix": "96656", "price": "0.0271", "country_name": "SAUDI ARABIA", "description": "Mobile - Mobily" }, "… 1 more items" ] } ``` ## DID Exchange Docs: https://www.telecomsxchange.com/api-docs/reference/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) ### 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 `POST https://apiv2.telecomsxchange.com/sellers/did/add` Docs: https://www.telecomsxchange.com/api-docs/reference/did-exchange#add-sell-new-did-number 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)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `number` | integer | required | `19542405099` | Unique DID Number ( Virtual Phone Number ) being sold for the first time | | `price_1` | number | required | `0.001` | Incoming Voice call price in USD per minute | | `interval_1` | integer | required | `60` | Billing Interval - Seconds or Minutes (60 for minutes and 1 for seconds) | | `monthly_fee` | integer | required | `10` | Monthly reccuring DID charge | | `setup_fee` | number | required | `1.00` | One time setup fee - charges once on purchase | | `did_type` | string | required | `mobile` | the phone number type (national, mobile, toll free or grey) | | `voice` | integer | required | `1` | Voice enabled (1 for yes and 0 for no) | | `sms` | integer | required | `0` | SMS enabled ( (1 for yes and 0 for no) | | `fax` | integer | required | `0` | Fax enabled (1 for yes and 0 for no) | | `video` | integer | required | `0` | Video enabled (1 for yes and 0 for no) | | `smpp_price` | number | required | `0.00` | Incoming SMS price in USD (per message) | | `capacity` | integer | required | `5` | Available channel capacity for the number (0 = unlimited) | | `status` | string | required | `blocked` | Phone number status (idle, blocked) if blocked is chosen the number will not be accessble or listed for buyers to purchase. only idle numbers are ready for sale | **Example request** ```bash curl --digest -u "USERNAME: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" ``` **Example response: Sell New DID (Success) (HTTP 200)** ```json { "status": "success", "message": "The DID has been successfully added." } ``` **Example response: Sell New DID (Already Exist Error) (HTTP 200)** ```json { "status": "error", "message": "This DID number already exists in the system" } ``` #### List DIDs `POST https://apiv2.telecomsxchange.com/sellers/did/list` Docs: https://www.telecomsxchange.com/api-docs/reference/did-exchange#list-dids List the seller DIDs with optional POST parameter prefix for DIDs list **Query parameters** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `prefix` | integer | optional | `1` | Optional prefix filter | **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `prefix` | integer | required | `380` | Optional - Filter DIDs by starting prefix | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/sellers/did/list" \ -d "prefix=380" ``` **Example response: List Seller DIDs (HTTP 200)** ```json { "status": "success", "dids": [ { "i_did": "2", "number": "380670493246", "price_1": "0.1", "price_n": "0.1", "interval_1": "1", "interval_n": "1", "monthly_fee": "10", "setup_fee": "10", "billing_i_account": "0", "i_vendor": "114", "status": "idle", "contact": "sip:380672942499@203.0.113.14:5060", "smpp_contact": "smpp:user:password:7777", "notes": "", "billed_to": "2020-01-19 10:51:17", "monthly_start_ts": "2020-01-19 10:51:17", "voice": "1", "sms": "1", "fax": "0", "video": "0", "capacity": "2", "did_type": "unknown", "verification_required": "1", "documents_verified": "0", "smpp_price": "0.03", "is_nexmo": "0", "email_warned": "0", "country_code": "ua", "country_name": "UKRAINE", "description": "Mobile - Kyivstar" } ] } ``` #### Update DID Record `POST https://apiv2.telecomsxchange.com/sellers/did/edit/{i_did}` Docs: https://www.telecomsxchange.com/api-docs/reference/did-exchange#update-did-record This API endpoint allows authenticated sellers to update an existing DID/Phone number on the exchange. **Path parameters** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `i_did` | integer | required | `46` | ID of the DID record to update, as returned by List DIDs. | **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `number` | integer | required | `19542405099` | Unique DID Number ( Virtual Phone Number ) being sold for the first time | | `price_1` | number | required | `0.001` | Incoming Voice call price in USD per minute | | `interval_1` | integer | required | `60` | Billing Interval - Seconds or Minutes (60 for minutes and 1 for seconds) | | `monthly_fee` | integer | required | `10` | Monthly reccuring DID charge | | `setup_fee` | number | required | `1.00` | One time setup fee - charges once on purchase | | `did_type` | string | required | `mobile` | the phone number type (national, mobile, toll free or grey) | | `voice` | integer | required | `1` | Voice enabled (1 for yes and 0 for no) | | `sms` | integer | required | `0` | SMS enabled ( (1 for yes and 0 for no) | | `fax` | integer | required | `0` | Fax enabled (1 for yes and 0 for no) | | `video` | integer | required | `0` | Video enabled (1 for yes and 0 for no) | | `smpp_price` | number | required | `0.00` | Incoming SMS price in USD (per message) | | `capacity` | integer | required | `5` | Available channel capacity for the number (0 = unlimited) | | `status` | string | required | `blocked` | Phone number status (idle, blocked) if blocked is chosen the number will not be accessble or listed for buyers to purchase. only idle numbers are ready for sale | **Example request** ```bash curl --digest -u "USERNAME: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" ``` **Example response: Sell New DID (Already Exist Error) (HTTP 200)** ```json { "status": "error", "message": "This DID number already exists in the system" } ``` **Example response: Update Virtual Number (Success) (HTTP 200)** ```json { "status": "success", "message": "DID entry has been updated. " } ``` **Example response: Sell New DID (Success) (HTTP 200)** ```json { "status": "success", "message": "The DID has been successfully added." } ``` ### 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 `POST https://apiv2.telecomsxchange.com/number/market` Docs: https://www.telecomsxchange.com/api-docs/reference/did-exchange#search-did-market-view 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)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `prefix` | integer | required | `1954` | The phone number, in E.164 (i.e. "1954") format. | | `country` | string | required | `United Kingdom` | The country name - string - (i.e. "Nigeria") | | `description` | string | required | `Mobile` | The network description - string - (i.e. "MTN") | | `seller` | string | optional | `Nexmo` | String - e.g "Nexmo" | | `voice` | integer | required | `1` | May contain value 0 or 1 to search for DIDs with capability “VOICE” | | `sms` | integer | required | `1` | May contain value 0 or 1 to search for DIDs with capability “SMS” | | `fax` | integer | required | `0` | May contain value 0 or 1 to search for DIDs with capability “fax” | | `video` | integer | required | `0` | May contain value 0 or 1 to search for DIDs with capability “Video” | | `did_type` | string | required | `any` | 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` | integer | required | `5` | “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. | | `off` | integer | required | `0` | “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. | **Example request** ```bash curl --digest -u "USERNAME: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" ``` **Example response: Available Numbers (HTTP 302)** ```json { "status": "success", "dids": [ { "i_did": "4", "number": "441861020078", "price_1": "0.0011", "price_n": "0.0011", "interval_1": "60", "interval_n": "60", "monthly_fee": "5.5000", "setup_fee": "1.1000", "i_vendor": "9", "status": "idle", "notes": "Verification Docs Required", "voice": "0", "sms": "0", "fax": "0", "video": "0", "capacity": "1", "did_type": "unknown", "verification_required": "0", "documents_verified": "0", "smpp_price": "0.0000", "is_nexmo": "0", "vendor_name": "Acme", "country_code": "gb", "country_name": "UNITED KINGDOM", "description": "Fixed - ROC" }, { "i_did": "54", "number": "447523410070", "price_1": "0.1000", "price_n": "0.1000", "interval_1": "1", "interval_n": "1", "monthly_fee": "5.0000", "setup_fee": "5.0000", "i_vendor": "16", "status": "idle", "notes": "", "voice": "1", "sms": "1", "fax": "0", "video": "0", "capacity": "2", "did_type": "mobile", "verification_required": "0", "documents_verified": "0", "smpp_price": "0.0300", "is_nexmo": "0", "vendor_name": "DIDWW", "country_code": "gb", "country_name": "UNITED KINGDOM", "description": "Mobile - Tismi" }, { "i_did": "15", "number": "447913314252", "price_1": "0.0200", "price_n": "0.0200", "interval_1": "60", "interval_n": "60", "monthly_fee": "1.0000", "setup_fee": "1.0000", "i_vendor": "10", "status": "idle", "notes": "Required docs:\r\n- LOI\r\n- Identification\r\n- Something else", "voice": "1", "sms": "1", "fax": "1", "video": "1", "capacity": "2", "did_type": "mobile", "verification_required": "1", "documents_verified": "0", "smpp_price": "0.0000", "is_nexmo": "0", "vendor_name": "DIDSeller", "country_code": "gb", "country_name": "UNITED KINGDOM", "description": "Mobile - O2" } ] } ``` **Example response: Search DID Market Place (HTTP 200)** ```json { "status": "success", "dids": [ { "country": "GB", "msisdn": "447418340370", "cost": "1.25", "type": "mobile-lvn", "features": [ "VOICE", "SMS" ], "monthly_fee": "2.5063", "number": "447410625182", "smpp_price": "0.0063", "price_1": "0.0050", "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": "gb", "country_name": "UNITED KINGDOM", "description": "Mobile - Tismi", "price_n": "0.0050" } ] } ``` **Example response: Search DID Market Place (HTTP 200)** ```json { "status": "success", "dids": [ { "country": "GB", "msisdn": "447418340370", "cost": "1.25", "type": "mobile-lvn", "features": [ "VOICE", "SMS" ], "monthly_fee": "2.5063", "number": "447410625182", "smpp_price": "0.0063", "price_1": "0.0050", "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": "gb", "country_name": "UNITED KINGDOM", "description": "Mobile - Tismi", "price_n": "0.0050" }, { "country": "GB", "msisdn": "447418342665", "cost": "1.25", "type": "mobile-lvn", "features": [ "VOICE", "SMS" ], "monthly_fee": "2.5063", "number": "447412098245", "smpp_price": "0.0063", "price_1": "0.0050", "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": "gb", "country_name": "UNITED KINGDOM", "description": "Mobile - Tismi", "price_n": "0.0050" }, { "country": "GB", "msisdn": "447418343514", "cost": "1.25", "type": "mobile-lvn", "features": [ "VOICE", "SMS" ], "monthly_fee": "2.5063", "number": "447411572303", "smpp_price": "0.0063", "price_1": "0.0050", "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": "gb", "country_name": "UNITED KINGDOM", "description": "Mobile - Tismi", "price_n": "0.0050" }, "… 2 more items" ] } ``` **Example response: Available Numbers (HTTP 302)** ```json { "status": "success", "dids": [ { "i_did": "4", "number": "441861020078", "price_1": "0.0011", "price_n": "0.0011", "interval_1": "60", "interval_n": "60", "monthly_fee": "5.5000", "setup_fee": "1.1000", "i_vendor": "9", "status": "idle", "notes": "Verification Docs Required", "voice": "0", "sms": "0", "fax": "0", "video": "0", "capacity": "1", "did_type": "unknown", "verification_required": "0", "documents_verified": "0", "smpp_price": "0.0000", "is_nexmo": "0", "vendor_name": "Acme", "country_code": "gb", "country_name": "UNITED KINGDOM", "description": "Fixed - ROC" }, { "i_did": "54", "number": "447523410070", "price_1": "0.1000", "price_n": "0.1000", "interval_1": "1", "interval_n": "1", "monthly_fee": "5.0000", "setup_fee": "5.0000", "i_vendor": "16", "status": "idle", "notes": "", "voice": "1", "sms": "1", "fax": "0", "video": "0", "capacity": "2", "did_type": "mobile", "verification_required": "0", "documents_verified": "0", "smpp_price": "0.0300", "is_nexmo": "0", "vendor_name": "DIDWW", "country_code": "gb", "country_name": "UNITED KINGDOM", "description": "Mobile - Tismi" }, { "i_did": "15", "number": "447913314252", "price_1": "0.0200", "price_n": "0.0200", "interval_1": "60", "interval_n": "60", "monthly_fee": "1.0000", "setup_fee": "1.0000", "i_vendor": "10", "status": "idle", "notes": "Required docs:\r\n- LOI\r\n- Identification\r\n- Something else", "voice": "1", "sms": "1", "fax": "1", "video": "1", "capacity": "2", "did_type": "mobile", "verification_required": "1", "documents_verified": "0", "smpp_price": "0.0000", "is_nexmo": "0", "vendor_name": "DIDSeller", "country_code": "gb", "country_name": "UNITED KINGDOM", "description": "Mobile - O2" } ] } ``` #### Purchase DID `POST https://apiv2.telecomsxchange.com/number/purchase` Docs: https://www.telecomsxchange.com/api-docs/reference/did-exchange#purchase-did This method allows you to purchase phone numbers (DIDs). **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `i_did` | integer | required | `25` | ID of the did you want to purchase | | `billing_i_account` | integer | required | `1022` | 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. | | `contact` | string | required | `sip:12345abc@sip.domain.com:5060` | Primary SIP Address e.g SIP: E.164@162.13.42.203 | | `contact2` | string | required | `sip:12345abc@sip.domain.com:5060` | Failover SIP Address e.g SIP: E.164@162.13.42.203 | | `smpp_contact` | string | required | `smpp:login:pass:12345abc@smpp.domain.com:2776` | SMPP contact for the DID number to be sent to, example “smpp:login:pass: 12345abc@smpp.domain.com :2776” | **Example request** ```bash curl --digest -u "USERNAME: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" ``` **Example response: Purchase DID (Error Example) (HTTP 200)** ```json { "status": "error", "message": "This DID can not be purchased, it has been already sold to other buyer" } ``` **Example response: Purchase DID (HTTP 200)** ```json { "status": "success", "message": "DID has been purchased" } ``` #### List Purchased DIDs `POST https://apiv2.telecomsxchange.com/number/list` Docs: https://www.telecomsxchange.com/api-docs/reference/did-exchange#list-purchased-dids 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)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `prefix` | integer | required | `44` | Filter results starting with Country Code (Prefix) e.g 971 will show all numbers that start with 971 | | `country` | string | required | `United Kingdom` | Filter results starting with Country Name e.g United will show all numbers that start with United | | `description` | string | required | `Mobile` | Filter results starting with description e.g Mobile will show all numbers that start with description Mobile | | `pager` | integer | required | `5` | | | `off` | integer | required | `0` | | **Example request** ```bash curl --digest -u "USERNAME: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" ``` **Example response: List Purchased DIDs (HTTP 200)** ```json { "status": "success", "dids": [ { "i_did": "23", "number": "971501021800", "price_1": "0.0000", "price_n": "0.0000", "interval_1": "60", "interval_n": "60", "monthly_fee": "0.0000", "setup_fee": "0.0000", "i_vendor": "9", "status": "purchased", "contact": "", "smpp_contact": "", "notes": "", "billed_to": "2019-11-28 13:19:18", "monthly_start_ts": "2019-11-28 13:19:18", "voice": "1", "sms": "1", "fax": "0", "video": "0", "capacity": "2", "did_type": "national", "verification_required": "1", "documents_verified": "0", "smpp_price": "0.0000", "is_nexmo": "0", "account_name": "Demo", "vendor_name": "Acme", "country_code": "ae", "country_name": "UNITED ARAB EMIRATES", "description": "Mobile - Etisalat" }, { "i_did": "19", "number": "971500808365", "price_1": "0.2000", "price_n": "0.2000", "interval_1": "60", "interval_n": "60", "monthly_fee": "20.0000", "setup_fee": "20.0000", "i_vendor": "10", "status": "purchased", "contact": "", "smpp_contact": "", "notes": "", "billed_to": "2019-11-26 17:52:35", "monthly_start_ts": "2019-11-26 17:52:35", "voice": "1", "sms": "1", "fax": "0", "video": "0", "capacity": "1", "did_type": "mobile", "verification_required": "1", "documents_verified": "0", "smpp_price": "0.0700", "is_nexmo": "0", "account_name": "Route Lab", "vendor_name": "DIDSeller", "country_code": "ae", "country_name": "UNITED ARAB EMIRATES", "description": "Mobile - Etisalat" } ] } ``` #### Update DID Entry `POST https://apiv2.telecomsxchange.com/number/update` Docs: https://www.telecomsxchange.com/api-docs/reference/did-exchange#update-did-entry 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](https://cloud.restcomm.com) 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](mailto:1234567893@_sip_udp_telecomsxchange.com.restcomm.com) **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `submit_edit` | integer | required | `1` | required field by tcxc api | | `edit` | integer | required | `1001` | this is the i_did value for e.g 380673333333 | | `contact` | string | required | `sip:380673333333@192.168.3.2:5060` | Primary SIP Address | | `contact2` | string | required | `sip:380673333333@192.168.3.2:5060` | Failover SIP Address | | `smpp_contact` | string | required | `smpp:did:did:380673333333@192.168.3.1:2776` | SMPP contact details - system id, password, phone number , SMPP host and SMPP port. | **Example request** ```bash curl --digest -u "USERNAME: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" ``` **Example response: Update DID Entry with Failover SIP address (HTTP 200)** ```json { "status": "success", "message": "DID entry has been updated." } ``` **Example response: Update DID Entry ERROR (HTTP 200)** ```json { "status": "error", "message": "There was an error." } ``` ## eSIM Exchange Docs: https://www.telecomsxchange.com/api-docs/reference/esim-exchange Welcome to the [TCXC eSIM Exchange](https://telecomsxchange.com/esim-exchange) , your gateway to global mobile data connectivity. These APIs let you integrate eSIM provisioning directly into your platform, enabling your customers to stay connected anywhere in the world without swapping physical SIM cards. **What You Can Do** | Endpoint | Purpose | | --- | --- | | eSIM Market | Browse available eSIM packages by country or region | | eSIM Countries | Get the full list of supported destinations | | Purchase eSIM | Provision a new eSIM instantly and receive activation credentials (QR code, LPA string) | | List Purchased eSIMs | Retrieve all eSIMs on your account with status, usage, and activation details | | Orders History | Review past purchases for billing reconciliation and reporting | | Top-up Packages | Discover available data add-ons for any active eSIM | | Purchase Top-up | Extend data or validity on an existing eSIM | **Universal vs. Regional eSIMs** Not all eSIMs are created equal. **Regional eSIMs** are destination-specific. Heading to a new country? Install another eSIM profile. **Universal eSIMs** work globally. New destination? Just add a data package. Same device. Same eSIM. Any country. The TCXC eSIM Exchange provides **Universal eSIMs by default** — one profile, unlimited destinations, seamless top-ups. **Quick Start** - Call eSIM Countries to see where coverage is available - Search eSIM Market to find packages for your target destination - Use Purchase eSIM with your chosen i_esim_package and i_account - Deliver the QR code or LPA string to your end user for instant activation ### Buyer **Buyer APIs** The Buyer folder contains endpoints for TelecomsXChange (TCXC) customers who act as **buyers** on the TCXC platform. These APIs allow you to discover, provision, and manage eSIMs offered by sellers in the TCXC exchange.. Use these endpoints after you have created and activated a **TCXC buyer account** and obtained your API credentials as described in the main TelecomsXChange (TCXC) collection overview. #### List Countries `GET https://apiv2.telecomsxchange.com/buyers/esim/countries` Docs: https://www.telecomsxchange.com/api-docs/reference/esim-exchange#list-countries Retrieves a comprehensive list of all countries where eSIM packages are currently available. Use this endpoint to populate country selection dropdowns or validate country availability before querying the marketplace. **Request Parameters** None required **Response** Returns an array of country objects with uppercase country names. **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X GET "https://apiv2.telecomsxchange.com/buyers/esim/countries" ``` **Example response: Success (HTTP 200)** ```json { "status": "success", "countries": [ { "country": "AFGHANISTAN" }, { "country": "ALBANIA" }, { "country": "ALGERIA" }, "… 251 more items" ] } ``` #### Market View (eSIM) `POST https://apiv2.telecomsxchange.com/buyers/esim/market` Docs: https://www.telecomsxchange.com/api-docs/reference/esim-exchange#market-view-esim Searches the eSIM marketplace for available data packages filtered by country. Returns package details including pricing, validity period, data allowance, and vendor information. Use this endpoint to display available eSIM options to end users or to programmatically select packages for purchase. **Response Fields** - i_esim_package — Unique package identifier (required for purchase) - price_with_fee — Total price including platform fees (USD) - validity_days — Package validity period in days - data_gb — Data allowance in gigabytes **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `country` | string | required | `JAPAN` | Target country name in uppercase (e.g., UKRAINE, UNITED STATES). Use the List Countries endpoint to retrieve valid country names. | | `esim_vendor` | string | required | `eSIMP` | Seller login/username, for e.g eSIM, Airalo | | `i_vendor` | integer | required | `484` | Seller numeric ID, for e.g. 484 for eSIMP, 485 for Airalo. | | `max_price` | number | required | `5.0` | Maximum price cap, for e.g. 5.0 | | `data_GB` | integer | required | `1` | Data size filter (0.5, 1, 5, 10, 20, -1 for unlimited) | | `pager` | integer | required | `5` | Results per page (default 20) | | `off` | integer | required | `0` | Pagination offset. Use 0 for the first page. Increment by the pager value for subsequent pages. | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/esim/market" \ -d "country=JAPAN" \ -d "esim_vendor=eSIMP" \ -d "i_vendor=484" \ -d "max_price=5.0" \ -d "data_GB=1" \ -d "pager=5" \ -d "off=0" ``` **Example response: Market View (eSIM) - Success (HTTP 200)** ```json { "status": "success", "search_results": [ { "i_esim_package": "1306", "i_vendor": "484", "country_code": "jp", "name": "Japan 1 GB 7 Days", "validity_days": "7", "data_gb": "1", "networks": "KDDI Rakuten Mobile Inc.", "vendor_login": "eSIMP", "price_with_fee": "3.49", "supported_countries": [ { "country_name": "JAPAN", "country_code": "JP" } ] }, { "i_esim_package": "1307", "i_vendor": "484", "country_code": "jp", "name": "Japan 3 GB 15 Days", "validity_days": "15", "data_gb": "3", "networks": "", "vendor_login": "eSIMP", "price_with_fee": "7.99", "supported_countries": [ { "country_name": "JAPAN", "country_code": "JP" } ] }, { "i_esim_package": "1308", "i_vendor": "484", "country_code": "jp", "name": "Japan 5 GB 30 Days", "validity_days": "30", "data_gb": "5", "networks": "KDDI Rakuten Mobile Inc.", "vendor_login": "eSIMP", "price_with_fee": "11.99", "supported_countries": [ { "country_name": "JAPAN", "country_code": "JP" } ] }, "… 2 more items" ] } ``` #### Purchase eSIM `POST https://apiv2.telecomsxchange.com/buyers/esim/purchase` Docs: https://www.telecomsxchange.com/api-docs/reference/esim-exchange#purchase-esim Initiates the purchase of a new eSIM package. Upon successful completion, returns the eSIM credentials including ICCID, LPA string, and QR code for device installation. The purchase amount is immediately deducted from the specified account balance. **Response Fields** - iccid — Integrated Circuit Card Identifier (unique eSIM identifier) - i_esim_order — Internal order reference number - order_uuid — Universally unique order identifier for tracking - lpa — Local Profile Assistant string for manual eSIM installation - qr_base64 — Base64-encoded QR code image for eSIM activation **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `i_account` | integer | required | `1181` | Account ID to be charged for this purchase. Must have sufficient balance to cover the package cost. | | `i_esim_package` | integer | required | `267` | Unique package identifier obtained from the List Packages endpoint. | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/esim/purchase" \ -d "i_account=1181" \ -d "i_esim_package=267" ``` **Example response: Purchase eSIM (HTTP 200)** ```json { "status": "success", "iccid": "8910300000050257244", "i_esim_order": 23, "order_uuid": "fe2d3c81-2b9b-4191-bc92-48aa1a658ab8", "lpa": "LPA:1$consumer.e-sim.global$TN20251216153212D5009E7E", "qr_base64": "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", "ios_install_link": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$consumer.e-sim.global$TN20251216153212D5009E7E" // You can use this link to install eSIM profile in IOS devices with one tap. } ``` #### Top-up Packages `POST https://apiv2.telecomsxchange.com/buyers/esim/topup/list` Docs: https://www.telecomsxchange.com/api-docs/reference/esim-exchange#top-up-packages Retrieves all available top-up packages compatible with a specific eSIM. Returns packages that can extend data allowance or validity for an existing eSIM profile. Use this endpoint to offer data renewal options to users with active eSIMs. Response Fields - package_type_id — Unique identifier required for top-up purchase - price_with_fee — Total top-up cost including platform fees (USD) - Final price - data_GB — Additional data allowance in gigabytes - validity_days — Extended validity period in days - activation_policy — Description of when the top-up validity begins - supported_countries — Array of countries where the top-up is valid **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `iccid` | integer | required | `89103000000273190001` | The 18-22 digit ICCID of the eSIM to query top-up options for. Must be a valid, previously purchased eSIM. | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/esim/topup/list" \ -d "iccid=89103000000273190001" ``` **Example response: Success (HTTP 200)** ```json { "status": "success", "packages": [ { "name": "Ukraine 1 GB 7 Days", "data_GB": "1.00", "network": [], "plan_type": "Data Only", "validity_days": 7, "validity_days_display": "7 Days", "package_type_id": 18509, "activation_policy": "The validity period starts when the eSIM connects to any supported network(s).", "supported_countries": [ { "country_name": "Ukraine", "country_code": "UA" } ], "price_with_fee": "1.10" }, { "name": "Ukraine 3 GB 30 Days", "data_GB": "3.00", "network": [], "plan_type": "Data Only", "validity_days": 30, "validity_days_display": "30 Days", "package_type_id": 13837, "activation_policy": "The validity period starts when the eSIM connects to any supported network(s).", "supported_countries": [ { "country_name": "Ukraine", "country_code": "UA" } ], "price_with_fee": "3.30" } ] } ``` #### Purchase topup package `POST https://apiv2.telecomsxchange.com/buyers/esim/topup/purchase` Docs: https://www.telecomsxchange.com/api-docs/reference/esim-exchange#purchase-topup-package Applies a data top-up to an existing eSIM profile. Extends the data allowance and/or validity period of the specified eSIM. The top-up is applied immediately upon successful purchase and the amount is deducted from the specified account. **Form-Data Parameters** | Parameter | Type | Required | Description | | --- | --- | --- | --- | | iccid | string | Yes | The ICCID of the target eSIM to apply the top-up to. Must be a valid, active eSIM owned by your account. | | package_type_id | integer | Yes | Top-up package identifier obtained from the List Top-Up Packages endpoint. | | i_account | integer | Yes | Account ID to be charged for this top-up. Must have sufficient balance. | **Response Fields** - order_uuid — Universally unique identifier for the top-up transaction **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/esim/topup/purchase" ``` **Example response: Success (HTTP 200)** ```json { "status": "success", "order_uuid": "c40d0f55-8993-40cf-8d83-108ff80ff4ed" } ``` #### Orders history `POST https://apiv2.telecomsxchange.com/buyers/esim/orders` Docs: https://www.telecomsxchange.com/api-docs/reference/esim-exchange#orders-history Retrieves a paginated history of all eSIM orders including initial purchases and top-ups. Use this endpoint for transaction reconciliation, order tracking, and generating purchase reports. Orders are returned in reverse chronological order (newest first). **Form-Data Parameters** | Parameter | Type | Required | Description | | --- | --- | --- | --- | | date_from | string | Yes | Start date for the query range. Format: YYYY-MM-DD HH:MM:SS (e.g., 2024-01-01 00:00:00 ). | | date_to | string | Yes | End date for the query range. Format: YYYY-MM-DD HH:MM:SS (e.g., 2025-12-31 23:59:59 ). | | pager | integer | Yes | Maximum number of orders to return per request. Recommended range: 10-100. | | off | integer | Yes | Pagination offset. Use 0 for the first page. Increment by the pager value to retrieve subsequent pages. | | | | | | | --- | --- | --- | --- | | | | | | | | | | | **Response Fields** - i_esim_order — Unique order identifier - order_type — Transaction type: purchase (new eSIM) or top-up (data reload) - amount_charged — Total amount charged (USD) - status — Order status: complete , pending , or failed - order_uuid — UUID for external reference and support inquiries - create_ts — Order timestamp (UTC) - iccid — Associated eSIM identifier - package_name — Human-readable package description **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `date_from` | datetime | required | `2020-01-01 00:00:00` | | | `date_to` | datetime | required | `2026-07-01 00:00:00` | | | `pager` | integer | required | `4` | | | `off` | integer | required | `0` | | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/esim/orders" \ -d "date_from=2020-01-01 00:00:00" \ -d "date_to=2026-07-01 00:00:00" \ -d "pager=4" \ -d "off=0" ``` **Example response: Success (HTTP 200)** ```json { "status": "success", "orders": [ { "i_esim_order": "6", "i_account": "1181", "i_vendor": "484", "package_name": "India 1 GB 7 Days", "package_country_code": "IN", "package_networks": "", "package_validity_days": "0", "package_data_gb": "0", "iccid": "8910300000027319600", "order_type": "top-up", "amount_charged": "3.49", "status": "complete", "order_uuid": "c40d0f55-8993-40cf-8d83-108ff80ff4ed", "activation_code": "", "sm_dp_address": "", "lpa": null, "qr_base64": null, "create_ts": "2025-12-18 22:15:49", "account_name": "RouteTester", "country_name": "INDIA" }, { "i_esim_order": "5", "i_account": "1181", "i_vendor": "484", "package_name": "India 1 GB 7 Days", "package_country_code": "in", "package_networks": "Reliance JIO", "package_validity_days": "7", "package_data_gb": "1", "iccid": "8910300000027319600", "order_type": "purchase", "amount_charged": "3.49", "status": "complete", "order_uuid": "503ee0f0-74a2-420a-a6a4-3168eead8bdf", "activation_code": "TN20241105110404EC9DF631", "sm_dp_address": "consumer.e-sim.global", "lpa": "LPA:1$consumer.e-sim.global$TN20241105110404EC9DF631", "qr_base64": "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", "create_ts": "2025-12-18 22:07:12", "account_name": "RouteTester", "country_name": "INDIA" }, { "i_esim_order": "4", "i_account": "1928", "i_vendor": "484", "package_name": "Kuwait 3 GB 15 Days", "package_country_code": "KW", "package_networks": "", "package_validity_days": "0", "package_data_gb": "0", "iccid": "8910300000030228001", "order_type": "top-up", "amount_charged": "10.99", "status": "complete", "order_uuid": "ec622b5a-418f-4c9a-8fce-838b41b989fc", "activation_code": "", "sm_dp_address": "", "lpa": null, "qr_base64": null, "create_ts": "2025-12-16 00:38:54", "account_name": "SMS-Route-Test", "country_name": "KUWAIT" }, "… 1 more items" ] } ``` #### List Purchased eSIMs `POST https://apiv2.telecomsxchange.com/buyers/esim/list` Docs: https://www.telecomsxchange.com/api-docs/reference/esim-exchange#list-purchased-esims Retrieves a paginated inventory of all eSIMs associated with your account. Returns comprehensive details including activation status, remaining data, expiry information, and installation credentials. Use this endpoint for eSIM lifecycle management and status monitoring. **Form-Data Parameters** | Parameter | Type | Required | Description | | --- | --- | --- | --- | | pager | integer | Yes | Maximum number of eSIM records to return per request. Recommended range: 10-100. | | off | integer | Yes | Pagination offset. Use 0 for the first page. Increment by the pager value for subsequent pages. | **Response Fields** - iccid — Unique eSIM identifier - esim_status — Current eSIM state: RELEASED , DOWNLOADED , INSTALLED , ENABLED - esim_status_message — Human-readable status description - data_usage_remaining_bytes — Remaining data allowance in bytes - data_allowance_bytes — Total data allowance in bytes - days_left_to_expiry — Days remaining until package expiration - lpa — LPA string for manual installation - qr_base64 — Base64-encoded QR code for device activation - sm_dp_address — SM-DP+ server address - activation_code — Activation code for manual entry **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `iccid` | integer | required | `8910300000050257244` | Filter by exact ICCID | | `pager` | integer | required | `3` | Results per page (max items returned | | `off` | integer | required | `0` | Pagination offset | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/esim/list" \ -d "iccid=8910300000050257244" \ -d "pager=3" \ -d "off=0" ``` **Example response: Success (HTTP 200)** ```json { "status": "success", "esims": [ { "i_esim": "45", "i_account": "48", "i_esim_order": "55", "iccid": "19220000000184396", "status": "complete", "create_ts": "2026-01-05 17:05:15", "i_vendor": "31", "package_name": "Europe 1 GB 7 Days", "package_country_code": "1E", "package_networks": "", "package_validity_days": "7", "package_data_gb": "1", "order_type": "purchase", "amount_charged": "1.1", "order_uuid": "b49ddddc-a67f-47e6-8b21-11180d280b52", "activation_code": "22184396", "sm_dp_address": "test.esim.com", "lpa": "LPA:1$test.esim.com$22184396", "qr_base64": "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", "order_status": "complete", "esim_status": "INSTALLED", "esim_create_ts": "2026-01-05 17:05:15", "order_package_networks": "", "supported_countries": [ { "country_name": "ALBANIA", "country_code": "AL" }, { "country_name": "AUSTRIA", "country_code": "AT" }, { "country_name": "BOSNIA AND HERZEGOWINA", "country_code": "BA" }, "… 46 more items" ], "esim_status_message": "eSIM Installed", "esim_last_operation_date": "2026-01-05 17:15:39", "data_usage_remaining_bytes": 1073741824, "days_left_to_expiry": 6, "data_allowance_bytes": 1073741824, "account_name": "Voice-QA", "ios_install_link": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$test.esim.com$22184396" }, { "i_esim": "44", "i_account": "4", "i_esim_order": "51", "iccid": "19220000000173165", "status": "complete", "create_ts": "2025-12-24 10:43:06", "i_vendor": "31", "package_name": "Israel 1 GB 7 Days", "package_country_code": "il", "package_networks": "", "package_validity_days": "7", "package_data_gb": "1", "order_type": "purchase", "amount_charged": "1.1", "order_uuid": "4e0ebf2c-8bbb-46c2-9156-1abf0a50e253", "activation_code": "22173165", "sm_dp_address": "test.esim.com", "lpa": "LPA:1$test.esim.com$22173165", "qr_base64": "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", "order_status": "complete", "esim_status": "ERROR", "esim_create_ts": "2025-12-24 10:43:06", "order_package_networks": "", "supported_countries": [], "esim_status_message": "The eSIM encountered an error while installing", "esim_last_operation_date": "2026-01-05 16:07:10", "data_usage_remaining_bytes": 1073741824, "days_left_to_expiry": -6, "data_allowance_bytes": 1073741824, "account_name": "smpp", "ios_install_link": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$test.esim.com$22173165" }, { "i_esim": "43", "i_account": "48", "i_esim_order": "50", "iccid": "19220000000191207", "status": "complete", "create_ts": "2025-12-16 09:59:38", "i_vendor": "31", "package_name": "Africa 1 GB 7 Days", "package_country_code": "1A", "package_networks": "", "package_validity_days": "7", "package_data_gb": "1", "order_type": "purchase", "amount_charged": "1.1", "order_uuid": "4a2d48e3-f4fb-48c6-b6bd-088da9d29556", "activation_code": "22191207", "sm_dp_address": "test.esim.com", "lpa": "LPA:1$test.esim.com$22191207", "qr_base64": "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", "order_status": "complete", "esim_status": "DOWNLOADED", "esim_create_ts": "2025-12-16 09:59:38", "order_package_networks": "", "supported_countries": [ { "country_name": "BOTSWANA", "country_code": "BW" }, { "country_name": "CONGO, THE DRC", "country_code": "CD" }, { "country_name": "COTE D IVOIRE", "country_code": "CI" }, "… 14 more items" ], "esim_status_message": "eSIM Installed but is off", "esim_last_operation_date": "2026-01-05 17:22:41", "data_usage_remaining_bytes": 4294967296, "days_left_to_expiry": 6, "data_allowance_bytes": 1073741824, "account_name": "Voice-QA", "ios_install_link": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$test.esim.com$22191207" } ] } ``` ## Interconnect Docs: https://www.telecomsxchange.com/api-docs/reference/interconnect **Overview** Imagine that you're able to interconnect with Tier 1 carriers like Airtel, TATA, Others.. using programmatically using API! This is exactly what this API endpoiunt allows you to acheive, after you initiate an interconnect you're able to start sending calls OR SMS messages via this carrier at wholesale prices, no contracts or commitments. TCXC has hundreds of pre-interconnected carriers that are one API call away from you to interconnect with and consume. #### Initiate Interconnect `POST https://apiv2.telecomsxchange.com/buyers/interconnect` Docs: https://www.telecomsxchange.com/api-docs/reference/interconnect#initiate-interconnect After you have searched market view API and found a termination partner you'd like to interconnect with, use this API to complete interconnection, once the interconnection is completed, you may start terminating traffic to the vendor. important You will be represented with Tech prefix and Download carrier pricelist url in API response. please note that we also send the same to your NOC and Rates team email addresses on file as well. **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `add` | integer | required | `1` | Required value for new interconnects | | `i_account` | integer | required | `1` | Buyer i_account (Retreived from Buyers List Accounts APi) | | `agree` | string | required | `yes` | Yes is required to proceed | | `id` | integer | required | `38` | i_connection ID - Retreived from Market View API. | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/interconnect" \ -d "add=1" \ -d "i_account=1" \ -d "agree=yes" \ -d "id=38" ``` **Example response: Interconnect (Successfull) (HTTP 200)** ```json { "status": "success", "message": "Interconnection with TATA Communications completed", "rates_url": "https://members.telecomsxchange.com/accounts.php?download=38", "tech_prefix": "33270#", "route_type": "voice" } ``` **Example response: Initiate Interconnect (Airtel) (HTTP 200)** ```json { "status": "success", "message": "Interconnection with AirTel completed", "rates_url": "https://members.telecomsxchange.com/accounts.php?download=1143", "tech_prefix": "55218#", "route_type": "voice" } ``` **Example response: Interconnect ERROR! (Route already purchased) (HTTP 200)** ```json { "status": "error", "message": "Error! Choose another account or route, this route is already purchased for this account." } ``` #### List Interconnects `POST https://apiv2.telecomsxchange.com/interconnections/list` Docs: https://www.telecomsxchange.com/api-docs/reference/interconnect#list-interconnects This API allows you to list all interconnections you have in the system. **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/interconnections/list" ``` **Example response: List Interconnects (HTTP 200)** ```json { "result": "success", "purchased_routes": [ { "i_purchased_route": "34619", "vendor_login": null, "connection_name": null, "i_tariff": null, "tech_prefix": null, "blocked": "0", "vendor_blocked": "0", "account_name": "Northwind", "i_vendor": null, "smpp": null }, { "i_purchased_route": "34620", "vendor_login": null, "connection_name": null, "i_tariff": null, "tech_prefix": null, "blocked": "0", "vendor_blocked": "0", "account_name": "Contoso Voice", "i_vendor": null, "smpp": null }, { "i_purchased_route": "90080", "vendor_login": "01SF001", "connection_name": "OpenRTP", "i_tariff": "832", "tech_prefix": "29435#", "blocked": "0", "vendor_blocked": "0", "account_name": "Contoso Voice", "i_vendor": "277", "smpp": "0" }, "… 457 more items" ], "inactive_prs": 27 } ``` **Example response: List Interconnects (HTTP 200)** ```json { "result": "success", "purchased_routes": [ { "i_purchased_route": "4", "vendor_login": "Airte", "connection_name": "Gold+", "i_tariff": "3", "tech_prefix": "36310#", "blocked": "0", "vendor_blocked": "0", "account_name": "Test", "i_vendor": "2", "smpp": "1" }, { "i_purchased_route": "3", "vendor_login": "Mitto2", "connection_name": "Premium", "i_tariff": "3", "tech_prefix": "36310#", "blocked": "0", "vendor_blocked": "0", "account_name": "smpp", "i_vendor": "2", "smpp": "1" }, { "i_purchased_route": "5", "vendor_login": "Mitto", "connection_name": "0 Hop", "i_tariff": "3", "tech_prefix": "36310#", "blocked": "0", "vendor_blocked": "0", "account_name": "SMPP-Test", "i_vendor": "2", "smpp": "1" }, "… 28 more items" ], "inactive_prs": 1 } ``` #### Block Interconnection `POST https://apiv2.telecomsxchange.com/interconnections/list` Docs: https://www.telecomsxchange.com/api-docs/reference/interconnect#block-interconnection This API allows you to block a specific active interconnection from receiving any further traffic. **"blocked": "1"**refers to the blocked interconnection. **"blocked": "0"** refers to active interconnection. **Query parameters** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `block` | integer | optional | `63` | | **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `block` | integer | required | `3` | The ID of the interconnection (aka i_purchased_route) | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/interconnections/list" \ -d "block=3" ``` **Example response: Block Interconnection (Successfull Response) (HTTP 200)** ```json { "result": "success", "purchased_routes": [ { "i_purchased_route": "4", "vendor_login": "Deutsche", "connection_name": "Hubbing", "i_tariff": "3", "tech_prefix": "36310#", "blocked": "1", "vendor_blocked": "0", "account_name": "Test", "i_vendor": "2", "smpp": "1" }, { "i_purchased_route": "3", "vendor_login": "Deutsche", "connection_name": "Hubbing", "i_tariff": "3", "tech_prefix": "36310#", "blocked": "1", "vendor_blocked": "0", "account_name": "smpp", "i_vendor": "2", "smpp": "1" }, { "i_purchased_route": "5", "vendor_login": "Deutsche", "connection_name": "Hubbing", "i_tariff": "3", "tech_prefix": "36310#", "blocked": "0", "vendor_blocked": "0", "account_name": "SMPP-Test", "i_vendor": "2", "smpp": "1" }, "… 29 more items" ], "inactive_prs": 4 } ``` ## Money Docs: https://www.telecomsxchange.com/api-docs/reference/money All APIs related to prepaid balances for buyers and sellers. ### Buyers This section shows how you can query the current balances of your account. #### Get Accounts Balance `POST https://apiv2.telecomsxchange.com/buyers/balance` Docs: https://www.telecomsxchange.com/api-docs/reference/money#get-accounts-balance Retrieve the current balance of your TCXC Buyer account. **Query parameters** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `i_payment_system` | integer | optional | `0` | Payment Type (0 for Any) | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/balance" ``` **Example response: List Account Balances (HTTP 200)** ```json { "status": "success", "accounts": [ { "i_account": "1855", "name": "A2P-Traffic", "ip_address": "198.51.100.14", "currency": "USD", "balance": "0", "use_balance": "1022", "credit_limit": "0", "i_customer": "1014", "blocked": "0", "notification_balance": null, "last_notification_status": "1", "smpp": "1", "parent_name": "Northwind", "parent_balance": "4106.060233818736" }, { "i_account": "1144", "name": "Contoso Voice", "ip_address": "192.0.2.14", "currency": "USD", "balance": "0", "use_balance": "1022", "credit_limit": "0", "i_customer": "1014", "blocked": "1", "notification_balance": null, "last_notification_status": "1", "smpp": "0", "parent_name": "Northwind", "parent_balance": "4106.060233818736" }, { "i_account": "1022", "name": "Northwind", "ip_address": "203.0.113.15", "currency": "USD", "balance": "4106.060233818736", "use_balance": "0", "credit_limit": "60000", "i_customer": "1014", "blocked": "0", "notification_balance": "1000", "last_notification_status": "0", "smpp": "0" } ] } ``` **Example response: Show Balance (HTTP 200)** ```json { "status": "success", "accounts": [ { "i_account": "10", "name": "SBC001", "ip_address": "198.51.100.15", "currency": "USD", "balance": "5000.00", "use_balance": "1", "credit_limit": "0.00", "i_customer": "1", "blocked": "0", "notification_balance": null, "last_notification_status": "1", "capacity_limit": "0", "voip_login": "sip354286", "voip_password": "pw1574069194", "smpp": "1", "smpp_rate_limit": "44", "parent_balance": "0.32", "parent_name": "DEMO" }, { "i_account": "1", "name": "PBX2", "ip_address": "", "currency": "USD", "balance": "0.32", "use_balance": "0", "credit_limit": "0", "i_customer": "1", "blocked": "0", "notification_balance": null, "last_notification_status": "1", "capacity_limit": "200", "voip_login": "sip194783", "voip_password": "pw4108521208", "smpp": "0", "smpp_rate_limit": "0", "parent_balance": "0.00", "parent_name": "" }, { "i_account": "30", "name": "PBX-LA", "ip_address": "", "currency": "USD", "balance": "100.00", "use_balance": "0", "credit_limit": "0", "i_customer": "1", "blocked": "0", "notification_balance": null, "last_notification_status": "1", "capacity_limit": "200", "voip_login": "sip290267", "voip_password": "pw0845258597", "smpp": "0", "smpp_rate_limit": "30", "parent_balance": "0.00", "parent_name": "" }, "… 7 more items" ] } ``` **Example response: List Buyer Balance Information (HTTP 200)** ```json { "status": "success", "accounts": [ { "i_account": "10", "name": "SBC001", "ip_address": "", "currency": "USD", "balance": "0", "use_balance": "1", "credit_limit": "10", "i_customer": "1", "blocked": "0", "notification_balance": null, "last_notification_status": "1", "smpp": "1", "parent_name": "Demo", "parent_balance": "0.318492338766288" }, { "i_account": "1", "name": "Demo", "ip_address": "", "currency": "USD", "balance": "1000.318492338766288", "use_balance": "0", "credit_limit": "0", "i_customer": "1", "blocked": "0", "notification_balance": null, "last_notification_status": "1", "smpp": "0" }, { "i_account": "30", "name": "DNA", "ip_address": "", "currency": "USD", "balance": "300", "use_balance": "0", "credit_limit": "0", "i_customer": "1", "blocked": "0", "notification_balance": null, "last_notification_status": "1", "smpp": "0" }, "… 8 more items" ] } ``` #### Payment History `POST https://apiv2.telecomsxchange.com/buyers/payhistory/` Docs: https://www.telecomsxchange.com/api-docs/reference/money#payment-history This API resource enables buyers to retreive their payment history detailed records. **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `i_payment_system` | integer | required | `1` | Payment Gateway (Use 0 for Any, 2 for PayPal, 1 for TCXC manual payment) | | `date_from` | datetime | required | `2019-01-01 00:00:00` | Only show payments that were sent or received on this date/time or later, date/time string, like YYYY-MM-DD HH:MM:SS (for example 2019-10-05 22:45:32) . | | `date_to` | datetime | required | `2020-01-01 00:00:00` | Only show payments that were sent or received on this date/time or earlier, date/time string, like YYYY-MM-DD HH:MM:SS (for example 2018-10-06 02:10:03) | | `pager` | integer | required | `5` | “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. | | `off` | integer | required | `0` | “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. | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/payhistory/" \ -d "i_payment_system=1" \ -d "date_from=2019-01-01 00:00:00" \ -d "date_to=2020-01-01 00:00:00" \ -d "pager=5" \ -d "off=0" ``` **Example response: Payment History (success) (HTTP 200)** ```json { "status": "success", "transactions": [ { "i_transaction": "13393", "i_account": "1022", "i_payment_system": "1", "currency": "USD", "amount": "-1.00", "status": "confirmed", "ts": "2019-12-06 12:00:01", "notepad": "Monthly charge for DID 19542405411", "account_name": "Northwind", "ps_name": "Manual Payment" }, { "i_transaction": "12715", "i_account": "1022", "i_payment_system": "1", "currency": "USD", "amount": "-1.00", "status": "confirmed", "ts": "2019-11-06 11:50:32", "notepad": "Monthly charge Fee for DID 19542405411", "account_name": "Northwind", "ps_name": "Manual Payment" }, { "i_transaction": "12207", "i_account": "1022", "i_payment_system": "1", "currency": "USD", "amount": "10,000.00", "status": "confirmed", "ts": "2019-10-23 10:53:02", "notepad": "BANK WIRE", "account_name": "Northwind", "ps_name": "Manual Payment" }, "… 1 more items" ] } ``` ### Sellers This section shows how you can query the current balance of your seller account. #### Get Seller Balance `POST https://apiv2.telecomsxchange.com/seller/balance` Docs: https://www.telecomsxchange.com/api-docs/reference/money#get-seller-balance Retrieve the current balance of your TCXC seller account **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/seller/balance" ``` **Example response: List Seller Available Balance (Success) (HTTP 200)** ```json { "status": "success", "balance": "22631.2636213539752" } ``` #### Payout History `POST https://apiv2.telecomsxchange.com/sellers/payhistory` Docs: https://www.telecomsxchange.com/api-docs/reference/money#payout-history Payout history API allows sellers to list and filter past payouts sent to their bank account, PayPal, Visa Card. This record also include DID numbers monthly recurring revenue (MRR). **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `date_from` | datetime | required | `2019-01-01 00:00:00` | Only show payments that were sent or received on this date/time or later, date/time string, like YYYY-MM-DD HH:MM:SS (for example 2019-10-05 22:45:32) . | | `date_to` | datetime | required | `2020-01-01 00:00:00` | Only show payments that were sent or received on this date/time or earlier, date/time string, like YYYY-MM-DD HH:MM:SS (for example 2018-10-06 02:10:03) | | `pager` | integer | required | `1000` | “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. | | `off` | integer | required | `2` | “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. | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/sellers/payhistory" \ -d "date_from=2019-01-01 00:00:00" \ -d "date_to=2020-01-01 00:00:00" \ -d "pager=1000" \ -d "off=2" ``` **Example response: Payout HIstory (Success) (HTTP 200)** ```json { "status": "success", "transactions": [ { "i_payout": "2873", "i_vendor": "287", "amount": "500", "i_admin": "0", "ts": "2019-12-24 22:14:41", "notepad": "Bank Wire" }, { "i_payout": "2872", "i_vendor": "287", "amount": "23000", "i_admin": "0", "ts": "2019-12-24 22:14:21", "notepad": "Bank wire" }, { "i_payout": "2865", "i_vendor": "287", "amount": "40000", "i_admin": "0", "ts": "2019-12-22 15:24:58", "notepad": "Bank Wire" }, "… 12 more items" ] } ``` **Example response: Payout HIstory (Error: Wrong date format) (HTTP 200)** ```json { "status": "error", "message": "Wrong date_from format, expected YYYY-MM-DD HH:MM:SS" } ``` ## Tools Docs: https://www.telecomsxchange.com/api-docs/reference/tools This folder contains utility endpoints and helper workflows for working with the TelecomsXChange (TCXC) platform. Use these requests to validate credentials, inspect account configuration, and troubleshoot common integration issues. #### List Sellers IDs `POST https://apiv2.telecomsxchange.com/sellers/list` Docs: https://www.telecomsxchange.com/api-docs/reference/tools#list-sellers-ids “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. **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `pager` | integer | required | `10000` | integer | | `off` | integer | required | `0` | integer | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/sellers/list" \ -d "pager=10000" \ -d "off=0" ``` **Example response: List Sellers IDs (Live) (HTTP 200)** ```json { "status": "success", "routes": [ { "seller_name": "JOOD", "i_vendor": "112", "route_name": "UAE", "i_connection": "128", "i_tariff": "129", "private": "0", "i_private_connection": null }, { "seller_name": "JOOD", "i_vendor": "112", "route_name": "Orange", "i_connection": "129", "i_tariff": "130", "private": "0", "i_private_connection": null }, { "seller_name": "JOOD", "i_vendor": "112", "route_name": "My Route 1e", "i_connection": "133", "i_tariff": "134", "private": "0", "i_private_connection": null }, "… 297 more items" ] } ``` #### Get Test Numbers `GET https://apiv2.telecomsxchange.com/buyers/tools/getnumbers` Docs: https://www.telecomsxchange.com/api-docs/reference/tools#get-test-numbers This API allows you to get valid phone numbers to any country in the world, and initiate your voice, sms test on.This API is designed for network operation center (NOC) that continously looking for working numbers in different countries to initiate tests on. [Try Demo App](https://tools.telecomsxchange.com) **Features for NOC automation** - Get valid phone numbers to any country in the world - Set a limit in the API call to how many numbers to get in the response - Get Country name, Code, Description in response - Get only valid numbers - Random Numbers on every API call to avoid duplicates Once numbers are retreived you can use the Route Test API to intiate test calls. **Query parameters** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `prefix` | integer | required | `91` | Country Code + Area code (e.164 format) | | `country` | string | required | `india` | country name - i.e. India | | `description` | string | required | `Airtel` | network name - i.e. Airtel | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X GET "https://apiv2.telecomsxchange.com/buyers/tools/getnumbers?prefix=&country=india&description=Airtel" ``` **Example response: Get Test Numbers (HTTP 200)** ```json { "status": "success", "cdrs": [ { "CLD": "201021634650", "billing_prefix": "2010", "country_code": "eg", "country_name": "Egypt", "description": "Mobile - Vodafone" }, { "CLD": "201023792381", "billing_prefix": "2010", "country_code": "eg", "country_name": "Egypt", "description": "Mobile - Vodafone" }, { "CLD": "201032091935", "billing_prefix": "2010", "country_code": "eg", "country_name": "Egypt", "description": "Mobile - Vodafone" }, "… 7 more items" ] } ``` **Example response: Get Test Numbers (Country + Description) (HTTP 200)** ```json { "status": "success", "cdrs": [ { "CLD": "919863110742", "billing_prefix": "9198", "country_code": "io", "country_name": "India", "description": "Mobile - Airtel" }, { "CLD": "918424080352", "billing_prefix": "918427", "country_code": "io", "country_name": "India", "description": "Mobile - Airtel" }, { "CLD": "919794267083", "billing_prefix": "91979", "country_code": "io", "country_name": "India", "description": "Mobile - Airtel" }, "… 7 more items" ] } ``` #### Get Phone Number Score `GET https://apiv2.telecomsxchange.com/buyers/tools/numberscore/` Docs: https://www.telecomsxchange.com/api-docs/reference/tools#get-phone-number-score **Features:** - Look up phone number - Get phone number score against TCXC database (Good Number or Risky) Good: the number has been recorded in our database and had high durations and most probably a good number that belongs to a real person. Risky: We have never seen this number before or it had too many failed calls that never connected. Use Cases: -Build Whitelist/Blacklist systems through API -Decrease SPAM/ROBO incoming calls -Save on HLR costs -Reject the risky phone numbers calls before it hits your infrastructure **Query parameters** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `cld` | integer | required | `380913104703` | Phone number to check | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X GET "https://apiv2.telecomsxchange.com/buyers/tools/numberscore/?cld=380913104703" ``` **Example response: Get Phone Number Score** ```json { "status": "success", "country_code": "ua", "phone_number": "+380910101783", "carrier": { "country_code": "ua", "country_name": "Ukraine", "description": "Ukr Telecom Mobile", "prefix": "38091", "number_score": "Risky number" } } ``` #### Initiate Route Test `POST https://apiv2.telecomsxchange.com/buyers/routetest` Docs: https://www.telecomsxchange.com/api-docs/reference/tools#initiate-route-test This API allows you to initiate testing to one or more routes using a single API request. **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `i_account` | integer | required | `1022` | Billing Account ID | | `cld1` | integer | required | `962790326274` | The first phone number to dial | | `cli1` | integer | required | `18882874637` | The caller id to use when calling the first number or CLD1 | | `i_connection1` | integer | required | `315` | Carrier Route to use for the test call e.g 315 is IDT, You can find this infromation in Market View API. | | `cld2` | string | required | `‭1305)7763097‬` | The second phone number to dial | | `cli2` | integer | required | `9542405411` | The second caller id to use when calling the second number or CLD 2 | | `i_connection2` | integer | required | `864` | Carrier Route to use for the test call on second number | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/routetest" \ -d "i_account=1022" \ -d "cld1=962790326274" \ -d "cli1=18882874637" \ -d "i_connection1=315" \ -d "cld2=‭1305)7763097‬" \ -d "cli2=9542405411" \ -d "i_connection2=864" ``` **Example response: Route Test (Error: Route Not Purchased) (HTTP 200)** ```json { "status": "ok", "status_text": "Selected account does not have a purchased for selected route(s), please choose other combination or purchase selected route(s) on this account" } ``` **Example response: Route Test (Success) (HTTP 200)** ```json { "status": "ok", "status_text": "Test call has been initiated" } ``` ## Members Messaging Docs: https://www.telecomsxchange.com/api-docs/reference/members-messaging **Keep it professional!** APis related to platform internal messaging, TCXC buyer and seller can communicate through this system to discuss deals, or raise trouble tickets. **Examples** - Buyer may send a message about Low ACD for a destination to a specific seller, the seller may reply with further information or confirming the issue has been resolved. - Buyer may request a rate decrease or negotiate a new deal with seller directly. ### Buyers This section shows how you can query the current inbox and outbox messages of your account, and if you want to respond to an existing message or compose a new one to a seller. #### List Incoming messages `POST https://apiv2.telecomsxchange.com/buyers/messages` Docs: https://www.telecomsxchange.com/api-docs/reference/members-messaging#list-incoming-messages Show all incoming and outgoing messages sent or received from other members on marketplace. **Query parameters** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `show` | string | optional | `inbox` | | | `limit` | integer | optional | `30` | | | `off` | integer | optional | `0` | | **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `show` | string | required | `inbox` | | | `limit` | integer | required | `30` | | | `off` | integer | required | `0` | | | `status` | string | optional | `read` | | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/messages" \ -d "show=inbox" \ -d "limit=30" \ -d "off=0" ``` **Example response: List Buyer Inbox messages (HTTP 200)** ```json { "status": "success", "messages": [ { "i_message": "12", "from_type": "vendor", "to_type": "customer", "i_from": "1", "i_to": "1", "ts": "10/24/19 4:06PM", "status": "unread", "reply_to": "9", "message_type": "message", "subject": "Low ASR% to Alegria - Resolved", "message": "The ticket has been resolved from our side, please retest.", "additional_data": null, "from_login": "AcmeInc", "mysql_ts": "2019-10-24 16:06:40", "seller_logo": "https://api.telecomsxchange.com/profilepics/vendor_101.png" } ] } ``` #### List Outgoing messages `POST https://apiv2.telecomsxchange.com/buyers/messages` Docs: https://www.telecomsxchange.com/api-docs/reference/members-messaging#list-outgoing-messages Show all sent messages (outbox) from my buyer account to vendors. **Query parameters** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `show` | string | optional | `outbox` | | | `limit` | integer | optional | `20` | | | `off` | integer | optional | `0` | | **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `show` | string | required | `outbox` | Sent messages | | `limit` | integer | required | `30` | limit returned results | | `off` | integer | required | `0` | offset | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/messages" \ -d "show=outbox" \ -d "limit=30" \ -d "off=0" ``` **Example response: List buyer outbox messages (HTTP 200)** ``` { "status": "success", "messages": [ { "i_message": "15", "from_type": "customer", "to_type": "vendor", "i_from": "1", "i_to": "1", "ts": "10/24/19 4:11PM", "status": "unread", "reply_to": "12", "message_type": "message", "subject": "Low ASR% to Chad", "message": "Sample numbers: 22712334566 ASR 10% and ACD 30 seconds", "additional_data": null, "to_login": "TATA", "mysql_ts": "2019-10-24 16:11:34" }, { "i_message": "14", "from_type": "customer", "to_type": "vendor", "i_from": "1", "i_to": "1", "ts": "10/24/19 4:11PM", "status": "read", "reply_to": "12", "message_type": "message", "subject": "Capacity Increase Request", "message": "Please increase our capacity to India to 1000 ports", "additional_data": null, "to_login": "Airtel", "mysql_ts": "2019-10-24 16:11:26" }, { "i_message": "13", "from_type": "customer", "to_type": "vendor", "i_from": "1", "i_to": "1", "ts": "10/24/19 4:10PM", "status": "read", "reply_to": "12", "message_type": "message", "subject": "Thank you", "message": "All issues are now resolved to Pakistan. Thank you!", "additional_data": null, "to_login": "Fabrikam", "mysql_ts": "2019-10-24 16:10:11" }, ``` #### Reply to Seller Message `POST https://apiv2.telecomsxchange.com/buyers/message/reply/{id}` Docs: https://www.telecomsxchange.com/api-docs/reference/members-messaging#reply-to-seller-message This API allows buyers to reply to sellers messages received in inbox. First you have to know the message {id} before you can reply to it. Check the list incoming messages API to retreive the message {id} that you're replying to. **Path parameters** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `id` | integer | required | `12` | ID of the inbox message you are replying to, as returned by List Incoming Messages. | **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `message` | string | required | `Ok, the case is now closed.` | | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/message/reply/12" \ -d "message=Ok, the case is now closed." ``` **Example response: Reply to Message (HTTP 200)** ```json { "status": "success", "message": "Replied", "i_message": 17 } ``` #### Compose New Message To Seller `POST https://apiv2.telecomsxchange.com/buyers/message/send` Docs: https://www.telecomsxchange.com/api-docs/reference/members-messaging#compose-new-message-to-seller This API allows you to compose a new message to sellers. **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `id` | integer | required | `2` | Seller ID | | `subject` | string | required | `Low ASR% to US Toll Free` | What is the message about ? | | `message` | string | required | `We're facing low ASR% to your Toll-Free USA route. This is a test trouble ticket! please ignore.` | What do you want to say ? "Keep it professional" | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/message/send" \ -d "id=2" \ -d "subject=Low ASR% to US Toll Free" \ -d "message=We're facing low ASR% to your Toll-Free USA route. This is a test trouble ticket! please ignore." ``` **Example response: Send message to seller (HTTP 200)** ```json { "status": "success", "message": "Message 19 sent successfully to seller Airtel", "i_message": 19 } ``` ### Sellers This section shows how you can query the current inbox and outbox messages of your seller account, and if want to reply to a buyer message or compose a new message. **Examples** - Seller may raise a message when receiving junk traffic from a specific buyer. - Seller may send a promo message about best performing routes to buyer(s). - Seller may notify buy about upcoming maintinance schedule. #### List Incoming Messages `POST https://apiv2.telecomsxchange.com/sellers/messages` Docs: https://www.telecomsxchange.com/api-docs/reference/members-messaging#sellers-list-incoming-messages Retrieve a paginated list of incoming messages sent from your TCXC account to other members. **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `show` | string | required | `inbox` | | | `pager` | integer | required | `3` | | | `off` | integer | required | `0` | | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/sellers/messages" \ -d "show=inbox" \ -d "pager=3" \ -d "off=0" ``` **Example response: List Incoming Messages (HTTP 200)** ```json { "status": "success", "messages": [ { "i_message": "20", "from_type": "customer", "to_type": "vendor", "i_from": "1", "i_to": "1", "ts": "10/28/19 2:24PM", "status": "unread", "reply_to": "12", "message_type": "message", "subject": "hi", "message": "Ok, the case is now closed.", "additional_data": null, "from_login": "AcmeInc", "buyer_logo": "http://api.telecomsxchange.com/profilepics/customer_1.png" }, { "i_message": "18", "from_type": "customer", "to_type": "vendor", "i_from": "1", "i_to": "1", "ts": "10/24/19 6:44PM", "status": "unread", "reply_to": null, "message_type": "message", "subject": "Low ASR% to US Toll Free", "message": "We're facing low ASR% to your Toll-Free USA route. This is a test trouble ticket! please ignore.", "additional_data": null, "from_login": "AcmeInc", "buyer_logo": "http://api.telecomsxchange.com/profilepics/customer_1.png" }, { "i_message": "17", "from_type": "customer", "to_type": "vendor", "i_from": "1", "i_to": "1", "ts": "10/24/19 6:39PM", "status": "unread", "reply_to": "12", "message_type": "message", "subject": "hi", "message": "Ok, the case is now closed.", "additional_data": null, "from_login": "AcmeInc", "buyer_logo": "http://api.telecomsxchange.com/profilepics/customer_1.png" } ] } ``` #### List Outgoing Messages `POST https://apiv2.telecomsxchange.com/sellers/messages` Docs: https://www.telecomsxchange.com/api-docs/reference/members-messaging#sellers-list-outgoing-messages Retrieve a paginated list of outgoing messages sent from your TCXC account to other members. **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `show` | string | required | `outbox` | | | `pager` | integer | required | `3` | | | `off` | integer | required | `0` | | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/sellers/messages" \ -d "show=outbox" \ -d "pager=3" \ -d "off=0" ``` **Example response: List Incoming Messages Copy (HTTP 200)** ```json { "status": "success", "messages": [ { "i_message": "24", "from_type": "vendor", "to_type": "customer", "i_from": "1", "i_to": "1", "ts": "10/28/19 4:55PM", "status": "unread", "reply_to": "17", "message_type": "message", "subject": "hi", "message": "testrply234567", "additional_data": null, "to_login": "AcmeInc", "buyer_logo": "http://api.telecomsxchange.com/profilepics/customer_1.png" }, { "i_message": "23", "from_type": "vendor", "to_type": "customer", "i_from": "1", "i_to": "1", "ts": "10/28/19 4:53PM", "status": "unread", "reply_to": null, "message_type": "message", "subject": "Re: Low ASR %", "message": "Thanks for th update- Please retest now", "additional_data": null, "to_login": "AcmeInc", "buyer_logo": "http://api.telecomsxchange.com/profilepics/customer_1.png" }, { "i_message": "22", "from_type": "vendor", "to_type": "customer", "i_from": "1", "i_to": "1", "ts": "10/28/19 4:52PM", "status": "unread", "reply_to": null, "message_type": "message", "subject": "hi", "message": "testmsg234567", "additional_data": null, "to_login": "AcmeInc", "buyer_logo": "http://api.telecomsxchange.com/profilepics/customer_1.png" } ] } ``` **Example response: List Incoming Messages (HTTP 200)** ```json { "status": "success", "messages": [ { "i_message": "20", "from_type": "customer", "to_type": "vendor", "i_from": "1", "i_to": "1", "ts": "10/28/19 2:24PM", "status": "unread", "reply_to": "12", "message_type": "message", "subject": "hi", "message": "Ok, the case is now closed.", "additional_data": null, "from_login": "AcmeInc", "buyer_logo": "http://api.telecomsxchange.com/profilepics/customer_1.png" }, { "i_message": "18", "from_type": "customer", "to_type": "vendor", "i_from": "1", "i_to": "1", "ts": "10/24/19 6:44PM", "status": "unread", "reply_to": null, "message_type": "message", "subject": "Low ASR% to US Toll Free", "message": "We're facing low ASR% to your Toll-Free USA route. This is a test trouble ticket! please ignore.", "additional_data": null, "from_login": "AcmeInc", "buyer_logo": "http://api.telecomsxchange.com/profilepics/customer_1.png" }, { "i_message": "17", "from_type": "customer", "to_type": "vendor", "i_from": "1", "i_to": "1", "ts": "10/24/19 6:39PM", "status": "unread", "reply_to": "12", "message_type": "message", "subject": "hi", "message": "Ok, the case is now closed.", "additional_data": null, "from_login": "AcmeInc", "buyer_logo": "http://api.telecomsxchange.com/profilepics/customer_1.png" } ] } ``` #### Reply to Buyer Message `POST https://apiv2.telecomsxchange.com/sellers/messages` Docs: https://www.telecomsxchange.com/api-docs/reference/members-messaging#reply-to-buyer-message As a seller on telecomsxchange, you can respond to a message sent to you by a buyer using this API. **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `show` | string | required | `outbox` | | | `pager` | integer | required | `3` | | | `off` | integer | required | `0` | | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/sellers/messages" \ -d "show=outbox" \ -d "pager=3" \ -d "off=0" ``` **Example response: Reply to Buyer Message (HTTP 200)** ```json { "status": "success", "message": "Replied", "i_message": 25 } ``` **Example response: List Incoming Messages Copy (HTTP 200)** ```json { "status": "success", "messages": [ { "i_message": "24", "from_type": "vendor", "to_type": "customer", "i_from": "1", "i_to": "1", "ts": "10/28/19 4:55PM", "status": "unread", "reply_to": "17", "message_type": "message", "subject": "hi", "message": "testrply234567", "additional_data": null, "to_login": "AcmeInc", "buyer_logo": "http://api.telecomsxchange.com/profilepics/customer_1.png" }, { "i_message": "23", "from_type": "vendor", "to_type": "customer", "i_from": "1", "i_to": "1", "ts": "10/28/19 4:53PM", "status": "unread", "reply_to": null, "message_type": "message", "subject": "Re: Low ASR %", "message": "Thanks for th update- Please retest now", "additional_data": null, "to_login": "AcmeInc", "buyer_logo": "http://api.telecomsxchange.com/profilepics/customer_1.png" }, { "i_message": "22", "from_type": "vendor", "to_type": "customer", "i_from": "1", "i_to": "1", "ts": "10/28/19 4:52PM", "status": "unread", "reply_to": null, "message_type": "message", "subject": "hi", "message": "testmsg234567", "additional_data": null, "to_login": "AcmeInc", "buyer_logo": "http://api.telecomsxchange.com/profilepics/customer_1.png" } ] } ``` **Example response: List Incoming Messages (HTTP 200)** ```json { "status": "success", "messages": [ { "i_message": "20", "from_type": "customer", "to_type": "vendor", "i_from": "1", "i_to": "1", "ts": "10/28/19 2:24PM", "status": "unread", "reply_to": "12", "message_type": "message", "subject": "hi", "message": "Ok, the case is now closed.", "additional_data": null, "from_login": "AcmeInc", "buyer_logo": "http://api.telecomsxchange.com/profilepics/customer_1.png" }, { "i_message": "18", "from_type": "customer", "to_type": "vendor", "i_from": "1", "i_to": "1", "ts": "10/24/19 6:44PM", "status": "unread", "reply_to": null, "message_type": "message", "subject": "Low ASR% to US Toll Free", "message": "We're facing low ASR% to your Toll-Free USA route. This is a test trouble ticket! please ignore.", "additional_data": null, "from_login": "AcmeInc", "buyer_logo": "http://api.telecomsxchange.com/profilepics/customer_1.png" }, { "i_message": "17", "from_type": "customer", "to_type": "vendor", "i_from": "1", "i_to": "1", "ts": "10/24/19 6:39PM", "status": "unread", "reply_to": "12", "message_type": "message", "subject": "hi", "message": "Ok, the case is now closed.", "additional_data": null, "from_login": "AcmeInc", "buyer_logo": "http://api.telecomsxchange.com/profilepics/customer_1.png" } ] } ``` #### Compose New Message To Buyer `POST https://apiv2.telecomsxchange.com/buyers/message/send` Docs: https://www.telecomsxchange.com/api-docs/reference/members-messaging#compose-new-message-to-buyer This API allows you to compose a new message to sellers. **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `id` | integer | required | `2` | Seller ID | | `subject` | string | required | `Low ASR% to US Toll Free` | What is the message about ? | | `message` | string | required | `We're facing low ASR% to your Toll-Free USA route. This is a test trouble ticket! please ignore.` | What do you want to say ? "Keep it professional" | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/message/send" \ -d "id=2" \ -d "subject=Low ASR% to US Toll Free" \ -d "message=We're facing low ASR% to your Toll-Free USA route. This is a test trouble ticket! please ignore." ``` **Example response: Send message to seller (HTTP 200)** ```json { "status": "success", "message": "Message 19 sent successfully to seller Airtel", "i_message": 19 } ``` **Example response: Compose New Message To Buyer (HTTP 200)** ```json { "status": "success", "message": "Message 26 sent successfully to Buyer ", "i_message": 26 } ``` #### List my buyers `POST https://apiv2.telecomsxchange.com/sellers/buyers/list` Docs: https://www.telecomsxchange.com/api-docs/reference/members-messaging#list-my-buyers This API allows you to list your subscribed buyers on TCXC. you may find out what services they have purchased from your and you can send them a message. **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/sellers/buyers/list" ``` **Example response: List my buyers (HTTP 200)** ```json { "status": "success", "buyers": [ { "i_customer": "1014", "login": "Northwind", "purchases": [ " Route:Gold+", " Route:A2P" ] }, { "i_customer": "1230", "login": "Globex", "purchases": [ " Route:Gold+" ] }, { "i_customer": "1015", "login": "demo", "purchases": [ " Route:Gold+", " Route:Silver+" ] }, "… 17 more items" ] } ``` #### Blast Message to Buyers `POST https://apiv2.telecomsxchange.com/sellers/buyers/message` Docs: https://www.telecomsxchange.com/api-docs/reference/members-messaging#blast-message-to-buyers Use this API to send a message blast to all your subscribed buyers on TelecmsXChange. **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `subject` | string | required | `New Coverage !` | Subject of message blast | | `message` | string | required | `New DID Coverage to Sudan now available for immediate use.` | Body of the blast message | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/sellers/buyers/message" \ -d "subject=New Coverage !" \ -d "message=New DID Coverage to Sudan now available for immediate use." ``` **Example response: Blast Message to Buyers (Example 2) (HTTP 200)** ```json { "status": "success", "message": "Messages have been sent successfully to buyers list " } ``` **Example response: Blast Message to Buyers (Success) (HTTP 200)** ```json { "status": "success", "message": "Messages have been sent successfully to buyers list " } ``` ## Rates Docs: https://www.telecomsxchange.com/api-docs/reference/rates The API endpoints below are recommended for those who want to sync large amount of data with their backend systems frequently. it enables you to download the current sell rates for a specific seller, connection for both voice and SMS in CSV format. **Prerequisites** The List Sellers Route Information API allows you to know the i_tariff and i_connection values for the seller / connection rates you want to download rates for. #### Carrier Rate Download (CSV) `POST https://apiv2.telecomsxchange.com/sellers/rates/{i_tariff}` Docs: https://www.telecomsxchange.com/api-docs/reference/rates#carrier-rate-download-csv This API allows you to download the current sell rates for a specific seller in CSV format. This API is ideal to retreive and sync full rate decks into your billing systems. **Prerequisites** You will need to know the i_tariff and i_connection values for the seller / connection rates you want to download rates for, it may be found through Market View API and Sellers List API. **Path parameters** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `i_tariff` | integer | required | `1065` | Tariff ID of the seller connection to download. Find it with Market View or List Sellers Route Information. | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/sellers/rates/1065" ``` **Example response: Carrier Rate Download (CSV) (HTTP 200)** ``` Country,Description,Prefix,Effective from,Rate Id,Forbidden,Discontinued,Price 1,Price N,Interval 1,Interval N,Last Day ASR,Last Week ASR,Last Day ACD,Last Week ACD,Last Day Minutes,Last Week Minutes,Statistics Time UNITED STATES OF AMERICA,Fixed - ROC,1,2019-07-09 11:39:43,107238581,0,0,0.0078,0.0078,1,1,0,0,0,0,0,0,0000-00-00 00:00:00 CANADA,Fixed - Manitoba,1204,2019-05-05 08:39:13,101549974,0,0,0.0237,0.0237,1,1,0,0,0,0,0,0,0000-00-00 00:00:00 CANADA,Fixed - Yukon Territories,1204131,2019-05-05 08:39:16,101552844,0,0,0.0237,0.0237,1,1,0,0,0,0,0,0,0000-00-00 00:00:00 CANADA,Fixed - Ontario,1226,2019-05-05 08:39:10,101547140,0,0,0.0237,0.0237,1,1,0,0,0,0,0,0,0000-00-00 00:00:00 CANADA,Fixed - Yukon Territories,1226131,2019-05-05 08:39:13,101549992,0,0,0.0237,0.0237,1,1,0,0,0,0,0,0,0000-00-00 00:00:00 CANADA,Fixed - Alberta,1236,2019-05-05 08:39:16,101552825,0,0,0.0237,0.0237,1,1,0,0,0,0,0,0,0000-00-00 00:00:00 BAHAMAS,Fixed - ROC,1242,2019-05-05 08:39:12,101549353,0,0,0.0237,0.0237,1,1,0,0,0,0,0,0,0000-00-00 00:00:00 BAHAMAS,Mobile - BaTelCo,1242357,2019-07-09 11:39:26,107229213,0,0,0.0246,0.0246,1,1,0,0,0,0,0,0,0000-00-00 00:00:00 BAHAMAS,Mobile - BaTelCo,1242359,2019-07-09 11:39:26,107229200,0,0,0.0246,0.0246,1,1,0,0,0,0,0,0,0000-00-00 00:00:00 BAHAMAS,Mobile - BaTelCo,1242375,2019-07-09 11:39:26,107229214,0,0,0.0246,0.0246,1,1,0,0,0,0,0,0,0000-00-00 00:00:00 BAHAMAS,Mobile - BaTelCo,1242376,2019-07-09 11:39:26,107229201,0,0,0.0246,0.0246,1,1,0,0,0,0,0,0,0000-00-00 00:00:00 BAHAMAS,Mobile - BaTelCo,1242395,2019-07-09 11:39:26,107229215,0,0,0.0246,0.0246,1,1,0,0,0,0,0,0,0000-00-00 00:00:00 BAHAMAS,Mobile - BaTelCo,124242,2019-07-09 11:39:26,107229202,0,0,0.0246,0.0246,1,1,0,0,0,0,0,0,0000-00-00 00:00:00 … ``` #### List Sellers Route Information `POST https://apiv2.telecomsxchange.com/sellers/list` Docs: https://www.telecomsxchange.com/api-docs/reference/rates#list-sellers-route-information “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. **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `pager` | integer | required | `10000` | integer | | `off` | integer | required | `0` | integer | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/sellers/list" \ -d "pager=10000" \ -d "off=0" ``` **Example response: List Sellers IDs (Live) (HTTP 200)** ```json { "status": "success", "routes": [ { "seller_name": "JOOD", "i_vendor": "112", "route_name": "UAE", "i_connection": "128", "i_tariff": "129", "private": "0", "i_private_connection": null }, { "seller_name": "JOOD", "i_vendor": "112", "route_name": "Orange", "i_connection": "129", "i_tariff": "130", "private": "0", "i_private_connection": null }, { "seller_name": "JOOD", "i_vendor": "112", "route_name": "My Route 1e", "i_connection": "133", "i_tariff": "134", "private": "0", "i_private_connection": null }, "… 297 more items" ] } ``` ## HLR Lookups Docs: https://www.telecomsxchange.com/api-docs/reference/hlr-lookups You can perform Global HLR lookups using Web UI or API. Get to know the portable status of the number,mobile network operator, active status, roaming and other details. With HLR Lookup you can clean your data lists, or check the status of a phone before sending an SMS. ### Buyers The **Buyers** folder contains APIs used by telecom buyers on TelecomsXChange (TCXC) to discover, test, and manage wholesale voice and messaging routes. These endpoints typically allow you to: - Authenticate as a registered TCXC buyer - Search and retrieve available routes and rate offers - Manage your orders, balances, and traffic control settings - Access reporting and quality metrics for your traffic #### Lookup Number `POST https://apiv2.telecomsxchange.com/buyers/hlr/lookup/{number}` Docs: https://www.telecomsxchange.com/api-docs/reference/hlr-lookups#lookup-number Lookup a single number data using HLR usinhg your TCXC Buyer Account. **Path parameters** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `number` | integer | required | `19542405400` | Phone number to look up in international format, without a leading + sign. | **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `i_account` | integer | required | `1501` | Enter your TCXC billing account ID. | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/hlr/lookup/19542405400" \ -d "i_account=1501" ``` **Example response: Lookup Number (HTTP 200)** ```json { "status": "success", "response": { "status": 0, "status_message": "Success", "request_id": "95c14e24-ef28-4078-b65d-fa13a909d130", "international_format_number": "19542263832", "national_format_number": "(954) 226-3832", "country_code": "US", "country_code_iso3": "USA", "country_name": "United States of America", "country_prefix": "1", "current_carrier": { "network_code": "310090", "name": "AT&T Mobility", "country": "US", "network_type": "mobile" }, "original_carrier": { "network_code": "310090", "name": "AT&T Mobility", "country": "US", "network_type": "mobile" }, "ported": "not_ported", "roaming": { "status": "unknown" } } } ``` ### Sellers The **Sellers** folder groups all endpoints used to manage, and monitor TelecomsXChange (TCXC) sellers account activity. #### Lookup Number `POST https://apiv2.telecomsxchange.com/sellers/hlr/lookup/{number}` Docs: https://www.telecomsxchange.com/api-docs/reference/hlr-lookups#sellers-lookup-number Lookup a single number data using HLR usinhg your TCXC Seller Account. **Path parameters** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `number` | integer | required | `19542405411` | Phone number to look up in international format, without a leading + sign. | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/sellers/hlr/lookup/19542405411" ``` **Example response: Lookup Number - HLR Response (HTTP 200)** ```json { "status": "success", "response": { "status": 0, "status_message": "Success", "request_id": "6d21408b-6fc5-45b7-a05b-415f299b4f4d", "international_format_number": "19542144815", "national_format_number": "(954) 214-4815", "country_code": "US", "country_code_iso3": "USA", "country_name": "United States of America", "country_prefix": "1", "current_carrier": { "network_code": "310260", "name": "T-mobile USA, Inc.", "country": "US", "network_type": "mobile" }, "original_carrier": { "network_code": "310090", "name": "AT&T Mobility", "country": "US", "network_type": "mobile" }, "ported": "ported", "roaming": { "status": "unknown" } } } ``` ## IoT Docs: https://www.telecomsxchange.com/api-docs/reference/iot All Internet of Things (IoT) apis go here. #### Buyer IoT History `POST https://apiv2.telecomsxchange.com/buyers/iothistory` Docs: https://www.telecomsxchange.com/api-docs/reference/iot#buyer-iot-history **Endpoint: POST /buyers/iothistory** **Description** The `POST /buyers/iothistory` endpoint from the TelecomsXchange API allows users to fetch the history of their Internet of Things (IoT) events. The user can filter the history based on a range of dates, allowing a better analysis of specific time periods. **Request** The API expects a `POST` request at the `https://apiv2.telecomsxchange.com/buyers/iothistory` URL. **Headers:** - Content-Type : This should be application/x-www-form-urlencoded . **Parameters:** - date_from (required): The beginning date and time of the period you want to analyze. This should be in the format YYYY-MM-DD HH:MM:SS . - date_to (required): The ending date and time of the period you want to analyze. This should be in the format YYYY-MM-DD HH:MM:SS . **Response** The API will return a JSON object containing a list of all IoT events within the specified date range. Each object will contain detailed information about the event, such as the device used, the time, the type of event, etc. **Success Response Code: 200 OK** Note: Please refer to the API's error handling documentation for information on how the API behaves when an error occurs or if incorrect data is submitted. **Rate Limiting** Please refer to the documentation of the TelecomsXchange API for details on rate limiting. **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `date_from` | datetime | required | `2021-01-01 00:00:00` | From Date YYYY-MM-DD hh:mm:ss | | `date_to` | datetime | required | `2023-06-15 00:00:00` | To Date YYYY-MM-DD hh:mm:ss | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/iothistory" \ -d "date_from=2021-01-01 00:00:00" \ -d "date_to=2023-06-15 00:00:00" ``` **Example response: Fetch IoT Detailed Records (HTTP 200)** ```json { "status": "success", "mqtt_messages": [ { "i_mqtt_message": "192", "i_account": "69", "i_customer": "1", "topic": "weather", "payload": "Amman 12°C and Mostly Cloudy", "direction": "1", "authorized": "1", "charged_amount": "0.0001", "ts": "2023-05-22 16:11:05", "account_name": "mqtt1" }, { "i_mqtt_message": "191", "i_account": "69", "i_customer": "1", "topic": "IOS", "payload": "Off", "direction": "1", "authorized": "1", "charged_amount": "0.0001", "ts": "2023-05-21 21:32:19", "account_name": "mqtt1" }, { "i_mqtt_message": "190", "i_account": "69", "i_customer": "1", "topic": "IOS", "payload": "Off", "direction": "1", "authorized": "1", "charged_amount": "0.0001", "ts": "2023-05-20 13:49:40", "account_name": "mqtt1" }, "… 47 more items" ] } ``` ## Reports Docs: https://www.telecomsxchange.com/api-docs/reference/reports ### Buyers #### Voice Summary Report `POST https://apiv2.telecomsxchange.com/buyers/voice/summary` Docs: https://www.telecomsxchange.com/api-docs/reference/reports#voice-summary-report **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `date_from` | datetime | required | `2026-08-01 00:00:00` | Start of the range, inclusive. Format YYYY-MM-DD HH:MM:SS. | | `date_to` | datetime | required | `2026-10-31 00:00:00` | End of the range, inclusive. Use 23:59:59 to get the whole final day. | | `time_format` | string | required | `monthly` | daily splits the range into one row per day. Any other value gives one row per calendar month. | | `status` | string | required | `all` | good reads answered calls. bad reads failed calls. Any other value, such as all, reads both. | | `i_vendor` | integer | optional | `299` | | | `i_connection` | integer | optional | `653` | integer connection ids, default all purchased routes | | `accounts[]` | integer | optional | `1855` | Your buyer account ids, repeated once per account. Omit the key entirely to cover all your voice accounts. | | `destination_descriptions[]` | string | optional | `EGYPT - Mobile - Vodafone` | Country and description joined by a hyphen, repeated once per destination. Omit to cover all destinations. | | `download` | integer | optional | `0` | 0 returns JSON. 1 returns a CSV attachment instead. | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/voice/summary" \ -d "date_from=2026-08-01 00:00:00" \ -d "date_to=2026-10-31 00:00:00" \ -d "time_format=monthly" \ -d "status=all" ``` **Example response: Voice Summary Report (HTTP 200)** ```json { "status": "success", "summary": [ { "date_from": "2026-08-01 00:00:00", "date_to": "2026-08-31 23:59:59", "date_text": "2026 Aug", "total_amt": 67.245, "total_minutes": 619.3167, "total_calls": 1034 }, { "date_from": "2026-09-01 00:00:00", "date_to": "2026-09-30 23:59:59", "date_text": "2026 Sep", "total_amt": 327.73, "total_minutes": 2982.7667, "total_calls": 5299 }, { "date_from": "2026-10-01 00:00:00", "date_to": "2026-10-31 00:00:00", "date_text": "2026 Oct", "total_amt": 0, "total_minutes": 0, "total_calls": 0 } ] } ``` #### SMS Summary Report `POST https://apiv2.telecomsxchange.com/buyers/sms/summary` Docs: https://www.telecomsxchange.com/api-docs/reference/reports#sms-summary-report **Body parameters (application/x-www-form-urlencoded)** | Name | Type | Required | Example | Description | | --- | --- | --- | --- | --- | | `date_from` | datetime | required | `2021-08-01 00:00:00` | Start of the range, inclusive. Format YYYY-MM-DD HH:MM:SS. | | `date_to` | datetime | required | `2026-09-31 23:59:59` | End of the range, inclusive. Use 23:59:59 to get the whole final day. | | `time_format` | string | required | `monthly` | daily splits the range into one row per day. Any other value gives one row per calendar month. | | `status` | string | required | `all` | good reads submitted messages. bad reads failed messages. Any other value, such as all, reads both. | | `i_vendor` | integer | optional | `436` | | | `i_connection` | integer | optional | `1160` | integer connection ids, default all purchased routes | | `accounts[]` | integer | optional | `1855` | Your buyer account ids, repeated once per account. Omit the key entirely to cover all your voice accounts. | | `destination_descriptions[]` | string | optional | `Oman` | Country and description joined by a hyphen, repeated once per destination. Omit to cover all destinations. | | `download` | integer | optional | `0` | 0 returns JSON. 1 returns a CSV attachment instead. | **Example request** ```bash curl --digest -u "USERNAME:API_KEY" -X POST "https://apiv2.telecomsxchange.com/buyers/sms/summary" \ -d "date_from=2021-08-01 00:00:00" \ -d "date_to=2026-09-31 23:59:59" \ -d "time_format=monthly" \ -d "status=all" ``` **Example response: SMS Summary Report (HTTP 200)** ```json { "status": "success", "summary": [ { "date_from": "2021-08-01 00:00:00", "date_to": "2021-08-31 23:59:59", "date_text": "2021 Aug", "total_amt": 3.3606, "total_sms": 28 }, { "date_from": "2021-09-01 00:00:00", "date_to": "2021-09-30 23:59:59", "date_text": "2021 Sep", "total_amt": 1.8883, "total_sms": 85 }, { "date_from": "2021-10-01 00:00:00", "date_to": "2021-10-31 23:59:59", "date_text": "2021 Oct", "total_amt": 0.0452, "total_sms": 2 }, "… 60 more items" ] } ```