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

# Numbers

> Search, buy, attach and release phone numbers; compliance applications (including India KYC); number masking.

Find a phone number to rent, manage numbers you own, and submit compliance documents. After [logging in](https://plivo.com/docs/cli/install.md#log-in-with-a-browser), search for a US number, then preview and confirm the rental:

```bash theme={null}
plivo numbers search --country US --limit 5
plivo numbers buy "<number>" --dry-run
plivo numbers buy "<number>" --yes
```

* Phone numbers use international format with the country code. Replace `<values>` with your own and omit `[flags]` unless adding options.
* Buying a number spends money and needs `--yes`. In India a number can only be rented (and used for calls) once a compliance application (KYC, know your customer) is `accepted`.
* Paged lists take `--limit`, `--offset` and `--all`. Global flags: see [Configuration](https://plivo.com/docs/cli/configure.md).

### Compliance when you buy or route a number

* `plivo numbers buy --compliance-application-id <id>` attaches a specific compliance application. Without it, Plivo picks your most recent applicable one. Use it when you keep one application per end customer, or for an India number when Plivo has none to attach by itself. A malformed ID is refused before any request.
* `plivo numbers update --app-id` or `--trunk-id` on an India (+91) number reads its compliance application first. The update is refused when no application is attached, when it isn't `accepted`, or when it can't be read. `--dry-run` runs the same check. `--force` skips only this local check: Plivo still enforces KYC on its side, so file KYC rather than forcing it. Changing only `--alias` or `--subaccount` isn't checked.
* `--trunk-id` routes the number to an inbound SIP trunk instead of an application; see [SIP trunking](https://plivo.com/docs/cli/apis/sip.md#route-a-number-to-a-trunk). It warns when the trunk is disabled, because no call reaches the number until you run `plivo sip trunks update <trunk_id> --status enabled`. An outbound trunk is refused.
* A number that isn't on your account is refused with a hint to run `plivo numbers list`. A malformed number is refused before any request.

A refusal for a number with no KYC exits with code `1`. The hint lists the KYC steps as CLI commands, and `docs_url` links the India KYC guide:

```json theme={null}
{ "error": { "code": "VALIDATION_ERROR",
             "message": "refusing to route 91XXXXXXXXXX: This number has no KYC. File KYC first at https://cx.plivo.com/phone-numbers?tab=compliance",
             "hint": "India numbers need an accepted compliance application (KYC): 1) `plivo numbers compliance list --country IN` lists your applications; 2) `plivo numbers compliance create --data @app.json --file 'documents[0].file=@doc.pdf'` submits one (`plivo numbers compliance update <compliance_id>` with the same flags resubmits a rejected one); 3) `plivo numbers compliance link --link 91XXXXXXXXXX=<compliance_id>` attaches an accepted one.",
             "docs_url": "https://www.plivo.com/docs/numbers/rent-india-numbers",
             "retryable": false } }
```

When an application is attached but not accepted, the message names its status, and step 1 of the hint becomes `plivo numbers compliance get <compliance_id>`, which shows the status and any rejection reason.

## Phone numbers

| Usage | What it does |
| - | - |
| `plivo numbers search [flags]` | Search available numbers to rent |
| `plivo numbers buy <number> [flags]` | Rent a phone number (requires --yes; spends money) |
| `plivo numbers list [flags]` | List numbers rented to your account |
| `plivo numbers get <number>` | Get details of a rented number |
| `plivo numbers update <number> [flags]` | Update settings on a rented number |
| `plivo numbers cnam <number>` | Caller ID name (CNAM) lookup for a US/CA number (spends money: requires --yes) |
| `plivo numbers release <number> [flags]` | Release a rented number (requires --yes; stops monthly billing) |

`buy` and `release` also take `--explain`, which narrates in plain English before running.

> [accordion] plivo numbers search
>
> | Flag | Description |
> | - | - |
> | `--country <value>` | ISO country code, e.g. US (required) |
> | `--pattern <value>` | digit pattern |
> | `--region <value>` | region filter |
> | `--type <value>` | local\|mobile\|fixed\|national\|tollfree |
>
> Takes `--limit` and `--offset` but not `--all`. When the API declines a search, its reason goes to stderr.

> [accordion] plivo numbers buy
>
> | Flag | Description |
> | - | - |
> | `--app-id <value>` | auto-attach to this application after purchase |
> | `--compliance-application-id <value>` | accepted compliance application to attach; if unset, Plivo picks your most recent applicable one |

> [accordion] plivo numbers list
>
> | Flag | Description |
> | - | - |
> | `--alias <value>` | filter by alias |
> | `--services <value>` | filter by services: voice\|sms\|mms\|voice,sms ... |
> | `--starts-with <value>` | prefix filter on E.164 |
> | `--subaccount <value>` | filter by subaccount auth\_id |
> | `--type <value>` | filter by type: local\|mobile\|fixed\|national\|tollfree |

> [accordion] plivo numbers update
>
> | Flag | Description |
> | - | - |
> | `--alias <value>` | set alias |
> | `--app-id <value>` | associate an application |
> | `--force` | skip the India compliance check on --app-id/--trunk-id (Plivo still enforces KYC) |
> | `--subaccount <value>` | move under subaccount |
> | `--trunk-id <value>` | route the number to an inbound SIP trunk |

## Number compliance

Look up the documents and fields required for a country and number type:

```bash theme={null}
plivo numbers compliance requirements --country IN --number-type local --user-type business
```

Use those requirements and the [India number guide](https://plivo.com/docs/numbers/rent-india-numbers.md) to write `app.json`. The `@` prefix tells the CLI to read a file. Upload field names must match the document entries in that JSON. `create` submits automatically; check the application status before linking a number. `update` works only on a rejected application and replaces its whole document set.

| Usage | What it does |
| - | - |
| `plivo numbers compliance requirements [flags]` | List documents/fields required to activate a regulated number |
| `plivo numbers compliance create [flags]` | Create and submit a compliance application (multipart) |
| `plivo numbers compliance list [flags]` | List compliance applications |
| `plivo numbers compliance get <compliance_id> [flags]` | Get a compliance application by ID |
| `plivo numbers compliance update <compliance_id> [flags]` | Update and resubmit a rejected compliance application (multipart) |
| `plivo numbers compliance link [flags]` | Bulk-link numbers to accepted compliance applications |
| `plivo numbers compliance delete <compliance_id>` | Delete a compliance application (requires --yes) |

> [accordion] plivo numbers compliance requirements
>
> | Flag | Description |
> | - | - |
> | `--country <value>` | ISO country code, e.g. US (required) |
> | `--number-type <value>` | local\|mobile\|tollfree (required) |
> | `--user-type <value>` | individual\|business (required) |

> [accordion] plivo numbers compliance create
>
> | Flag | Description |
> | - | - |
> | `--data <value>` | application JSON; inline or @file.json (required) |
> | `--file <value>` | document upload as field=path, e.g. documents\[0].file=@id.pdf (repeatable) |
>
> ```bash theme={null}
> plivo numbers compliance create \
>   --data @app.json \
>   --file 'documents[0].file=@passport.pdf' \
>   --file 'documents[1].file=@address-proof.pdf'
> ```

> [accordion] plivo numbers compliance list
>
> | Flag | Description |
> | - | - |
> | `--alias <value>` | filter by alias |
> | `--country <value>` | filter by ISO country code |
> | `--number-type <value>` | filter by number type: local\|mobile\|tollfree\|national |
> | `--status <value>` | filter by status: draft\|submitted\|accepted\|rejected\|suspended\|expired |
> | `--user-type <value>` | filter by user type: individual\|business |

> [accordion] plivo numbers compliance get
>
> | Flag | Description |
> | - | - |
> | `--expand <value>` | comma-separated: end\_user,documents,linked\_numbers |

> [accordion] plivo numbers compliance update
>
> | Flag | Description |
> | - | - |
> | `--data <value>` | updated application JSON; inline or @file.json (required) |
> | `--file <value>` | document upload as field=path (repeatable; replaces all documents) |

> [accordion] plivo numbers compliance link
>
> | Flag | Description |
> | - | - |
> | `--data <value>` | full link JSON body; inline or @file.json (alternative to --link) |
> | `--link <value>` | number=compliance\_application\_id (repeatable) |
>
> ```bash theme={null}
> plivo numbers compliance link --link +14155551234="<compliance_id>" --link +14155556789="<compliance_id>"
> ```

## Number masking

A masking session connects two parties through a Plivo number so they don't see each other's phone numbers.

| Usage | What it does |
| - | - |
| `plivo numbers masking sessions create [flags]` | Create a masking session (spends money: requires --yes) |
| `plivo numbers masking sessions list [flags]` | List masking sessions |
| `plivo numbers masking sessions get <session_uuid>` | Get a masking session by uuid |
| `plivo numbers masking sessions delete <session_uuid>` | End a masking session (requires --yes) |

The API puts list rows at `data.response.objects`, and `--all`, `-o jsonl` and `-o csv` read them there. `get` returns the session under `response`.

> [accordion] plivo numbers masking sessions create
>
> | Flag | Description |
> | - | - |
> | `--call-time-limit <integer>` | max per-call duration in seconds |
> | `--first-party <value>` | first party E.164 (required) |
> | `--record` | record calls in this session |
> | `--second-party <value>` | second party E.164 (required) |
> | `--session-expiry <integer>` | session lifetime in seconds |