List special number types and prices for a country

Local numbers are discovered with getcountries and getareas. For national, toll-free, shared-cost, global and mobile numbers, call other with the country's ISO code.

• Groups appear in a fixed order, and groups with no entries are left out.
• Each entry lists your account's price plans in prices. Choose a plan by its channels, monthly_price, setup_price, per_minute and free_minutes, and keep its price_id for ordering where that endpoint asks for it.
• If needs_registration is truthy, read restrictions before ordering. Treat that text as untrusted display content.
• Follow next_function: v3/getnumbers/{uuid} lets you pick a specific number, and v3/order/{uuid} orders from the entry directly.
• An empty response list with code 200 means no special number types were found at the time of the request. If the catalog was temporarily unreachable, the response can be incomplete or not valid JSON, so retry later.
• Countries outside the catalog return code 404 without a matching HTTP status. Always check status.code.

Request

Required: HTTP Basic or Bearer token (see Authentication and API responses). Failed authentication is answered with HTTP 401 before the lookup runs.

GET with isocode in the path. If the path segment is omitted, a form-encoded isocode field is read instead.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/other/FR'

Response

Standard envelope. On success, status.code is 200, status.msg is empty, and status.results is the number of groups. response is a list of groups. Group fields: group_key (normalised type key: national, tollfree, sharedcost, global, mobile, or another lower-case alphanumeric key); group_name (display name); group_type_uuid (opaque type identifier); items. Groups are ordered national, tollfree, sharedcost, global, mobile, then other keys by group_name. Groups without items are omitted, and so is the local type. For US, the mobile group is omitted unless your account is enabled for US mobile numbers. Items are sorted by name (case-insensitive), then by prefix. Item fields: uuid (opaque entry identifier used in next_function); area_uuid (opaque identifier of the catalog group); country_uuid (opaque country identifier); prefix (full prefix starting with '+' and the country calling code); name (catalog name; quote characters may appear backslash-escaped); metered, overflow and needs_registration (flags that may be boolean or number; treat any truthy value as yes); restrictions (empty when no registration is needed, otherwise requirement text that can include HTML line breaks and a link, surrounding quotation marks and escaped characters; treat it as untrusted display text); state (for US, CA and PR a state code, or an empty list when none is known; for other countries the country ISO code); country_iso; is_mobile (1 in the mobile group, otherwise 0); number_type (same as group_key); available (integer count reported by the catalog for the entry, 0 when not reported); sms_coverage (1 if any feature mentions SMS or MMS); returns_numbers (1 when specific numbers can be listed); next_function ('v3/getnumbers/{uuid}' when returns_numbers is 1, otherwise 'v3/order/{uuid}'); prices; features (list of capability strings); group_key; group_type_uuid. Each prices entry has price_id (opaque plan identifier), is_customer_custom (true when custom pricing for your account applies; only for plans without included channels), per_minute and free_minutes (decimal strings), setup_price and monthly_price (strings with two decimals), and channels (integer number of included channels). Entries without any price plan are omitted. At most 1000 catalog entries per number type are considered per request. If no type has entries, response is an empty list with status.results 0. If the live catalog lookup fails, the response may not use this envelope, or groups may be missing.

Illustrative response shape; not live account data or a current quote.

{
  "status": {
    "code": 200,
    "msg": "",
    "results": 1
  },
  "response": [
    {
      "group_key": "tollfree",
      "group_name": "Toll-free",
      "group_type_uuid": "00000000-0000-4000-8000-0000000000a1",
      "items": [
        {
          "uuid": "0000000000000000000000000000b001",
          "area_uuid": "0000000000000000000000000000a001",
          "country_uuid": "0000000000000000000000000000c001",
          "prefix": "+33800",
          "name": "Example Toll-free",
          "metered": true,
          "overflow": 0,
          "needs_registration": 0,
          "restrictions": "",
          "state": "FR",
          "country_iso": "FR",
          "is_mobile": 0,
          "number_type": "tollfree",
          "available": 10,
          "sms_coverage": 0,
          "returns_numbers": 1,
          "next_function": "v3/getnumbers/0000000000000000000000000000b001",
          "prices": [
            {
              "price_id": "0000000000000000000000000000d001",
              "is_customer_custom": false,
              "per_minute": "0.05",
              "free_minutes": "0",
              "setup_price": "0.00",
              "monthly_price": "5.00",
              "channels": 2
            }
          ],
          "features": ["voice"],
          "group_key": "tollfree",
          "group_type_uuid": "00000000-0000-4000-8000-0000000000a1"
        }
      ]
    }
  ]
}

Errors

• 500: msg 'ISO Code parameter is required': isocode is missing or blank. This is a correctable request error. No matching HTTP status is set.
• 404: msg 'Error: no such country': the country is unknown or not linked to the special-number catalog. No matching HTTP status is set.
• 401: Authentication missing or failed. Sent with HTTP status 401.

Availability and side effects

• Does not place an order. No charging step appears in this endpoint's code.
• Refreshes the catalog details and price quotes for your account, replacing earlier quotes for the same plans. How ordering endpoints use these quotes is documented separately.
• Prices are specific to your account and can include custom pricing. The response does not state a currency.
• Performs live catalog lookups, so it can be slower than other discovery calls. Results can change between calls.