PhoneNumber

The following actions can be performed with the PhoneNumber API. Using this API you can search for a number based on the number pattern, region and number type.

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

Search for New Numbers

This API lets you search for fixed, mobile and tollfree numbers available on Plivo. Searches can be performed based on the country ISO, pattern, number type and region. We return a list of numbers which can then be bought.

GET https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/

Arguments

Parameter Description
country_iso (mandatory) 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.
type (optional) The type of number you are looking for. The possible number types are fixed, mobile and tollfree. Defaults to any if this field is not specified. type also accepts the value any, which will search for all 3 number types.
pattern (optional) Represents the pattern of the number to be searched. Adding a pattern will search for numbers which start with the country code + pattern. For eg. a pattern of 415 and a country_iso: US will search for numbers starting with 1415.
region (optional) This filter is only applicable when the type is fixed. If the type is not provided, it is assumed to be fixed. Region based filtering can be performed with the following terms:
  • Exact names of the region: You could use region=Frankfurt if you were looking for a number in Frankfurt. Performed if the search term is three or more characters in length.
services (optional) Filters out phone numbers according to the services you want from that number. The following values are valid:
  • voice - If this option is selected, it ensures that the results have voice enabled numbers. These numbers may or may not be SMS enabled.
  • voice,sms - If this option is selected, it ensures that the results have both voice and sms enabled on the same number.
  • sms - If this option is selected, it ensures that the results have sms enabled numbers. These numbers may or may not be voice enabled.
By default, numbers that have either voice or sms or both enabled are returned.
lata (optional) Numbers can be searched using Local Access and Transport Area. This filter is applicable only for country_iso US and CA.
rate_center (optional) Numbers can be searched using Rate Center. This filter is application only for country_iso US and CA.
limit (optional) Used to display the number of results per page. The maximum number of results that can be fetched is 20.
offset (optional) 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 Code: 200

{
    "api_id": "859428b0-1c88-11e4-a2d1-22000ac5040c",
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 9
        },
    "objects": [
    {
        "country": "UNITED STATES",
        "lata": 722,
        "monthly_rental_rate": "0.80000",
        "number": "14154009186",
        "type": "fixed",
        "prefix": "415",
        "rate_center": "SNFC CNTRL",
        "region": "United States",
        "resource_uri": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/PhoneNumber/14154009186/",
        "restriction": null,
        "restriction_text": null,
        "setup_rate": "0.00000",
        "sms_enabled": true,
        "sms_rate": "0.00800",
        "voice_enabled": true,
        "voice_rate": "0.00500"
        },
    {
        "country": "UNITED STATES",
        "lata": 722,
        "monthly_rental_rate": "0.80000",
        "number": "14154009187",
        "type": "fixed",
        "prefix": "415",
        "rate_center": "SNFC CNTRL",
        "region": "United States",
        "resource_uri": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/PhoneNumber/14154009187/",
        "restriction": null,
        "restriction_text": null,
        "setup_rate": "0.00000",
        "sms_enabled": true,
        "sms_rate": "0.00800",
        "voice_enabled": true,
        "voice_rate": "0.00500"
        }
    ]
}

Response Attributes

country
string The country to which the number belongs to.
lata
string lata represents Local access and transport area and will only be present for United States and Canada numbers.
number
string The phone number which is available on Plivo and can be purchased using the API.
type
string The type of the number associated with the group. The values can be 'fixed', 'mobile' and 'tollfree'
prefix
string The number prefix. This is the area code of the number.
rate_center
string The rate_center is only available for United States and Canada numbers.
restriction
string Numbers in some countries will have a restriction, in such a case, you will have to provide a verification document to activate the number after buying it. Numbers can have the following restriction values:
  • city-address: A local city address proof is needed to activate this number.
  • country-address: An address proof is needed of the country this number belongs to.
  • terms-and-conditions: Your number will be activated without any verification, however you must submit a local address proof whenever Plivo requests for one.
  • null: Your number will be activated after buying and no address proof is required.
restriction_text
string Contains text which describes the restriction.
region
string The region, with the city and the country this number belongs to.
monthly_rental_rate
string The monthly rent in USD for each number. The monthly rent is deducted on the 1st of every month and is pro-rated if the number is purchased any time in the middle of a month. For eg. If the number is bought on 20th of a month, Plivo will charge for the next 10 days of the month.
setup_rate
string The one-time setup cost for the number in USD.
sms_enabled
boolean Lets you know if the number is SMS enabled. If the value returned is 'true', then you will be able to receive SMS on this number.
sms_rate
string The cost of receiving an SMS on the number in USD.
voice_enabled
boolean Lets you know if the number is voice enabled. If the value returned is 'true', then you will be able to receive calls on this number.
voice_rate
string The cost of receiving a voice call on this number per minute in USD.

Buy Number

The number retrieved from the search above should be used as an input to buy the number.

 POST https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/{number}/

Arguments

Parameter Description
app_id (optional) 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 Code: 201

{
    "api_id": "aa52882c-1c88-11e4-bd8a-12313f016a39",
    "message": "created",
    "numbers": [
        {
            "number": "14154009186",
            "status": "Success"
        }
    ],
    "status": "fulfilled"
}

In certain countries where there are address regulations, you will receive a response similar to the following response. We will send an email to your registered account email with the requirements.

{
    "api_id": "aa52882c-1c88-11e4-bd8a-12313f016a39",
    "message": "created",
    "numbers": [
        {
            "number": "4969365065273",
            "status": "pending"
        }
    ],
    "status": "fulfilled"
}