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	Required/Optional	Default	Description
country	required		The country where the number is located.
state	required by some countries		The state where the number is located. Some countries require this to be specified.
region	required		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	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	optional	1	The quantity of telephone numbers to purchase.
based_on	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	optional	False	"True" or "False". Determines whether the request responds as having succeeded even if not all the requested telephone numbers are available.
did_type	optional	geographic	The type of each new number purchased. One of "geographic", "national", "mobile" or "tollfree".
allow_landline	optional	False	"True" or "False". For toll free numbers only. "True" to allow calls from landline numbers. Otherwise calls from landlines are blocked.
allow_cellular	optional	False	"True" or "False". For toll free numbers only. "True" to allow calls from cellular (mobile) phones. Otherwise calls from cell phones (mobiles) are blocked.
allow_payphone	optional	False	"True" or "False". For toll free numbers only. "True" to allow calls from payphones. Otherwise calls from payphones are blocked.

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	Required/Optional	Default	Description
country	optional	all countries	The country where the number is located.
state	optional	all states	The state where the number is located. Only valid for some countries.
region	optional	all regions	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	optional	all types	The type of numbers to include in the list. One of "geographic", "national", "mobile" or "tollfree".

Response

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

Parameter	Type	Availability	Description
country	string	always	The country in which the number is located.
state	string	Only for countries that have states.	The state in which the number is located.
region	string	always	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.
price	string	always	The price per month for the number in US dollars.
purchased	string	always	The date on which the number was purchased in the format YYYY-MM-DD.
did_type	string	always	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	Required/Optional	Default	Description
numbers	required		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	Type	Availability	Description
status	string	always	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	NotDeleted object	if status is not OK	A JSON object describing each number that was not deleted keyed by the number.

The NotDeleted object:

Parameter	Type	Availability	Description
description	string	if status is not OK	A description of the reason for the non deletion.
code	string	if status is not OK	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	Required/Optional	Default	Description
did_type	optional	geographic	The type of numbers supported by a country for that country to be listed. One of "geographic", "national", "mobile" or "tollfree".

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	Required/Optional	Default	Description
country	required		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	Required/Optional	Default	Description
country	required		The country in which to list the supported regions.
state	optional		The state in which to list the supported regions. Only valid for countries that support states.
did_type	optional	geographic	The type of numbers supported by a region for that region to be listed. One of "geographic", "national", "mobile" or "tollfree".

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"
    }
  }