> ## 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.

# Account Phone Numbers API

> Manage phone numbers in your Plivo account

Manage phone numbers that you've rented from Plivo or added from your carrier. List, retrieve, update, and unrent numbers.

**API Endpoint**

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

***

## The AccountPhoneNumber Object

### Attributes

**number** `string`

The phone number.

**alias** `string`

Alias for the phone number.

**subaccount** `string`

Associated subaccount (null if main account).

**added\_on** `string`

Date rented. Format: `YYYY-MM-DD`.

**application** `string`

Linked application URI.

**carrier** `string`

Plivo or incoming carrier name.

**region** `string`

City and country.

**number\_type** `string`

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

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

Monthly fee (USD).

**renewal\_date** `string`

Next billing date. Format: `YYYY-MM-DD`.

**sms\_enabled** `boolean`

Can receive SMS.

**sms\_rate** `string`

Cost per SMS (USD).

**mms\_enabled** `boolean`

Can receive MMS.

**mms\_rate** `string`

Cost per MMS (USD).

**voice\_enabled** `boolean`

Can receive calls.

**voice\_rate** `string`

Cost per minute (USD).

**cnam\_lookup** `string`

CNAM lookup status. Values: `enabled`, `disabled`, `null`.

**cnam** `string`

Caller ID name for outbound calls.

**tendlc\_registration\_status** `string`

10DLC status. Values: `UNREGISTERED`, `PROCESSING`, `COMPLETED`.

**tendlc\_campaign\_id** `string`

Linked 10DLC campaign ID.

**toll\_free\_sms\_verification** `string`

TF SMS verification. Values: `UNVERIFIED`, `PENDING_VERIFICATION`, `VERIFIED`.

**profile\_uuid** `string`

UUID of the linked business profile. `null` if no profile is linked.

**caller\_reputation\_status** `string`

Merged Caller Reputation status for the number across carrier networks. Values: `PENDING`, `ACTIVE`, `FAILED`, `NOT_REGISTERED`, `null`. Read `caller_reputation_by_carrier` for each network's real status.

**caller\_reputation\_by\_carrier** `object`

