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.

Note

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

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

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.

Request


URL	: https://ws-[cloudID].aculabcloud.net/tel_purchase
Methods	: GET, POST

Parameter	Value	Description
country	string	the country where the number is located.
state	string (required by some countries)	the state where the number is located. Some countries require this to be specified.
region	string	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.
regulation_address	string (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.
quantity	integer (optional)	the quantity of telephone numbers to purchase. Default is 1.
based_on	string (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_partial	string (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_type	string (optional)	the type of each new number purchased. One of "geographic", "national", "mobile" or "tollfree". Default is "geographic".
allow_landline	string (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_cellular	string (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_payphone	string (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

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.

Response

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

Request

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

Response

  [
    "15873155555"
  ]

Example 1

Request

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

Response

  [
    "21887377377",
    "21846373876"
  ]

Example 2

Request

https://ws-[cloudID].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.

Request


URL	: https://ws-[cloudID].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.

Response

Tel List Numbers

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

Request


URL	: https://ws-[cloudID].aculabcloud.net/tel_list_numbers
Methods	: GET, POST

Parameter	Value	Description
country	string (optional)	the country where the number is located.
state	string (optional for some countries)	the state where the number is located.
region	string (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_type	string (optional)	the type of numbers to include in the list. One of "geographic", "national", "mobile" or "tollfree". Default is to list all types.

Response

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

Parameter	Value	Description
country	string	the country in which the number is located.
state	string	the state in which the number is located. Only present for countries that have states.
region	string	the region in which the number is located.
price	string	the price per month for the number in US dollars.
purchased	string	the date on which the number was purchased in the format YYYY-MM-DD.
did_type	string	the type of the number. One of "geographic", "national", "mobile" or "tollfree".

Example

Request

https://ws-[cloudID].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.

Request


URL	: https://ws-[cloudID].aculabcloud.net/tel_delete_numbers
Methods	: GET, POST

Parameter	Value	Description
numbers	string	a comma-separated list of the telephone numbers to delete.

Response

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.

Parameter	Value	Description
status	string	a 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.
numbers	JSON object	contains the numbers not deleted and the reason.
description	string	a description of the reason for the non deletion.
code	string	a numeric error code from Error Codes.

Example 1

Request

https://ws-[cloudID].aculabcloud.net/tel_delete_numbers?numbers=441908538007,441908538008,441908538009

Response

  {
    "status": "OK"
  }

Example 2

Request

https://ws-[cloudID].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.

Request


URL	: https://ws-[cloudID].aculabcloud.net/tel_get_supported_countries
Methods	: GET, POST

Parameter	Value	Description
did_type	string (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".

Response

A JSON array containing the names of the countries supported.

Example 1

Request

https://ws-[cloudID].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 3

Request

https://ws-[cloudID].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.

Request


URL	: https://ws-[cloudID].aculabcloud.net/tel_get_supported_states
Methods	: GET, POST

Parameter	Value	Description
country	string	the country in which to list the supported states.

Response

A JSON array containing the names of the states supported.

Example

Request

https://ws-[cloudID].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.

Request


URL	: https://ws-[cloudID].aculabcloud.net/tel_get_supported_regions
Methods	: GET, POST

Parameter	Value	Description
country	string	the country in which to list the supported regions.
state	string (optional for some countries)	the state in which to list the supported regions.
did_type	string (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".

Response

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 1

Request

https://ws-[cloudID].aculabcloud.net/tel_get_supported_regions?country=Canada&state=Manitoba

Response

  [
    "Oakbank", "Winnipeg"
  ]

Example 2

Request

https://ws-[cloudID].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.

Request


URL	: https://ws-[cloudID].aculabcloud.net/tel_list_regulation_addresses
Methods	: GET, POST

Response

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

Example

Request

https://ws-[cloudID].aculabcloud.net/tel_list_regulation_addresses

Response

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