Number

The following actions can be performed using the Number APIs.

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

List All Rented Numbers

This API lets you list of numbers rented on Plivo and numbers added to your account.

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

Arguments

Parameter Description
type The type of number you are filtering. You can filter by local and tollfree numbers. Defaults to a local number.
number_startswith Used to specify the beginning of the number. For example, if the number '24' is specified, the API will fetch only those numbers beginning with '24'.
subaccount Requires the auth_id of the subaccount as input. If this parameter is included in the request, all numbers of the particular subaccount are displayed.
alias This is a name given to the number. The API will fetch only those numbers with the alias specified.
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 Code: 200

{
    "api_id": "114de006-1c95-11e4-8a4a-123140008edf",
    "meta": {
        "limit": 3,
        "next": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Number/?limit=3&offset=3",
        "offset": 0,
        "previous": null,
        "total_count": 20
    },
    "objects": [
        {
            "added_on": "2014-08-05",
            "alias": null,
            "application": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Application/29986316244302815/",
            "carrier": "Plivo",
            "monthly_rental_rate": "0.80000",
            "number": "18135401302",
            "number_type": "local",
            "region": "Florida, UNITED STATES",
            "resource_uri": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Number/18135401302/",
            "sms_enabled": true,
            "sms_rate": "0.00000",
            "sub_account": null,
            "voice_enabled": true,
            "voice_rate": "0.00850"
        },
        {
            "added_on": "2013-01-01",
            "alias": "",
            "application": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Application/16632559604105954/",
            "carrier": "Plivo",
            "monthly_rental_rate": "0.80000",
            "number": "14153661106",
            "number_type": "local",
            "region": "BELVEDERE, UNITED STATES",
            "resource_uri": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Number/14153661106/",
            "sms_enabled": true,
            "sms_rate": "0.00000",
            "sub_account": null,
            "voice_enabled": true,
            "voice_rate": "0.00850"
        },
        {
            "added_on": "2013-03-25",
            "alias": "",
            "application": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Application/20372631212782799/",
            "carrier": "Plivo",
            "monthly_rental_rate": "0.80000",
            "number": "14152753408",
            "number_type": "local",
            "region": "California, UNITED STATES",
            "resource_uri": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Number/14152753408/",
            "sms_enabled": true,
            "sms_rate": "0.00000",
            "sub_account": null,
            "voice_enabled": true,
            "voice_rate": "0.00850"
        }
    ]
}

Response Attributes

added_on
string The date on which the number was rented on your account. The date format is YYYY-MM-DD
alias
string A friendly name for your Plivo number.
carrier
string The carrier which is linked to this number. This can either be a Plivo carrier or a custom carrier added using the IncomingCarrier API.
monthly_rental_rate
string The monthly rental for this number in USD.
number
string The phone number itself.
number_type
string The type of the number. The values can be 'local', 'tollfree' and 'national'
region
string The region, with the city and the country this number belongs to.
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.
subaccount
string The subaccount associated with the number. If the number belongs to the main parent account, this value will be null.

Get Details of a Rented Number

This API lets you get details of a single number on your Plivo account.

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

Arguments

None

Response

HTTP Status Code: 200

{
    "added_on": "2014-02-14",
    "alias": null,
    "api_id": "88625e5e-1c92-11e4-80aa-12313f048015",
    "application": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Application/29986316244302815/",
    "carrier": "Plivo",
    "monthly_rental_rate": "0.80000",
    "number": "17609915566",
    "number_type": "local",
    "region": "California, UNITED STATES",
    "resource_uri": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Number/17609915566/",
    "sms_enabled": true,
    "sms_rate": "0.00000",
    "sub_account": null,
    "voice_enabled": true,
    "voice_rate": "0.00850"
}

Response Attributes

added_on
string The date on which the number was rented on your account. The date format is YYYY-MM-DD
alias
string A friendly name for your Plivo number.
application
string The Plivo application linked to the number.
carrier
string The carrier which is linked to this number. This can either be a Plivo carrier or a custom carrier added using the IncomingCarrier API.
monthly_rental_rate
string The monthly rental for this number in USD.
number
string The phone number itself.
number_type
string The type of the number. The values can be 'local', 'tollfree' and 'national'
region
string The region, with the city and the country this number belongs to.
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.
subaccount
string The subaccount associated with the number. If the number belongs to the main parent account, this value will be null.

Add a number from your own carrier

This API enables you to add a number of your own carrier.

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

Arguments

Parameter Description
numbers (mandatory) A comma separated list of numbers that need to be added for the carrier. Make sure that you configure the numbers to point to the sip server @sbc.plivo.com. Eg: If the number you own from your carrier is 18554675486 then the sip address it needs to point to is 18554675486@sbc.plivo.com
carrier (mandatory) The carrier_id of the IncomingCarrier that the number is associated with. For more information, check our IncomingCarrier API
region (mandatory) This is the region that is associated with the Number. You can use it to organize numbers based on the area they are from.
number_type (optional) This field does not impact the way Plivo uses this number. It is primarily adding more information about your number. You may use this field to categorize between local and tollfree numbers. Default is local.
app_id (optional) The application id of the application that is to be linked.
subaccount (optional) The auth_id of the subaccount to which this number should be added. This can only be performed by a main account holder.

Response

HTTP Status Code: 202

{
  "message": "changed",
  "api_id": "5a9fcb68-582d-11e1-86da-6ff39efcb949"
}

Edit a Number

This API enables you to change the application and subaccount associated with a number you rented.

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

Arguments

Parameter Description
app_id (optional) The application id of the application that is to be linked. If this is set to null, then any existing application is unlinked from the number.
subaccount (optional) The auth_id of the subaccount to which this number should be added. This can only be performed by a main account holder.
alias (optional) The textual name given to the number.

Response

HTTP Status Code: 202

{
  "message": "changed",
  "api_id": "5a9fcb68-582d-11e1-86da-6ff39efcb949"
}

Unrent a Number

This API lets you unrent a number on Plivo. This operation cannot be undone.

DELETE https://api.plivo.com/v1/Account/{auth_id}/Number/{number}/

Arguments

None

Response

HTTP Status Code: 204