Per-carrier Caller Reputation status for the number, keyed by carrier network: `at&t` and `t-mobile`, plus `verizon` when it was explicitly requested (reported as `NOT_SUPPORTED`). Each entry contains `status`, `reason_code`, `reason`, and `updated_at`. See [Status values](https://plivo.com/docs/voice/concepts/caller-reputation.md#status-values).

**resource\_uri** `string`

URI to the number resource.

### Example Object

```json theme={null}
{
  "number": "17609915566",
  "alias": null,
  "sub_account": null,
  "added_on": "2023-02-14",
  "application": "/v1/Account/MA2025RK4E639VJFZAGV/Application/29986316244302815/",
  "carrier": "Plivo",
  "region": "California, UNITED STATES",
  "number_type": "local",
  "monthly_rental_rate": "0.80000",
  "renewal_date": "2023-05-10",
  "sms_enabled": true,
  "sms_rate": "0.00000",
  "voice_enabled": true,
  "voice_rate": "0.00850",
  "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Number/17609915566/",
  "tendlc_campaign_id": "2FA_campaign",
  "tendlc_registration_status": "COMPLETED",
  "toll_free_sms_verification": null,
  "profile_uuid": null,
  "caller_reputation_status": null
}
```

***

## List Account Phone Numbers

Returns all phone numbers in your account.

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

### Query Parameters

**type** `string`

Filter by type. Values: `local`, `mobile`, `fixed`, `national`, `tollfree`.

**number\_startswith** `string`

Filter by prefix.

**subaccount** `string`

Filter by subaccount.

**alias** `string`

Filter by exact alias.

**services** `string`

Filter by services. Values: `voice`, `sms`, `mms`, or combinations.

**cnam\_lookup** `string`

Filter by CNAM status. Values: `enabled`, `disabled`.

**renewal\_date** `string`

Filter by renewal date. Format: `YYYY-MM-DD`. Supports variants: `renewal_date__gt`, `renewal_date__gte`, `renewal_date__lt`, `renewal_date__lte`.

**tendlc\_registration\_status** `string`

Filter by 10DLC status. Values: `unregistered`, `in_progress`, `registered`.

**tendlc\_campaign\_id** `string`

Filter by campaign ID.

**toll\_free\_sms\_verification** `string`

Filter by TF verification status. Values: `unverified`, `pending_verification`, `verified`.

**limit** `integer`

Results per page. Max: 20. Default: 20.

**offset** `integer`

Pagination offset.

### Example

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

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

response = client.numbers.list(limit=10, type='local')
print(response)
```

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

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

client.numbers.list({ limit: 10, type: 'local' })
    .then(response => console.log(response));
```

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

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

response = client.numbers.list(limit: 10, type: 'local')
puts response
```

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

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

$response = $client->numbers->list(['limit' => 10, 'type' => 'local']);
print_r($response);
```

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

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

ListResponse<Number> response = Number.lister()
    .limit(10)
    .list();
System.out.println(response);
```

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

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

var response = api.Number.List(limit: 10, type: "local");
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.Numbers.List(plivo.NumberListParams{Limit: 10})
    fmt.Println(response)
}
```

```bash cURL theme={null}
curl "https://api.plivo.com/v1/Account/{auth_id}/Number/?limit=10&type=local" \
  -u '<auth_id>:<auth_token>'
```

***

## Get an Account Phone Number

Retrieve details of a specific phone number.

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

### Example

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

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

response = client.numbers.get(number='17609915566')
print(response)
```

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

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

client.numbers.get('17609915566')
    .then(response => console.log(response));
```

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

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

response = client.numbers.get('17609915566')
puts response
```

```bash cURL theme={null}
curl "https://api.plivo.com/v1/Account/{auth_id}/Number/17609915566/" \
  -u '<auth_id>:<auth_token>'
```

***

## Update an Account Phone Number

Change the application, subaccount, or alias for a phone number.

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

### Arguments

**app\_id** `string`

Application to assign (or Zentrunk inbound trunk\_id).

**subaccount** `string`

Subaccount auth\_id to transfer number to.

* **Number linked to a compliance application filed for a subaccount:** it can't move to another subaccount or back to your main account. To change the owner, [unrent it](#unrent-a-number) and buy it again for the new owner. Unrenting can't be undone.
* **Exception, number still pending activation:** you can move it if the same request also passes a `compliance_application_id` filed for the destination subaccount or for your main account.

**alias** `string`

Alias for the number.

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

UUID of an `accepted` compliance application to link to this number. The application must match the number's country and type. It must be filed for your main account or for the subaccount the number belongs to after this update. This parameter only takes effect while the number is **pending activation** — for numbers that are already active, use the [Bulk Link endpoint](https://plivo.com/docs/numbers/compliance.md#bulk-link) instead. See the [Compliance API](https://plivo.com/docs/numbers/compliance.md) for details.

**cnam\_lookup** `string`

CNAM lookup. Values: `enabled`, `disabled`. US only.

**cnam** `string`

Caller ID name for outbound calls.

**cnam\_callback\_url** `string`

URL for CNAM registration updates.

**cnam\_callback\_method** `string`

HTTP method. Values: `GET`, `POST`. Default: `POST`.

**caller\_reputation** `string`

Enable or disable Caller Reputation for this number. Values: `enabled`, `disabled`. When set to `enabled`, `profile_uuid` is required and the profile must have a registered business with at least one carrier network approved — the number attaches on every approved network, and the response reports each network's status. If no network is approved, the request returns a `400`. US local and toll-free numbers only. Early access beta. See [Caller Reputation](https://plivo.com/docs/voice/concepts/caller-reputation.md) for the full flow.

**profile\_uuid** `string`

UUID of the business profile to associate with this number. Required when `caller_reputation` is set to `enabled`.

**caller\_reputation\_callback\_url** `string` *deprecated*

**Deprecated.** Set `url` on the profile instead — see [Status callbacks](https://plivo.com/docs/voice/concepts/caller-reputation.md#status-callbacks). Plivo accepts this parameter during the migration period and ignores it after.

**caller\_reputation\_callback\_method** `string` *deprecated*

**Deprecated.** Set `method` on the profile instead. Plivo accepts this parameter during the migration period and ignores it after.

### Example

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

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

response = client.numbers.update(number='17609915566', alias='Main Line')
print(response)
```

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

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

client.numbers.update('17609915566', { alias: 'Main Line' })
    .then(response => console.log(response));
```

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

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

response = client.numbers.update('17609915566', alias: 'Main Line')
puts response
```

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

### Response

```json theme={null}
{
  "message": "changed",
  "api_id": "5a9fcb68-582d-11e1-86da-6ff39efcb949"
}
```

### Compliance Errors

An update that changes `subaccount` or passes `compliance_application_id` can return these errors, each with `400 bad request`:

| Condition | Error message |
| - | - |
| Moving a number linked to a subaccount's application to another owner | `Number 912212345678 is linked to compliance application xxx, which was filed for its sub-account. Keep the number on that sub-account, or release it and rent it again for the new one.` |
| The `compliance_application_id` passed was filed for a different subaccount | `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.` |
| The number's linked application could not be checked (retry) | `Could not verify the compliance application linked to number 912212345678. Please try again.` |

To release a number, [unrent it](#unrent-a-number). See [India Number KYC](https://plivo.com/docs/numbers/rent-india-numbers.md#using-the-api-with-subaccounts) for how compliance applications filed for subaccounts work.

***

## Unrent a Number

Remove a phone number from your account. This operation cannot be undone.

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

### Example

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

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

response = client.numbers.delete(number='17609915566')
print(response)
```

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

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

client.numbers.unrent('17609915566')
    .then(response => console.log(response));
```

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

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

response = client.numbers.delete('17609915566')
puts response
```

```bash cURL theme={null}
curl -X DELETE "https://api.plivo.com/v1/Account/{auth_id}/Number/17609915566/" \
  -u '<auth_id>:<auth_token>'
```

### Response

```text theme={null}
HTTP Status Code: 204
```

***

## Related

* [Phone Numbers](https://plivo.com/docs/numbers/phone-numbers.md) - Search and buy numbers
* [Incoming Carriers](https://plivo.com/docs/numbers/incoming-carriers/) - Add numbers from your carrier
* [Regulatory Compliance](https://plivo.com/docs/numbers/compliance.md) - Verification requirements
* [Caller Reputation](https://plivo.com/docs/voice/concepts/caller-reputation.md) - Register your business identity to reduce spam flagging