AvailableNumberGroup

The following actions can be performed with the AvailableNumberGroup APIs. The available numbers are grouped together according to their country, number type, area code/prefix and pricing. Each number group is available as a resource from which numbers can be ordered.

  BaseURI: https://api.plivo.com/v1/Account/{auth_id}/AvailableNumberGroup/

Search for New Numbers

  URI: https://api.plivo.com/v1/Account/{auth_id}/AvailableNumberGroup/
  Method: GET

Parameters

The following parameters are required to search for new numbers:

Required Parameters
Parameter Description
country_iso The ISO code A2 of the country ( BE for Belgium, DE for Germany, GB for United Kingdom, US for United States etc ). See the Wikipedia site for a list of ISOs for different countries.
Optional Parameters

The following optional parameters can be specified when you are searching for new numbers:

Parameter Description
number_type The type of number you are looking for. The possible number types are local, national and tollfree. Defaults to local if this field is not specified.
prefix Represents the area code of the number for a local number. Represents the country specific prefix for national numbers and for a tollfree number, this represents the tollfree prefix. This parameter must be numeric and has a maximum length of 5 digits.
region This filter is only applicable when the number_type is local. If the number_type is not provided, it is assumed to be local. Region based filtering can be performed with the following terms:
  • Region Codes: You could use region=NY if you were looking for a number in New York. This search is performed when the search term is two characters in length.
  • Exact names of the region: You could use region=California if you were looking for a number in California. Performed if the search term is three or more characters in length.
  • Contained in the region: You could use region=ebra will return Nebraska. Performed if the search term is three or more characters in length.
services Filters out phone numbers according to the services you want from that number. The following values are valid:
  • voice - Returns a list of numbers that provide 'voice' services. Additionally, if the numbers offer both 'voice' and 'sms', they are also listed. Note - This option does not exclusively list those services that provide both voice and sms .
  • voice,sms - Returns a list of numbers that provide both 'voice' and 'sms' services.
  • sms - Returns a list of numbers that provide only 'sms' services.
limit Used to display the number of results per page. The maximum number of results that can be fetched is 20.
offset Denotes the number of value items by which the results should be offset. Eg:- If the result contains a 1000 values and limit is set to 10 and offset is set to 705, then values 706 through 715 are displayed in the results. This parameter is also used for pagination of the results.

Response

HTTP status: 200

JSON: 
{
  "meta": {
    "previous": null,
    "total_count": 1,
    "offset": 0,
    "limit": 20,
    "next": null
  },
  "api_id": "26590c12-5831-11e1-86da-6ff39efcb949",
  "objects": [
    {
      group_id: "55350421590053",
      number_type: "local",
      prefix: "3",
      region: "AMIENS, FRANCE",
      rental_rate: "0.80000",
      resource_uri: "/v1/Account/MAC4NMQ3YJVHYJM0N2Y1/AvailableNumberGroup/55350421590053/",
      setup_rate: "0.80000",
      sms_enabled: false,
      sms_rate: -1,
      stock: 9731,
      voice_enabled: true,
      voice_rate: "0.00700"
    }
  ]
}

Rent a Number

The group id parameter that is obtained from the number search API above should be passed as a parameter to this POST request. 

    URI: https://api.plivo.com/v1/Account/{auth_id}/AvailableNumberGroup/{group_id}/
    Method: POST

Parameters

There are no mandatory parameters for this API. The following optional parameters can be specified:

Optional Parameters
Parameter Description
quantity The quantity of numbers that are to be ordered from the number group. Default value is 1.
app_id The id of the application that you want assigned to the Number. If not specified, then it is assigned to the default application of the Account.

Response

HTTP status: 201

JSON: 
{
  "numbers": [{"number": "553139560512", "status": "Success"}, {"number": "553139560513", "status": "Success"}],
  "status": "fulfilled"
}

In certain countries where there are address regulations, you will receive a response similar to the following response:

HTTP status: 201

JSON: 
{
  "details": "Order for 2 numbers(Region: AMIENS, FRANCE, number_type: local, Prefix:  3) initiated. For this order, some additional information is required by the telecom regulatory authorities. Our support team will get in touch with you soon.",
  "message": "created",
  "status": "pending"
}

Developers

Navigation