User Tools

Site Tools


api:destination:list

API : Destination List

Introduction

This request will return a list of destinations.

Destinations and their prices are common for all customers, but a reseller may create one or more SIP or MVNO rateplan products where specific destinations are overriden. The prices presented in this list will include the overrides, if a product which may contain overrides is specified.

Request

URL https://api.telecomx.dk/destination
Method GET
Access level VIEWER, MANAGER, OWNER, RESELLER, RESELLER_ADMIN, ADMIN.
Query prefix [optional] Prefix or whole phone number that the destinations must be valid for. Must always start with +<country-code>, (e.g. +4531). Ignored if not valid.
country [optional] Country that the destinations must belong to, ISO3166 2-char country codes. Ignored if not valid.
type [optional] Type of destination:
FIXED - normal landline and IP numbers.
MOBILE - mobile phones.
SPECIAL - special service numbers and other high-rated numbers such as satellite phones.
region [optional] Voice region the destinations belongs to:
HOMELAND - Denmark
EU_NORDIC - EU and nordic countries
REST_OF_EUROPE - rest of Europe + Thailand
WORLD1 - USA, Canada, Puerto Rico
WORLD2 - World region 2
WORLD3 - World region 3
roamingRegion [optional] Id of a roaming region; only destinations linked to that roaming region are returned. Must be sent together with provider. Ignored if not a valid id.
provider [optional] The network provider the roaming region applies to: TELENOR or TDC. Only used together with roamingRegion.
offset [optional] Index of the first destination to return, default 0.
limit [optional] The number of destinations to return, default 100, min 1, max 1000.
full [optional] If true, complete destination objects will be returned instead of the condensed versions.
product [optional] A product which may contain overrides. If so they are merged into the result.
format [optional] Can be either 'csv' or 'json'. Defaults to json. When 'csv', limit is ignored and all matching destinations are returned as a CSV file (see CSV response below).

Query examples

https://api.telecomx.dk/destination
https://api.telecomx.dk/destination?prefix=%2B462
https://api.telecomx.dk/destination?country=DE&type=MOBILE
https://api.telecomx.dk/destination?region=EU_NORDIC
https://api.telecomx.dk/destination?country=US&type=MOBILE&offset=50&limit=100&full=true
https://api.telecomx.dk/destination?country=US&type=MOBILE&offset=50&limit=100&full=true&format=csv

Response

