api:destination:list
Table of Contents
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