{
 "openapi": "3.0.3",
 "info": {
  "title": "TelecomsXchange API",
  "version": "2026-10-15",
  "description": "Verified against the platform source. Guides and examples: https://help.telecomsxchange.com/reference/",
  "contact": {
   "name": "TelecomsXchange",
   "url": "https://www.telecomsxchange.com"
  }
 },
 "servers": [
  {
   "url": "https://apiv2.telecomsxchange.com"
  }
 ],
 "security": [
  {
   "digestAuth": []
  }
 ],
 "components": {
  "securitySchemes": {
   "digestAuth": {
    "type": "http",
    "scheme": "digest",
    "description": "Username: your portal login. Password: your API key (Profile & Preferences)."
   }
  }
 },
 "tags": [
  {
   "name": "Accounts",
   "description": "A buyer account is how traffic reaches TelecomsXchange: a SIP trunk authorised by IP or digest login, an SMPP bind, or an IoT (MQTT) login. Each account has its own balance (or uses another account's), its own purchased routes and its own alerts. Create accounts, change their credentials and authorise extra IP addresses."
  },
  {
   "name": "Voice and SMS market",
   "description": "Market View is the exchange's live order book: every seller's routes with their current price, quality (ASR, ACD) and capacity. Search it for a destination, download a seller's full rate deck, read the busiest destinations, and list your active calls and call or message records."
  },
  {
   "name": "Interconnects",
   "description": "Buying a route from Market View creates an interconnect between one of your accounts and the seller's route. Traffic sent with the route's tech prefix then terminates on it, billed per minute or per message from the account's balance. Purchasing is free; you pay only for traffic."
  },
  {
   "name": "Routing groups",
   "description": "A routing group combines several purchased routes behind one tech prefix (444 and three digits) and chooses a route for each call or message by least cost, failover order or weighted load balancing, with optional rules per destination or caller prefix."
  },
  {
   "name": "Phone numbers (DIDs)",
   "description": "Buy and sell virtual phone numbers. Buyers search the number market, purchase numbers and point them at a SIP or SMPP endpoint; sellers list their numbers with setup and recurring fees. Numbers renew automatically from the billing account's balance."
  },
  {
   "name": "eSIMs",
   "description": "Prepaid data eSIMs for single countries, regions and the whole world, sold by the eSIM providers on the exchange, such as Airalo and eSimplified. Purchases are charged to an account balance and return the activation code, LPA string and QR code at once."
  },
  {
   "name": "HLR lookups",
   "description": "Ask the mobile networks about a number: its current carrier and MCC/MNC, whether it has been ported and whether it is roaming. Each lookup costs $0.05 and is charged as soon as it is sent."
  },
  {
   "name": "Balances and payments",
   "description": "Read buyer account balances and payment history, and the seller balance and payout history."
  },
  {
   "name": "Reports",
   "description": "Traffic summaries by period, and the detail records for IoT (MQTT) messages."
  },
  {
   "name": "Messages",
   "description": "The exchange's internal messaging between buyers and sellers: read your inbox, reply, write to a seller about one of their routes, and, as a seller, list your buyers and message them."
  },
  {
   "name": "Tools",
   "description": "Helpers for testing and integration: list seller IDs and score a phone number by whether it has carried traffic on the exchange."
  },
  {
   "name": "Message classification (AI)",
   "description": "Open Text Shield, the TelecomsXchange SMS classifiers, served from their own host. The threat classifier labels a message as ham, spam or phishing; the category classifier labels what kind of message it is."
  }
 ],
 "paths": {
  "/buyers/account/add": {
   "post": {
    "tags": [
     "Accounts"
    ],
    "summary": "Create a buyer account",
    "description": "Creates a buyer account: a voice SIP trunk authorised by IP address, SIP login or both (`smpp=0`), an SMPP bind (`smpp=1`) or an IoT MQTT login (`smpp=2`). Returns the new `i_account`. For voice and SMPP accounts TCXC emails you, and texts you if an SMS number is on file, that a new origination IP or login was registered. Free.\n\nSend every field in the form body; fields in the query string are ignored.",
    "operationId": "buyers-accounts-add",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/accounts/#create-a-buyer-account"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Account has been added",
           "new_i_account": 2088
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "name": {
          "type": "string",
          "example": "Northwind-SIP",
          "description": "Account name, unique among your accounts."
         },
         "smpp": {
          "type": "integer",
          "enum": [
           0,
           1,
           2
          ],
          "default": 0,
          "example": 0,
          "description": "Account type: 0 voice (SIP), 1 SMPP, 2 IoT (MQTT)."
         },
         "ip_address": {
          "type": "string",
          "example": "203.0.113.25",
          "description": "IPv4 or IPv6 address your traffic comes from. Voice accounts need `ip_address`, `voip_login` or both. An IP used for IP-only authentication cannot be shared with another account."
         },
         "voip_login": {
          "type": "string",
          "example": "nw_sip_01",
          "description": "SIP username (voice), SMPP system_id (required when smpp=1) or MQTT username (smpp=2; must start with your customer ID zero-padded to 10 digits, such as 0000001014). Must be unique."
         },
         "voip_password": {
          "type": "string",
          "example": "pw-Xr83kq2L",
          "description": "SIP, SMPP or MQTT password for `voip_login`."
         },
         "use_balance": {
          "type": "integer",
          "default": 0,
          "example": 0,
          "description": "`i_account` of another of your accounts whose balance this account should spend. 0 gives the account its own balance."
         },
         "subscribe_all_pr": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": 1,
          "description": "Voice accounts only: 1 adds every unblocked route your other accounts have bought to the new account, with the same ASR and ACD alert and block thresholds."
         }
        },
        "required": [
         "name"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "You have to specify IP Address or voip_login or both",
      "when": "a voice account (smpp=0) has neither ip_address nor voip_login"
     },
     {
      "message": "IP should be IP address, say 1.2.3.4",
      "when": "ip_address is given but is not a valid IPv4 or IPv6 address"
     },
     {
      "message": "IP is not unique",
      "when": "a voice account without voip_login uses an IP already authorised for IP-only authentication on the exchange"
     },
     {
      "message": "This IP address is already being authenticated",
      "when": "a voice account without voip_login uses an IP that another voice account already has"
     },
     {
      "message": "Wrong Prefix for login",
      "when": "smpp=2 and voip_login does not start with your 10-digit zero-padded customer ID"
     },
     {
      "message": "This Login is not unique",
      "when": "smpp=2 and voip_login is already in use"
     },
     {
      "message": "Empty SMPP system Id not allowed:",
      "when": "smpp=1 and voip_login is empty"
     },
     {
      "message": "Name is not unique, choose another name",
      "when": "you already have an account with this name"
     },
     {
      "message": "Empty name not allowed",
      "when": "name is empty"
     },
     {
      "message": "voip_login is not unique, choose another voip_login<voip_login>",
      "when": "a voice account's voip_login is already taken; the login follows the message with no space"
     },
     {
      "message": "voip_login is not unique om the ip, choose another voip_login or ip",
      "when": "an SMPP account with the same system_id and IP already exists"
     }
    ]
   }
  },
  "/buyers/account/edit/{i_account}": {
   "post": {
    "tags": [
     "Accounts"
    ],
    "summary": "Update a buyer account",
    "description": "Replaces the settings of one of your accounts: name, IP, login and password, which balance it spends, low-balance alert, block flag and, for SMPP accounts, the default route or routing group. This is a full update: optional fields you leave out are reset, so `blocked` becomes 0, `notification_balance` is cleared, and `smpp_rate_limit`, `default_routing_group` and `subspace` become 0. If the IP address or login changes, TCXC emails you, and texts you if an SMS number is on file. Free.\n\nSend every field in the form body; fields in the query string are ignored. Send the account's current values for any setting you don't want to change.",
    "operationId": "buyers-accounts-edit",
    "parameters": [
     {
      "name": "i_account",
      "in": "path",
      "required": true,
      "description": "The account to update.",
      "schema": {
       "type": "integer",
       "example": 1022
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/accounts/#update-a-buyer-account"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Account has been updated"
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "name": {
          "type": "string",
          "example": "Northwind",
          "description": "Account name."
         },
         "use_balance": {
          "type": "integer",
          "example": 0,
          "description": "`i_account` of the account whose balance this one spends, or 0 for its own balance."
         },
         "ip_address": {
          "type": "string",
          "example": "203.0.113.10",
          "description": "IPv4 or IPv6 address. Voice accounts need `ip_address`, `voip_login` or both."
         },
         "voip_login": {
          "type": "string",
          "description": "SIP username, SMPP system_id (required for SMPP accounts) or MQTT username."
         },
         "voip_password": {
          "type": "string",
          "description": "New password. Leave empty to keep the current one."
         },
         "blocked": {
          "type": "integer",
          "description": "Send this field, with any value, to block the account; omit it to leave the account unblocked. A blocked account cannot send traffic."
         },
         "notification_balance": {
          "type": "number",
          "example": 1000,
          "description": "Send a low-balance alert when the balance falls below this amount. Empty switches the alert off."
         },
         "smpp_rate_limit": {
          "type": "integer",
          "default": 0,
          "example": 0,
          "description": "SMPP accounts: messages-per-second limit for the bind; 0 sets no limit."
         },
         "default_routing_group": {
          "type": "integer",
          "default": 0,
          "example": 0,
          "description": "SMPP accounts: `i_routing_group` to use by default; must be one of your routing groups. Setting it clears the default purchased route."
         },
         "smpp_default": {
          "type": "integer",
          "description": "SMPP accounts: `i_purchased_route` of one of this account's routes to make the default; clears `default_routing_group`."
         },
         "subspace": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": 0,
          "description": "1 authenticates calls from the Subspace network by its special header instead of the source IP."
         }
        },
        "required": [
         "name",
         "use_balance"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Unexpected DB error",
      "when": "i_account is not one of your accounts; returned as plain text, not JSON"
     },
     {
      "message": "You have to specify IP Address or voip_login or both",
      "when": "a voice or IoT account has neither ip_address nor voip_login"
     },
     {
      "message": "IP should be either IP address, say 1.2.3.4 or host:port like 1.2.3.4:5060",
      "when": "ip_address is not a valid IPv4 or IPv6 address (host:port is not accepted)"
     },
     {
      "message": "IP is not unique",
      "when": "a voice account without voip_login uses an IP already authorised for IP-only authentication on another account"
     },
     {
      "message": "'notification_balance' parameter expects numeric",
      "when": "notification_balance is not empty and not a number"
     },
     {
      "message": "This IP address is already being authenticated",
      "when": "a voice account without voip_login uses an IP that another voice account has"
     },
     {
      "message": "Empty SMPP system Id not allowed",
      "when": "an SMPP account's voip_login is empty"
     },
     {
      "message": "rouing group not found",
      "when": "an SMPP account's default_routing_group is not one of your routing groups"
     },
     {
      "message": "'use_balance' parameter expects integer",
      "when": "use_balance is missing or not a number"
     },
     {
      "message": "voip_login is not unique, choose another voip_login",
      "when": "a voice account's voip_login is used by another account"
     },
     {
      "message": "voip_login is not unique on the ip, choose another voip_login",
      "when": "another SMPP account has the same system_id and IP"
     },
     {
      "message": "Empty name not allowed",
      "when": "name is empty"
     }
    ]
   }
  },
  "/buyers/account/additional_ip_add/{i_account}": {
   "post": {
    "tags": [
     "Accounts"
    ],
    "summary": "Add an extra IP to an account",
    "description": "Authorises one more source IP address for one of your accounts, so traffic from the main IP or any additional IP is accepted for it. Returns the ID of the new IP entry. Free.\n\nSend `ip_address` in the form body; it is ignored in the query string.",
    "operationId": "buyers-accounts-additional-ip-add",
    "parameters": [
     {
      "name": "i_account",
      "in": "path",
      "required": true,
      "description": "The account to add the IP to.",
      "schema": {
       "type": "integer",
       "example": 1022
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/accounts/#add-an-extra-ip-to-an-account"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "IP has been added",
           "new_i_remote_ip_auth": 311
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "ip_address": {
          "type": "string",
          "example": "198.51.100.40",
          "description": "IPv4 or IPv6 address to authorise."
         }
        },
        "required": [
         "ip_address"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Missing i_account",
      "when": "the path has no i_account, or it is 0"
     },
     {
      "message": "i_account not found",
      "when": "the account is not one of yours"
     },
     {
      "message": "IP should be IP address, say 1.2.3.4",
      "when": "ip_address is missing or not a valid IPv4 or IPv6 address"
     },
     {
      "message": "The IP is already used up",
      "when": "the account has no voip_login and the IP is already authorised for IP-only authentication on the exchange"
     }
    ]
   }
  },
  "/marketview/search": {
   "post": {
    "tags": [
     "Voice and SMS market"
    ],
    "summary": "Search Market View",
    "description": "Searches the live order book of seller routes (voice by default, SMS with smpp=1) by prefix, country, destination description or seller. Each rate comes with the seller and route, the price you pay including the TCXC commission, billing intervals, capacity, daily and weekly ASR, ACD and minutes, the seller's rating, and any scheduled price changes in `frates`. Routes from anonymous sellers show `vendor_name` Anonymous and `i_vendor` 0. Results are sorted by weekly ASR unless you set `order`. Searching is free.\n\nErrors return `{\"status\": \"error\", \"message\": \"...\"}`. The response has no total count: keep requesting with a higher `off` until fewer than `pager` rates come back. Prefer `country_name` to `country_code`, which can be inaccurate for a few countries.",
    "operationId": "voice-exchange-search-market-view-voice",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/market/#search-market-view"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "rates": [
            {
             "prefix": "4477",
             "vendor_name": "Northwind",
             "connection_name": "UK Mobile Premium",
             "i_tariff": "655",
             "daily_asr": 41.2,
             "weekly_asr": 38.75,
             "daily_acd": 3.1,
             "weekly_acd": 2.9,
             "daily_minutes": 15230,
             "weekly_minutes": 98410,
             "stats_time": "2026-10-21 03:05:27",
             "i_connection": "653",
             "effective_from": "10/01/26 9:00AM",
             "price_1": "0.011330",
             "price_n": "0.011330",
             "interval_1": "1",
             "interval_n": "1",
             "i_vendor": "299",
             "capacity_limit": "500",
             "i_rate": "143754804",
             "forbidden": "0",
             "discontinued": "0",
             "route_type": "CLI",
             "seller_registration_date": "2019-09-13 20:16:26",
             "vendor_short_memo": "Tier 1 carrier routes",
             "connection_short_memo": "Direct to network, CLI delivered",
             "anonymous": "0",
             "pos_on_page": 0,
             "country_code": "gb",
             "country_name": "United Kingdom",
             "description": "Mobile - Vodafone",
             "mccmnc": "23415",
             "seller_avg_rating": 4.5,
             "seller_reviews": 12,
             "orig_effective_from": "2026-10-01 09:00:00",
             "rateid": 143754804,
             "frates": [
              {
               "effective_from": "2026-11-01 00:00:00",
               "price_1": "0.0115",
               "price_n": "0.0115",
               "interval_1": "1",
               "interval_n": "1"
              }
             ]
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "searchform": {
          "type": "integer",
          "enum": [
           1
          ],
          "example": 1,
          "description": "Always send 1. Without it the response contains no rates."
         },
         "prefix": {
          "type": "string",
          "example": "4477",
          "description": "Dialling prefix to match: country code, optionally followed by an area or network code. Digits only. A prefix that starts with 1 needs at least four digits. Send at least one of prefix, country, description or seller."
         },
         "country": {
          "type": "string",
          "example": "UNITED KINGDOM",
          "description": "Country name exactly as TCXC lists it, for example UNITED KINGDOM."
         },
         "description": {
          "type": "string",
          "example": "Mobile",
          "description": "Text to match in the destination description, such as Mobile or a network name."
         },
         "seller": {
          "type": "string",
          "example": "Northwind",
          "description": "Seller login. Must be an existing seller; routes are matched on any login containing this text. Anonymous routes are excluded when you set it."
         },
         "sellerlike": {
          "type": "string",
          "enum": [
           "LIKE",
           "NOT LIKE"
          ],
          "default": "LIKE",
          "description": "Send NOT LIKE to exclude the seller given in `seller` instead of matching it."
         },
         "route": {
          "type": "string",
          "description": "Route name to match exactly. `any` means no filter."
         },
         "type": {
          "type": "string",
          "example": "CLI",
          "description": "Route type, for example CLI, NCLI, TDM or NA. `any` means no filter."
         },
         "smpp": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": 0,
          "description": "1 searches SMS routes, 0 voice routes."
         },
         "order": {
          "type": "string",
          "enum": [
           "asr",
           "acd",
           "minutes",
           "price"
          ],
          "default": "asr",
          "description": "Sort by weekly ASR, weekly ACD or weekly minutes (highest first), or by price (lowest first)."
         },
         "min_price": {
          "type": "number",
          "description": "Only routes priced at or above this amount per minute or per message, including a 3% commission."
         },
         "max_price": {
          "type": "number",
          "description": "Only routes priced at or below this amount per minute or per message, including a 3% commission."
         },
         "pager": {
          "type": "integer",
          "default": 50,
          "example": 50,
          "description": "Number of rates to return."
         },
         "off": {
          "type": "integer",
          "default": 0,
          "example": 0,
          "description": "Number of rates to skip, for paging."
         },
         "download": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "description": "1 returns every matching rate as a CSV file (route_lookup.csv) instead of JSON, ignoring pager and off."
         }
        },
        "required": [
         "searchform"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "At least one of  Search Criterias Prefix/Country/Description/Seller is mandatory.",
      "when": "prefix, country, description and seller are all empty"
     },
     {
      "message": "The prefix must be only numbers.",
      "when": "prefix contains anything other than digits"
     },
     {
      "message": "Prefix 1 should be followed by at least 3 digit area code.",
      "when": "prefix starts with 1 and is shorter than four digits"
     },
     {
      "message": "Seller Not Found",
      "when": "seller is not an existing seller login"
     },
     {
      "message": "Country Not Found",
      "when": "country is not a country name TCXC lists"
     },
     {
      "message": "The country must be only characters.",
      "when": "country contains no letters"
     },
     {
      "message": "The description must be only characters.",
      "when": "description contains no letters"
     },
     {
      "message": "The term 'SELECT' cannot be used in your search.",
      "when": "country or description contains the word SELECT (DELETE and UPDATE return the same message with that word)"
     }
    ]
   }
  },
  "/sellers/rates/{i_tariff}": {
   "post": {
    "tags": [
     "Voice and SMS market"
    ],
    "summary": "Download a route's rate deck",
    "description": "Downloads the full rate deck of a seller route as a CSV file: one row per prefix with country, description, effective date, rate ID, forbidden and discontinued flags, first and next-interval prices, billing intervals, and last-day and last-week ASR, ACD and minutes. Prices include the TCXC commission, so they are what you pay. Find a route's `i_tariff` with Market View, List seller routes or List interconnects. Authenticate with your buyer credentials. Free.\n\nThe file arrives as an attachment named after the seller and route, for example NorthStarTel_route_Premium.csv. An unknown `i_tariff` returns only the header row. Send `xls` in the form body.",
    "operationId": "voice-exchange-carrier-rate-download-csv",
    "parameters": [
     {
      "name": "i_tariff",
      "in": "path",
      "required": true,
      "description": "The route's tariff ID (`i_tariff`).",
      "schema": {
       "type": "integer",
       "example": 866
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/market/#download-a-route-s-rate-deck"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {}
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "xls": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "description": "1 returns an Excel (.xls) file instead of CSV."
         }
        }
       }
      }
     }
    }
   }
  },
  "/sellers/toproutes": {
   "get": {
    "tags": [
     "Voice and SMS market"
    ],
    "summary": "Top destinations by traffic",
    "description": "Returns the busiest destinations across the whole exchange over a period: the last 24 hours, the 24 hours before that, the last 7 days or the last month. Results are grouped by country, busiest first. Each country lists its billing prefixes with the price billed, the route type and the route ID (`id`), busiest first. Voice is ranked by minutes, SMS (smpp=1) by message count. Free.\n\nAuthenticate with your buyer login and API key; seller credentials are rejected on this path. Errors return `{\"status\": \"error\", \"message\": \"...\"}`. SMS results have no `type` field.",
    "operationId": "voice-exchange-top-voice-destinations",
    "parameters": [
     {
      "name": "period",
      "in": "query",
      "required": true,
      "description": "today is the last 24 hours, yesterday the 24 hours before that, week the last 7 days, month the last month up to now.",
      "schema": {
       "type": "string",
       "enum": [
        "today",
        "yesterday",
        "week",
        "month"
       ],
       "example": "week"
      }
     },
     {
      "name": "number",
      "in": "query",
      "required": false,
      "description": "How many countries to return, from 1 to 20.",
      "schema": {
       "type": "integer",
       "default": 5,
       "example": 5
      }
     },
     {
      "name": "type",
      "in": "query",
      "required": false,
      "description": "Only count traffic on routes of this type. Voice only: leave empty when smpp is 1.",
      "schema": {
       "type": "string",
       "enum": [
        "CLI",
        "NCLI",
        "TDM",
        "NA"
       ],
       "example": "CLI"
      }
     },
     {
      "name": "smpp",
      "in": "query",
      "required": false,
      "description": "1 ranks SMS traffic, 0 voice traffic.",
      "schema": {
       "type": "integer",
       "enum": [
        0,
        1
       ],
       "default": 0,
       "example": 0
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/market/#top-destinations-by-traffic"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "top_routes": {
            "NIGERIA": {
             "routes": [
              {
               "billing_prefix": "234803",
               "price": "0.0761",
               "type": "CLI",
               "id": "882",
               "description": "Mobile - MTN"
              },
              {
               "billing_prefix": "234805",
               "price": "0.0702",
               "type": "CLI",
               "id": "882",
               "description": "Mobile - Glo"
              }
             ]
            },
            "UNITED KINGDOM": {
             "routes": [
              {
               "billing_prefix": "447",
               "price": "0.0113",
               "type": "CLI",
               "id": "653",
               "description": "Mobile"
              }
             ]
            }
           }
          }
         }
        }
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "period parameter error. Supported values are today, yesterday, week, month",
      "when": "period is missing or not one of the four values"
     },
     {
      "message": "type parameter error. Supported values are <empty value>/<unset>, TDM, CLI, NCLI, NA",
      "when": "type is set to anything other than TDM, CLI, NCLI or NA"
     },
     {
      "message": "smpp parameter error. Supported values are <empty value>/<unset>, 0, 1 ",
      "when": "smpp is not 0 or 1"
     },
     {
      "message": "type parameter error. Only support for non-smpp reports",
      "when": "type is set together with smpp=1"
     },
     {
      "message": "number parameter error. Allowed values are from 1 to 20",
      "when": "number is below 1, above 20, or not a number"
     }
    ]
   }
  },
  "/buyers/account/list": {
   "post": {
    "tags": [
     "Voice and SMS market"
    ],
    "summary": "List buyer accounts",
    "description": "Returns your buyer accounts (voice, SMPP and IoT) with their settings: authorised IP, SIP or SMPP login, balance, credit and capacity limits, the account whose balance each one spends, and, for SMPP accounts, whether the bind is online. Blocked accounts are left out unless `show_blocked=1`. Free.\n\nSend parameters in the form body; they are ignored in the query string. Names are upper-case and balances are formatted strings with two decimals and a thousands separator, such as \"4,035.45\". `smpp_bind_status` is ONLINE or OFFLINE for SMPP accounts and empty for others.",
    "operationId": "voice-exchange-list-buyer-accounts",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/market/#list-buyer-accounts"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "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": "smpp307104",
             "smpp": "1",
             "smpp_rate_limit": "0",
             "default_routing_group": "0",
             "subspace": "0",
             "mqtt": "0",
             "window_size": "1000",
             "recurring": "0",
             "recurring_amount": "0",
             "lower_limit": "0",
             "parent_balance": "4,035.45",
             "parent_name": "NORTHWIND",
             "smpp_bind_status": "ONLINE"
            },
            {
             "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": "",
             "smpp": "0",
             "smpp_rate_limit": "0",
             "default_routing_group": "0",
             "subspace": "0",
             "mqtt": "0",
             "window_size": "1000",
             "recurring": "0",
             "recurring_amount": "0",
             "lower_limit": "0",
             "parent_balance": "0.00",
             "parent_name": "",
             "smpp_bind_status": ""
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "show_blocked": {
          "type": "integer",
          "enum": [
           0,
           1,
           -1
          ],
          "default": 0,
          "example": 0,
          "description": "1 includes blocked accounts. 0 or -1 leaves them out."
         },
         "disable_recurring": {
          "type": "integer",
          "description": "An `i_account` whose automatic card top-up should be switched off before the list is returned. This clears the account's top-up amount, threshold and saved card."
         }
        }
       }
      }
     }
    }
   }
  },
  "/buyers/tools/getnumbers": {
   "get": {
    "tags": [
     "Voice and SMS market"
    ],
    "summary": "Get test numbers",
    "description": "Returns phone numbers that recently carried traffic on the exchange for a prefix, country or network, to use as targets in route tests. Numbers are picked at random from recent matching calls, so repeated requests return different numbers. Each comes with its billing prefix and the destination's country and description. Free.\n\nWhen you put the prefix in the path, send `country`, `description` and `limit` in a POST body; they are ignored in the query string on that form. Errors return `{\"status\": \"error\", \"message\": \"...\"}`. When a number's destination is unknown, `country_code`, `country_name` and `description` are N/A. Prefer `country_name` to `country_code`, which can be inaccurate for a few countries.",
    "operationId": "voice-exchange-get-test-numbers",
    "parameters": [
     {
      "name": "prefix",
      "in": "query",
      "required": false,
      "description": "Number prefix to match: country code plus an optional area or network code. You can also put it in the path: /buyers/tools/getnumbers/{prefix}. Send at least one of prefix, country or description.",
      "schema": {
       "type": "string",
       "example": "91"
      }
     },
     {
      "name": "country",
      "in": "query",
      "required": false,
      "description": "Text to match in the country name, for example India.",
      "schema": {
       "type": "string",
       "example": "India"
      }
     },
     {
      "name": "description",
      "in": "query",
      "required": false,
      "description": "Text to match in the destination description, usually a network name such as Airtel.",
      "schema": {
       "type": "string",
       "example": "Airtel"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "How many numbers to return, up to 1000.",
      "schema": {
       "type": "integer",
       "default": 10,
       "example": 10
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/market/#get-test-numbers"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "cdrs": [
            {
             "CLD": "919812345670",
             "billing_prefix": "9198",
             "country_code": "in",
             "country_name": "India",
             "description": "Mobile - Airtel"
            },
            {
             "CLD": "919845551203",
             "billing_prefix": "9198",
             "country_code": "in",
             "country_name": "India",
             "description": "Mobile - Airtel"
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "prefix or country description parameters expected",
      "when": "prefix, country and description are all empty"
     },
     {
      "message": "Prefix format error. Expected \"12345\" ",
      "when": "prefix contains no digits; the rejected value follows the message"
     },
     {
      "message": "Country may only contain letters ",
      "when": "country contains no letters"
     },
     {
      "message": "Description may only contain letters ",
      "when": "description contains no letters"
     },
     {
      "message": "Limit less than 1000 expected",
      "when": "limit is above 1000"
     }
    ]
   }
  },
  "/buyers/routetest": {
   "post": {
    "tags": [
     "Voice and SMS market"
    ],
    "summary": "Start a route test call",
    "description": "Queues a two-leg test call through one of your accounts: TCXC calls `cld1` over route `i_connection1` showing caller ID `cli1`, then calls `cld2` over route `i_connection2` showing `cli2`. Both routes must be purchased on `i_account`; to test one route, send the same route ID twice. Both legs are ordinary calls charged to `i_account` at the purchased routes' rates. The response confirms the test was queued, not how the calls went.\n\nCheck `status_text`, not `status`: errors also return `status: ok`. Always send `i_account`; without it the response body is empty. Send `cld1` and `cld2` as plain digits.",
    "operationId": "voice-exchange-initiate-route-test",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/market/#start-a-route-test-call"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "ok",
           "status_text": "Test call has been initiated"
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "i_account": {
          "type": "integer",
          "example": 1501,
          "description": "ID of your account that places and pays for the test calls."
         },
         "cld1": {
          "type": "string",
          "example": "447700900123",
          "description": "First number to call, in E.164 format without the plus sign."
         },
         "cli1": {
          "type": "string",
          "example": "12025550143",
          "description": "Caller ID to show on the first call. Digits only; a leading + or 0 is removed."
         },
         "i_connection1": {
          "type": "integer",
          "example": 653,
          "description": "Route ID (`i_connection` in Market View) for the first call. Must be purchased on `i_account`."
         },
         "cld2": {
          "type": "string",
          "example": "4915112345678",
          "description": "Second number to call, in E.164 format without the plus sign."
         },
         "cli2": {
          "type": "string",
          "example": "12025550178",
          "description": "Caller ID to show on the second call. Digits only."
         },
         "i_connection2": {
          "type": "integer",
          "example": 864,
          "description": "Route ID for the second call. Must be purchased on `i_account`. Repeat `i_connection1` to test one route."
         }
        },
        "required": [
         "i_account",
         "cld1",
         "cli1",
         "i_connection1",
         "cld2",
         "cli2",
         "i_connection2"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Selected account does not have a purchased for selected route(s), please choose other combination or purchase selected route(s) on this account",
      "when": "i_account is not one of your accounts, or i_connection1 or i_connection2 is not purchased on it"
     },
     {
      "message": "CLD format error",
      "when": "cld1 or cld2 is not a number"
     }
    ]
   }
  },
  "/buyers/livecalls": {
   "post": {
    "tags": [
     "Voice and SMS market"
    ],
    "summary": "List active calls",
    "description": "Lists the calls in progress or being routed on all of your accounts, oldest first: called and calling numbers, seller and route, billing prices, authorised duration and amount, and seconds elapsed. Inbound calls to your numbers show `connection_name` Inbound and `route_type` DID. Can also hang up one of your calls. Free.\n\n`type` is Connected or Routing. `total_rows` counts every matching call, not just this page. A `disconnect` request returns the call list; check that the call has gone from a later list to confirm the hang-up.",
    "operationId": "voice-exchange-list-active-calls",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/market/#list-active-calls"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "live_calls": [
            {
             "i_live_call": "608114221",
             "call_id": "46a570fafe8c11e9a4880cc47ab0b860@198.51.100.10-b2b_1",
             "type": "Connected",
             "CLD": "447700900123",
             "CLI": "12025550143",
             "authorized_duration": "3600",
             "authorized_amount": 0.6798,
             "connect_time": "2026-10-22 10:53:58",
             "setup_time": "2026-10-22 10:53:57",
             "interim_update_time": null,
             "i_account": "1501",
             "i_purchased_route": "90124",
             "i_vendor": "259",
             "i_connection": "653",
             "i_rate": "111788009",
             "billing_prefix": "4477",
             "billing_price_1": 0.0113,
             "billing_price_n": 0.0113,
             "billing_interval_1": "1",
             "billing_interval_n": "1",
             "cancel_flag": "0",
             "parent_call_id": "46a570fafe8c11e9a4880cc47ab0b860@198.51.100.10",
             "route_order": "1",
             "visible": "1",
             "duration": "94",
             "vendor_name": "Northwind",
             "account_name": "Main SIP trunk",
             "connection_name": "UK Mobile Premium",
             "route_type": "CLI",
             "anonymous": "0",
             "link": "i_connection=653",
             "country_name": "UNITED KINGDOM",
             "description": "Mobile - Vodafone",
             "country_code": "gb"
            }
           ],
           "total_rows": "1"
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "prefix": {
          "type": "string",
          "example": "44",
          "description": "Only calls whose called number starts with this prefix. Leave empty for all calls."
         },
         "show": {
          "type": "string",
          "enum": [
           "all",
           "call",
           "auth"
          ],
          "default": "all",
          "description": "call returns only connected calls, auth only calls still being routed, all both."
         },
         "pager": {
          "type": "integer",
          "default": 100,
          "description": "Maximum number of calls to return."
         },
         "off": {
          "type": "integer",
          "default": 0,
          "description": "Number of calls to skip, for paging."
         },
         "disconnect": {
          "type": "integer",
          "description": "`i_live_call` of one of your calls to hang up before the list is returned."
         },
         "download": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "description": "1 returns the list as a CSV file (live_calls.csv) instead of JSON."
         }
        }
       }
      }
     }
    }
   }
  },
  "/buyers/callhistory": {
   "post": {
    "tags": [
     "Voice and SMS market"
    ],
    "summary": "List call records (CDRs)",
    "description": "Lists the call detail records of all your accounts between two times, newest first: called and calling numbers, duration and billed duration, amount charged, billing prices, seller and route, and the disconnect code and reason. Use `show` to choose answered calls, failed calls or both. Sellers of anonymous routes appear as Anonymous. Free.\n\nWith `show=all`, every record also has `sip_code` (0 for answered calls). For anonymous routes `i_vendor` is omitted. The response has no total count: page with `pager` and `off`.",
    "operationId": "voice-exchange-list-cdrs",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/market/#list-call-records-cdrs"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "cdrs": [
            {
             "i_cdr": "524807884",
             "CLD": "447700900123",
             "CLI": "12025550143",
             "call_id": "0edc2626fe9311e99c4f002590d192ea@203.0.113.11-b2b_1",
             "duration": "94",
             "billed_duration": "94",
             "connect_time": "2026-10-21 23:38:37",
             "disconnect_time": "2026-10-21 23:40:11",
             "setup_time": "2026-10-21 23:38:31",
             "billing_prefix": "4477",
             "billing_price_1": 0.0113,
             "billing_price_n": 0.0113,
             "billing_interval_1": "1",
             "billing_interval_n": "1",
             "customer_amount": "0.017703",
             "i_customer": "1014",
             "i_account": "1501",
             "i_vendor": "423",
             "i_connection": "653",
             "i_purchased_route": "97967",
             "disconnect_code": "16",
             "customer_ip": "203.0.113.10",
             "i_rate": "114110752",
             "vendor_name": "Northwind",
             "account_name": "Main SIP trunk",
             "connection_name": "UK Mobile Premium",
             "disconnect_reason": "Normal call clearing",
             "anonymous": "0",
             "link": "i_connection=653",
             "country_name": "UNITED KINGDOM",
             "description": "Mobile - Vodafone"
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "show": {
          "type": "string",
          "enum": [
           "good",
           "bad",
           "all"
          ],
          "default": "all",
          "example": "good",
          "description": "good returns answered calls (duration above zero), bad failed calls (zero duration), all both."
         },
         "date_from": {
          "type": "string",
          "example": "2026-10-21 00:00:00",
          "description": "Start of the period, matched on call setup time, as YYYY-MM-DD HH:MM:SS. Defaults to 24 hours ago."
         },
         "date_to": {
          "type": "string",
          "example": "2026-10-22 00:00:00",
          "description": "End of the period, as YYYY-MM-DD HH:MM:SS. Defaults to now."
         },
         "prefix": {
          "type": "string",
          "example": "4477",
          "description": "Only calls whose called number starts with this prefix. A full number works too, and % matches any characters."
         },
         "pager": {
          "type": "integer",
          "default": 50,
          "example": 50,
          "description": "Maximum number of records to return."
         },
         "off": {
          "type": "integer",
          "default": 0,
          "example": 0,
          "description": "Number of records to skip, for paging."
         },
         "download": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "description": "1 returns all matching records as a CSV file (cdrs.csv) instead of JSON, ignoring pager and off."
         }
        }
       }
      }
     }
    }
   }
  },
  "/buyers/smshistory": {
   "post": {
    "tags": [
     "Voice and SMS market"
    ],
    "summary": "List SMS records",
    "description": "Lists the SMS records of all your accounts between two times, newest first: sender and recipient, message text, delivery status, billed message parts, amount charged, seller and route, and destination. Sellers of anonymous routes appear as Anonymous. Free.\n\nFilter on `sent` to choose accepted or failed messages. `customer_amount` is the amount charged, commission included. For anonymous routes `i_vendor` is omitted.",
    "operationId": "sms-exchange-list-sdrs",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/market/#list-sms-records"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "sms": [
            {
             "i_message": "567878",
             "message_id": "5d309d43-d6b1-0810-c16e-6c844fa59aeb",
             "ts": "2026-10-21 15:47:12",
             "delivered": "1",
             "sent": "1",
             "i_account": "1855",
             "i_customer": "1014",
             "i_connection": "1160",
             "i_vendor": "436",
             "message_text": "Your verification code is 482913",
             "from_number": "12025550143",
             "to_number": "447700900123",
             "i_rate": "117989386",
             "delivered_in_sec": "3",
             "error_text": null,
             "billed_msgs_cnt": "1",
             "vendor_name": "Northwind",
             "account_name": "A2P traffic",
             "connection_name": "UK Direct",
             "anonymous": "0",
             "link": "i_connection=1160",
             "country_name": "UNITED KINGDOM",
             "description": "Mobile - Vodafone",
             "billing_price_1": 0.0255,
             "billing_price_n": 0.0255,
             "customer_amount": 0.0255
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "sent": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 1,
          "example": 1,
          "description": "1 returns messages the seller accepted, 0 messages that failed to submit. Any other number returns both."
         },
         "prefix": {
          "type": "string",
          "example": "44",
          "description": "Only messages whose recipient number starts with this prefix."
         },
         "date_from": {
          "type": "string",
          "example": "2026-10-21 00:00:00",
          "description": "Start of the period, as YYYY-MM-DD HH:MM:SS. Defaults to 24 hours ago."
         },
         "date_to": {
          "type": "string",
          "example": "2026-10-22 00:00:00",
          "description": "End of the period, as YYYY-MM-DD HH:MM:SS. Defaults to now."
         },
         "pager": {
          "type": "integer",
          "default": 50,
          "description": "Maximum number of records to return."
         },
         "off": {
          "type": "integer",
          "default": 0,
          "description": "Number of records to skip, for paging."
         },
         "download": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "description": "1 returns all matching records as a CSV file (sms.csv) instead of JSON."
         }
        }
       }
      }
     }
    }
   }
  },
  "/buyers/toproutes": {
   "get": {
    "tags": [
     "Voice and SMS market"
    ],
    "summary": "Top destinations by traffic (buyers)",
    "description": "Returns the busiest destinations across the whole exchange over a period, grouped by country, busiest first. With smpp=1 it ranks SMS traffic by message count; with smpp=0 (the default) it ranks voice traffic by minutes. Each country lists its billing prefixes with the price billed, the route ID (`id`) and, for voice, the route type. Free.\n\nErrors return `{\"status\": \"error\", \"message\": \"...\"}`. `top_routes` is always an object keyed by country name.",
    "operationId": "sms-exchange-top-sms-destinations",
    "parameters": [
     {
      "name": "period",
      "in": "query",
      "required": true,
      "description": "today is the last 24 hours, yesterday the 24 hours before that, week the last 7 days, month the last month up to now.",
      "schema": {
       "type": "string",
       "enum": [
        "today",
        "yesterday",
        "week",
        "month"
       ],
       "example": "week"
      }
     },
     {
      "name": "smpp",
      "in": "query",
      "required": false,
      "description": "1 ranks SMS traffic. Leave unset or send 0 for voice.",
      "schema": {
       "type": "integer",
       "enum": [
        0,
        1
       ],
       "default": 0,
       "example": 1
      }
     },
     {
      "name": "number",
      "in": "query",
      "required": false,
      "description": "How many countries to return, from 1 to 20.",
      "schema": {
       "type": "integer",
       "default": 5,
       "example": 10
      }
     },
     {
      "name": "type",
      "in": "query",
      "required": false,
      "description": "Voice only: count only traffic on routes of this type. Leave empty when smpp is 1.",
      "schema": {
       "type": "string",
       "enum": [
        "CLI",
        "NCLI",
        "TDM",
        "NA"
       ]
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/market/#top-destinations-by-traffic-buyers"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "top_routes": {
            "SPAIN": {
             "routes": [
              {
               "billing_prefix": "34607",
               "price": "0.0255",
               "id": "1160",
               "description": "Mobile - Vodafone"
              },
              {
               "billing_prefix": "34635",
               "price": "0.0249",
               "id": "1160",
               "description": "Mobile - Orange"
              }
             ]
            },
            "SAUDI ARABIA": {
             "routes": [
              {
               "billing_prefix": "96650",
               "price": "0.0133",
               "id": "1202",
               "description": "Mobile - Al Jawal"
              }
             ]
            }
           }
          }
         }
        }
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "period parameter error. Supported values are today, yesterday, week, month",
      "when": "period is missing or not one of the four values"
     },
     {
      "message": "type parameter error. Supported values are <empty value>/<unset>, TDM, CLI, NCLI, NA",
      "when": "type is set to anything other than TDM, CLI, NCLI or NA"
     },
     {
      "message": "smpp parameter error. Supported values are <empty value>/<unset>, 0, 1 ",
      "when": "smpp is not 0 or 1"
     },
     {
      "message": "type parameter error. Only support for non-smpp reports",
      "when": "type is set together with smpp=1"
     },
     {
      "message": "number parameter error. Allowed values are from 1 to 20",
      "when": "number is below 1, above 20, or not a number"
     }
    ]
   }
  },
  "/api/callback/initiate/{login}/{i_account}/{cld1}/{cli1}/{i_connection1}/{cld2}/{cli2}/{i_connection2}/{ts}/{signature}": {
   "get": {
    "tags": [
     "Voice and SMS market"
    ],
    "summary": "Start a route test call (signed URL)",
    "description": "Queues the same two-leg test call as POST /buyers/routetest, with every value in the URL and a SHA-256 signature. TCXC calls `cld1` over `i_connection1` showing `cli1`, then `cld2` over `i_connection2` showing `cli2`. Both routes must be purchased on `i_account`, and both legs are charged to `i_account` at the purchased routes' rates.\n\nPrefer POST /buyers/routetest. On apiv2.telecomsxchange.com, also send your HTTP Digest credentials. The signature error is plain text, not JSON. Check `status_text`, not `status`: errors also return `status: ok`.",
    "operationId": "voice-exchange-callback-initiate-signed",
    "parameters": [
     {
      "name": "login",
      "in": "path",
      "required": true,
      "description": "Your buyer portal login. API access must be enabled for it.",
      "schema": {
       "type": "string",
       "example": "acme-voice"
      }
     },
     {
      "name": "i_account",
      "in": "path",
      "required": true,
      "description": "ID of your account that places and pays for the test calls.",
      "schema": {
       "type": "integer",
       "example": 1501
      }
     },
     {
      "name": "cld1",
      "in": "path",
      "required": true,
      "description": "First number to call, digits only (E.164 without the plus sign).",
      "schema": {
       "type": "string",
       "example": "447700900123"
      }
     },
     {
      "name": "cli1",
      "in": "path",
      "required": true,
      "description": "Caller ID for the first call, digits only, with no leading 0 or plus sign.",
      "schema": {
       "type": "string",
       "example": "12025550143"
      }
     },
     {
      "name": "i_connection1",
      "in": "path",
      "required": true,
      "description": "Route ID for the first call. Must be purchased on `i_account`.",
      "schema": {
       "type": "integer",
       "example": 653
      }
     },
     {
      "name": "cld2",
      "in": "path",
      "required": true,
      "description": "Second number to call, digits only.",
      "schema": {
       "type": "string",
       "example": "4915112345678"
      }
     },
     {
      "name": "cli2",
      "in": "path",
      "required": true,
      "description": "Caller ID for the second call, digits only, with no leading 0 or plus sign.",
      "schema": {
       "type": "string",
       "example": "12025550178"
      }
     },
     {
      "name": "i_connection2",
      "in": "path",
      "required": true,
      "description": "Route ID for the second call. Repeat `i_connection1` to test one route.",
      "schema": {
       "type": "integer",
       "example": 653
      }
     },
     {
      "name": "ts",
      "in": "path",
      "required": true,
      "description": "Current Unix time in seconds. Must be within 12 hours of TCXC's clock.",
      "schema": {
       "type": "integer",
       "example": 1792658400
      }
     },
     {
      "name": "signature",
      "in": "path",
      "required": true,
      "description": "Lower-case hex SHA-256 of the URL path up to and including the slash after `ts`, followed directly by your API key: sha256('/api/callback/initiate/{login}/{i_account}/{cld1}/{cli1}/{i_connection1}/{cld2}/{cli2}/{i_connection2}/{ts}/' + api_key).",
      "schema": {
       "type": "string",
       "example": "9f2c4e1a7b0d3f5e8a6c2b4d1e7f9a3c5b8d0e2f4a6c8e1b3d5f7a9c0e2b4d6f"
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/market/#start-a-route-test-call-signed-url"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "ok",
           "status_text": "Test call has been initiated"
          }
         }
        }
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "{\"status\":\"error\",\"status_text\": \"CLDs should be numeric only in E.164 format\"}",
      "when": "cld1 or cld2 contains anything other than digits"
     },
     {
      "message": "{\"status\":\"error\",\"status_text\": \"API authentication error (TS)\"}",
      "when": "ts is more than 12 hours away from TCXC's clock"
     },
     {
      "message": "API authentication error (<signed path>) <signature>",
      "when": "the signature does not match, or the login does not exist or has API access disabled"
     },
     {
      "message": "Selected account does not have a purchased for selected route(s), please choose other combination or purchase selected route(s) on this account",
      "when": "i_account is not one of your accounts or a route is not purchased on it"
     }
    ]
   }
  },
  "/buyers/interconnect": {
   "post": {
    "tags": [
     "Interconnects"
    ],
    "summary": "Buy a route (create an interconnect)",
    "description": "Buys a seller's route for one of your accounts, or for all of them, so you can send it traffic. Returns the tech prefix to put in front of the dialled number (voice) or to use for the route (SMS), the route type, and a link to a rate deck. Buying is free; you pay only for the traffic you send. The account must match the route: a voice account for a voice route, an SMPP account for an SMS route.\n\nSend all fields in the form body. `route_type` is sms for SMS routes and voice otherwise. Anonymous routes show the seller as Anonymous. To get the route's rate deck, call Download a route's rate deck with the route's `i_tariff` rather than following `rates_url`. If `i_account` is not one of your accounts of the route's type, the response is not JSON: check the account before buying.",
    "operationId": "interconnect-initiate-interconnect",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/interconnects/#buy-a-route-create-an-interconnect"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Interconnection with NorthStarTel completed",
           "rates_url": "https://members.telecomsxchange.com/accounts.php?download=38",
           "tech_prefix": "33270#",
           "route_type": "voice"
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "add": {
          "type": "integer",
          "example": 1,
          "description": "Must be 1 to perform the purchase."
         },
         "id": {
          "type": "integer",
          "example": 38,
          "description": "The route's `i_connection`, from Market View or List seller routes."
         },
         "i_account": {
          "type": "integer",
          "example": 1022,
          "description": "The buyer account to attach the route to. 0 attaches it to every one of your accounts of the matching type that does not already have it."
         },
         "agree": {
          "type": "string",
          "enum": [
           "yes"
          ],
          "example": "yes",
          "description": "Must be yes, confirming you accept the seller's terms and conditions."
         }
        },
        "required": [
         "add",
         "id",
         "i_account",
         "agree"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "This API expects parameter add=1 for route purchase",
      "when": "add is missing or 0"
     },
     {
      "message": "Error! You have to agree to seller terms and conditions to purchase the route (agree=yes).",
      "when": "agree is not exactly yes"
     },
     {
      "message": "Error! Choose another account or route, this route is already purchased for this account.",
      "when": "the account already has this route"
     },
     {
      "message": "Error! Seller has blocked one of your accounts on this route, you can not purchase it until it gets unblocked.",
      "when": "the seller has blocked any of your accounts on this route"
     },
     {
      "message": "Error! Private route.",
      "when": "the route is private and the seller has not opened it to you"
     }
    ]
   }
  },
  "/interconnections/list": {
   "post": {
    "tags": [
     "Interconnects"
    ],
    "summary": "List interconnects",
    "description": "Lists the routes you have bought (your interconnects) across all your accounts, with the seller, route name, tech prefix, `i_tariff`, and whether you or the seller has blocked it. The same call can first block or unblock one interconnect: pass its `i_purchased_route` in `block` or `unblock`, and the list returned already reflects the change. A blocked interconnect carries none of your traffic. Free.\n\nCheck `result`, not `status`, for success. `inactive_prs` counts all your interconnects blocked by you or by the seller. Anonymous routes show `vendor_login` Anonymous and have no `i_vendor`. A `block` or `unblock` value that is not one of your interconnects is ignored.",
    "operationId": "interconnect-list-interconnects",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/interconnects/#list-interconnects"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "result": "success",
           "purchased_routes": [
            {
             "i_purchased_route": "4",
             "vendor_login": "NorthStarTel",
             "connection_name": "Gold+",
             "i_tariff": "3",
             "tech_prefix": "36310#",
             "blocked": "0",
             "vendor_blocked": "0",
             "account_name": "Northwind",
             "i_vendor": "2",
             "smpp": "1",
             "anonymous": "0"
            },
            {
             "i_purchased_route": "9",
             "vendor_login": "Anonymous",
             "connection_name": "Premium CLI",
             "i_tariff": "41",
             "tech_prefix": "41822#",
             "blocked": "1",
             "vendor_blocked": "0",
             "account_name": "Northwind",
             "smpp": "0",
             "anonymous": "1"
            }
           ],
           "inactive_prs": 1
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "block": {
          "type": "integer",
          "example": "3",
          "description": "`i_purchased_route` of an interconnect to block."
         },
         "unblock": {
          "type": "integer",
          "description": "`i_purchased_route` of an interconnect to unblock."
         },
         "q": {
          "type": "string",
          "description": "Search text matched against route name, account name, tech prefix and seller login (or the word Anonymous for anonymous routes). Up to 100 characters."
         },
         "pager": {
          "type": "integer",
          "default": 50,
          "example": 50,
          "description": "Maximum number of interconnects to return."
         },
         "off": {
          "type": "integer",
          "default": 0,
          "example": 0,
          "description": "Number of interconnects to skip, for paging."
         }
        }
       }
      }
     }
    }
   }
  },
  "/buyers/rg/list": {
   "post": {
    "tags": [
     "Routing groups"
    ],
    "summary": "List routing groups",
    "description": "Returns all your routing groups with their tech prefix, policy, hunt-stop codes and routes (`routing_group_entries`). Voice groups also include their routing rules (`routing_rules`), each with its own routes. Every other routing-group call uses the IDs returned here. Free.\n\n`rg_data` is a route's position in an `order` group (1 is tried first) or its weight in a `weight` group; `lcr` groups ignore it. Routes are sorted by position for `order`, by weight (highest first) for `weight`, otherwise by seller and route name. `smpp` is 1 for SMS groups, which have no `routing_rules`. `entries` and `rules` are counts; other values are strings.",
    "operationId": "buyers-routing-groups-list",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/routing-groups/#list-routing-groups"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "routing_groups": [
            {
             "i_routing_group": "311",
             "name": "UK mobile blend",
             "policy": "order",
             "hunt_stop_codes": "486,404,604",
             "tech_prefix": "444517#",
             "i_customer": "1042",
             "smpp": "0",
             "created": "2026-03-04 10:12:55",
             "entries": 2,
             "seller_names": "NorthwindVoice, Anonymous",
             "rules": 1,
             "routing_group_entries": [
              {
               "name": "UK Mobile CLI",
               "rg_data": "1",
               "i_routing_group_entry": "9021",
               "connection_name": "NorthwindVoice / UK Mobile CLI",
               "i_connection": "5531",
               "created": "2026-03-04 10:14:02",
               "i_vendor": "87",
               "anonymous": "0"
              },
              {
               "name": "Premium UK",
               "rg_data": "2",
               "i_routing_group_entry": "9022",
               "connection_name": "Anonymous / Premium UK",
               "i_connection": "5610",
               "created": "2026-03-04 10:14:40",
               "anonymous": "1"
              }
             ],
             "routing_rules": [
              {
               "i_routing_group": "318",
               "name": "",
               "policy": "lcr",
               "hunt_stop_codes": "",
               "tech_prefix": "",
               "i_customer": "1042",
               "smpp": "0",
               "created": "2026-03-05 08:01:13",
               "subrule_order": "1",
               "subrule_cld_prefix": "447",
               "subrule_cli_prefix": "",
               "entries": 1,
               "seller_names": "NorthwindVoice",
               "rules": 0,
               "routing_group_entries": [
                {
                 "name": "UK Mobile CLI",
                 "rg_data": "1",
                 "i_routing_group_entry": "9030",
                 "connection_name": "NorthwindVoice / UK Mobile CLI",
                 "i_connection": "5531",
                 "created": "2026-03-05 08:02:40",
                 "i_vendor": "87",
                 "anonymous": "0"
                }
               ]
              }
             ]
            }
           ]
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/buyers/rg/add": {
   "post": {
    "tags": [
     "Routing groups"
    ],
    "summary": "Create a routing group",
    "description": "Creates a voice or SMS routing group and gives it a unique tech prefix: 444, three random digits and #. Send traffic with that prefix to route it through the group. Voice groups start with hunt-stop codes 486,404,604. The response returns the new group's ID; call List routing groups to read its tech prefix. Free.\n\nAlways send one of `lcr`, `order` or `weight` as `policy`; the value is stored as sent.",
    "operationId": "buyers-routing-groups-create",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/routing-groups/#create-a-routing-group"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Routing Group has been added",
           "i_routing_group": 311
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "name": {
          "type": "string",
          "example": "UK mobile blend",
          "description": "Group name, unique among your routing groups, up to 128 characters."
         },
         "policy": {
          "type": "string",
          "enum": [
           "lcr",
           "order",
           "weight"
          ],
          "example": "order",
          "description": "How a route is chosen: `lcr` cheapest first, `order` a fixed failover order, `weight` weighted load balancing."
         },
         "smpp": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": 0,
          "description": "0 for a voice group, 1 for an SMS group."
         }
        },
        "required": [
         "name",
         "policy"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Please enter a name for the routing group.",
      "when": "`name` is missing or blank"
     },
     {
      "message": "A routing group with this name already exists - choose a different name.",
      "when": "you already have a group with this name"
     }
    ]
   }
  },
  "/buyers/rg/edit/{id}": {
   "post": {
    "tags": [
     "Routing groups"
    ],
    "summary": "Update a routing group",
    "description": "Renames a routing group and changes its policy and hunt-stop codes. Switching to `order` numbers the group's routes 1, 2, 3, ...; switching to `weight` sets every route's weight to 1. Free.\n\nSend `hunt_stop_codes` on every edit: omitting it clears the list. If `id` is a routing rule, this call behaves like Update a routing rule.",
    "operationId": "buyers-routing-groups-edit",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "Routing group ID (`i_routing_group`).",
      "schema": {
       "type": "integer",
       "example": 311
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/routing-groups/#update-a-routing-group"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Routing group updated successfully"
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "name": {
          "type": "string",
          "example": "UK mobile blend",
          "description": "Group name, unique among your routing groups. Send the current name to keep it."
         },
         "policy": {
          "type": "string",
          "enum": [
           "lcr",
           "order",
           "weight"
          ],
          "example": "weight",
          "description": "New policy. A missing or unknown value keeps the current policy."
         },
         "hunt_stop_codes": {
          "type": "string",
          "example": "404,486,603",
          "description": "Comma-separated SIP response codes from 400 to 699 that stop failover to the next route. Other values are dropped, and the list is de-duplicated and sorted."
         }
        },
        "required": [
         "name"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Routing Group not found",
      "when": "`id` is not one of your routing groups or rules"
     },
     {
      "message": "Please enter a name for the routing group.",
      "when": "`name` is missing or blank"
     },
     {
      "message": "A routing group with this name already exists \u2014 choose a different name.",
      "when": "another of your groups has this name"
     }
    ]
   }
  },
  "/buyers/rg/{id}/add_rule": {
   "post": {
    "tags": [
     "Routing groups"
    ],
    "summary": "Add a routing rule",
    "description": "Adds a routing rule to a voice routing group. A rule matches calls by destination (CLD) prefix, caller (CLI) prefix or both, and routes them through its own routes and policy. Rules are checked in order and a new rule goes to the bottom. It starts with policy `lcr` and no routes; add routes with Add a route to a group, using the rule's ID. Free.\n\nThe returned `i_routing_group` is the new rule's ID. Use it as `{id}` when adding routes to the rule and in Update a routing rule.",
    "operationId": "buyers-routing-groups-add-rule",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "ID of the parent voice routing group.",
      "schema": {
       "type": "integer",
       "example": 311
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/routing-groups/#add-a-routing-rule"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Routing Rule has been added",
           "i_routing_group": 318
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "subrule_cld_prefix": {
          "type": "string",
          "example": "447",
          "description": "Destination prefix to match, digits only, up to 15. Send at least one of the two prefixes."
         },
         "subrule_cli_prefix": {
          "type": "string",
          "description": "Caller ID prefix to match, digits only, up to 15, or `EMPTY` to match calls that have no caller ID."
         }
        }
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Routing Group not found",
      "when": "`id` is not one of your voice routing groups (SMS groups and rules can't have rules)"
     },
     {
      "message": "Enter at least one prefix: CLD (destination) or CLI (caller).",
      "when": "both prefixes are missing or empty"
     },
     {
      "message": "CLD prefix may contain digits only.",
      "when": "`subrule_cld_prefix` contains a non-digit"
     },
     {
      "message": "CLI prefix may contain digits only, or the special value EMPTY.",
      "when": "`subrule_cli_prefix` is neither digits nor EMPTY"
     },
     {
      "message": "A prefix can be at most 15 digits.",
      "when": "either prefix is longer than 15 characters"
     },
     {
      "message": "A rule with this CLD/CLI prefix already exists in this group.",
      "when": "the group already has a rule with the same CLD and CLI pair"
     }
    ]
   }
  },
  "/buyers/rg/rule/{id}/edit": {
   "post": {
    "tags": [
     "Routing groups"
    ],
    "summary": "Update a routing rule",
    "description": "Changes a routing rule's CLD and CLI prefixes, policy and hunt-stop codes. Switching to `order` numbers the rule's routes 1, 2, 3, ...; switching to `weight` sets their weights to 1. Free.\n\nSend both prefixes and `hunt_stop_codes` on every edit: any of them you omit is cleared. If `id` is a top-level group, this call behaves like Update a routing group and requires `name`.",
    "operationId": "buyers-routing-groups-edit-rule",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "Routing rule ID.",
      "schema": {
       "type": "integer",
       "example": 318
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/routing-groups/#update-a-routing-rule"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Routing Rule updated successfully"
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "subrule_cld_prefix": {
          "type": "string",
          "example": "4477",
          "description": "Destination prefix, digits only, up to 15. Send at least one of the two prefixes."
         },
         "subrule_cli_prefix": {
          "type": "string",
          "description": "Caller ID prefix, digits only or `EMPTY`, up to 15."
         },
         "policy": {
          "type": "string",
          "enum": [
           "lcr",
           "order",
           "weight"
          ],
          "example": "order",
          "description": "New policy. A missing or unknown value keeps the current policy."
         },
         "hunt_stop_codes": {
          "type": "string",
          "description": "Comma-separated SIP response codes from 400 to 699 that stop failover."
         }
        }
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Routing Group not found",
      "when": "`id` is not one of your rules or groups"
     },
     {
      "message": "Enter at least one prefix: CLD (destination) or CLI (caller).",
      "when": "both prefixes are missing or empty"
     },
     {
      "message": "CLD prefix may contain digits only.",
      "when": "`subrule_cld_prefix` contains a non-digit"
     },
     {
      "message": "CLI prefix may contain digits only, or the special value EMPTY.",
      "when": "`subrule_cli_prefix` is neither digits nor EMPTY"
     },
     {
      "message": "A prefix can be at most 15 digits.",
      "when": "either prefix is longer than 15 characters"
     },
     {
      "message": "A rule with this CLD/CLI prefix already exists in this group.",
      "when": "another rule in the same group has this CLD and CLI pair"
     }
    ]
   }
  },
  "/buyers/rg/{id}/rule/{rule_id}/delete": {
   "post": {
    "tags": [
     "Routing groups"
    ],
    "summary": "Delete a routing rule",
    "description": "Deletes a routing rule and its route list, and moves the rules below it up one place. Your purchased routes are not affected. Free.",
    "operationId": "buyers-routing-groups-delete-rule",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "Parent routing group ID.",
      "schema": {
       "type": "integer",
       "example": 311
      }
     },
     {
      "name": "rule_id",
      "in": "path",
      "required": true,
      "description": "ID of the rule to delete.",
      "schema": {
       "type": "integer",
       "example": 318
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/routing-groups/#delete-a-routing-rule"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Rule has been deleted"
          }
         }
        }
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Rule not found",
      "when": "`rule_id` is not one of your rules in group `id`"
     }
    ]
   }
  },
  "/buyers/rg/{id}/rule/{rule_id}/up": {
   "post": {
    "tags": [
     "Routing groups"
    ],
    "summary": "Move a routing rule up",
    "description": "Moves a routing rule one place up in its group's evaluation order, swapping it with the rule above. Free.",
    "operationId": "buyers-routing-groups-rule-move-up",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "Parent routing group ID.",
      "schema": {
       "type": "integer",
       "example": 311
      }
     },
     {
      "name": "rule_id",
      "in": "path",
      "required": true,
      "description": "ID of the rule to move.",
      "schema": {
       "type": "integer",
       "example": 319
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/routing-groups/#move-a-routing-rule-up"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Routing Rule moved up"
          }
         }
        }
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "This rule is on top",
      "when": "the rule is already first"
     },
     {
      "message": "Rule not found",
      "when": "`rule_id` is not one of your rules in group `id`"
     }
    ]
   }
  },
  "/buyers/rg/{id}/rule/{rule_id}/down": {
   "post": {
    "tags": [
     "Routing groups"
    ],
    "summary": "Move a routing rule down",
    "description": "Moves a routing rule one place down in its group's evaluation order, swapping it with the rule below. Free.",
    "operationId": "buyers-routing-groups-rule-move-down",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "Parent routing group ID.",
      "schema": {
       "type": "integer",
       "example": 311
      }
     },
     {
      "name": "rule_id",
      "in": "path",
      "required": true,
      "description": "ID of the rule to move.",
      "schema": {
       "type": "integer",
       "example": 318
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/routing-groups/#move-a-routing-rule-down"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Routing Rule moved down"
          }
         }
        }
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "This rule is on the bottom",
      "when": "the rule is already last"
     },
     {
      "message": "Rule not found",
      "when": "`rule_id` is not one of your rules in group `id`"
     }
    ]
   }
  },
  "/buyers/rg/{id}/entry/add/{i_connection}": {
   "post": {
    "tags": [
     "Routing groups"
    ],
    "summary": "Add a route to a group",
    "description": "Adds one of your purchased routes to a routing group or rule. In an `order` group the route goes to the end of the failover list; in a `weight` group it starts with weight 1. Returns the new entry ID, used by the remove, move and set-weight calls. Adding a route to a group costs nothing.\n\nAdd voice routes to voice groups and SMS routes to SMS groups; the route type is not checked. If `id` is not one of your groups or rules, the response is empty.",
    "operationId": "buyers-routing-groups-add-entry",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "Routing group or routing rule ID.",
      "schema": {
       "type": "integer",
       "example": 311
      }
     },
     {
      "name": "i_connection",
      "in": "path",
      "required": true,
      "description": "ID of a route purchased on any of your accounts, from List interconnects.",
      "schema": {
       "type": "integer",
       "example": 5531
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/routing-groups/#add-a-route-to-a-group"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Route added to this group",
           "i_routing_group_entry": 9021
          }
         }
        }
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "i_connection expects integer",
      "when": "the route ID is not a number"
     },
     {
      "message": "You can only add routes you have purchased in the Market.",
      "when": "the route is not purchased on any of your accounts"
     },
     {
      "message": "This route is already in this group.",
      "when": "the route is already in this group or rule"
     }
    ]
   }
  },
  "/buyers/rg/{id}/entry/{entry_id}/remove": {
   "post": {
    "tags": [
     "Routing groups"
    ],
    "summary": "Remove a route from a group",
    "description": "Removes a route from a routing group or rule. In an `order` group, the routes below it move up one place. Your purchased route is not affected. Free.\n\nPass the group or rule that contains the entry as `id`; the entry is removed even if it belongs to another of your groups. If `id` is not one of your groups or rules, the response is empty.",
    "operationId": "buyers-routing-groups-remove-entry",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "Routing group or routing rule ID that contains the entry.",
      "schema": {
       "type": "integer",
       "example": 311
      }
     },
     {
      "name": "entry_id",
      "in": "path",
      "required": true,
      "description": "Entry ID (`i_routing_group_entry`), from List routing groups.",
      "schema": {
       "type": "integer",
       "example": 9022
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/routing-groups/#remove-a-route-from-a-group"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Route removed from this group"
          }
         }
        }
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Entry not found",
      "when": "`entry_id` is not an entry in any of your routing groups"
     }
    ]
   }
  },
  "/buyers/rg/{id}/entry/{entry_id}/up": {
   "post": {
    "tags": [
     "Routing groups"
    ],
    "summary": "Move a route up",
    "description": "Moves a route one place up in the failover order of an `order` group or rule, swapping it with the route above. Free.\n\nIf `id` is not one of your groups or rules, the response is empty.",
    "operationId": "buyers-routing-groups-entry-move-up",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "Routing group or routing rule ID.",
      "schema": {
       "type": "integer",
       "example": 311
      }
     },
     {
      "name": "entry_id",
      "in": "path",
      "required": true,
      "description": "Entry ID to move.",
      "schema": {
       "type": "integer",
       "example": 9022
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/routing-groups/#move-a-route-up"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Route moved up"
          }
         }
        }
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "up action only supported for ordered policy",
      "when": "the group's policy is not `order`"
     },
     {
      "message": "This rule is on top",
      "when": "the route is already first"
     },
     {
      "message": "entry not found",
      "when": "`entry_id` is not an entry in your routing groups"
     }
    ]
   }
  },
  "/buyers/rg/{id}/entry/{entry_id}/down": {
   "post": {
    "tags": [
     "Routing groups"
    ],
    "summary": "Move a route down",
    "description": "Moves a route one place down in the failover order of an `order` group or rule, swapping it with the route below. Free.\n\nIf `id` is not one of your groups or rules, the response is empty.",
    "operationId": "buyers-routing-groups-entry-move-down",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "Routing group or routing rule ID.",
      "schema": {
       "type": "integer",
       "example": 311
      }
     },
     {
      "name": "entry_id",
      "in": "path",
      "required": true,
      "description": "Entry ID to move.",
      "schema": {
       "type": "integer",
       "example": 9021
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/routing-groups/#move-a-route-down"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Route moved down"
          }
         }
        }
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "down action only supported for ordered policy",
      "when": "the group's policy is not `order`"
     },
     {
      "message": "This entry is on the bottom",
      "when": "the route is already last"
     },
     {
      "message": "entry not found",
      "when": "`entry_id` is not an entry in your routing groups"
     }
    ]
   }
  },
  "/buyers/rg/{id}/entry/{entry_id}/set_weight/{weight}": {
   "post": {
    "tags": [
     "Routing groups"
    ],
    "summary": "Set a route's weight",
    "description": "Sets the load-balancing weight of a route in a `weight` group or rule. Each route receives a share of traffic equal to its weight divided by the sum of all weights in the group. Free.\n\nIf `id` is not one of your groups or rules, the response is empty.",
    "operationId": "buyers-routing-groups-entry-set-weight",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "Routing group or routing rule ID.",
      "schema": {
       "type": "integer",
       "example": 311
      }
     },
     {
      "name": "entry_id",
      "in": "path",
      "required": true,
      "description": "Entry ID (`i_routing_group_entry`).",
      "schema": {
       "type": "integer",
       "example": 9021
      }
     },
     {
      "name": "weight",
      "in": "path",
      "required": true,
      "description": "Whole number from 1 to 100.",
      "schema": {
       "type": "integer",
       "example": 70
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/routing-groups/#set-a-route-s-weight"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Weight updated successfully"
          }
         }
        }
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Weight must be a whole number between 1 and 100.",
      "when": "`weight` is not a whole number from 1 to 100"
     },
     {
      "message": "set_weight action only supported for weighted policy",
      "when": "the group's policy is not `weight`"
     },
     {
      "message": "entry not found",
      "when": "`entry_id` is not an entry of group `id`"
     }
    ]
   }
  },
  "/sellers/did/add": {
   "post": {
    "tags": [
     "Phone numbers (DIDs)"
    ],
    "summary": "Add a DID for sale",
    "description": "Lists a new phone number (DID) for sale on the DID market under your seller account. The number appears in the market while its status is idle. Returns a confirmation message; call List your DIDs to get the new i_did. Free, except anonymous listings, which charge the anonymous DID fee to your seller balance. Point voice numbers at sip01.telecomsxchange.com (SIP) and SMS numbers at smpp01.telecomsxchange.com port 2776 (SMPP 3.4 or 5.0).\n\nErrors return HTTP 200 with status \"error\".",
    "operationId": "did-exchange-add-sell-new-did-number",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/numbers/#add-a-did-for-sale"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "The DID has been successfully added."
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "number": {
          "type": "integer",
          "example": "19545550142",
          "description": "The phone number in international format, digits only, 4 to 15 digits. A leading + is accepted and dropped; leading zeros are dropped."
         },
         "price_1": {
          "type": "number",
          "example": "0.004",
          "description": "Price per minute, in USD, the buyer pays for incoming voice calls."
         },
         "interval_1": {
          "type": "integer",
          "example": "60",
          "description": "Billing increment in seconds, 1 to 300 (for example 1 for per-second or 60 for per-minute billing)."
         },
         "smpp_price": {
          "type": "number",
          "example": "0.005",
          "description": "Price per incoming SMS, in USD. Send 0 for numbers without SMS."
         },
         "periodic_fee": {
          "type": "number",
          "example": "3.50",
          "description": "Recurring fee, in USD, charged to the buyer every periodic_interval."
         },
         "periodic_interval": {
          "type": "string",
          "enum": [
           "Monthly",
           "Quarterly",
           "Annual"
          ],
          "example": "Monthly",
          "description": "How often periodic_fee is charged. Case-sensitive."
         },
         "setup_fee": {
          "type": "number",
          "example": "1.00",
          "description": "One-time fee, in USD, charged to the buyer at purchase. Send 0 for none."
         },
         "parent": {
          "type": "string",
          "enum": [
           "international",
           "domestic"
          ],
          "example": "international",
          "description": "Who may buy the number: international (anyone, shown as Any in the portal) or domestic (local buyers only, shown as Local Only)."
         },
         "status": {
          "type": "string",
          "enum": [
           "idle",
           "blocked"
          ],
          "example": "idle",
          "description": "idle lists the number for sale; blocked hides it from the market."
         },
         "capacity": {
          "type": "integer",
          "example": "5",
          "description": "Number of simultaneous calls the number supports."
         },
         "voice": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": "1",
          "description": "1 if the number receives voice calls. At least one of voice, sms, fax and video must be 1."
         },
         "sms": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": "1",
          "description": "1 if the number receives SMS."
         },
         "fax": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": "0",
          "description": "1 if the number receives fax."
         },
         "video": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": "0",
          "description": "1 if the number receives video calls."
         },
         "did_type": {
          "type": "string",
          "example": "mobile",
          "description": "Number type shown to buyers and used by the market's did_type filter, for example national, mobile or tollfree."
         },
         "notes": {
          "type": "string",
          "example": "Proof of local address required",
          "description": "Free-text notes shown to buyers, for example the documents you need."
         },
         "verification_required": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": "0",
          "description": "1 if buyers must send identity documents before the number is activated."
         },
         "documents_verified": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": "0",
          "description": "Documents-verified flag stored with the number."
         },
         "anonymous": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": "0",
          "description": "1 to sell the number anonymously (buyers see the seller as Anonymous). Charges the anonymous DID fee to your seller balance."
         }
        },
        "required": [
         "number",
         "price_1",
         "interval_1",
         "smpp_price",
         "periodic_fee",
         "periodic_interval",
         "setup_fee",
         "parent",
         "status",
         "capacity"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "DID number should contain only digits",
      "when": "number is missing or not an integer"
     },
     {
      "message": "DID number should be of length 4..15 digits",
      "when": "number has fewer than 4 or more than 15 digits"
     },
     {
      "message": "This DID number already exists in the system",
      "when": "the number is already listed"
     },
     {
      "message": "Local Requirements can only be 'Any' or 'Local Only'",
      "when": "parent is missing or not international or domestic"
     },
     {
      "message": "Price should be numeric",
      "when": "price_1 is missing or not a number"
     },
     {
      "message": "SMS Price should be numeric",
      "when": "smpp_price is missing or not a number"
     },
     {
      "message": "Interval should contain only digits",
      "when": "interval_1 is missing or not an integer"
     },
     {
      "message": "Voice can be only 1 or 0",
      "when": "voice is not 0 or 1 (SMS, Fax and Video return the same message with their own name)"
     },
     {
      "message": "Voice SMS Fax or Video access should be enabled",
      "when": "voice, sms, fax and video are all 0 or missing"
     },
     {
      "message": "Capacity should be numeric",
      "when": "capacity is missing or not a number"
     },
     {
      "message": " Interval should be between 1 and 300 seconds",
      "when": "interval_1 is below 1 or above 300"
     },
     {
      "message": "Periodic Fee should be numeric",
      "when": "periodic_fee is missing or not a number"
     },
     {
      "message": "Periodic Interval should be one of Monthly, Quarterly or Annual",
      "when": "periodic_interval is missing or another value"
     },
     {
      "message": "Setup Fee should be numeric",
      "when": "setup_fee is missing or not a number"
     },
     {
      "message": "Only idle or blocked status allowed",
      "when": "status is missing or another value"
     },
     {
      "message": "Not enough balance to pay for DID anonymous fee <fee>",
      "when": "anonymous is 1 and your seller balance is below the anonymous DID fee"
     },
     {
      "message": "DID has not been added. DB ERROR. Please check all fields.",
      "when": "the number could not be saved"
     }
    ]
   }
  },
  "/sellers/did/list": {
   "post": {
    "tags": [
     "Phone numbers (DIDs)"
    ],
    "summary": "List your DIDs (seller)",
    "description": "Lists the phone numbers you sell, newest first, with their prices, capabilities and status. Purchased numbers also show the buyer's login and customer ID. A pending price increase appears as an upcoming object on the number's row and as an extra row whose number is \"<number> <effective date>\" and whose i_did is 0. All matching numbers are returned in one reply. Free.\n\ncustomer_login and i_customer appear only on purchased numbers; upcoming appears only when a price increase is pending. There is no paging: pager and off have no effect.",
    "operationId": "did-exchange-list-dids",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/numbers/#list-your-dids-seller"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "dids": [
            {
             "i_did": "2318",
             "number": "19545550142",
             "price_1": "0.004",
             "price_n": "0.004",
             "interval_1": "60",
             "interval_n": "60",
             "periodic_fee": "3.5",
             "periodic_interval": "Monthly",
             "setup_fee": "1",
             "billing_i_account": "1501",
             "i_vendor": "114",
             "status": "purchased",
             "contact": "sip:19545550142@203.0.113.14:5060",
             "contact2": "",
             "smpp_contact": "smpp:buyer01:secret:19545550142@203.0.113.15:2776",
             "notes": "",
             "billed_to": "2026-11-21 10:51:17",
             "monthly_start_ts": "2026-11-21 10:51:17",
             "voice": "1",
             "sms": "1",
             "fax": "0",
             "video": "0",
             "capacity": "5",
             "did_type": "national",
             "verification_required": "0",
             "documents_verified": "0",
             "smpp_price": "0.005",
             "is_nexmo": "0",
             "email_warned": "0",
             "anonymous": "0",
             "anonymous_billed_to": "2026-10-21 10:51:17",
             "parent": "international",
             "config_changed": "0",
             "anonymous_billed_ok": "0",
             "country_code": "us",
             "country_name": "UNITED STATES",
             "description": "Fixed - Florida",
             "customer_login": "acme-voice",
             "i_customer": "3307"
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "prefix": {
          "type": "string",
          "example": "1954",
          "description": "Return only numbers that start with these digits."
         },
         "country": {
          "type": "string",
          "example": "United States",
          "description": "Return only numbers whose destination country name contains this text, for example United States."
         },
         "description": {
          "type": "string",
          "example": "Fixed",
          "description": "Return only numbers whose destination description contains this text, for example Mobile."
         },
         "status": {
          "type": "string",
          "enum": [
           "idle",
           "purchased",
           "blocked"
          ],
          "example": "purchased",
          "description": "Return only numbers in this state. Any other value returns all."
         }
        }
       }
      }
     }
    }
   }
  },
  "/sellers/did/edit/{i_did}": {
   "post": {
    "tags": [
     "Phone numbers (DIDs)"
    ],
    "summary": "Update a DID you sell",
    "description": "Changes the prices, capabilities, status and document settings of a number you sell. Send every field, as on Add a DID for sale: missing fields fail validation. Price changes are dated 30 days ahead. A price increase on a number that has been bought takes effect after 30 days, and the other changes sent in the same request are not applied either; send those in a separate request without the increase. Setting documents_verified to 1 emails the buyer that their documents were accepted. Free.\n\nSend all fields in the form body; query-string parameters are ignored on this path. A price increase on a purchased number returns \"DID entry has been updated.  Price increase changes will become effective in 30 days.\"",
    "operationId": "did-exchange-update-did-record",
    "parameters": [
     {
      "name": "i_did",
      "in": "path",
      "required": true,
      "description": "ID of the number, from List your DIDs.",
      "schema": {
       "type": "integer",
       "example": "2318"
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/numbers/#update-a-did-you-sell"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "DID entry has been updated. "
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "number": {
          "type": "integer",
          "example": "19545550142",
          "description": "New phone number, 4 to 15 digits. Required while the number is not purchased; a purchased number cannot be changed."
         },
         "price_1": {
          "type": "number",
          "example": "0.004",
          "description": "Price per minute, in USD, for incoming voice calls."
         },
         "interval_1": {
          "type": "integer",
          "example": "60",
          "description": "Billing increment in seconds."
         },
         "smpp_price": {
          "type": "number",
          "example": "0.005",
          "description": "Price per incoming SMS, in USD."
         },
         "periodic_fee": {
          "type": "number",
          "example": "3.50",
          "description": "Recurring fee, in USD."
         },
         "periodic_interval": {
          "type": "string",
          "enum": [
           "Monthly",
           "Quarterly",
           "Annual"
          ],
          "example": "Monthly",
          "description": "How often periodic_fee is charged."
         },
         "setup_fee": {
          "type": "number",
          "example": "1.00",
          "description": "One-time fee, in USD, charged at purchase."
         },
         "parent": {
          "type": "string",
          "enum": [
           "international",
           "domestic"
          ],
          "example": "international",
          "description": "Who may buy the number: international (anyone) or domestic (local buyers only)."
         },
         "capacity": {
          "type": "integer",
          "example": "5",
          "description": "Number of simultaneous calls the number supports."
         },
         "status": {
          "type": "string",
          "enum": [
           "idle",
           "blocked"
          ],
          "example": "idle",
          "description": "Required while the number is not purchased. A purchased number stays purchased."
         },
         "voice": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": "1",
          "description": "1 if the number receives voice calls. At least one of voice, sms, fax and video must be 1."
         },
         "sms": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": "1",
          "description": "1 if the number receives SMS."
         },
         "fax": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": "0",
          "description": "1 if the number receives fax."
         },
         "video": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": "0",
          "description": "1 if the number receives video calls."
         },
         "did_type": {
          "type": "string",
          "example": "national",
          "description": "Number type, for example national, mobile or tollfree. Sending nothing clears it."
         },
         "notes": {
          "type": "string",
          "example": "Proof of local address required",
          "description": "Notes shown to buyers. Sending nothing clears them."
         },
         "verification_required": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": "0",
          "description": "1 if buyers must send documents. Cannot be turned on for a purchased number."
         },
         "documents_verified": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": "0",
          "description": "1 to mark the buyer's documents as accepted (only when verification_required is on). Emails the buyer."
         }
        },
        "required": [
         "price_1",
         "interval_1",
         "smpp_price",
         "periodic_fee",
         "periodic_interval",
         "setup_fee",
         "parent",
         "capacity"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "DID number should be of length 4..15 digits",
      "when": "the number is not purchased and number is missing or not 4 to 15 digits"
     },
     {
      "message": "DID number should contain only digits",
      "when": "the number is not purchased and number is not an integer"
     },
     {
      "message": "DID not found.",
      "when": "i_did is not one of your numbers"
     },
     {
      "message": "Price should be numeric",
      "when": "price_1 is missing or not a number"
     },
     {
      "message": "SMS Price should be numeric",
      "when": "smpp_price is missing or not a number"
     },
     {
      "message": "Interval should contain only digits",
      "when": "interval_1 is missing or not an integer"
     },
     {
      "message": "Periodic Fee should be numeric",
      "when": "periodic_fee is missing or not a number"
     },
     {
      "message": "Periodic Interval should be one of Monthly, Quarterly or Annual",
      "when": "periodic_interval is missing or another value"
     },
     {
      "message": "Parent can only be international or domestic",
      "when": "parent is missing or another value"
     },
     {
      "message": "Setup Fee should be numeric",
      "when": "setup_fee is missing or not a number"
     },
     {
      "message": "Voice can be only 1 or 0",
      "when": "voice is not 0 or 1 (SMS, Fax and Video return the same message with their own name)"
     },
     {
      "message": "Voice SMS Fax or Video access should be enabled",
      "when": "voice, sms, fax and video are all 0 or missing"
     },
     {
      "message": "Capacity should be numeric",
      "when": "capacity is missing or not a number"
     },
     {
      "message": "Only idle or blocked status allowed",
      "when": "the number is not purchased and status is missing or another value"
     },
     {
      "message": "You can't enable document verification for a purchased DID",
      "when": "verification_required is 1 for a purchased number that did not require it"
     },
     {
      "message": "You can not verify documents for DIDs which do not have it enabled, enable verification first",
      "when": "documents_verified is 1 but the number does not require verification"
     },
     {
      "message": "You can not change number of purchased DID",
      "when": "number differs from the current number of a purchased DID"
     }
    ]
   }
  },
  "/number/market": {
   "post": {
    "tags": [
     "Phone numbers (DIDs)"
    ],
    "summary": "Search the DID market",
    "description": "Searches phone numbers for sale from TCXC sellers and, for international searches, from partner inventory. Give at least one of prefix, country or description. Returns each number with its setup fee, recurring fee, per-minute and per-SMS prices (USD, including the TCXC commission), capabilities and seller. Numbers already sold are hidden. Free.\n\nEvery match is returned in one reply; pager and off have no effect. Partner-inventory rows have is_nexmo 1 and no i_did, carry their ISO country code in country, and are bought with is_nexmo=1 on Purchase DID. When you filter with voice or sms, check each row's voice and sms fields: partner-inventory rows are not always filtered. A pending price increase adds an extra row whose number is \"<number> <effective date>\" and whose i_did is 0.",
    "operationId": "did-exchange-search-did-market-view",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/numbers/#search-the-did-market"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "dids": [
            {
             "i_did": "2318",
             "number": "441615550123",
             "price_1": "0.0055",
             "price_n": "0.0055",
             "interval_1": "60",
             "interval_n": "60",
             "periodic_fee": "3.8500",
             "periodic_interval": "Monthly",
             "setup_fee": "1.1000",
             "i_vendor": "114",
             "status": "idle",
             "notes": "",
             "voice": "1",
             "sms": "0",
             "fax": "0",
             "video": "0",
             "capacity": "5",
             "did_type": "national",
             "verification_required": "0",
             "documents_verified": "0",
             "smpp_price": "0.0000",
             "is_nexmo": "0",
             "email_warned": "0",
             "anonymous": "0",
             "anonymous_billed_to": "2026-10-01 00:00:00",
             "parent": "international",
             "config_changed": "0",
             "vendor_name": "Acme",
             "vendor_short_memo": "UK geographic numbers",
             "country_code": "gb",
             "country_name": "UNITED KINGDOM",
             "description": "Fixed - Manchester"
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "prefix": {
          "type": "string",
          "example": "1954",
          "description": "Return numbers that start with these digits, for example 1954. Prefixes shorter than 3 digits that contain a 1 are rejected."
         },
         "country": {
          "type": "string",
          "example": "United Kingdom",
          "description": "Destination country name, or part of it, for example United Kingdom."
         },
         "description": {
          "type": "string",
          "example": "Mobile",
          "description": "Destination description, or part of it, for example Mobile."
         },
         "seller": {
          "type": "string",
          "example": "acme-numbers",
          "description": "Return only this seller's numbers, by seller login. An unknown login returns no seller numbers."
         },
         "did_type": {
          "type": "string",
          "enum": [
           "any",
           "national",
           "mobile",
           "tollfree",
           "unknown"
          ],
          "default": "any",
          "example": "mobile",
          "description": "Number type."
         },
         "voice": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": "1",
          "description": "1 returns only numbers that receive voice calls."
         },
         "sms": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": "0",
          "description": "1 returns only numbers that receive SMS."
         },
         "fax": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": "0",
          "description": "1 returns only numbers that receive fax."
         },
         "video": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": "0",
          "description": "1 returns only numbers that receive video calls."
         },
         "parent": {
          "type": "string",
          "enum": [
           "international",
           "domestic"
          ],
          "default": "international",
          "example": "international",
          "description": "international searches numbers open to all buyers, including partner inventory; domestic searches local-only numbers."
         }
        }
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "You have to specify some search pattern, prefix or country or description",
      "when": "prefix, country and description are all empty"
     },
     {
      "message": "You have to specify longer prefix for this country code",
      "when": "prefix is shorter than 3 digits and contains a 1"
     }
    ]
   }
  },
  "/number/purchase": {
   "post": {
    "tags": [
     "Phone numbers (DIDs)"
    ],
    "summary": "Purchase a DID",
    "description": "Buys a phone number and points it at your SIP and/or SMPP endpoint. Charges the setup fee and the first recurring fee (both including commission) at once to the billing account, or to the account whose balance it uses; later fees renew automatically every periodic_interval. Numbers that need documents start working once the seller verifies them. Returns a confirmation message.\n\nFor partner-inventory numbers, a number that is already taken, no longer offered or has no price returns a plain-text body (DID alredy purchased, Error DID not found or DID price not found) instead of JSON. Both charges appear in the billing account's transaction history.",
    "operationId": "did-exchange-purchase-did",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/numbers/#purchase-a-did"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "DID has been purchased"
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "i_did": {
          "type": "integer",
          "example": "2318",
          "description": "ID of the number, from Search the DID market. Required unless is_nexmo is 1."
         },
         "billing_i_account": {
          "type": "integer",
          "example": "1501",
          "description": "Your account to charge, from List buyer accounts. If it uses another account's balance, that account is charged."
         },
         "contact": {
          "type": "string",
          "example": "sip:19545550142@203.0.113.14:5060",
          "description": "Where to send calls, as sip:<user>@<host>[:port]. Required for voice, fax or video numbers. Stored in lower case."
         },
         "contact2": {
          "type": "string",
          "example": "sip:19545550142@203.0.113.24:5060",
          "description": "Failover SIP address, same format as contact."
         },
         "smpp_contact": {
          "type": "string",
          "example": "smpp:buyer01:secret:19545550142@203.0.113.15:2776",
          "description": "Where to deliver SMS, as smpp:<login>:<password>:<number>@<host>:<port>. Required for SMS numbers."
         },
         "is_nexmo": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": "0",
          "description": "Set to 1 when buying a number from partner inventory (rows marked is_nexmo 1 in the market). The number is then identified by country and number instead of i_did."
         },
         "country": {
          "type": "string",
          "example": "GB",
          "description": "Partner inventory only: the row's ISO country code, from the market's country field."
         },
         "number": {
          "type": "string",
          "example": "447700900123",
          "description": "Partner inventory only: the number to buy."
         },
         "voice": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "example": "1",
          "description": "Partner inventory only, and then required: 1 to enable voice on the number."
         },
         "sms": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "example": "1",
          "description": "Partner inventory only, and then required: 1 to enable SMS on the number."
         }
        },
        "required": [
         "billing_i_account"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Point to SIP should be in format sip:12345abc@sip.domain.com:5060",
      "when": "the number has voice, fax or video and contact is missing or malformed"
     },
     {
      "message": "Point to SIP(secondary) should be in format sip:12345abc@sip.domain.com:5060",
      "when": "contact2 is given and malformed"
     },
     {
      "message": "Point to SMPP should be in format  smpp:login:pass:12345abc@smpp.domain.com:2776",
      "when": "the number has SMS and smpp_contact is missing or malformed"
     },
     {
      "message": "Can not purchase DID on this account",
      "when": "billing_i_account is not one of your accounts"
     },
     {
      "message": "This DID can not be purchased, it has been already sold to other buyer",
      "when": "the number is not available, or i_did does not exist"
     },
     {
      "message": "Selected account does not have enough funds: this DID needs $<total> up front ($<setup> setup + $<fee> first <interval> fee). Choose another account or top up.",
      "when": "balance plus credit limit is below the setup fee plus the first recurring fee"
     },
     {
      "message": "DID subscribe error:<reason>",
      "when": "a partner-inventory number cannot be reserved"
     },
     {
      "message": "DID subscribe/configure error:<reason>",
      "when": "a partner-inventory number is reserved but cannot be configured"
     }
    ]
   }
  },
  "/number/list": {
   "post": {
    "tags": [
     "Phone numbers (DIDs)"
    ],
    "summary": "List purchased DIDs",
    "description": "Lists the numbers you have bought, ordered by number, with their current prices (including commission), the account billed, where calls and SMS are sent and the next billing date. A pending price increase appears as an upcoming object on the row and as an extra row dated in its number. Free.\n\nWith off=0 the reply holds every number. To page, send pager and an off of 1 or more.",
    "operationId": "did-exchange-list-purchased-dids",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/numbers/#list-purchased-dids"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "dids": [
            {
             "i_did": "2318",
             "number": "441615550123",
             "price_1": "0.0055",
             "price_n": "0.0055",
             "interval_1": "60",
             "interval_n": "60",
             "periodic_fee": "3.8500",
             "periodic_interval": "Monthly",
             "setup_fee": "1.1000",
             "i_vendor": "114",
             "status": "purchased",
             "contact": "sip:441615550123@203.0.113.14:5060",
             "contact2": "",
             "smpp_contact": "",
             "notes": "",
             "billed_to": "2026-11-21 10:51:17",
             "monthly_start_ts": "2026-11-21 10:51:17",
             "voice": "1",
             "sms": "0",
             "fax": "0",
             "video": "0",
             "capacity": "5",
             "did_type": "national",
             "verification_required": "0",
             "documents_verified": "0",
             "smpp_price": "0.0000",
             "is_nexmo": "0",
             "email_warned": "0",
             "anonymous": "0",
             "anonymous_billed_to": "2026-10-01 00:00:00",
             "parent": "international",
             "config_changed": "0",
             "account_name": "Main trunk",
             "vendor_name": "Acme",
             "country_code": "gb",
             "country_name": "UNITED KINGDOM",
             "description": "Fixed - Manchester"
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "prefix": {
          "type": "string",
          "example": "44",
          "description": "Return only numbers that start with these digits."
         },
         "country": {
          "type": "string",
          "example": "United Kingdom",
          "description": "Return only numbers whose destination country name contains this text."
         },
         "description": {
          "type": "string",
          "example": "Mobile",
          "description": "Return only numbers whose destination description contains this text."
         },
         "pager": {
          "type": "integer",
          "example": "50",
          "description": "Page size. Takes effect only together with an off of 1 or more."
         },
         "off": {
          "type": "integer",
          "default": 0,
          "example": "50",
          "description": "Offset of the first row."
         }
        }
       }
      }
     }
    }
   }
  },
  "/number/update": {
   "post": {
    "tags": [
     "Phone numbers (DIDs)"
    ],
    "summary": "Update a purchased DID's destination",
    "description": "Changes where a number you bought sends calls (contact, contact2) and SMS (smpp_contact). Free.\n\nWhen contact, contact2 or smpp_contact is not in the documented format, the reply is an HTML page instead of JSON. Check the formats before sending: sip:<user>@<host>[:port] and smpp:<login>:<password>:<number>@<host>:<port>.",
    "operationId": "did-exchange-update-did-entry",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/numbers/#update-a-purchased-did-s-destination"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "DID entry has been updated."
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "edit": {
          "type": "integer",
          "example": "2318",
          "description": "ID (i_did) of the purchased number, from List purchased DIDs. This is the record ID, not the phone number."
         },
         "contact": {
          "type": "string",
          "example": "sip:441615550123@203.0.113.14:5060",
          "description": "Where to send calls, as sip:<user>@<host>[:port]. Required for voice, fax or video numbers. Stored in lower case."
         },
         "contact2": {
          "type": "string",
          "example": "sip:441615550123@203.0.113.24:5060",
          "description": "Failover SIP address, same format. Send it empty to remove it."
         },
         "smpp_contact": {
          "type": "string",
          "example": "smpp:buyer01:secret:441615550123@203.0.113.15:2776",
          "description": "Where to deliver SMS, as smpp:<login>:<password>:<number>@<host>:<port>. Required for SMS numbers."
         },
         "sip_srv": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": "0",
          "description": "1 to resolve the SIP host by DNS SRV (_sip._udp. is inserted after the @ of contact and contact2). Give the host without a port."
         }
        },
        "required": [
         "edit"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "There was an error.",
      "when": "edit is not one of your purchased numbers"
     }
    ]
   }
  },
  "/number/unsubscribe": {
   "post": {
    "tags": [
     "Phone numbers (DIDs)"
    ],
    "summary": "Cancel a purchased DID",
    "description": "Cancels a number you bought. The number stops working and returns to the market at once, its SIP and SMPP destinations and document verification are cleared, and no further recurring fees are charged. Fees already paid are not refunded. The seller is emailed a cancellation notice.\n\nWithout unsubscribe, this path returns your purchased numbers, as List purchased DIDs does.",
    "operationId": "did-exchange-unsubscribe-did",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/numbers/#cancel-a-purchased-did"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Unsubscribed successfully"
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "unsubscribe": {
          "type": "integer",
          "example": "2318",
          "description": "ID (i_did) of the purchased number, from List purchased DIDs."
         }
        },
        "required": [
         "unsubscribe"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "There was an error",
      "when": "unsubscribe is not one of your purchased numbers"
     },
     {
      "message": "Error: <reason>",
      "when": "a partner-inventory number cannot be released; returned as plain text, not JSON"
     }
    ]
   }
  },
  "/buyers/esim/countries": {
   "get": {
    "tags": [
     "eSIMs"
    ],
    "summary": "List eSIM countries",
    "description": "Lists the country names, followed by the region names, you can pass as country to Market View (eSIM). Country names are upper case (for example JAPAN); region names are as the sellers define them (for example Europe). Free.\n\nThe list covers every country TCXC knows, not only countries with packages. The call can take several seconds.",
    "operationId": "esim-exchange-list-countries",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/esims/#list-esim-countries"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "countries": [
            {
             "country": "AFGHANISTAN"
            },
            {
             "country": "ALBANIA"
            },
            {
             "country": "Europe"
            }
           ]
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/buyers/esim/market": {
   "post": {
    "tags": [
     "eSIMs"
    ],
    "summary": "Market View (eSIM)",
    "description": "Searches eSIM data packages for a country, a region or worldwide (Global). Returns each package's ID, name, validity, data allowance, networks, supported countries, seller and price_with_fee (USD, including the TCXC commission). Packages listed for the exact country come first, then by price. Free.\n\nThe first search for a country can take several seconds. max_price and data_GB values other than those listed return a plain-text error instead of results; filter by price_with_fee and data_gb in your own code.",
    "operationId": "esim-exchange-market-view-esim",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/esims/#market-view-esim"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "market-view-esim-success": {
          "summary": "Market View (eSIM) - Success",
          "value": {
           "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"
              }
             ]
            },
            "\u2026 2 more items"
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "country": {
          "type": "string",
          "example": "JAPAN",
          "description": "Country name from List eSIM countries (for example JAPAN), a region name such as Europe, or Global for worldwide packages. Case does not matter."
         },
         "i_vendor": {
          "type": "integer",
          "example": "484",
          "description": "Search only this seller, by ID. 0 or empty searches all sellers."
         },
         "esim_vendor": {
          "type": "string",
          "example": "eSIMP",
          "description": "Seller login to search, for example eSIMP. Ignored when i_vendor is set; an unknown login searches all sellers."
         },
         "data_GB": {
          "type": "number",
          "enum": [
           0.5,
           1,
           5,
           10
          ],
          "example": "1",
          "description": "Data allowance range: 0.5 (0.5 to 1 GB), 1 (1 to 5 GB), 5 (5 to 10 GB), 10 (10 to 20 GB)."
         },
         "validity_days": {
          "type": "integer",
          "enum": [
           1,
           7,
           15,
           30,
           60,
           90
          ],
          "example": "30",
          "description": "Validity range: 1 (1 to 7 days), 7 (7 to 15), 15 (15 to 30), 30 (30 to 60), 60 (60 to 90), 90 (90 or more)."
         },
         "pager": {
          "type": "integer",
          "default": 20,
          "example": "5",
          "description": "Packages to return per seller, not in total."
         },
         "off": {
          "type": "integer",
          "default": 0,
          "example": "0",
          "description": "Offset within each seller's results."
         }
        },
        "required": [
         "country"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "country parameter is required",
      "when": "country is empty"
     }
    ]
   }
  },
  "/buyers/esim/purchase": {
   "post": {
    "tags": [
     "eSIMs"
    ],
    "summary": "Purchase an eSIM",
    "description": "Buys an eSIM package from Market View (eSIM). Charges the package price plus the TCXC commission to the account (or the account whose balance it uses) and returns the ICCID, the LPA activation string, a PNG QR code in base64 and an iOS install link, ready to install. Available funds are checked against the listed price before buying.\n\nError replies carry their text in a key named `messsage` (three s), not `message`. The amount charged is the final package price at the moment of purchase plus commission, which can differ slightly from the listed price_with_fee.",
    "operationId": "esim-exchange-purchase-esim",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/esims/#purchase-an-esim"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "iccid": "8910300000012345678",
           "i_esim_order": 412,
           "order_uuid": "5f0c6a7e-2b1d-4c8e-9a3f-7d2e1b6c9a40",
           "lpa": "LPA:1$smdp.example.net$TN20261022A1B2C3D4",
           "qr_base64": "iVBORw0KGgoAAAANSUhEUgAAAXgAAAF4CAIAAAD...",
           "ios_install_link": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.example.net$TN20261022A1B2C3D4"
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "i_esim_package": {
          "type": "integer",
          "example": "1306",
          "description": "Package ID from Market View (eSIM)."
         },
         "i_account": {
          "type": "integer",
          "example": "1501",
          "description": "Your account to charge. It needs balance plus credit limit of at least the package's price_with_fee."
         }
        },
        "required": [
         "i_esim_package",
         "i_account"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "i_esim_package parameter is required to identify the package",
      "when": "i_esim_package is missing or 0"
     },
     {
      "message": "i_account parameter is required",
      "when": "i_account is missing or 0"
     },
     {
      "message": "Package not found",
      "when": "no package has this ID"
     },
     {
      "message": "Package not found (3)",
      "when": "the package's seller is no longer available"
     },
     {
      "message": "Account not found",
      "when": "i_account is not one of your accounts"
     },
     {
      "message": "Insufficient available funds (own) for selected account",
      "when": "the account's balance plus credit limit is below the package price with commission"
     },
     {
      "message": "Insufficient available funds (use balance of) for selected account",
      "when": "the account uses another account's balance and that account cannot cover the price"
     },
     {
      "message": "Package is not available anymore, please retry market search to get the updated list of packages",
      "when": "the package is no longer offered"
     },
     {
      "message": "Purchase process encountered unexpected error, please retry market search to get the updated list of packages",
      "when": "the eSIM could not be issued"
     }
    ]
   }
  },
  "/buyers/esim/topup/list": {
   "post": {
    "tags": [
     "eSIMs"
    ],
    "summary": "List top-up packages",
    "description": "Lists the top-up packages available for one of your eSIMs, with price_with_fee in USD including the TCXC commission. Only USD-priced packages are returned. Free.\n\nThe fields of each package depend on the seller of the eSIM; use package_type_id to buy one.",
    "operationId": "esim-exchange-top-up-packages",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/esims/#list-top-up-packages"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "success": {
          "summary": "Success",
          "value": {
           "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"
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "iccid": {
          "type": "string",
          "example": "8910300000012345678",
          "description": "ICCID of an eSIM you bought. Non-digits are removed."
         }
        },
        "required": [
         "iccid"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "iccid parameter is required",
      "when": "iccid is missing or has no digits"
     },
     {
      "message": "ICCID not found",
      "when": "the ICCID is not on one of your accounts"
     },
     {
      "message": "API Error, please try again later",
      "when": "top-ups cannot be retrieved at the moment"
     }
    ]
   }
  },
  "/buyers/esim/topup/purchase": {
   "post": {
    "tags": [
     "eSIMs"
    ],
    "summary": "Purchase a top-up",
    "description": "Buys a top-up package for one of your eSIMs. The package price is confirmed again at purchase, the price plus commission is charged to i_account (or the account whose balance it uses), and the order UUID is returned. The paying account does not have to be the one that holds the eSIM.",
    "operationId": "esim-exchange-purchase-topup-package",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/esims/#purchase-a-top-up"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "order_uuid": "c40d0f55-8993-40cf-8d83-108ff80ff4ed"
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "iccid": {
          "type": "string",
          "example": "8910300000012345678",
          "description": "ICCID of an eSIM you bought."
         },
         "package_type_id": {
          "type": "string",
          "example": "18509",
          "description": "package_type_id from List top-up packages (numeric or text, depending on the eSIM)."
         },
         "i_account": {
          "type": "integer",
          "example": "1501",
          "description": "Your account to charge."
         }
        },
        "required": [
         "iccid",
         "package_type_id",
         "i_account"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "iccid parameter is required",
      "when": "iccid is missing or has no digits"
     },
     {
      "message": "i_account parameter is required",
      "when": "i_account is missing or 0"
     },
     {
      "message": "package_type_id parameter is required",
      "when": "package_type_id is missing"
     },
     {
      "message": "Account not found (1)",
      "when": "the ICCID is not on one of your accounts"
     },
     {
      "message": "API Error, please try again later",
      "when": "top-ups cannot be retrieved at the moment"
     },
     {
      "message": "Package not found, try to search for topup packages again",
      "when": "package_type_id is not among the eSIM's current USD top-ups"
     },
     {
      "message": "Account not found",
      "when": "i_account is not one of your accounts"
     },
     {
      "message": "Insufficient available funds for account (own)",
      "when": "the account's balance plus credit limit is below the price"
     },
     {
      "message": "Insufficient available funds for account (use balance of)",
      "when": "the account uses another account's balance and that account cannot cover the price"
     },
     {
      "message": "Package is not available anymore, please try another package",
      "when": "the top-up is no longer offered"
     }
    ]
   }
  },
  "/buyers/esim/orders": {
   "post": {
    "tags": [
     "eSIMs"
    ],
    "summary": "eSIM order history",
    "description": "Lists your eSIM purchases and top-ups in a time range, newest first, with the amount charged, status, ICCID, package details and, for purchases, the activation code, LPA string and QR code. Free.\n\nTop-up orders have empty activation_code, sm_dp_address, lpa and qr_base64, and 0 validity and data.",
    "operationId": "esim-exchange-orders-history",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/esims/#esim-order-history"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "success": {
          "summary": "Success",
          "value": {
           "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": "iVBORw0KGgoAAAANSUhEUgAAAXgAAAF4CAIAAADR/3XxAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAHMklEQVR4nO3dS25bMRQFwSjw/rfs7CCgYPYV+Vw1DmR9G5yc8PX9/f0HoPT3008AeD6hAXJCA+SEBsgJDZATGiAnNEBOaICc0AA5oQFyQgPkhAbICQ2Q+1r/p6/Xq3seh1vZuO96f3bt6W98Prve58n/k8DvYoUTDZATGiAnNEBOaICc0AA5oQFyQgPkhAbICQ2QExogJzRA7o2t04ob77186lblxs9i0uRm6sbPYu/vwokGyAkNkBMaICc0QE5ogJzQADmhAXJCA+SEBsgJDZATGiC3eeu0YnJbNLkxmbz7aZff/HxO2x89+7U70QA5oQFyQgPkhAbICQ2QExogJzRATmiAnNAAOaEBckID5D6wdWLGru3Mrl3MabsqJjnRADmhAXJCA+SEBsgJDZATGiAnNEBOaICc0AA5oQFyQgPkbJ22seX5uRvvxmKFEw2QExogJzRATmiAnNAAOaEBckID5IQGyAkNkBMaICc0QO4DW6dd9wTdaPK1T97H5O6nn3v278KJBsgJDZATGiAnNEBOaICc0AA5oQFyQgPkhAbICQ2QExogt3nr9Ju3Krvs2hZNbpR2mbzXyYZrkhMNkBMaICc0QE5ogJzQADmhAXJCA+SEBsgJDZATGiAnNEDuja3TabuY3+zG7czk92fy/fG7WOFEA+SEBsgJDZATGiAnNEBOaICc0AA5oQFyQgPkhAbICQ2Qe60vNW7cj+x6zpP3DU2afF2nbYKe+nmtmP9MnWiAnNAAOaEBckID5IQGyAkNkBMaICc0QE5ogJzQADmhAXIfuNdp185i5XFO29esOO19vtHkd+O0LdiZn7sTDZATGiAnNEBOaICc0AA5oQFyQgPkhAbICQ2QExogJzRA7o2t0y677hK6cRty2nOefO27PtMztzz/d9r9WfPvoRMNkBMaICc0QE5ogJzQADmhAXJCA+SEBsgJDZATGiAnNEBu89bptB3KaZupXc9nci922kbptL3Yja99/m850QA5oQFyQgPkhAbICQ2QExogJzRATmiAnNAAOaEBckID5A6912nF5N1GkxuTFb95UzbpqTumFXs/UycaICc0QE5ogJzQADmhAXJCA+SEBsgJDZATGiAnNEBOaIDcB7ZOkzudyV3VaXfunLaHmjS5g7vR/K7KiQbICQ2QExogJzRATmiAnNAAOaEBckID5IQGyAkNkBMaIPdaXz3s2vtMPs6k0+6ruvE9nHTanU03/r7c6wQcRGiAnNAAOaEBckID5IQGyAkNkBMaICc0QE5ogJzQALk3tk5LD3fY/Udn7j7uMrn3WXHaZ3Ha+3MmJxogJzRATmiAnNAAOaEBckID5IQGyAkNkBMaICc0QE5ogNzX+j/dtek47V6nybuN7GJ+7rT7s1actvOa/x460QA5oQFyQgPkhAbICQ2QExogJzRATmiAnNAAOaEBckID5N7YOp12V85p9zFNPufT7jba5cYtz1M/r73Px4kGyAkNkBMaICc0QE5ogJzQADmhAXJCA+SEBsgJDZATGiD3gXudVkzumE7bQ0268U6rXXZ9pqdtlM78XTjRADmhAXJCA+SEBsgJDZATGiAnNEBOaICc0AA5oQFyQgPkXvNLjck7d3Y57TnfeE/QpNP2azf+rb2caICc0AA5oQFyQgPkhAbICQ2QExogJzRATmiAnNAAOaEBcm9snW7c+9xo1507N/6tFU/93HexdQJ+KaEBckID5IQGyAkNkBMaICc0QE5ogJzQADmhAXJCA+S+1v/paRuK057Prjt3Jh/nRjfus1bce2fTCicaICc0QE5ogJzQADmhAXJCA+SEBsgJDZATGiAnNEBOaIDcG1unp25nVqxsTG7cxUw+zuT+aHIP9dSN0t7X5UQD5IQGyAkNkBMaICc0QE5ogJzQADmhAXJCA+SEBsgJDZB7Y+u04qmbjl2Ps+v9mdwx7XLaFmyX017X5HdsnRMNkBMaICc0QE5ogJzQADmhAXJCA+SEBsgJDZATGiAnNEBu89ZpxVN3KKfdJbTLaX/rtG3RU7nXCbiM0AA5oQFyQgPkhAbICQ2QExogJzRATmiAnNAAOaEBch/YOvFzk7uqSZOva/JurNP2YvOcaICc0AA5oQFyQgPkhAbICQ2QExogJzRATmiAnNAAOaEBcrZO29y4Z7nxOU/e67TL5K5qxfweyokGyAkNkBMaICc0QE5ogJzQADmhAXJCA+SEBsgJDZATGiD3ga3TjVuVSZN7ltO2M5PfjTPvP/q/XZ/p/G/QiQbICQ2QExogJzRATmiAnNAAOaEBckID5IQGyAkNkBMaILd563TjfuRGp+2Ydt1bNPm3VkzexzT5ulbs/Y450QA5oQFyQgPkhAbICQ2QExogJzRATmiAnNAAOaEBckID5F5uWQJqTjRATmiAnNAAOaEBckID5IQGyAkNkBMaICc0QE5ogJzQADmhAXJCA+T+AVxK9S9t1uyKAAAAAElFTkSuQmCC",
             "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"
            },
            "\u2026 1 more items"
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "date_from": {
          "type": "string",
          "example": "2026-10-01 00:00:00",
          "description": "Start of the range, YYYY-MM-DD HH:MM:SS. Default: 24 hours ago."
         },
         "date_to": {
          "type": "string",
          "example": "2026-10-22 23:59:59",
          "description": "End of the range, YYYY-MM-DD HH:MM:SS. Default: now."
         },
         "pager": {
          "type": "integer",
          "default": 20,
          "example": "20",
          "description": "Orders per page."
         },
         "off": {
          "type": "integer",
          "default": 0,
          "example": "0",
          "description": "Offset of the first order."
         }
        }
       }
      }
     }
    }
   }
  },
  "/buyers/esim/list": {
   "post": {
    "tags": [
     "eSIMs"
    ],
    "summary": "List purchased eSIMs",
    "description": "Lists your eSIMs, newest first, with their live status: profile state (for example RELEASED, INSTALLED, ENABLED), remaining data, days to expiry, and the activation details and iOS install link. With iccid, returns that one eSIM as an esim object instead of an esims list. Free; each eSIM's status is fetched live, so large pages are slower.\n\nWith iccid the reply is {\"status\": \"success\", \"esim\": {...}}; without it, {\"status\": \"success\", \"esims\": [...]}. When live status is unavailable, an eSIM is returned with its last known status and empty usage fields.",
    "operationId": "esim-exchange-list-purchased-esims",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/esims/#list-purchased-esims"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "success": {
          "summary": "Success",
          "value": {
           "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": "iVBORw0KGgoAAAANSUhEUgAAAUgAAAFICAIAAAC9dvBkAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAFuUlEQVR4nO3dQW4bSRBFweFA97+yZ+G1jSKUk6x+ilgbZIvgQ20+y69fv379A7T8++kHAOYJG4KEDUHChiBhQ5CwIUjYECRsCBI2BAkbgoQNQcKGIGFD0Nf5P329Xv/fc1xu6jdwJ5/h5u/tNp9n6r18D084sSFI2BAkbAgSNgQJG4KEDUHChiBhQ5CwIUjYECRsCHpjK37iif+vyNT2eHPDXH2vKT/5e/ibExuChA1BwoYgYUOQsCFI2BAkbAgSNgQJG4KEDUHChqDhrfiJze3x5mZ46k7sqc/ntvvAb1P9Hv7mxIYgYUOQsCFI2BAkbAgSNgQJG4KEDUHChiBhQ5CwIegDW/GqzY335ub8RHVP/lxObAgSNgQJG4KEDUHChiBhQ5CwIUjYECRsCBI2BAkbgmzFx9x2j7f7yX8yJzYECRuChA1BwoYgYUOQsCFI2BAkbAgSNgQJG4KEDUEf2IpX98BP3EI/cXM+5bbnmeXEhiBhQ5CwIUjYECRsCBI2BAkbgoQNQcKGIGFDkLAhaHgrPrUr5lmmNuebd5i3ObEhSNgQJGwIEjYECRuChA1BwoYgYUOQsCFI2BAkbAh6Yyvevof5+6Y+n9t217ep/l2znNgQJGwIEjYECRuChA1BwoYgYUOQsCFI2BAkbAgSNgS9zpe3T7yreWp3fZvN+7c3t9lTz1N9nXNObAgSNgQJG4KEDUHChiBhQ5CwIUjYECRsCBI2BAkbgt64V/zE5oZ56nWeuBme+nzc0b1jf0/uxIYgYUOQsCFI2BAkbAgSNgQJG4KEDUHChiBhQ5CwIeiNe8WPXi66qd502377iZ/hlNt++2ArDj+asCFI2BAkbAgSNgQJG4KEDUHChiBhQ5CwIUjYEPTGVry6Gd7cZm9uhmfvqf7+e5144t9153s5sSFI2BAkbAgSNgQJG4KEDUHChiBhQ5CwIUjYECRsCPraf8vb7hXf3AOfuO3zOXmd6l3ot23XzzmxIUjYECRsCBI2BAkbgoQNQcKGIGFDkLAhSNgQJGwI+sBWfMqdG93vm9o537Yn39ylbz7zif07+Z3YECRsCBI2BAkbgoQNQcKGIGFDkLAhSNgQJGwIEjYEDW/Fp7bZ7R3v9019zk/cVD9x/7/PiQ1BwoYgYUOQsCFI2BAkbAgSNgQJG4KEDUHChiBhQ9CD7xWfsnlP9ZSpbfbmM1c33pu7/XNObAgSNgQJG4KEDUHChiBhQ5CwIUjYECRsCBI2BAkbgl7nS9fNO6g377I+Ud05b27gq/e337nbd2JDkLAhSNgQJGwIEjYECRuChA1BwoYgYUOQsCFI2BD0xlacv6tu4G97nim3bbxnd/tObAgSNgQJG4KEDUHChiBhQ5CwIUjYECRsCBI2BAkbgr7O/+kT74Wectuifmrj/cR7xTef+ba//ZwTG4KEDUHChiBhQ5CwIUjYECRsCBI2BAkbgoQNQcKGoDe24idu21Sf2Lxf+ok759vcdvf4yfPs39/uxIYgYUOQsCFI2BAkbAgSNgQJG4KEDUHChiBhQ5CwIWh4K35i847lJ+6Kb7vre3Pn/MS76zd/a3DOiQ1BwoYgYUOQsCFI2BAkbAgSNgQJG4KEDUHChiBhQ9AHtuL83eY2e3O7fttvBG7b5M8+jxMbgoQNQcKGIGFDkLAhSNgQJGwIEjYECRuChA1BwoYgW/FVt228N9/rJ9/xvr+ld2JDkLAhSNgQJGwIEjYECRuChA1BwoYgYUOQsCFI2BD0ga345mb4Nrfdv32ieq/45uvsc2JDkLAhSNgQJGwIEjYECRuChA1BwoYgYUOQsCFI2BA0vBW/bef8RJv3XW/eB765J9/8u+78zjuxIUjYECRsCBI2BAkbgoQNQcKGIGFDkLAhSNgQJGwIej335mTgT5zYECRsCBI2BAkbgoQNQcKGIGFDkLAhSNgQJGwIEjYECRuChA1B/wEW5aCaWPW86QAAAABJRU5ErkJggg==",
             "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"
              },
              "\u2026 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": "iVBORw0KGgoAAAANSUhEUgAAAUgAAAFICAIAAAC9dvBkAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAFmUlEQVR4nO3dQW4jRxBFQdPw/a8sL7Qeowmli1lPEWtj1KT6oTZf5dfX19dfQMvfn34AYJ6wIUjYECRsCBI2BAkbgoQNQcKGIGFDkLAhSNgQJGwIEjYE/fP8P329Xv/fcyw39TdwJ7/Dk8988m8EvYdPOLEhSNgQJGwIEjYECRuChA1BwoYgYUOQsCFI2BAkbAh6Yyv+xI3/X5Hqfnvbpvrk5tx76MSGIGFDkLAhSNgQJGwIEjYECRuChA1BwoYgYUOQsCFoeCv+xI3b7Ck3fvapZ/a7OMmJDUHChiBhQ5CwIUjYECRsCBI2BAkbgoQNQcKGIGFD0Ae24lVT92ZPbZi3bbxP3iuOExuChA1BwoYgYUOQsCFI2BAkbAgSNgQJG4KEDUHChiBb8Sud3JxzIyc2BAkbgoQNQcKGIGFDkLAhSNgQJGwIEjYECRuChA1BH9iKV++O3rbf3nYf+Lbf+7bnmeXEhiBhQ5CwIUjYECRsCBI2BAkbgoQNQcKGIGFDkLAhaHgr/pvvsp7aVE99h1PPM+Xk8/zm9/CbExuChA1BwoYgYUOQsCFI2BAkbAgSNgQJG4KEDUHChqBX+3blbbbtt5+48S50nNgQJGwIEjYECRuChA1BwoYgYUOQsCFI2BAkbAgSNgS9ca/41GZ4213WU07eiX3jz9rmxvf5OSc2BAkbgoQNQcKGIGFDkLAhSNgQJGwIEjYECRuChA1Bb9wrfnJba8N8xtTv4qSTz3zyXZ19553YECRsCBI2BAkbgoQNQcKGIGFDkLAhSNgQJGwIEjYEvXGv+I274m2b4amf9cS238WUbZ9rZxdObAgSNgQJG4KEDUHChiBhQ5CwIUjYECRsCBI2BAkbgt7Yit941/fJ3fW2jffU82z7Dqvv4eye3IkNQcKGIGFDkLAhSNgQJGwIEjYECRuChA1BwoYgYUPQG1vxJ27c8d64Az/J9/Nz7hUHBggbgoQNQcKGIGFDkLAhSNgQJGwIEjYECRuChA1Br+cr3207cBvmnzt/3/V/23aH+dTPmvL8mZ3YECRsCBI2BAkbgoQNQcKGIGFDkLAhSNgQJGwIEjYEDd8rftK2XfG2Lf0TJz/7E9u+w3v/RsCJDUHChiBhQ5CwIUjYECRsCBI2BAkbgoQNQcKGIGFD0NKt+M67mn9u6nOd3K5v+3embPtcs++8ExuChA1BwoYgYUOQsCFI2BAkbAgSNgQJG4KEDUHChqAPbMW3bWu37benVPfbNzr/PTuxIUjYECRsCBI2BAkbgoQNQcKGIGFDkLAhSNgQJGwIep1cArfduHPedm/2tl36vc/jxIYgYUOQsCFI2BAkbAgSNgQJG4KEDUHChiBhQ5CwIeiNe8Vv3EJPmdoMT/0723bOJ2377Nue55sTG4KEDUHChiBhQ5CwIUjYECRsCBI2BAkbgoQNQcKGoDe24k/cuE+ubuCnNsxTd4ZP2faObXueb05sCBI2BAkbgoQNQcKGIGFDkLAhSNgQJGwIEjYECRuChrfiT1R3xTfeGb7tTuxtu/1731UnNgQJG4KEDUHChiBhQ5CwIUjYECRsCBI2BAkbgoQNQR/Yiv9mU9vjqX9n25Z+2+c6uRWf3e07sSFI2BAkbAgSNgQJG4KEDUHChiBhQ5CwIUjYECRsCLIVP+rkNvtGN96XvnOX7sSGIGFDkLAhSNgQJGwIEjYECRuChA1BwoYgYUOQsCHoA1vx6l765J3YJ7fQ2+5Cf6L6jj3nxIYgYUOQsCFI2BAkbAgSNgQJG4KEDUHChiBhQ5CwIWh4K35yD8weJ/ftJ7fr927OndgQJGwIEjYECRuChA1BwoYgYUOQsCFI2BAkbAgSNgS97l3DAn/ixIYgYUOQsCFI2BAkbAgSNgQJG4KEDUHChiBhQ5CwIUjYECRsCPoX0mhkwcOKX1IAAAAASUVORK5CYII=",
             "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": "iVBORw0KGgoAAAANSUhEUgAAAUgAAAFICAIAAAC9dvBkAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAFs0lEQVR4nO3dQW4bSRBFweFg7n9leaH1AEWonMp+jFgbZFPiQ22+yq+vr69/gJZ/f/sBgPuEDUHChiBhQ5CwIUjYECRsCBI2BAkbgoQNQcKGIGFDkLAh6L/zf/p6vf7ecyx362/gTn6Gk39vN/k8t97L9/CEExuChA1BwoYgYUOQsCFI2BAkbAgSNgQJG4KEDUHChqA3tuInnvj/itzaHk9umKvvdcsnfw+/ObEhSNgQJGwIEjYECRuChA1BwoYgYUOQsCFI2BAkbAi6vBU/Mbk9ntwM37oT+9bPZ9t94NtUv4ffnNgQJGwIEjYECRuChA1BwoYgYUOQsCFI2BAkbAgSNgT9wla8anLjPbk5P1Hdkz+XExuChA1BwoYgYUOQsCFI2BAkbAgSNgQJG4KEDUHChiBb8Wu23ePtfvJP5sSGIGFDkLAhSNgQJGwIEjYECRuChA1BwoYgYUOQsCHoF7bi1T3wti305Mb7xLbf+7bnucuJDUHChiBhQ5CwIUjYECRsCBI2BAkbgoQNQcKGIGFD0OWt+K1dMT83uV2/dc/5tn37czmxIUjYECRsCBI2BAkbgoQNQcKGIGFDkLAhSNgQJGwIemMr3r6H+eequ+ttqp/rLic2BAkbgoQNQcKGIGFDkLAhSNgQJGwIEjYECRuChA1Br/Pl7RPvar61u95m8v7tyW32reepvs45JzYECRuChA1BwoYgYUOQsCFI2BAkbAgSNgQJG4KEDUGX7xWf3Nbe8snP447uGfN7cic2BAkbgoQNQcKGIGFDkLAhSNgQJGwIEjYECRuChA1Bb9wrfu0tB+9Y3rap3vbZt+3kt3nu99CJDUHChiBhQ5CwIUjYECRsCBI2BAkbgoQNQcKGIGFD0Bv3ip+Y3BVP7m+fuPG+Zds950/8Xcxv8p3YECRsCBI2BAkbgoQNQcKGIGFDkLAhSNgQJGwIEjYEvbEV37bRveWJ2+xbrzO5hZ5U3a6fc2JDkLAhSNgQJGwIEjYECRuChA1BwoYgYUOQsCFI2BD0Ol+xTu63t91lPemJP+dtm+rJZ550/vNxYkOQsCFI2BAkbAgSNgQJG4KEDUHChiBhQ5CwIUjYEPTGveIntu2uq1voW8+zbVO9847uJ3JiQ5CwIUjYECRsCBI2BAkbgoQNQcKGIGFDkLAhSNgQdHkrPmnb7vqW6p3q1Y335F3o55zYECRsCBI2BAkbgoQNQcKGIGFDkLAhSNgQJGwIEjYELd2Kb7vvenLnPHm39q332ra3P9H+jjmxIUjYECRsCBI2BAkbgoQNQcKGIGFDkLAhSNgQJGwIelVve543uRl+4nud2LbJP7Ftt//NiQ1BwoYgYUOQsCFI2BAkbAgSNgQJG4KEDUHChiBhQ9Ab94pvuxd60q098K1t9s598s/f69brTP6+Tsy348SGIGFDkLAhSNgQJGwIEjYECRuChA1BwoYgYUOQsCHoja34iSfeUl69o3tyUz1p293jJ88z/91wYkOQsCFI2BAkbAgSNgQJG4KEDUHChiBhQ5CwIUjYEHR5K35ici/9xF3xLZN3mE/eGb7N5N8anHNiQ5CwIUjYECRsCBI2BAkbgoQNQcKGIGFDkLAhSNgQ9Atb8U+2bQv9xD35icnPdeLkve4+jxMbgoQNQcKGIGFDkLAhSNgQJGwIEjYECRuChA1BwoYgW/FHqt5Pfsvkvv3kdea39E5sCBI2BAkbgoQNQcKGIGFDkLAhSNgQJGwIEjYECRuCfmErPrkZ/mTb9tLb7hWffJ15TmwIEjYECRuChA1BwoYgYUOQsCFI2BAkbAgSNgQJG4Iub8Un98CfbNsO/MTknnzyc+38zjuxIUjYECRsCBI2BAkbgoQNQcKGIGFDkLAhSNgQJGwIej335mTg/zixIUjYECRsCBI2BAkbgoQNQcKGIGFDkLAhSNgQJGwIEjYECRuC/gCs2ayRRSfxsAAAAABJRU5ErkJggg==",
             "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"
              },
              "\u2026 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"
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "iccid": {
          "type": "string",
          "example": "8910300000012345678",
          "description": "Return only this eSIM. Non-digits are removed."
         },
         "esim_vendor": {
          "type": "string",
          "example": "eSIMP",
          "description": "Seller login to filter by, for example eSIMP. An unknown login is ignored."
         },
         "pager": {
          "type": "integer",
          "default": 6,
          "example": "6",
          "description": "eSIMs per page."
         },
         "off": {
          "type": "integer",
          "default": 0,
          "example": "0",
          "description": "Offset of the first eSIM."
         }
        }
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "eSIM not found",
      "when": "iccid is given and no eSIM of yours matches"
     }
    ]
   }
  },
  "/buyers/esim/regions": {
   "get": {
    "tags": [
     "eSIMs"
    ],
    "summary": "List eSIM regions",
    "description": "Lists the eSIM regions the sellers define, each with its region code. Use the region name as country in Market View (eSIM). Free.\n\nA region offered by more than one seller appears once per seller.",
    "operationId": "esim-exchange-list-regions",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/esims/#list-esim-regions"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "regions": [
            {
             "region": "Europe",
             "region_country_code": "1E"
            },
            {
             "region": "Asia",
             "region_country_code": "1A"
            },
            {
             "region": "Global",
             "region_country_code": "2G"
            }
           ]
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/buyers/esim/countries_regions": {
   "post": {
    "tags": [
     "eSIMs"
    ],
    "summary": "List regions covering a country",
    "description": "Lists the region codes whose regional packages cover a country, so you can tell which regional packages also work there. Free.\n\nSend pager; without it the list is empty. The call can take several seconds.",
    "operationId": "esim-exchange-list-country-regions",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/esims/#list-regions-covering-a-country"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "countries_region": [
            {
             "country_code": "jp",
             "region_country_code": "1A"
            },
            {
             "country_code": "jp",
             "region_country_code": "2G"
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "country_code": {
          "type": "string",
          "example": "jp",
          "description": "Two-letter ISO country code in lower case, for example jp."
         },
         "pager": {
          "type": "integer",
          "example": "50",
          "description": "Number of rows to return."
         },
         "off": {
          "type": "integer",
          "default": 0,
          "example": "0",
          "description": "Offset of the first row."
         }
        },
        "required": [
         "country_code",
         "pager"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "missing country_code",
      "when": "country_code is empty"
     }
    ]
   }
  },
  "/buyers/hlr/lookup/{number}": {
   "post": {
    "tags": [
     "HLR lookups"
    ],
    "summary": "Look up a number (buyer)",
    "description": "Runs a live HLR lookup on a mobile number and returns its current and original network, MCC/MNC (`network_code`), porting status and roaming status. Each lookup costs $0.05, charged to the buyer account you name and shown in its transactions as \"HLR Lookup <number>\".\n\nEach lookup costs $0.05, including lookups the network can't answer. Leading zeros in the number are dropped, so always send the full international number.",
    "operationId": "hlr-lookups-lookup-number",
    "parameters": [
     {
      "name": "number",
      "in": "path",
      "required": true,
      "description": "Number in international format, digits only, with no + or leading zeros.",
      "schema": {
       "type": "string",
       "example": "447700900123"
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/hlr/#look-up-a-number-buyer"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "response": {
            "status": 0,
            "status_message": "Success",
            "request_id": "aa0e2a3c-5d1b-4f6e-9c1a-3f2b7d8e9a10",
            "international_format_number": "447700900123",
            "national_format_number": "07700 900123",
            "country_code": "GB",
            "country_code_iso3": "GBR",
            "country_name": "United Kingdom",
            "country_prefix": "44",
            "current_carrier": {
             "network_code": "23415",
             "name": "Vodafone Limited",
             "country": "GB",
             "network_type": "mobile"
            },
            "original_carrier": {
             "network_code": "23410",
             "name": "Telefonica UK Limited",
             "country": "GB",
             "network_type": "mobile"
            },
            "ported": "ported",
            "roaming": {
             "status": "unknown"
            }
           }
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "i_account": {
          "type": "integer",
          "example": 1501,
          "description": "ID of the buyer account to charge. Its balance plus credit limit must be at least $0.05."
         }
        },
        "required": [
         "i_account"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Account error",
      "when": "`i_account` is missing or is not one of your accounts"
     },
     {
      "message": "Account balance insufficient to run query",
      "when": "the account's balance plus credit limit is below $0.05"
     },
     {
      "message": "CLD missing, or wrong format (only digits are supported)",
      "when": "the number is not all digits"
     },
     {
      "message": "{\"status\": \"error\", \"response\": {...}}",
      "when": "the network cannot answer for this number or does not reply in time; `response` carries the provider's status and status_message"
     }
    ]
   }
  },
  "/sellers/hlr/lookup/{number}": {
   "post": {
    "tags": [
     "HLR lookups"
    ],
    "summary": "Look up a number (seller)",
    "description": "Runs a live HLR lookup on a mobile number with seller credentials and returns its current and original network, MCC/MNC (`network_code`), porting status and roaming status. Each lookup costs $0.05, deducted from your seller balance and listed in your payouts as \"HLR Lookup <number>\".\n\nEach lookup costs $0.05, including lookups the network can't answer.",
    "operationId": "hlr-lookups-sellers-lookup-number",
    "parameters": [
     {
      "name": "number",
      "in": "path",
      "required": true,
      "description": "Number in international format, digits only, with no + or leading zeros.",
      "schema": {
       "type": "string",
       "example": "447700900123"
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/hlr/#look-up-a-number-seller"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "response": {
            "status": 0,
            "status_message": "Success",
            "request_id": "c41f8b20-77e9-4d3a-a5b6-0e9d1c2b3a45",
            "international_format_number": "447700900123",
            "national_format_number": "07700 900123",
            "country_code": "GB",
            "country_code_iso3": "GBR",
            "country_name": "United Kingdom",
            "country_prefix": "44",
            "current_carrier": {
             "network_code": "23415",
             "name": "Vodafone Limited",
             "country": "GB",
             "network_type": "mobile"
            },
            "original_carrier": {
             "network_code": "23415",
             "name": "Vodafone Limited",
             "country": "GB",
             "network_type": "mobile"
            },
            "ported": "not_ported",
            "roaming": {
             "status": "unknown"
            }
           }
          }
         }
        }
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Seller balance insufficient to run query",
      "when": "your seller balance is below $0.05"
     },
     {
      "message": "CLD missing, or wrong format (only digits are supported)",
      "when": "the number is not all digits"
     },
     {
      "message": "{\"status\": \"error\", \"response\": {...}}",
      "when": "the network cannot answer for this number or does not reply in time"
     }
    ]
   }
  },
  "/buyers/balance": {
   "post": {
    "tags": [
     "Balances and payments"
    ],
    "summary": "List account balances",
    "description": "Returns every buyer account you own, blocked ones included, with its balance, credit limit and low-balance alert settings, sorted by name. An account that spends another account's balance (`use_balance` greater than 0) also carries `parent_name` and `parent_balance`. Free.\n\nSend `pager` and `off` in the form body; they are ignored in the query string. Balances are unrounded decimal strings.",
    "operationId": "money-get-accounts-balance",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/money/#list-account-balances"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "accounts": [
            {
             "i_account": "1855",
             "name": "A2P-Traffic",
             "ip_address": "",
             "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": "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"
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "pager": {
          "type": "integer",
          "default": 30,
          "example": 30,
          "description": "Maximum number of accounts to return."
         },
         "off": {
          "type": "integer",
          "default": 0,
          "example": 0,
          "description": "Number of accounts to skip, for paging."
         }
        }
       }
      }
     }
    }
   }
  },
  "/buyers/payhistory": {
   "post": {
    "tags": [
     "Balances and payments"
    ],
    "summary": "List payment history",
    "description": "Returns the payments and charges posted to all of your buyer accounts between `date_from` and `date_to`, newest first: top-ups, bank-wire credits, DID monthly fees and other balance adjustments. Each row names the account and the payment method. Free.\n\n`amount` is a formatted string with a thousands separator, such as \"10,000.00\". `status` is new, confirmed or declined. Send `download=1` to get every matching transaction in one response, without paging.",
    "operationId": "money-payment-history",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/money/#list-payment-history"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "transactions": [
            {
             "i_transaction": "48213",
             "i_account": "1022",
             "i_payment_system": "1",
             "currency": "USD",
             "amount": "-1.00",
             "status": "confirmed",
             "ts": "2026-09-06 12:00:01",
             "notepad": "Monthly charge for DID 15550104411",
             "account_name": "Northwind",
             "ps_name": "Manual Payment"
            },
            {
             "i_transaction": "47702",
             "i_account": "1022",
             "i_payment_system": "1",
             "currency": "USD",
             "amount": "10,000.00",
             "status": "confirmed",
             "ts": "2026-08-23 10:53:02",
             "notepad": "BANK WIRE",
             "account_name": "Northwind",
             "ps_name": "Manual Payment"
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "date_from": {
          "type": "string",
          "example": "2026-01-01 00:00:00",
          "description": "Start of the range, inclusive, as YYYY-MM-DD HH:MM:SS."
         },
         "date_to": {
          "type": "string",
          "example": "2026-09-30 23:59:59",
          "description": "End of the range, inclusive, as YYYY-MM-DD HH:MM:SS."
         },
         "i_payment_system": {
          "type": "integer",
          "default": 0,
          "example": 0,
          "description": "Only return transactions from this payment method: 1 for manual payments such as bank wire, 2 for PayPal. 0 returns all."
         },
         "amount": {
          "type": "string",
          "description": "Only return transactions of exactly this amount, for example -1.00."
         },
         "notes": {
          "type": "string",
          "description": "Only return transactions whose note contains this text, for example DID."
         },
         "pager": {
          "type": "integer",
          "default": 50,
          "example": 50,
          "description": "Maximum number of transactions to return."
         },
         "off": {
          "type": "integer",
          "default": 0,
          "example": 0,
          "description": "Number of transactions to skip, for paging."
         }
        },
        "required": [
         "date_from",
         "date_to"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Wrong date_from format, expected YYYY-MM-DD HH:MM:SS",
      "when": "date_from is missing or is not a YYYY-MM-DD HH:MM:SS timestamp"
     },
     {
      "message": "Wrong date_to format, expected YYYY-MM-DD HH:MM:SS",
      "when": "date_to is missing or is not a YYYY-MM-DD HH:MM:SS timestamp"
     }
    ]
   }
  },
  "/sellers/balance": {
   "post": {
    "tags": [
     "Balances and payments"
    ],
    "summary": "Get seller balance",
    "description": "Returns your seller balance: the earnings available for payout, in USD. Authenticate with your seller login and seller API key. Free.\n\nUse your seller credentials; buyer credentials are rejected.",
    "operationId": "money-get-seller-balance",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/money/#get-seller-balance"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "balance": "22631.2636213539752"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/sellers/payhistory": {
   "post": {
    "tags": [
     "Balances and payments"
    ],
    "summary": "List payout history",
    "description": "Returns the payouts TCXC has sent you as a seller, such as bank wires and PayPal transfers, between `date_from` and `date_to`, newest first. Authenticate with your seller login and seller API key. Free.\n\nSend `download=1` to get every matching payout in one response, without paging.",
    "operationId": "money-payout-history",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/money/#list-payout-history"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "transactions": [
            {
             "i_payout": "2873",
             "i_vendor": "287",
             "amount": "500",
             "i_admin": "0",
             "ts": "2026-08-24 22:14:41",
             "notepad": "Bank Wire"
            },
            {
             "i_payout": "2865",
             "i_vendor": "287",
             "amount": "23000",
             "i_admin": "0",
             "ts": "2026-07-22 15:24:58",
             "notepad": "Bank Wire"
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "date_from": {
          "type": "string",
          "example": "2026-01-01 00:00:00",
          "description": "Start of the range, inclusive, as YYYY-MM-DD HH:MM:SS."
         },
         "date_to": {
          "type": "string",
          "example": "2026-09-30 23:59:59",
          "description": "End of the range, inclusive, as YYYY-MM-DD HH:MM:SS."
         },
         "amount": {
          "type": "string",
          "description": "Only return payouts of exactly this amount."
         },
         "notes": {
          "type": "string",
          "description": "Only return payouts whose note contains this text, for example wire."
         },
         "pager": {
          "type": "integer",
          "default": 50,
          "example": 50,
          "description": "Maximum number of payouts to return."
         },
         "off": {
          "type": "integer",
          "default": 0,
          "example": 0,
          "description": "Number of payouts to skip, for paging."
         }
        },
        "required": [
         "date_from",
         "date_to"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Wrong date_from format, expected YYYY-MM-DD HH:MM:SS",
      "when": "date_from is missing or is not a YYYY-MM-DD HH:MM:SS timestamp"
     },
     {
      "message": "Wrong date_to format, expected YYYY-MM-DD HH:MM:SS",
      "when": "date_to is missing or is not a YYYY-MM-DD HH:MM:SS timestamp"
     }
    ]
   }
  },
  "/buyers/iothistory": {
   "post": {
    "tags": [
     "Reports"
    ],
    "summary": "List IoT (MQTT) message records",
    "description": "Lists the MQTT messages published or received by your IoT accounts between two times, newest first: account, topic, payload, direction, whether the message was authorised, and the amount charged. Free.\n\nResults can't be filtered by topic: filter on `topic` in your own code after fetching.",
    "operationId": "iot-buyer-iot-history",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/reports/#list-iot-mqtt-message-records"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "mqtt_messages": [
            {
             "i_mqtt_message": "192",
             "i_account": "2203",
             "i_customer": "1014",
             "topic": "sensors/warehouse-3/temperature",
             "payload": "21.4",
             "direction": "1",
             "authorized": "1",
             "charged_amount": "0.0001",
             "ts": "2026-10-21 16:11:05",
             "account_name": "mqtt-warehouse"
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "date_from": {
          "type": "string",
          "example": "2026-10-01 00:00:00",
          "description": "Start of the period, as YYYY-MM-DD HH:MM:SS. Defaults to 24 hours ago."
         },
         "date_to": {
          "type": "string",
          "example": "2026-10-22 00:00:00",
          "description": "End of the period, as YYYY-MM-DD HH:MM:SS. Defaults to now."
         },
         "show": {
          "type": "string",
          "enum": [
           "good",
           "bad"
          ],
          "description": "good returns only authorised messages, bad only rejected ones. Leave empty for both."
         },
         "pager": {
          "type": "integer",
          "default": 50,
          "description": "Maximum number of records to return."
         },
         "off": {
          "type": "integer",
          "default": 0,
          "description": "Number of records to skip, for paging."
         },
         "download": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "description": "1 returns all matching records as a CSV file (mqtt_messages.csv) instead of JSON."
         }
        }
       }
      }
     }
    }
   }
  },
  "/buyers/voice/summary": {
   "post": {
    "tags": [
     "Reports"
    ],
    "summary": "Voice summary report",
    "description": "Totals your voice traffic per day or per month: spend, billed minutes and number of calls, optionally narrowed to some of your accounts, purchased routes and destinations. Returns JSON, or a CSV file when `download=1`. Free.\n\nA destination that matches nothing returns zero totals rather than an error. Write destinations without spaces around the first hyphen: EGYPT-Mobile - Vodafone, not EGYPT - Mobile - Vodafone.",
    "operationId": "reports-voice-summary-report",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/reports/#voice-summary-report"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "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 23:59:59",
             "date_text": "2026 Oct",
             "total_amt": 0,
             "total_minutes": 0,
             "total_calls": 0
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "date_from": {
          "type": "string",
          "example": "2026-08-01 00:00:00",
          "description": "Start of the range, inclusive, as YYYY-MM-DD HH:MM:SS. Send both dates, or neither for the last 12 days."
         },
         "date_to": {
          "type": "string",
          "example": "2026-10-31 23:59:59",
          "description": "End of the range, inclusive, as YYYY-MM-DD HH:MM:SS. Use 23:59:59 to include the whole final day."
         },
         "time_format": {
          "type": "string",
          "default": "daily",
          "example": "monthly",
          "description": "daily returns one row per day; any other value, such as monthly, returns one row per calendar month."
         },
         "status": {
          "type": "string",
          "default": "good",
          "example": "all",
          "description": "good counts answered calls, bad counts failed calls, any other value (such as all) counts both. With all, spend and minutes come from answered calls and the call count includes failed calls."
         },
         "accounts[]": {
          "type": "integer",
          "example": 1022,
          "description": "One of your voice account IDs; repeat the field for several. Omit to include all your voice accounts."
         },
         "connections[]": {
          "type": "integer",
          "example": 653,
          "description": "`i_connection` of a purchased voice route; repeat the field for several. Omit to include all your purchased voice routes."
         },
         "destination_descriptions[]": {
          "type": "string",
          "example": "EGYPT-Mobile - Vodafone",
          "description": "A destination as the country and the description joined by a single hyphen with no spaces around it, for example EGYPT-Mobile - Vodafone; repeat for several. % works as a wildcard, so EGYPT-% covers the whole country. Omit for all destinations."
         },
         "download": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": 0,
          "description": "1 returns a CSV attachment (voice_summary.csv) instead of JSON."
         }
        }
       }
      }
     }
    }
   }
  },
  "/buyers/sms/summary": {
   "post": {
    "tags": [
     "Reports"
    ],
    "summary": "SMS summary report",
    "description": "Totals your SMS traffic per day or per month: spend and number of messages, optionally narrowed to some of your SMS accounts, purchased SMS routes and destinations. Returns JSON, or a CSV file broken down by sender ID when `download=1`. Free.\n\nA destination that matches nothing returns zero totals rather than an error. To cover a whole country, send the country followed by -%, for example OMAN-%.",
    "operationId": "reports-sms-summary-report",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/reports/#sms-summary-report"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "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": 3.3606,
             "total_sms": 28
            },
            {
             "date_from": "2026-09-01 00:00:00",
             "date_to": "2026-09-30 23:59:59",
             "date_text": "2026 Sep",
             "total_amt": 1.8883,
             "total_sms": 85
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "date_from": {
          "type": "string",
          "example": "2026-08-01 00:00:00",
          "description": "Start of the range, inclusive, as YYYY-MM-DD HH:MM:SS. Send both dates, or neither for the last 12 days."
         },
         "date_to": {
          "type": "string",
          "example": "2026-09-30 23:59:59",
          "description": "End of the range, inclusive, as YYYY-MM-DD HH:MM:SS. Use 23:59:59 to include the whole final day."
         },
         "time_format": {
          "type": "string",
          "default": "daily",
          "example": "monthly",
          "description": "daily returns one row per day; any other value, such as monthly, returns one row per calendar month."
         },
         "status": {
          "type": "string",
          "default": "good",
          "example": "all",
          "description": "good counts messages accepted by the route, bad counts messages that failed, any other value (such as all) counts both."
         },
         "accounts[]": {
          "type": "integer",
          "example": 1855,
          "description": "One of your SMPP or IoT account IDs; repeat the field for several. Omit to include all of them."
         },
         "connections[]": {
          "type": "integer",
          "example": 1160,
          "description": "`i_connection` of a purchased SMS route; repeat the field for several. Omit to include all your purchased SMS routes."
         },
         "destination_descriptions[]": {
          "type": "string",
          "example": "OMAN-%",
          "description": "A destination as the country and the description joined by a single hyphen with no spaces around it, for example OMAN-Mobile - Omantel; repeat for several. % works as a wildcard, so OMAN-% covers the whole country. Omit for all destinations."
         },
         "download": {
          "type": "integer",
          "enum": [
           0,
           1
          ],
          "default": 0,
          "example": 0,
          "description": "1 returns a CSV attachment (sms_summary.csv) with one row per period and sender ID instead of JSON."
         }
        }
       }
      }
     }
    }
   }
  },
  "/buyers/messages": {
   "post": {
    "tags": [
     "Messages"
    ],
    "summary": "List buyer messages",
    "description": "Returns one page of your messages with sellers, newest first: the inbox (messages from sellers) or the outbox (messages you sent). Pass `id` to read a single message instead; reading an unread inbox message marks it as read. Messages about an anonymous route or DID name the sender as \"Anonymous Owner of Route <name>\" or \"Anonymous Owner of DID Number <number>\", leave out the seller ID and logo, and carry `anonymous: 1`. Free.\n\nParameters work in the query string or the form body. Outbox rows carry `to_login` instead of `from_login`. `ts` is formatted m/d/y h:mmAM; the same time is also returned as YYYY-MM-DD HH:MM:SS (see the example). Only `inbox` and `outbox` are accepted for `show`; any other value returns an error that is not JSON.",
    "operationId": "members-messaging-list-incoming-messages",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/messages/#list-buyer-messages"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "messages": [
            {
             "i_message": "4821",
             "from_type": "vendor",
             "to_type": "customer",
             "i_from": "87",
             "i_to": "1042",
             "ts": "03/14/26 9:42AM",
             "status": "unread",
             "reply_to": "4807",
             "message_type": "message",
             "subject": "Low ASR to UK mobile",
             "message": "We rerouted the traffic; please test again.",
             "additional_data": null,
             "i_did": "0",
             "i_connection": "0",
             "thread_id": null,
             "from_login": "NorthwindVoice",
             "mysql_ts": "2026-03-14 09:42:17",
             "seller_logo": "https://apiv2.telecomsxchange.com/profilepics/vendor_87.png"
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "show": {
          "type": "string",
          "enum": [
           "inbox",
           "outbox"
          ],
          "default": "inbox",
          "example": "inbox",
          "description": "Which folder to list."
         },
         "pager": {
          "type": "integer",
          "default": 30,
          "example": 30,
          "description": "Page size. Values below 1 fall back to 30."
         },
         "off": {
          "type": "integer",
          "default": 0,
          "example": 0,
          "description": "Number of messages to skip, for paging."
         },
         "id": {
          "type": "integer",
          "example": 4821,
          "description": "Return only this message, one you sent or received, as `message` instead of a `messages` list. Marks it read if it is an unread message to you."
         }
        }
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Message not found",
      "when": "`id` is not a message you sent or received"
     }
    ]
   }
  },
  "/buyers/message/reply/{id}": {
   "post": {
    "tags": [
     "Messages"
    ],
    "summary": "Reply to a seller message",
    "description": "Replies to a message in your inbox. The reply keeps the original subject, is linked to it through `reply_to`, stays anonymous when the original was about an anonymous route or DID, and the seller is notified by email. Returns the new message's ID. Free.\n\nSend `message` in the form body; it is ignored in the query string. If `message` is empty, nothing is sent and the response returns the original message with status \"success\"; check for `i_message` in the response to confirm a reply was sent. If `id` is not a message addressed to you, the response is empty.",
    "operationId": "members-messaging-reply-to-seller-message",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "ID (`i_message`) of the inbox message you are replying to, from List buyer messages.",
      "schema": {
       "type": "integer",
       "example": 4821
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/messages/#reply-to-a-seller-message"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Replied",
           "i_message": 4830
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "message": {
          "type": "string",
          "example": "Thanks, test calls now complete normally.",
          "description": "Reply text."
         }
        },
        "required": [
         "message"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "error sending customer email",
      "when": "the notification email cannot be sent; the reply is already saved (plain-text response)"
     }
    ]
   }
  },
  "/buyers/message/send": {
   "post": {
    "tags": [
     "Messages"
    ],
    "summary": "Send a message to a seller",
    "description": "Starts a conversation with a seller. Address the seller by `id`, or by `i_connection` or `i_did` to write to the owner of a route or number; for anonymous routes and DIDs the seller's identity stays hidden. The seller gets the message in their inbox and by email. Returns the new message's ID. Free.\n\nSend parameters in the form body; they are ignored in the query string. When you write through `i_connection` or `i_did` to an anonymous seller, the confirmation names the recipient as \"Anonymous Owner of Route <name>\" or \"Anonymous Owner of DID Number <number>\".",
    "operationId": "members-messaging-compose-new-message-to-seller",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/messages/#send-a-message-to-a-seller"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Message 4835 sent successfully to seller NorthwindVoice",
           "i_message": 4835
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "id": {
          "type": "integer",
          "example": 87,
          "description": "Seller ID (`i_vendor`), from List sellers. Required unless `i_connection` or `i_did` is given."
         },
         "i_connection": {
          "type": "integer",
          "example": 5531,
          "description": "Route ID: writes to the owner of this route. Used only when `id` is not given."
         },
         "i_did": {
          "type": "integer",
          "example": 22014,
          "description": "DID ID: writes to the owner of this number. Used only when `id` is not given; `i_connection` takes precedence if both are sent."
         },
         "subject": {
          "type": "string",
          "example": "Low ASR to UK mobile",
          "description": "Message subject."
         },
         "message": {
          "type": "string",
          "example": "ASR on your UK Mobile CLI route dropped to 18% since 09:00 UTC. Can you check?",
          "description": "Message text."
         }
        },
        "required": [
         "subject",
         "message"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Seller id missing (id=123)",
      "when": "no `id` is sent and no seller matches `i_connection` or `i_did`"
     },
     {
      "message": "Expecting id parameter",
      "when": "`subject` or `message` is empty"
     },
     {
      "message": "error sending customer email",
      "when": "the notification email cannot be sent; the message is already saved (plain-text response)"
     }
    ]
   }
  },
  "/sellers/messages": {
   "post": {
    "tags": [
     "Messages"
    ],
    "summary": "List seller messages",
    "description": "Returns one page of your messages with buyers, newest first: the inbox (messages from buyers) or the outbox (messages you sent). Pass `id` to read a single message; reading an unread inbox message marks it as read. Free.\n\nParameters work in the query string or the form body. A non-zero `i_connection` or `i_did` means the buyer wrote to you about that route or number. Outbox rows carry `to_login` instead of `from_login`. Only `inbox` and `outbox` are accepted for `show`; any other value returns an error that is not JSON. To answer a message, use Reply to a buyer message.",
    "operationId": "members-messaging-sellers-list-incoming-messages",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/messages/#list-seller-messages"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "messages": [
            {
             "i_message": "4835",
             "from_type": "customer",
             "to_type": "vendor",
             "i_from": "1042",
             "i_to": "87",
             "ts": "03/14/26 10:05AM",
             "status": "unread",
             "reply_to": null,
             "message_type": "message",
             "subject": "Low ASR to UK mobile",
             "message": "ASR on your UK Mobile CLI route dropped to 18% since 09:00 UTC. Can you check?",
             "additional_data": null,
             "i_did": "0",
             "i_connection": "5531",
             "thread_id": null,
             "from_login": "AcmeTelecom",
             "buyer_logo": "https://apiv2.telecomsxchange.com/profilepics/customer_1042.png"
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "show": {
          "type": "string",
          "enum": [
           "inbox",
           "outbox"
          ],
          "default": "inbox",
          "example": "inbox",
          "description": "Which folder to list."
         },
         "pager": {
          "type": "integer",
          "default": 30,
          "example": 30,
          "description": "Page size. Values below 1 fall back to 30."
         },
         "off": {
          "type": "integer",
          "default": 0,
          "example": 0,
          "description": "Number of messages to skip, for paging."
         },
         "id": {
          "type": "integer",
          "example": 4835,
          "description": "Return only this message, one you sent or received, as `message` instead of a list. Marks it read if it is an unread message to you."
         }
        }
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Message not found",
      "when": "`id` is not a message you sent or received"
     }
    ]
   }
  },
  "/sellers/buyers/list": {
   "post": {
    "tags": [
     "Messages"
    ],
    "summary": "List my buyers",
    "description": "Returns the buyers who use your routes (default) or rent your DIDs, 20 per page, each with the routes or numbers they use from you. Use the buyer IDs with Send a message to a buyer. Free.\n\nEach `purchases` item starts with a space followed by \"Route:\" or \"DID:\".",
    "operationId": "members-messaging-list-my-buyers",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/messages/#list-my-buyers"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "buyers": [
            {
             "i_customer": "1042",
             "login": "AcmeTelecom",
             "purchases": [
              " Route:UK Mobile CLI",
              " Route:Premium A2P"
             ]
            },
            {
             "i_customer": "1188",
             "login": "GlobexComms",
             "purchases": [
              " Route:UK Mobile CLI"
             ]
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "show_type": {
          "type": "string",
          "enum": [
           "routes",
           "dids"
          ],
          "default": "routes",
          "example": "routes",
          "description": "`routes` lists buyers of your routes; `dids` lists buyers renting your numbers."
         },
         "login_or_email": {
          "type": "string",
          "example": "acme",
          "description": "Only return buyers whose login or email contains this text."
         },
         "off": {
          "type": "integer",
          "default": 0,
          "example": 0,
          "description": "Number of buyers to skip. Pages hold 20 buyers."
         }
        }
       }
      }
     }
    }
   }
  },
  "/sellers/buyers/message": {
   "post": {
    "tags": [
     "Messages"
    ],
    "summary": "Message my buyers",
    "description": "Sends the same message to each buyer on one page of List my buyers: up to 20 buyers, chosen with the same `show_type`, `login_or_email` and `off` filters. Each buyer gets it in their inbox and by email. Free.\n\nEach call reaches at most 20 buyers; page through with `off` to message all of them. On each page, buyers after the first see the subject prefixed with \"TCXC Message: \" in their inbox.",
    "operationId": "members-messaging-blast-message-to-buyers",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/messages/#message-my-buyers"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Messages have been sent successfully to buyers list "
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "subject": {
          "type": "string",
          "example": "New coverage: Sudan DIDs",
          "description": "Message subject."
         },
         "message": {
          "type": "string",
          "example": "Sudanese mobile DIDs are now available for immediate activation.",
          "description": "Message text."
         },
         "show_type": {
          "type": "string",
          "enum": [
           "routes",
           "dids"
          ],
          "default": "routes",
          "example": "routes",
          "description": "Message buyers of your routes or renters of your DIDs."
         },
         "login_or_email": {
          "type": "string",
          "description": "Only message buyers whose login or email contains this text."
         },
         "off": {
          "type": "integer",
          "default": 0,
          "example": 0,
          "description": "Number of buyers to skip. Each call messages at most 20 buyers; repeat with off=20, 40,... to reach everyone."
         }
        },
        "required": [
         "subject",
         "message"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Empty subject or message are not allowed",
      "when": "`subject` or `message` is missing or empty"
     },
     {
      "message": "error sending customer email",
      "when": "a notification email cannot be sent; buyers earlier in the page have already been messaged (plain-text response)"
     }
    ]
   }
  },
  "/sellers/message/send": {
   "post": {
    "tags": [
     "Messages"
    ],
    "summary": "Send a message to a buyer",
    "description": "Sends a new message from you as a seller to one of your buyers, identified by buyer ID from List my buyers. The buyer gets it in their inbox and by email. Returns the new message's ID. Free.\n\nSend parameters in the form body; they are ignored in the query string. Send both `subject` and `message`: if either is empty, the response is empty and nothing is sent.",
    "operationId": "sellers-message-send",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/messages/#send-a-message-to-a-buyer"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Message 4840 sent successfully to buyer AcmeTelecom",
           "i_message": 4840
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "id": {
          "type": "integer",
          "example": 1042,
          "description": "Buyer ID (`i_customer`)."
         },
         "subject": {
          "type": "string",
          "example": "Maintenance window",
          "description": "Message subject."
         },
         "message": {
          "type": "string",
          "example": "Our UK Mobile CLI route will be in maintenance on 20 March, 02:00-03:00 UTC.",
          "description": "Message text."
         }
        },
        "required": [
         "id",
         "subject",
         "message"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Buyer id missing (id=123)",
      "when": "`id` is missing or 0"
     },
     {
      "message": "error sending customer email",
      "when": "the notification email cannot be sent; the message is already saved (plain-text response)"
     }
    ]
   }
  },
  "/sellers/message/reply/{id}": {
   "post": {
    "tags": [
     "Messages"
    ],
    "summary": "Reply to a buyer message",
    "description": "Replies to a message in your seller inbox. The reply keeps the original subject, is linked through `reply_to`, stays anonymous when the buyer wrote about an anonymous route or DID, and the buyer is notified by email. Returns the new message's ID. Free.\n\nSend `message` in the form body; it is ignored in the query string. If `message` is empty, nothing is sent and the response returns the original message with status \"success\"; check for `i_message` to confirm a reply was sent.",
    "operationId": "sellers-message-reply",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "ID (`i_message`) of the inbox message you are replying to, from List seller messages.",
      "schema": {
       "type": "integer",
       "example": 4835
      }
     }
    ],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/messages/#reply-to-a-buyer-message"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "message": "Replied",
           "i_message": 4841
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "message": {
          "type": "string",
          "example": "We have rerouted UK mobile traffic; ASR is back above 45%.",
          "description": "Reply text."
         }
        },
        "required": [
         "message"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "Sorry",
      "when": "`id` is not a message addressed to you (plain-text response)"
     },
     {
      "message": "error sending customer email",
      "when": "the notification email cannot be sent; the reply is already saved (plain-text response)"
     }
    ]
   }
  },
  "/sellers/list": {
   "post": {
    "tags": [
     "Tools"
    ],
    "summary": "List seller routes",
    "description": "Lists the routes on the exchange that you can see: every public route plus the private routes a seller has opened to you, with the seller's login and `i_vendor`, the route's `i_connection` and `i_tariff`, and its type label. Use `i_connection` to buy a route and `i_tariff` to download its rate deck. Free.\n\nSend `pager` and `off` in the form body; they are ignored in the query string. `pager` is an end position: off=30 with pager=30 returns no routes.",
    "operationId": "tools-list-sellers-ids",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/tools/#list-seller-routes"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "example": {
          "summary": "Example",
          "value": {
           "status": "success",
           "routes": [
            {
             "seller_name": "NorthStarTel",
             "i_vendor": "112",
             "route_name": "UAE Premium",
             "i_connection": "128",
             "i_tariff": "129",
             "private": "0",
             "i_private_connection": null,
             "type": "NA"
            },
            {
             "seller_name": "NorthStarTel",
             "i_vendor": "112",
             "route_name": "Egypt CLI",
             "i_connection": "133",
             "i_tariff": "134",
             "private": "1",
             "i_private_connection": "57",
             "type": "NA"
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": false,
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "off": {
          "type": "integer",
          "default": 0,
          "example": 0,
          "description": "Position of the first route to return, counting from 0."
         },
         "pager": {
          "type": "integer",
          "default": 30,
          "example": 10000,
          "description": "Position at which to stop, exclusive. This is an end position, not a page size: to read routes 30 to 59, send off=30 and pager=60. Send a large value such as 10000 to get every route."
         }
        }
       }
      }
     }
    }
   }
  },
  "/predict": {
   "post": {
    "tags": [
     "Message classification (AI)"
    ],
    "summary": "Check message safety",
    "description": "Classifies one SMS text as `ham`, `spam` or `phishing`. The text is normalised first, so full-width, look-alike and leetspeak disguises (for example `paypa1`) are classified as the text they imitate. Returns the label, `probability` (the model's confidence in that label, 0 to 1), `processing_time` (server-side seconds) and `model_info`. Free, and needs no credentials.",
    "operationId": "tcxc-ai-check-message-safety",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/ai/#check-message-safety"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "phishing": {
          "summary": "Phishing",
          "value": {
           "label": "phishing",
           "probability": 0.9997455477714539,
           "processing_time": 0.1476691383868456,
           "model_info": {
            "name": "OTS_mBERT",
            "version": "2.9",
            "architecture": "bert-base-multilingual-cased",
            "author": "TelecomsXChange (TCXC)",
            "last_training": "2024-03-20"
           }
          }
         },
         "ham": {
          "summary": "Ham",
          "value": {
           "label": "ham",
           "probability": 0.9994045495986938,
           "processing_time": 0.155810184776783,
           "model_info": {
            "name": "OTS_mBERT",
            "version": "2.9",
            "architecture": "bert-base-multilingual-cased",
            "author": "TelecomsXChange (TCXC)",
            "last_training": "2024-03-20"
           }
          }
         },
         "empty-text": {
          "summary": "Empty text",
          "value": {
           "detail": [
            {
             "type": "string_too_short",
             "loc": [
              "body",
              "text"
             ],
             "msg": "String should have at least 1 character",
             "input": "",
             "ctx": {
              "min_length": 1
             }
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "text": {
          "type": "string",
          "example": "Your account has been suspended. Verify now at http://secure-login-check.example",
          "description": "The message to classify, 1 to 512 characters."
         },
         "model": {
          "type": "string",
          "enum": [
           "ots-mbert"
          ],
          "example": "ots-mbert",
          "description": "Model to run. Use `ots-mbert`."
         }
        },
        "required": [
         "text",
         "model"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "String should have at least 1 character",
      "when": "`text` is empty (HTTP 422, in `detail[].msg`)."
     }
    ],
    "servers": [
     {
      "url": "https://ots.telecomsxchange.com"
     }
    ],
    "security": []
   }
  },
  "/health": {
   "get": {
    "tags": [
     "Message classification (AI)"
    ],
    "summary": "Threat classifier health",
    "description": "Returns the threat classifier's status, API version and loaded model version. Suitable as a load-balancer health check. Free, and needs no credentials.",
    "operationId": "tcxc-ai-threat-classifier-health",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/ai/#threat-classifier-health"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "healthy": {
          "summary": "Healthy",
          "value": {
           "status": "healthy",
           "api_version": "2.11.0",
           "version": "2.11.0",
           "model": {
            "name": "OTS_mBERT",
            "version": "2.9",
            "architecture": "bert-base-multilingual-cased"
           },
           "models_loaded": {
            "mbert_multilingual": true
           },
           "timestamp": "2026-10-15T20:22:02.957002+00:00"
          }
         }
        }
       }
      }
     }
    },
    "servers": [
     {
      "url": "https://ots.telecomsxchange.com"
     }
    ],
    "security": []
   }
  },
  "/cc/v1/classify": {
   "post": {
    "tags": [
     "Message classification (AI)"
    ],
    "summary": "Classify message category",
    "description": "Sorts one SMS text into a category: `verification` (one-time codes, 2FA and login codes, verification links, \"confirm it's you\" prompts), `marketing` (promotions, sales, loyalty pushes, launches, re-engagement, referral offers) or `transactional` (order, delivery, payment, booking, balance, reminder and account-event notifications). Returns the `label`, its `confidence`, all three `scores` (they sum to 1) and `ms`, the server-side model time in milliseconds. Free, and needs no credentials.",
    "operationId": "tcxc-ai-classify-message-category",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/ai/#classify-message-category"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "verification": {
          "summary": "Verification",
          "value": {
           "label": "verification",
           "confidence": 0.9662,
           "scores": {
            "verification": 0.9662,
            "marketing": 0.0162,
            "transactional": 0.0176
           },
           "ms": 16.82
          }
         },
         "verification-indonesian": {
          "summary": "Verification (Indonesian)",
          "value": {
           "label": "verification",
           "confidence": 0.9649,
           "scores": {
            "verification": 0.9649,
            "marketing": 0.0162,
            "transactional": 0.0189
           },
           "ms": 20.97
          }
         },
         "empty-text": {
          "summary": "Empty text",
          "value": {
           "detail": [
            {
             "type": "string_too_short",
             "loc": [
              "body",
              "text"
             ],
             "msg": "String should have at least 1 character",
             "input": "",
             "ctx": {
              "min_length": 1
             }
            }
           ]
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "text": {
          "type": "string",
          "example": "Your verification code is 482913. It expires in 10 minutes.",
          "description": "The message to classify, 1 to 2,000 characters."
         }
        },
        "required": [
         "text"
        ]
       }
      }
     }
    },
    "x-errors": [
     {
      "message": "String should have at least 1 character",
      "when": "`text` is empty (HTTP 422, in `detail[].msg`)."
     }
    ],
    "servers": [
     {
      "url": "https://ots.telecomsxchange.com"
     }
    ],
    "security": []
   }
  },
  "/cc/v1/classify/batch": {
   "post": {
    "tags": [
     "Message classification (AI)"
    ],
    "summary": "Classify message categories in bulk",
    "description": "Classifies up to 256 SMS texts in one request. `results` is in the same order as `texts`; each result has the same fields as the single-message call except that its `ms` is null, and the top-level `ms` is the model time for the whole batch. `count` is the number of messages classified. Free, and needs no credentials.",
    "operationId": "tcxc-ai-classify-message-category-batch",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/ai/#classify-message-categories-in-bulk"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "two-messages": {
          "summary": "Two messages",
          "value": {
           "results": [
            {
             "label": "marketing",
             "confidence": 0.9383,
             "scores": {
              "verification": 0.0276,
              "marketing": 0.9383,
              "transactional": 0.0341
             },
             "ms": null
            },
            {
             "label": "transactional",
             "confidence": 0.9722,
             "scores": {
              "verification": 0.0146,
              "marketing": 0.0132,
              "transactional": 0.9722
             },
             "ms": null
            }
           ],
           "count": 2,
           "ms": 19.15
          }
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "texts": {
          "type": "array",
          "example": [
           "50% off everything this weekend",
           "Your parcel has been delivered"
          ],
          "description": "Messages to classify: up to 256 strings, each 1 to 2,000 characters."
         }
        },
        "required": [
         "texts"
        ]
       }
      }
     }
    },
    "servers": [
     {
      "url": "https://ots.telecomsxchange.com"
     }
    ],
    "security": []
   }
  },
  "/cc/v1/labels": {
   "get": {
    "tags": [
     "Message classification (AI)"
    ],
    "summary": "List categories",
    "description": "Returns the three labels the category classifier can return and the definition of each. Free, and needs no credentials.",
    "operationId": "tcxc-ai-list-categories",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/ai/#list-categories"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "labels": {
          "summary": "Labels",
          "value": {
           "labels": [
            "verification",
            "marketing",
            "transactional"
           ],
           "definitions": {
            "verification": "One-time codes, 2FA/login codes, verification links, 'confirm it's you' prompts.",
            "marketing": "Promotions, offers, sales, loyalty pushes, product launches, re-engagement, surveys-for-rewards.",
            "transactional": "Order, delivery, payment, booking, balance, reminder and account-event notifications triggered by something the user did or holds."
           }
          }
         }
        }
       }
      }
     }
    },
    "servers": [
     {
      "url": "https://ots.telecomsxchange.com"
     }
    ],
    "security": []
   }
  },
  "/cc/health": {
   "get": {
    "tags": [
     "Message classification (AI)"
    ],
    "summary": "Category classifier health",
    "description": "Returns the category classifier's status, service and model versions, supported languages and labels, uptime, and whether an API key is required. Suitable as a load-balancer health check. Free, and needs no credentials.",
    "operationId": "tcxc-ai-category-classifier-health",
    "parameters": [],
    "externalDocs": {
     "url": "https://help.telecomsxchange.com/reference/ai/#category-classifier-health"
    },
    "responses": {
     "200": {
      "description": "JSON reply; check `status`.",
      "content": {
       "application/json": {
        "examples": {
         "healthy": {
          "summary": "Healthy",
          "value": {
           "status": "ok",
           "service": "ots-cc",
           "name": "Open Text Shield Category Classifier",
           "version": "0.2.2",
           "model_name": "OTS Category Classifier",
           "model_version": "v8",
           "model_base": "mmBERT small",
           "languages": [
            "en",
            "es",
            "id",
            "\u2026 6 more items"
           ],
           "model": "model_int8.onnx",
           "base": "jhu-clsp/mmBERT-small",
           "labels": [
            "verification",
            "marketing",
            "transactional"
           ],
           "api_key_required": false,
           "uptime_s": 221088.3
          }
         }
        }
       }
      }
     }
    },
    "servers": [
     {
      "url": "https://ots.telecomsxchange.com"
     }
    ],
    "security": []
   }
  }
 }
}