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, search for a US number, then preview and confirm the rental:

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.

​

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

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

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.

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

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

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:

plivo numbers compliance requirements --country IN --number-type local --user-type business

Use those requirements and the India number guide 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)

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)

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)

plivo numbers compliance create \
  --data @app.json \
  --file 'documents[0].file=@passport.pdf' \
  --file 'documents[1].file=@address-proof.pdf'

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

plivo numbers compliance get

Flag	Description
--expand <value>	comma-separated: end_user,documents,linked_numbers

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)

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)

plivo numbers compliance link --link [phone]="<compliance_id>" --link [phone]="<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.

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