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

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

Parameters

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

Optional Parameters

Parameter Description
number_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: 200

JSON:
{
  meta: {
    previous: null,
    total_count: 1,
    offset: 0,
    limit: 20,
    next: null
  },
  api_id: "14d30e2c-7459-11e1-8ea7-12313806be9a",
  objects: [
    {
      voice_enabled: true,
      description: "TOLEDO",
      plivo_number: true,
      sms_enabled: true,
      number: "15676988323",
      alias: "Test Number",
      application: "/v1/Account/MAGWNTM3ZTK1M2YZMDF5/Application/72509666337566/",
      number_type: "local",
      added_on: "2012-03-21",
      resource_uri: "/v1/Account/MAGWNTM3ZTK1M2YZMDF5/Number/15676988323/"
    }
  ]
}

Get Details of a Rented Number

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

Parameters

None

Response

HTTP status: 200

JSON:
{
  voice_enabled: true,
  description: "TOLEDO",
  plivo_number: true,
  sms_enabled: true,
  number: "15676988323",
  alias: "Test Number",
  api_id: "43eb869e-7459-11e1-8ea7-1231380bc196",
  application: "/v1/Account/MAGWNTM3ZTK1M2YZMDF5/Application/72509666337566/",
  number_type: "local",
  added_on: "2012-03-21",
  resource_uri: "/v1/Account/MAGWNTM3ZTK1M2YZMDF5/Number/15676988323/"
}

Add a number from your own carrier

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

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

Parameters

Mandatory Parameters

Parameter Description
numbers 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 The carrier_id of the IncomingCarrier that the number is associated with. For more information on incoming carrier, click here
region This is the region that is associated with the Number. You can use it to organize numbers based on the area they are from.

Optional Parameters

Parameter Description
number_type 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 The application id of the application that is to be linked.
subaccount 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: 202

JSON:
{
  "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.

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

Parameters

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

Optional Parameters

Parameter Description
app_id 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 The auth_id of the subaccount to which this number should be added. This can only be performed by a main account holder.
alias The textual name given to the number.

Response

HTTP status: 202

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

Unrent a Number

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

Parameters

None

Response

HTTP status: 204

Asynchronous Mode

All Plivo APIs can be invoked in asynchronous mode with the inclusion of the callback_url parameter. Note: In asynchronous mode, you will only get back a response with the api_id. The response is sent to the callback_url which is fired immediately after execution of the Plivo API. See API Request and API Response for more information.

Asynchronous Parameters

Parameter Description
callback_url The URL that is notified by the API when the response is available and to which the response is sent.
callback_method The method used to notify the callback_url URL. Defaults to POST.

Asynchronous Response

The Asynchronous Response is sent in json format in the response field.

See the API Response section for more information.