client.phone_numbers

Phone numbers on your account. These methods are on client.phone_numbers, where client is a MoreVoice client (see the Python SDK). On AsyncMoreVoice the same methods are awaited. Each one returns the response object and raises an exception when the API answers with an error.

`create()`

Create a sandbox number (test mode). With a test key: allocates a sandbox number (source: sandbox) in the +972 50 999 range, at no cost and with no carrier, at most 5 per organisation. Dial it with POST /v1/test_helpers/inbound_calls. A sandbox number never receives real calls. With a live key the endpoint is not available yet (buy numbers in the dashboard).

def create(self, body: _m.PhoneNumberCreateParamsInput | Mapping[str, Any] | Unset = UNSET, *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.PhoneNumber

client.phone_numbers.create() · await async_client.phone_numbers.create() · POST /phone_numbers · API reference

Request body

Field	Type	Required	Description
`assistant_id`	`string`	no	Inbound test calls to the number reach this assistant.
`flow_id`	`string`	no	Inbound test calls to the number run this published flow.
`inbound_route_id`	`string`	no	Inbound test calls to the number follow this inbound route.
`label`	`string`	no	A name for the number, shown in lists.

Returns

PhoneNumber:

Field	Type	Description
`id`	`string`	The number’s ID (stable).
`object`	`"phone_number"`	Always `phone_number`.
`livemode`	`boolean`	`true` in live mode, `false` in test mode.
`e164`	`string`	The number in E.164.
`country`	`string \| null`	ISO 3166-1 alpha-2, when known.
`source`	`"provisioned" \| "connection" \| "sandbox"`	`provisioned`: bought through the platform. `connection`: a number of your own SIP connection (its caller IDs and the numbers your inbound routes match). `sandbox`: a test-mode number.
`provider`	`string \| null`	The carrier of a provisioned number; null for your own connections.
`status`	`string`	`active`; provisioned numbers can also be `pending`, `pending_kyc`, `porting_in`, `suspended`, `releasing` or `released`.
`connection_id`	`string \| null`	`conn_…` ID.
`inbound_route_id`	`string \| null`	`rte_…` ID.
`label`	`string \| null`	—
`inbound`	`boolean`	Calls to the number are answered here (a route or connection matches it).
`outbound_caller_id`	`boolean`	The number can be presented as caller ID on outbound calls.
`created`	`string \| null`	When the number was added (null for numbers derived from a connection).

Example

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

phone_number = client.phone_numbers.create({
    "assistant_id": "asst_4Gk2LmN9pQ4rS6tV8wX0yZ",
    "label": "Support line (test)",
})
print(phone_number)

`delete()`

Release a sandbox number (test mode). With a test key: releases a sandbox number. With a live key the endpoint is not available yet.

def delete(self, id: str, *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.DeletedPhoneNumber

client.phone_numbers.delete() · await async_client.phone_numbers.delete() · DELETE /phone_numbers/{id} · API reference

Parameters

Name	Type	Required	Description
`id`	`str`	yes	A phone number ID (`pn_…`).

Returns

DeletedPhoneNumber:

Field	Type	Description
`id`	`string`	The released number’s ID.
`object`	`"phone_number"`	Always `phone_number`.
`deleted`	`true`	—

Example

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

deleted_phone_number = client.phone_numbers.delete("pn_7Hk2Lm9Qp")
print(deleted_phone_number)

`list()`

List phone numbers. Numbers bought through the platform, then the numbers of your own SIP connections (their caller IDs and the numbers your inbound routes match exactly). Test-mode keys list sandbox numbers.

def list(self, *, limit: int | Unset = 20, starting_after: str | Unset = UNSET, ending_before: str | Unset = UNSET, more_voice_version: str | Unset = UNSET) -> AsyncPage[_m.PhoneNumber]

client.phone_numbers.list() · await async_client.phone_numbers.list() · GET /phone_numbers · API reference

Parameters

Name	Type	Required	Description
`limit`	`integer`	no	How many objects to return, 1–100 (default 20).
`starting_after`	`string`	no	A cursor (`next_cursor`) or object ID: return the objects after it (older).
`ending_before`	`string`	no	A cursor or object ID: return the objects before it (newer).

Returns

A page of results (PhoneNumberList): data, has_more and next_cursor.

Example

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

for phone_number in client.phone_numbers.list():
    print(phone_number)

`retrieve()`

Retrieve a phone number. Returns a phone number: its E.164 form, where it comes from (source: a number of one of your SIP connections, a number provisioned through the platform, or a test-mode sandbox number), whether it answers inbound calls (and the route that answers them) and whether it can be the caller ID of outbound calls.

def retrieve(self, id: str, *, more_voice_version: str | Unset = UNSET) -> _m.PhoneNumber

client.phone_numbers.retrieve() · await async_client.phone_numbers.retrieve() · GET /phone_numbers/{id} · API reference

Parameters

Name	Type	Required	Description
`id`	`str`	yes	A phone number ID (`pn_…`).

Returns

PhoneNumber:

Field	Type	Description
`id`	`string`	The number’s ID (stable).
`object`	`"phone_number"`	Always `phone_number`.
`livemode`	`boolean`	`true` in live mode, `false` in test mode.
`e164`	`string`	The number in E.164.
`country`	`string \| null`	ISO 3166-1 alpha-2, when known.
`source`	`"provisioned" \| "connection" \| "sandbox"`	`provisioned`: bought through the platform. `connection`: a number of your own SIP connection (its caller IDs and the numbers your inbound routes match). `sandbox`: a test-mode number.
`provider`	`string \| null`	The carrier of a provisioned number; null for your own connections.
`status`	`string`	`active`; provisioned numbers can also be `pending`, `pending_kyc`, `porting_in`, `suspended`, `releasing` or `released`.
`connection_id`	`string \| null`	`conn_…` ID.
`inbound_route_id`	`string \| null`	`rte_…` ID.
`label`	`string \| null`	—
`inbound`	`boolean`	Calls to the number are answered here (a route or connection matches it).
`outbound_caller_id`	`boolean`	The number can be presented as caller ID on outbound calls.
`created`	`string \| null`	When the number was added (null for numbers derived from a connection).

Example

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

phone_number = client.phone_numbers.retrieve("pn_7Hk2Lm9Qp")
print(phone_number)