> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone Numbers API

> Search and buy phone numbers from Plivo's inventory

Search for and purchase phone numbers from Plivo. You can search for local, toll-free, national, mobile, and fixed phone numbers that match specific criteria.

**API Endpoint**

```bash theme={null}
https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/
```

***

## The PhoneNumber Object

### Attributes

**number** `string`

Phone number that can be purchased.

**prefix** `string`

Area code of the number.

**city** `string`

City of the number. Returns `null` for national numbers.

**country** `string`

Country of the number.

**region** `string`

City and country of the number.

**rate\_center** `string`

Rate center. US and Canada only.

**lata** `string`

Local access and transport area. US and Canada only.

**type** `string`

Number type. Values: `fixed`, `mobile`, or `tollfree`.

**sub\_type** `string`

Number subtype. Values: `fixed`, `mobile`, `tollfree`, `national`, or `local`.

**setup\_rate** `string`

One-time setup fee in USD.

**monthly\_rental\_rate** `string`

Monthly rental fee in USD.

**sms\_enabled** `boolean`

Whether the number can receive SMS.

**sms\_rate** `string`

Cost per SMS received in USD.

**mms\_enabled** `boolean`

Whether the number can receive MMS.

**mms\_rate** `string`

Cost per MMS received in USD.

**voice\_enabled** `boolean`

Whether the number can receive calls.

**voice\_rate** `string`

Cost per minute for calls in USD.

**restriction** `string`

Verification requirement. Values: `city-address`, `country-address`, `terms-and-conditions`, or `null`.

**restriction\_text** `string`

Description of verification requirements.

**resource\_uri** `string`

URI to the phone number resource.

### Example Object

```json theme={null}
{
  "number": "14155559186",
  "prefix": "415",
  "city": "SAN FRANCISCO",
  "country": "UNITED STATES",
  "region": "United States",
  "rate_center": "SNFC CNTRL",
  "lata": 722,
  "type": "fixed",
  "sub_type": "local",
  "setup_rate": "0.00000",
  "monthly_rental_rate": "0.80000",
  "sms_enabled": true,
  "sms_rate": "0.00800",
  "voice_enabled": true,
  "voice_rate": "0.00500",
  "restriction": null,
  "restriction_text": null,
  "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/PhoneNumber/14155559186/"
}
```

***

## Search Phone Numbers

Returns available phone numbers matching your criteria.

```bash theme={null}
GET https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/
```

### Arguments

**country\_iso** `string` *required*