JSON object
offset Index of the first destination returned.
limit Number of destinations to return. Note that the actual number of destinations returned may be lower.
total Number of destinations that can be returned when offset and limit is not considered. This is to be used for paging through the data.
destinations Array of destinations, see definition below.
Destination object (JSON)
_id String ISO3166 2-char uppercase country code.
prefix String Prefix for the country, e.g. +45.
image ObjectId Image Id
names Array List of names, used for localization
names[].language String ISO 639-1 language code: 'da' or 'en'
names[].text String The localization of the name.
region String Voice region the country belongs to: HOMELAND, EU_NORDIC, REST_OF_EUROPE, WORLD1, WORLD2, WORLD3
roamingRegion Object Roaming region the country belongs to, depending on mobile network. The key is the provider ID, and the value is the region. Keys can be “telenor”, or “tdc”
roamingRegion.<provider> ObjectId ID of roaming region
fixed Object prices for fixed destinations
fixed.costFee Number Connection fee cost (RESELLER_ADMIN/ADMIN only)
fixed.costRate Number Pr. minute rate cost (RESELLER_ADMIN/ADMIN only)
fixed.wholesaleFee Number Connection fee for reseller (RESELLER/RESELLER_ADMIN/ADMIN only)
fixed.customerFee Number Connection fee for customer
fixed.wholesaleRate Number Pr. minute rate for reseller (RESELLER/RESELLER_ADMIN/ADMIN only)
fixed.customerRate Number Pr. minute rate for customer
mobile Object prices for mobile destinations
mobile.costFee Number Connection fee cost (RESELLER_ADMIN/ADMIN only)
mobile.costRate Number Pr. minute rate cost (RESELLER_ADMIN/ADMIN only)
mobile.wholesaleFee Number Connection fee for reseller (RESELLER/RESELLER_ADMIN/ADMIN only)
mobile.customerFee Number Connection fee for customer
mobile.wholesaleRate Number Pr. minute rate for reseller (RESELLER/RESELLER_ADMIN/ADMIN only)
mobile.customerRate Number Pr. minute rate for customer
special Object prices for special destinations
special.costFee Number Connection fee cost (RESELLER_ADMIN/ADMIN only)
special.costRate Number Pr. minute rate cost (RESELLER_ADMIN/ADMIN only)
special.wholesaleFee Number Connection fee for reseller (RESELLER/RESELLER_ADMIN/ADMIN only)
special.customerFee Number Connection fee for customer
special.wholesaleRate Number Pr. minute rate for reseller (RESELLER/RESELLER_ADMIN/ADMIN only)
special.customerRate Number Pr. minute rate for customer
Destination object if full=true (JSON)
_id String ISO3166 2-char uppercase country code.
prefix String Prefix for the country, e.g. +45.
image ObjectId Image Id
names Array List of names, used for localization
names[].language String ISO 639-1 language code: 'da' or 'en'
names[].text String The localization of the name.
region String Voice region the country belongs to: HOMELAND, EU_NORDIC, REST_OF_EUROPE, WORLD1, WORLD2, WORLD3
roamingRegion Object Roaming region the country belongs to, depending on mobile network. The key is the provider ID, and the value is the region. Keys can be “telenor”, or “tdc”
roamingRegion.<provider> ObjectId ID of roaming region
breakouts Array List of breakouts within a country, with prefix, type, fee-cost, fee-rate
breakouts[].prefix Array Array of strings, which is the prefixes, that this destination/type covers
breakouts[].type String FIXED, MOBILE, SPECIAL
breakouts[].cost Object Cost prices for each peer (RESELLER_ADMIN/ADMIN only).
breakouts[].cost.<PeerId> Object Cost prices for one peer, keyed by peer id: TELENOR, SUPERTEL or TDC.
breakouts[].cost.<PeerId>.fee Number Connection fee cost.
breakouts[].cost.<PeerId>.rate Number Pr. minute cost.
breakouts[].cost.<PeerId>.rates Array List of cost rates for the prefixes in this breakout.
fixed Object prices for fixed destinations
fixed.wholesaleFee Number Connection fee for reseller (RESELLER/RESELLER_ADMIN/ADMIN only)
fixed.customerFee Number Connection fee for customer
fixed.wholesaleRate Number Pr. minute rate for reseller (RESELLER/RESELLER_ADMIN/ADMIN only)
fixed.customerRate Number Pr. minute rate for customer
mobile Object prices for mobile destinations
mobile.wholesaleFee Number Connection fee for reseller (RESELLER/RESELLER_ADMIN/ADMIN only)
mobile.customerFee Number Connection fee for customer
mobile.wholesaleRate Number Pr. minute rate for reseller (RESELLER/RESELLER_ADMIN/ADMIN only)
mobile.customerRate Number Pr. minute rate for customer
special Object prices for special destinations
special.wholesaleFee Number Connection fee for reseller (RESELLER/RESELLER_ADMIN/ADMIN only)
special.customerFee Number Connection fee for customer
special.wholesaleRate Number Pr. minute rate for reseller (RESELLER/RESELLER_ADMIN/ADMIN only)
special.customerRate Number Pr. minute rate for customer

Note that properties holding no value may be omitted from the object.

Response examples

Normal condensed

