# Service enfonica.numbering.v1beta1.PhoneNumberInstances

## Methods

| CreatePhoneNumberInstance |
| -- |
| <span class="e-code">rpc CreatePhoneNumberInstance(<span class="e-code">[CreatePhoneNumberInstanceRequest](#createphonenumberinstancerequest)</span>) returns (<span class="e-code">[PhoneNumberInstance](#resource-phonenumberinstance)</span>)</span><br/><br/>Creates a phone number instance. This provisions a phone number against a project.<br/><br/>The caller must have `numbering.phoneNumberInstances.create` permission on the project. |

| DeletePhoneNumberInstance |
| -- |
| <span class="e-code">rpc DeletePhoneNumberInstance(<span class="e-code">[DeletePhoneNumberInstanceRequest](#deletephonenumberinstancerequest)</span>) returns (<span class="e-code">[PhoneNumberInstance](#resource-phonenumberinstance)</span>)</span><br/><br/>Deletes a phone number instance. This disconnects the phone number.<br/><br/>The caller must have `numbering.phoneNumberInstances.delete` permission on the project. |

| GetPhoneNumberInstance |
| -- |
| <span class="e-code">rpc GetPhoneNumberInstance(<span class="e-code">[GetPhoneNumberInstanceRequest](#getphonenumberinstancerequest)</span>) returns (<span class="e-code">[PhoneNumberInstance](#resource-phonenumberinstance)</span>)</span><br/><br/>Retrieves a phone number instance identified by the supplied resource name.<br/><br/>The caller must have `numbering.phoneNumberInstances.get` permission on the project. |

| ListPhoneNumberInstances |
| -- |
| <span class="e-code">rpc ListPhoneNumberInstances(<span class="e-code">[ListPhoneNumberInstancesRequest](#listphonenumberinstancesrequest)</span>) returns (<span class="e-code">[ListPhoneNumberInstancesResponse](#listphonenumberinstancesresponse)</span>)</span><br/><br/>Lists all phone number instances.<br/><br/>List returns phone number instances sorted by `create_time` descending.<br/><br/>The caller must have `numbering.phoneNumberInstances.list` permission on the project. |

| MovePhoneNumberInstance |
| -- |
| <span class="e-code">rpc MovePhoneNumberInstance(<span class="e-code">[MovePhoneNumberInstanceRequest](#movephonenumberinstancerequest)</span>) returns (<span class="e-code">[PhoneNumberInstance](#resource-phonenumberinstance)</span>)</span><br/><br/>Moves the phone number instance to another project.<br/><br/>Warning: moving a phone number instance may cause the current configuration of the phone number instance to stop working. Any connected flows or SIP domains will need to be reconfigured in the destination project. Any programmable handler will need to accept the signing key of the destination project.<br/><br/>The caller must have `numbering.phoneNumberInstances.move` permission on both the source and destination projects. |

| SplitRange |
| -- |
| <span class="e-code">rpc SplitRange(<span class="e-code">[SplitRangeRequest](#splitrangerequest)</span>) returns (<span class="e-code">[SplitRangeResponse](#splitrangeresponse)</span>)</span><br/><br/>Splits a phone number range into two ranges.<br/><br/>To split a range, you specify how many numbers to keep in this range. These numbers are taken from the start of the range. The remaining numbers will be moved into a new range.<br/><br/>For example, if you have a range +61255501100-99 and you split it with a `size` of 20, then: - the original range will be modified to +61255501100-19 (size 20) - a new range will be created with +61255501120-99 (size 80)<br/><br/>The caller must have `numbering.phoneNumberInstances.splitRange` permission on the project. |

| UpdatePhoneNumberInstance |
| -- |
| <span class="e-code">rpc UpdatePhoneNumberInstance(<span class="e-code">[UpdatePhoneNumberInstanceRequest](#updatephonenumberinstancerequest)</span>) returns (<span class="e-code">[PhoneNumberInstance](#resource-phonenumberinstance)</span>)</span><br/><br/>Updates a phone number instance.<br/><br/>The caller must have `numbering.phoneNumberInstances.update` permission on the project.  |

## Resource: PhoneNumberInstance

The phone number instance resource.

A phone number instance represents a provisioned phone number or range of phone numbers.

Fields | &nbsp;
--|--
<span class="e-code">name</span> | <span class="e-code">string</span><br/>Resource name of the phone number instance. It must match the pattern `projects/*/phoneNumberInstances/*`
<span class="e-code">phone_number</span> | <span class="e-code">[PhoneNumber](/docs/phone-numbers/api-reference/rpc/enfonica.numbering.v1beta1/PhoneNumbers/#resource-phonenumber)</span><br/>The phone number associated with the instance. Can only be set on creation.
<span class="e-code">display_name</span> | <span class="e-code">string</span><br/>The display name of the phone number for use in the UI. Max length 100 characters.
<span class="e-code">labels</span> | <span class="e-code">map<<span class="e-code">string</span>, <span class="e-code">string</span>></span><br/>The labels associated with the phone number. Max key length 100.  Max value length 1000. Max keys 50.
<span class="e-code">incoming_message_handler_uris[]</span> | <span class="e-code">string</span><br/>List of URIs in priority order where incoming messages will be sent to.<br/><br/>The first URI is the primary, and the subsequent URIs are used in order if the previous URIs fail.  If no URIs are specified, then no action is taken when receiving messages.<br/><br/>Currently URIs must be fully qualified HTTP/HTTPS URLs, but this may change to include other types of URIs.<br/><br/>Maximum 5 URIs.
<span class="e-code">incoming_call_handler_uris[]</span> | <span class="e-code">string</span><br/>List of URIs in priority order that will be executed for incoming calls.<br/><br/>The first URI is the primary, and the subsequent URIs are used in order if the previous URIs fail.  If no URIs are specified, then no action is taken when receiving messages.<br/><br/>The following URIs are supported: - absolute `http` and `https` URIs. - `sip` URIs in the format sip:user@domain.com[:port] - `tel` URIs in the format tel:+phone_number<br/><br/>Additional URIs may be supported in the future.<br/><br/>Maximum 5 URIs.
<span class="e-code">call_recording_trigger</span> | <span class="e-code">[RecordingTrigger](#phonenumberinstancerecordingtrigger)</span><br/>The trigger that will start call recording.<br/><br/>You need to comply with certain laws and regulations, including those regarding obtaining consent to record. Enfonica recommends that you consult with your legal counsel to make sure that you are complying with all applicable laws in connection with communications you record or store using Enfonica.<br/><br/>Defaults to DISABLED.
<span class="e-code">create_time</span> | <span class="e-code"><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#timestamp" target="_blank">google.protobuf.Timestamp</a></span><br/>Output only. The creation time of the phone number instance.
<span class="e-code">delete_time</span> | <span class="e-code"><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#timestamp" target="_blank">google.protobuf.Timestamp</a></span><br/>Output only. The deletion time of the phone number instance, if it has been deleted.
<span class="e-code">activate_time</span> | <span class="e-code"><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#timestamp" target="_blank">google.protobuf.Timestamp</a></span><br/>Output only. The time when the phone number instance became active. For a phone number purchased from inventory, this should match `create_time`. For a phone number that was ported in, this will be the time when the port in was successful. If not set, the instance has not become active. Output only.
<span class="e-code">lifecycle_state</span> | <span class="e-code">[LifecycleState](#phonenumberinstancelifecyclestate)</span><br/>Output only. The state of the phone number instance in its lifecycle.
<span class="e-code">range</span> | <span class="e-code">[PhoneNumberRange](#phonenumberrange)</span><br/>Output only. If this resource represents a range of phone numbers, this field will be set and will contain the details of the range. If this field is unset, this resource represents a single phone number.
<span class="e-code">regulatory_listing</span> | <span class="e-code">string</span><br/>Output only. The regulatory listing associated with this phone number instance. This field specifies the end-user that is using this resource. The requirements for regulatory listings varies depending on the region and type of phone number. Of the form `projects/*/regulatoryListings/*`.
<span class="e-code">compliant</span> | <span class="e-code">boolean</span><br/>Output only. Whether this phone number instance is compliant with the regulations for phone numbers that Enfonica has inferred. The value of this field is not a substitute for independent legal advice and should be used as a guide only.

## Resource: PhoneNumber

The PhoneNumber resource.

Fields | &nbsp;
--|--
<span class="e-code">name</span> | <span class="e-code">string</span><br/>Resource name of the phone number. It must match the pattern `phoneNumbers/*`
<span class="e-code">phone_number</span> | <span class="e-code">string</span><br/>The phone number, in +E164 format.
<span class="e-code">capabilities[]</span> | <span class="e-code">[PhoneNumberCapability](/docs/phone-numbers/api-reference/rpc/enfonica.numbering.v1beta1/PhoneNumbers/#phonenumberphonenumbercapability)</span><br/>The capabilities of the phone number.
<span class="e-code">sku</span> | <span class="e-code">string</span><br/>The SKU that will be used to bill the phone number for the monthly service charge. In the form `services/*/skus/*`. Output only.
<span class="e-code">activation_sku</span> | <span class="e-code">string</span><br/>The SKU that will be used to bill the phone number for the once-off activation charge. In the form `services/*/skus/*`. If not set, there is no activation charge. Output only.
<span class="e-code">number_type</span> | <span class="e-code">[PhoneNumberType](/docs/phone-numbers/api-reference/rpc/enfonica.numbering.v1beta1/PhoneNumbers/#phonenumberphonenumbertype)</span><br/>The type of phone number.
<span class="e-code">country_code</span> | <span class="e-code">string</span><br/>The alpha-2 country code that identifies the country associated with the phone number. 

## PhoneNumberInstance.LifecycleState

Lifecycle states of phone number instances.

Enums | &nbsp;
--|--
<span class="e-code">LIFECYCLE_STATE_UNSPECIFIED</span> | Unspecified lifecycle state.
<span class="e-code">ACTIVE</span> | The phone number instance is active and can be used.
<span class="e-code">DELETED</span> | The phone number instance has been deleted.
<span class="e-code">SUSPENDED</span> | The phone number instance has been suspended.
<span class="e-code">PENDING</span> | Activation for this phone number instance is pending, possibly because the associated phone number is awaiting port in.<br/><br/>This state is used when the associated phone number has not yet been activated (ie its `activate_time` is not set).

## PhoneNumberInstance.RecordingTrigger

The trigger to start call recording.

Enums | &nbsp;
--|--
<span class="e-code">RECORDING_TRIGGER_UNSPECIFIED</span> | Unspecified recording trigger.
<span class="e-code">DISABLED</span> | Recording is disabled for calls to this phone number instance.
<span class="e-code">ANSWER</span> | Recording will begin when calls to this phone number instance are answered.
<span class="e-code">BRIDGE</span> | Recording will begin when calls to this phone number instance are bridged. This won't include any messages or menus played before the call was bridged. This is useful if you want to record only conversations.

## PhoneNumberRange

Describes a phone number range.

A phone number range is a group of phone number instances that are managed by a primary phone number instance representing the first phone number in the range.

Phone number ranges simplify the management of multiple contiguous phone numbers.

Fields | &nbsp;
--|--
<span class="e-code">primary_phone_number_instance</span> | <span class="e-code">string</span><br/>The resource name of the primary phone number instance of the range.
<span class="e-code">start_phone_number</span> | <span class="e-code">string</span><br/>The first phone number in the range.
<span class="e-code">end_phone_number</span> | <span class="e-code">string</span><br/>The last phone number in the range.
<span class="e-code">size</span> | <span class="e-code">int32</span><br/>The total quantity of phone numbers in the range.

## PhoneNumber.PhoneNumberCapability

A capability of a phone number.

Enums | &nbsp;
--|--
<span class="e-code">PHONE_NUMBER_CAPABILITY_UNSPECIFIED</span> | Unspecified phone number capability.
<span class="e-code">SMS</span> | The phone number is capable of SMS.
<span class="e-code">MMS</span> | The phone number is capable of MMS.
<span class="e-code">VOICE</span> | The phone number is capable of voice.

## PhoneNumber.PhoneNumberType

The type of phone number.

Enums | &nbsp;
--|--
<span class="e-code">PHONE_NUMBER_TYPE_UNSPECIFIED</span> | Unspecified phone number type.
<span class="e-code">LOCAL</span> | The phone number is a local phone number and corresponds to a specific geography within a country.
<span class="e-code">NATIONAL</span> | The phone number is a national phone number and is independent of geography within a country.
<span class="e-code">MOBILE</span> | The phone number is a mobile-only phone number and is independent of geography within a country.
<span class="e-code">TOLL_FREE</span> | The phone number is a toll-free number, where the caller can call the number typically without any cost to the caller.
<span class="e-code">SHARED_RATE</span> | The phone number is a shared-rate number, where both the caller and holder of the phone number both typically share in the cost of calls to the phone number.

## CreatePhoneNumberInstanceRequest

Request to create a new phone number instance.

Fields | &nbsp;
--|--
<span class="e-code">parent</span> | <span class="e-code">string</span><br/>Required. The project under which to create the phone number instance in the form `projects/*`.
<span class="e-code">phone_number_instance</span> | <span class="e-code">[PhoneNumberInstance](#resource-phonenumberinstance)</span><br/>Required. The phone number resource to be created. At minimum, you must supply `phone_number.phone_number`.

## GetPhoneNumberInstanceRequest

The GetPhoneNumberInstance request message.

Fields | &nbsp;
--|--
<span class="e-code">name</span> | <span class="e-code">string</span><br/>Required. The resource name of the phone number instance to retrieve. Must be of the form `projects/*/phoneNumberInstances/*`.

## ListPhoneNumberInstancesRequest

The ListPhoneNumberInstances request.

Fields | &nbsp;
--|--
<span class="e-code">parent</span> | <span class="e-code">string</span><br/>Required. The project under which to list phone number instance, in the form `projects/*`.
<span class="e-code">page_size</span> | <span class="e-code">int32</span><br/>The maximum number of phone number instance to return in the response. Default value of 10 and maximum value of 100.
<span class="e-code">page_token</span> | <span class="e-code">string</span><br/>A pagination token returned from a previous call to `ListPhoneNumberInstances` that indicates where this listing should continue from.
<span class="e-code">prefix</span> | <span class="e-code">string</span><br/>The prefix, either in E164 or 0NSN, of numbers to retrieve. 
<span class="e-code">include_deleted</span> | <span class="e-code">boolean</span><br/>Whether to include deleted phone numbers in the response. Defaults to false. 

## ListPhoneNumberInstancesResponse

The ListPhoneNumberInstances response.

Fields | &nbsp;
--|--
<span class="e-code">phone_number_instances[]</span> | <span class="e-code">[PhoneNumberInstance](#resource-phonenumberinstance)</span><br/>A possibly paginated list of phone number instance that are direct descendants of the specified parent resource.
<span class="e-code">next_page_token</span> | <span class="e-code">string</span><br/>A pagination token returned from a previous call to `ListPhoneNumberInstances` that indicates from where listing should continue.

## UpdatePhoneNumberInstanceRequest

The request message for updating a phonenumberinstance's properties.

Fields | &nbsp;
--|--
<span class="e-code">name</span> | <span class="e-code">string</span><br/>Required. The name of the phone number instance to be updated. Must be of the form `projects/*/phoneNumberInstances/*`. 
<span class="e-code">phone_number_instance</span> | <span class="e-code">[PhoneNumberInstance](#resource-phonenumberinstance)</span><br/>Required. The new definition of the PhoneNumberInstance.
<span class="e-code">update_mask</span> | <span class="e-code"><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask" target="_blank">google.protobuf.FieldMask</a></span><br/>Fields to be updated.

## DeletePhoneNumberInstanceRequest

The DeletePhoneNumberInstance request message.

Fields | &nbsp;
--|--
<span class="e-code">name</span> | <span class="e-code">string</span><br/>Required. The resource name of the phone number instance to be deleted. Must be of the form `projects/*/phoneNumberInstances/*`.

## MovePhoneNumberInstanceRequest

The MovePhoneNumberInstance request message.

Fields | &nbsp;
--|--
<span class="e-code">name</span> | <span class="e-code">string</span><br/>Required. The name of the phone number instance to move. Must be of the form `projects/*/phoneNumberInstances/*`.
<span class="e-code">destination_parent</span> | <span class="e-code">string</span><br/>Required. The new parent project to move the phone number instance to. Must be of the form `projects/*`.
<span class="e-code">regulatory_listing</span> | <span class="e-code">string</span><br/>Output only. The regulatory listing in the destination project to associate with this phone number instance. The requirements for regulatory listings varies depending on the region and type of phone number. Of the form `projects/*/regulatoryListings/*`.

## SplitRangeRequest

The SplitRange request message.

Fields | &nbsp;
--|--
<span class="e-code">phone_number_instance</span> | <span class="e-code">string</span><br/>Required. The name of the phone number instance to split. It must represent a range. Must be of the form `projects/*/phoneNumberInstances/*`.
<span class="e-code">size</span> | <span class="e-code">int32</span><br/>Required. The quantity of numbers to keep in the range of the specified phone number instance. The remaining numbers will be moved to a new range.

## SplitRangeResponse

The SplitRange response message.

Fields | &nbsp;
--|--
<span class="e-code">first</span> | <span class="e-code">[PhoneNumberInstance](#resource-phonenumberinstance)</span><br/>The first range, representing the phone number instance that was split.
<span class="e-code">second</span> | <span class="e-code">[PhoneNumberInstance](#resource-phonenumberinstance)</span><br/>The second range, representing the remaining phone numbers in the range.