[ISO 3166 alpha-2 country code](https://www.iban.com/country-codes) of the country.

**type** `string`

Number type filter. Values: `tollfree`, `local`, `mobile`, `national`, or `fixed`.

**pattern** `string`

Pattern to match. For example, `415` returns numbers starting with 1415.

**npanxx** `integer`

Six-digit prefix filter. US and Canada only.

**local\_calling\_area** `boolean`

Expand search to local calling area of `npanxx`.

**region** `string`

Region name (e.g., `Frankfurt`). For `fixed` type only.

**city** `string`

City name. For `local` type only.

**services** `string`

Filter by capabilities. Values: `voice`, `sms`, `mms`, `voice,sms`, or `voice,sms,mms`.

**lata** `integer`

LATA filter. US and Canada only.

**rate\_center** `string`

Rate center filter. US and Canada only.

**limit** `integer`

Results per page. Maximum 20, default 20.

**offset** `integer`

Pagination offset. Default 0.

### Example

```python Python theme={null}
import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.numbers.search(country_iso='US', type='local', pattern='415')
print(response)
```

```javascript Node.js theme={null}
const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.numbers.search('US', { type: 'local', pattern: '415' })
    .then(response => console.log(response));
```

```ruby Ruby theme={null}
require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.phone_numbers.search('US', type: 'local', pattern: '415')
puts response
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->phonenumbers->list('US', ['type' => 'local', 'pattern' => '415']);
print_r($response);
```

```java Java theme={null}
import com.plivo.api.Plivo;
import com.plivo.api.models.number.PhoneNumber;

Plivo.init("<auth_id>", "<auth_token>");

ListResponse<PhoneNumber> response = PhoneNumber.lister("US")
    .type("local")
    .pattern("415")
    .list();
System.out.println(response);
```

```csharp .NET theme={null}
using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.PhoneNumber.List(countryIso: "US", type: "local", pattern: "415");
Console.WriteLine(response);
```

```go Go theme={null}
package main

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.PhoneNumbers.List(plivo.PhoneNumberListParams{
        CountryISO: "US",
        Type:       "local",
        Pattern:    "415",
    })
    fmt.Println(response)
}
```

```bash cURL theme={null}
curl "https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/?country_iso=US&type=local&pattern=415" \
  -u '<auth_id>:<auth_token>'
```

### Response

```json theme={null}
{
  "api_id": "859428b0-1c88-11e4-a2d1-22000ac5040c",
  "meta": {
    "limit": 20,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 9
  },
  "objects": [
    {
      "number": "14154009186",
      "prefix": "415",
      "city": "SAN FRANCISCO",
      "country": "UNITED STATES",
      "type": "fixed",
      "sub_type": "local",
      "monthly_rental_rate": "0.80000",
      "sms_enabled": true,
      "voice_enabled": true,
      "restriction": null,
      "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/PhoneNumber/14154009186/"
    }
  ]
}
```

***

## Buy a Phone Number

Purchase a phone number and add it to your account.

```bash theme={null}
POST https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/{number}/
```

### Arguments

**app\_id** `string`

Application to assign. Defaults to `default_number_app`.

**cnam\_lookup** `string`

Enable CNAM lookup. Values: `enabled` or `disabled`. US only.

**compliance\_application\_id** `string`

UUID of an `accepted` compliance application to attach to the number at purchase. The application's country and number type must match the number. If the application was filed for a subaccount, buy the number for that subaccount (pass `subaccount`). See the [Compliance API](https://plivo.com/docs/numbers/compliance.md).

If you omit it, Plivo auto-selects the most recent accepted application that matches the number's country and type:

* **With `subaccount`:** one filed for that subaccount first, then one of your main account's.
* **Without `subaccount`:** one of your main account's.

Plivo never auto-selects an application filed for a different subaccount.

**subaccount** `string`

Auth ID of a subaccount to assign the number to at purchase. Requires main-account credentials (see note below).

> [!NOTE]
>
> If the number requires verification documents, the number status will be `pending` until documents are approved.

> [!NOTE]
>
> Call this endpoint with **main-account credentials**. Phone numbers are billed and owned at the main-account level, so a request made with subaccount credentials returns `404 not found` even when [Search](#search-phone-numbers) works with the same credentials. To buy a number for a subaccount, call this endpoint with main-account credentials and pass the `subaccount` parameter. To move an already-rented number to a subaccount, use the [Update an Account Phone Number](https://plivo.com/docs/numbers/account-phone-numbers.md#update-an-account-phone-number) endpoint's `subaccount` parameter. A number linked to a compliance application filed for a subaccount stays on that subaccount; see the `subaccount` parameter there.

### Example

```python Python theme={null}
import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.numbers.buy(number='14155559186')
print(response)
```

```javascript Node.js theme={null}
const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.numbers.buy('14155559186')
    .then(response => console.log(response));
```

```ruby Ruby theme={null}
require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.phone_numbers.buy('14155559186')
puts response
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->phonenumbers->buy('14155559186');
print_r($response);
```

```java Java theme={null}
import com.plivo.api.Plivo;
import com.plivo.api.models.number.PhoneNumber;

Plivo.init("<auth_id>", "<auth_token>");

PhoneNumberCreateResponse response = PhoneNumber.creator("14155559186").create();
System.out.println(response);
```

```csharp .NET theme={null}
using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.PhoneNumber.Buy(number: "14155559186");
Console.WriteLine(response);
```

```go Go theme={null}
package main

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.PhoneNumbers.Create("14155559186", plivo.PhoneNumberCreateParams{})
    fmt.Println(response)
}
```

```bash cURL theme={null}
curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/14155559186/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json"
```

### Response

```json theme={null}
{
    "api_id": "aa52882c-1c88-11e4-bd8a-12313f016a39",
    "message": "created",
    "numbers": [
        {
            "number": "14155559186",
            "status": "Success"
        }
    ],
    "status": "fulfilled"
}
```

### Compliance Errors

Renting a number that requires compliance, such as an India number, needs a compliance application in `accepted` status. Requests that don't meet this condition return `400 bad request`:

| Condition | Error message |
| - | - |
| No `compliance_application_id` passed and no accepted application Plivo can auto-select for this purchase (see `compliance_application_id` above) | `compliance_application_id is required to rent this number. Refer to https://www.plivo.com/docs/numbers/rent-india-numbers for details.` |
| The `compliance_application_id` passed is not in `accepted` status | `Compliance application must be in 'accepted' status. Current status: 'submitted'.` |
| The `compliance_application_id` passed was filed for a subaccount other than the one the number is bought for | `Compliance application xxx was filed for another sub-account. Use one filed for this number's sub-account, or one of the account's own.` |

See [India Number KYC](https://plivo.com/docs/numbers/rent-india-numbers.md#application-status) for how to resolve each application status.

***

## Related

* [Account Phone Numbers](https://plivo.com/docs/numbers/account-phone-numbers.md) - Manage your rented numbers
* [Regulatory Compliance](https://plivo.com/docs/numbers/compliance.md) - Verification requirements
* [Number Porting](https://plivo.com/docs/numbers/number-porting.md) - Port numbers to Plivo