{
  "offset": 0,
  "limit": 50,
  "total": 235,
  "destinations": [
    {
      "_id": "DE",
      "prefix": "+49",
      "image": "650000000000000000000001",
      "names": [
        { "language": "da", "text": "Tyskland" },
        { "language": "en", "text": "Germany" }
      ],
      "region": "EU_NORDIC",
      "roamingRegion": {
        "tdc": "650000000000000000000002",
        "telenor": "650000000000000000000003"
      },
      "fixed": {
        "wholesaleFee": 0.1,
        "wholesaleRate": 0.15,
        "customerFee": 0.2,
        "customerRate": 0.25,
        "costFee": 0.02,
        "costRate": 0.0955
      },
      "mobile": {
        "wholesaleFee": 0.1,
        "wholesaleRate": 0.5,
        "customerFee": 0.2,
        "customerRate": 0.75,
        "costFee": 0.02,
        "costRate": 0.1795
      },
      "special": {
        "wholesaleFee": 0.2,
        "wholesaleRate": 0.5,
        "customerFee": 0.2,
        "customerRate": 0.6
      }
    }
  ]
}

Full

{
  "offset": 0,
  "limit": 50,
  "total": 235,
  "destinations": [
    {
      "_id": "DE",
      "prefix": "+49",
      "image": "650000000000000000000001",
      "names": [
        { "language": "da", "text": "Tyskland" },
        { "language": "en", "text": "Germany" }
      ],
      "region": "EU_NORDIC",
      "roamingRegion": {
        "tdc": "650000000000000000000002",
        "telenor": "650000000000000000000003"
      },
      "breakouts": [
        {
          "prefix": [ "+4915", "+49151", "+49152", "+49160", "+49170" ],
          "type": "MOBILE",
          "cost": {
            "TELENOR": { "fee": 0.02, "rate": 0.1795 },
            "TDC": { "fee": 0, "rate": 0.2931 },
            "SUPERTEL": { "fee": 0, "rate": 0.161, "rates": [ 0.1523, 0.161 ] }
          }
        },
        {
          "prefix": [ "+49", "+4930", "+4940" ],
          "type": "FIXED",
          "cost": {
            "TELENOR": { "fee": 0.02, "rate": 0.0955 },
            "TDC": { "fee": 0, "rate": 0.4266 },
            "SUPERTEL": { "fee": 0, "rate": 0.0647, "rates": [ 0.055, 0.0647 ] }
          }
        },
        {
          "prefix": [ "+49700", "+49701" ],
          "type": "SPECIAL",
          "cost": {
            "TELENOR": { "fee": 0.2, "rate": 0.1975 },
            "TDC": { "fee": 0, "rate": 0.18 }
          }
        }
      ],
      "fixed": {
        "wholesaleFee": 0.1,
        "wholesaleRate": 0.15,
        "customerFee": 0.2,
        "customerRate": 0.25
      },
      "mobile": {
        "wholesaleFee": 0.1,
        "wholesaleRate": 0.5,
        "customerFee": 0.2,
        "customerRate": 0.75
      },
      "special": {
        "wholesaleFee": 0.2,
        "wholesaleRate": 0.5,
        "customerFee": 0.2,
        "customerRate": 0.6
      }
    }
  ]
}

CSV

When format=csv the response is a semicolon separated file (text/csv) with a header line, one line pr. destination and decimal comma as the decimal separator. limit is ignored. The wholesale columns are empty for callers below RESELLER.

Column
CountryCode 2-Char ISO3166 country code.
Country Name of the country in English.
Prefix Prefix for the country, written as +“45”.
Region Voice region: HOMELAND, EU_NORDIC, REST_OF_EUROPE, WORLD1, WORLD2, WORLD3.
TDC region Name of the TDC roaming region, or n/a.
Telenor region Name of the Telenor roaming region, or n/a.
CustomerFixedFee / CustomerFixedRate Customer prices for fixed destinations.
CustomerMobileFee / CustomerMobileRate Customer prices for mobile destinations.
ResellerFixedFee / ResellerFixedRate Wholesale prices for fixed destinations.
ResellerMobileFee / ResellerMobileRate Wholesale prices for mobile destinations.

Errors

Error code Message Description
404 product Product not found or not a rateplan product
422 product The product parameter was sent with an empty value
422 roamingRegion The roamingRegion parameter was sent with an empty value
403 access_denied Insufficient access level
500 internal_error <Unspecified>
api/destination/list.txt · Last modified: by Mikkel Meerwaldt Jørgensen

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki