Managing Inbound Telephone Numbers

This describes the web services that manage purchase and deletion of inbound telephone numbers.

Note:
Several regions available for purchase include non-ASCII characters in the name. In such a case, unicode must be provided. Each unicode character must be represented by its four digit \u code, for example, \u00f6 represents the ö character. The Mönchengladbach region in Germany, for example, would be purchased by specifying the "M\u00f6nchengladbach" name.

 This is a low level API. For information on higher level APIs see the Web Services Language Wrappers
  • Tel Purchase

    This purchases an inbound telephone number in the region, state (optional) and country you choose - for example London, United Kingdom. Please note that this service results in an immediate and subsequent monthly cost.

    Authorisation

    This API uses basic authentication, using your cloud account username and API Access Key.

    Username : cloudID/username (e.g. 1-2-0/bob@example.com)
    Password : API Access key

    Request:

    Url:https://ws.aculabcloud.net/tel_purchase
    Methods:GET, POST

    ParameterValueDescription
    countrystringthe country where the number is located.
    statestring (required by some countries)the state where the number is located. Some countries require this to be specified.
    regionstringthe region where the number is located. This is a region name for geographic numbers or a number prefix for toll free or national numbers.
    regulation_addressstring (required by some countries)the name of registered regulation address that exists on the cloud account being used. Some countries require this to be specified. Regulation addresses can be registered here.
    quantityinteger (optional)the quantity of telephone numbers to purchase. Default is 1.
    based_onstring (optional)the name of an existing inbound service. If set then a new service will be created for each new number purchased, based on the specified service.
    allow_partialstring (optional)"True" or "False". Determines whether the request responds as having succeeded even if not all the requested telephone numbers are available. Defaults to "False".
    did_typestring (optional)the type of each new number purchased. One of "geographic", "national", "mobile" or "tollfree". Default is "geographic".
    allow_landlinestring (optional)"True" or "False". For toll free numbers only. "True" to allow calls from landline numbers. Otherwise calls from landlines are blocked. Defaults to "False".
    allow_cellularstring (optional)"True" or "False". For toll free numbers only. "True" to allow calls from cellular (mobile) phones. Otherwise calls from cell phones (mobiles) are blocked. Defaults to "False".
    allow_payphonestring (optional)"True" or "False". For toll free numbers only. "True" to allow calls from payphones. Otherwise calls from payphones are blocked. Defaults to "False".

    Note on toll free numbers: some countries and prefixes are not allowed to accept calls from certain types of phone - for example, cellular - and any user attempt to allow them will fail. At least one call type must be allowed for the purchase to go through. Toll free numbers incur an extra cost per minute. The amount is determined by the types of call that are allowed and the cost per minute for each call type.

    Returns:

    A JSON array containing the numbers purchased. A confirmation email is also sent to the account holder. Please note that the purchase may take several seconds to complete.

    Example:

    https://ws.aculabcloud.net/tel_purchase?country=Canada&state=Alberta&region=Calgary

    Response:

      [
        "15873155555"
      ]

    Example:

    https://ws.aculabcloud.net/tel_purchase?country=Spain&region=Bilbao&quantity=2

    Response:

      [
        "21887377377",
        "21846373876"
      ]

    Example:

    https://ws.aculabcloud.net/tel_purchase?country=Spain&region=901&quantity=3&did_type=tollfree&allow_landline=True&allow_payphone=True

    Response:

      [
        "90179198344",
        "90127397463",
        "90106358277"
      ]
  • Tel Purchase Development

    This mimics tel_purchase and is provided for development use. It does not result in a purchase so no cost is incurred.

    Authorisation

    This API uses basic authentication, using your cloud account username and API Access Key.

    Username : cloudID/username (e.g. 1-2-0/bob@example.com)
    Password : API Access key

    Request:

    Url:https://ws.aculabcloud.net/tel_purchase_development
    Methods:GET, POST

    This service accepts parameters and generates a response with the same specifications as the tel_purchase service.
    When called with valid parameters it always responds with:

    Response:

      [
        "1234567",
        "89012345"
      ]
    
  • Tel List Numbers

    This lists purchased telephone numbers. It can be filtered by location.

    Authorisation

    This API uses basic authentication, using your cloud account username and API Access Key.

    Username : cloudID/username (e.g. 1-2-0/bob@example.com)
    Password : API Access key

    Request:

    Url:https://ws.aculabcloud.net/tel_list_numbers
    Methods:GET, POST

    ParameterValueDescription
    countrystring (optional)the country where the number is located.
    statestring (optional for some countries)the state where the number is located.
    regionstring (optional)the region where the number is located. This is a region name for geographic numbers or a number prefix for toll free or national numbers.
    did_typestring (optional)the type of numbers to include in the list. One of "geographic", "national", "mobile" or "tollfree". Default is to list all types.

    Returns:

    A JSON object containing the existing telephone numbers with corresponding JSON objects containing their details.

    ParameterValueDescription
    countrystringthe country in which the number is located.
    statestringthe state in which the number is located. Only present for countries that have states.
    regionstringthe region in which the number is located.
    pricestringthe price per month for the number in US dollars.
    purchasedstringthe date on which the number was purchased in the format YYYY-MM-DD.
    did_typestringthe type of the number. One of "geographic", "national", "mobile" or "tollfree".

    Example:

    https://ws.aculabcloud.net/tel_list_numbers?country=United Kingdom

    Response:

      {
        "441908538007":
        {
      	  "country": "United Kingdom",
    	  "price": "3.00",
    	  "region": "Milton Keynes",
    	  "purchased": "2011-09-14",
    	  "did_type": "geographic"
        }
      }
  • Tel Delete Numbers

    This deletes one or more of the purchased telephone numbers.

    Authorisation

    This API uses basic authentication, using your cloud account username and API Access Key.

    Username : cloudID/username (e.g. 1-2-0/bob@example.com)
    Password : API Access key

    Request:

    Url:https://ws.aculabcloud.net/tel_delete_numbers
    Methods:GET, POST

    ParameterValueDescription
    numbersstringa comma-separated list of the telephone numbers to delete.

    Returns:

    A JSON object containing the result of the deletion. If not all the numbers were deleted then the reasons for the deletion failure are included in the response.

    ParameterValueDescription
    statusstringa status string containing "OK" if all the specified numbers were deleted, "PARTIAL" if at least one, but not all the numbers were deleted and "FAIL" if none of the numbers were deleted.
    numbersJSON objectcontains the numbers not deleted and the reason.
    descriptionstringa description of the reason for the non deletion.
    codestringa numeric error code from Error Codes.

    Example:

    https://ws.aculabcloud.net/tel_delete_numbers?numbers=441908538007,441908538008,441908538009

    Response:

      {
        "status": "OK"
      }

    Example:

    https://ws.aculabcloud.net/tel_delete_numbers?numbers=441908538010,441908538011,441908538009

    Response:

      {
        "status": "PARTIAL",
        "numbers":
        {
          "441908538009":
          {
            "description": "Telephone number 441908538009 does not belong to you",
            "code": "0300"
          }
        }
      } 
  • Tel Get Supported Countries

    This obtains a list of the countries for which telephone numbers can be purchased.

    Authorisation

    This API uses basic authentication, using your cloud account username and API Access Key.

    Username : cloudID/username (e.g. 1-2-0/bob@example.com)
    Password : API Access key

    Request:

    Url:https://ws.aculabcloud.net/tel_get_supported_countries
    Methods:GET, POST

    ParameterValueDescription
    did_typestring (optional)the type of numbers supported by a country for that country to be listed. One of "geographic", "national", "mobile" or "tollfree". Default is "geographic".

    Returns:

    A JSON array containing the names of the countries supported.

    Example:

    https://ws.aculabcloud.net/tel_get_supported_countries

    Response:

      [
        "Israel", "Georgia", "Mexico", "Lithuania", "United Kingdom", "Netherlands",
        "Croatia", "Greece", "Switzerland", "Dominican Republic", "Brazil", "Romania",
        "Czech Republic", "El Salvador", "Poland", "South Africa", "Luxembourg", "Sweden",
        "Germany", "Peru", "Puerto Rico", "Hungary", "Norway", "Spain", "Canada", "Italy",
        "Denmark", "Finland", "United States", "Slovenia", "Ireland", "Argentina",
        "Cyprus", "Australia", "France", "New Zealand", "Latvia", "Slovakia", "Chile",
        "Belgium", "Japan", "Bulgaria"
      ]

    Example:

    https://ws.aculabcloud.net/tel_get_supported_countries?did_type=national

    Response:

      [
        "Israel", "Georgia", "Portugal", "South Africa", "United Kingdom", "Netherlands",
        "Singapore", "Austria", "Luxembourg", "Sweden",     "Germany", "Norway", "Spain",
        "Finland", "Malta", "Slovenia", "Ireland", "Bahrain", "Estonia", "Hong Kong",
        "Panama", "France", "Belgium"
      ]
  • Tel Get Supported States

    This obtains a list of the states in a specified country for which telephone numbers can be purchased. Note that not all countries support states.

    Authorisation

    This API uses basic authentication, using your cloud account username and API Access Key.

    Username : cloudID/username (e.g. 1-2-0/bob@example.com)
    Password : API Access key

    Request:

    Url:https://ws.aculabcloud.net/tel_get_supported_states
    Methods:GET, POST

    ParameterValueDescription
    countrystringthe country in which to list the supported states.

    Returns:

    A JSON array containing the names of the states supported.

    Example:

    https://ws.aculabcloud.net/tel_get_supported_states?country=Canada

    Response:

      [
        "British Columbia", "Newfoundland And Labrador", "Saskatchewan", "Prince Edward Island",
        "Ontario", "Nova Scotia", "Quebec", "Alberta", "Manitoba", "New Brunswick"
      ]
  • Tel Get Supported Regions

    This obtains a list of the regions in a specified country for which telephone numbers can be purchased.

    Authorisation

    This API uses basic authentication, using your cloud account username and API Access Key.

    Username : cloudID/username (e.g. 1-2-0/bob@example.com)
    Password : API Access key

    Request:

    Url:https://ws.aculabcloud.net/tel_get_supported_regions
    Methods:GET, POST

    ParameterValueDescription
    countrystringthe country in which to list the supported regions.
    statestring (optional for some countries)the state in which to list the supported regions.
    did_typestring (optional)the type of numbers supported by a region for that region to be listed. One of "geographic", "national", "mobile" or "tollfree". Default is "geographic".

    Returns:

    A JSON array containing the names or numbers of the regions supported. For "geographic" types, the region names are returned in the array. For "national" and "tollfree" types, the supported number prefixes are returned.

    Example:

    https://ws.aculabcloud.net/tel_get_supported_regions?country=Canada&state=Manitoba

    Response:

      [
        "Oakbank", "Winnipeg"
      ] 

    Example:

    https://ws.aculabcloud.net/tel_get_supported_regions?country=Canada&did_type=tollfree

    Response:

      [
        "855", "888", "866", "877"
      ] 
  • Tel List Regulation Addresses

    This lists any regulation addresses that have been registered on a cloud account. Some countries require an address to be specified when purchasing a telephone number. Regulation addresses can be registered here.

    Authorisation

    This API uses basic authentication, using your cloud account username and API Access Key.

    Username : cloudID/username (e.g. 1-2-0/bob@example.com)
    Password : API Access key

    Request:

    Url:https://ws.aculabcloud.net/tel_list_regulation_addresses
    Methods:GET, POST

    Returns:

    A JSON object containing the address names. For each address a JSON object contains the location of the address.

    Example:

    https://ws.aculabcloud.net/tel_list_regulation_addresses

    Response:

      {
        "My french place":
        {
          "country": "France",
          "region": "Avignon"
        }
      }