---
title: "Update a phone number"
method: PATCH
path: "/phone_numbers/{id}"
tags: ["Phone Number Configurations"]
---

# Update a phone number

`PATCH /phone_numbers/{id}`

Updates the configurable settings of the specified phone number. The response contains the complete updated phone-number representation.

## Path parameters

- `id` string, required

## Request body

- UpdatePhoneNumberRequest
  - `address_id` string — Identifies the address associated with the phone number.
  - `billing_group_id` string — Identifies the billing group associated with the phone number.
  - `connection_id` string — Identifies the connection associated with the phone number.
  - `customer_reference` string — A customer reference string for customer look ups.
  - `external_pin` string — If someone attempts to port your phone number away from Telnyx and your phone number has an external PIN set, we will attempt to verify that you provided the correct external PIN to the winning carrier. Note that not all carriers cooperate with this security mechanism.
  - `hd_voice_enabled` boolean — Indicates whether HD voice is enabled for this number.
  - `id` string — Identifies the type of resource.
  - `tags` string[] — A list of user-assigned tags to help organize phone numbers.

## Response `200`

Successful response with details about a phone number.

- object
  - `data` NumbersPhoneNumberDetailed
    - `activated_at` string, date-time, nullable — ISO 8601 formatted date indicating when the phone number was first activated (transitioned from purchase-pending or port-pending to active). Will be null for numbers that have not yet been activated, or for legacy numbers activated before this field was tracked.
    - `billing_group_id` string, nullable — Identifies the billing group associated with the phone number.
    - `call_forwarding_enabled` boolean — Indicates if call forwarding will be enabled for this number if forwards_to and forwarding_type are filled in. Defaults to true for backwards compatibility with APIV1 use of numbers endpoints.
    - `call_recording_enabled` boolean — Indicates whether call recording is enabled for this number.
    - `caller_id_name_enabled` boolean — Indicates whether caller ID is enabled for this number.
    - `cnam_listing_enabled` boolean — Indicates whether a CNAM listing is enabled for this number.
    - `connection_id` string, nullable — Identifies the connection associated with the phone number.
    - `connection_name` string, nullable — The user-assigned name of the connection to be associated with this phone number.
    - `country_iso_alpha2` string, required — The ISO 3166-1 alpha-2 country code of the phone number.
    - `created_at` string, date-time, required — ISO 8601 formatted date indicating when the resource was created.
    - `customer_reference` string, nullable — A customer reference string for customer look ups.
    - `deletion_lock_enabled` boolean, required — Indicates whether deletion lock is enabled for this number. When enabled, this prevents the phone number from being deleted via the API or Telnyx portal.
    - `emergency_address_id` string, nullable — Identifies the emergency address associated with the phone number.
    - `emergency_enabled` boolean — Indicates whether emergency services are enabled for this number.
    - `emergency_status` 'active' | 'deprovisioning' | 'disabled' | 'provisioning' | 'provisioning-failed' — Indicates the status of the provisioning of emergency services for the phone number. This field contains information about activity that may be ongoing for a number where it either is being provisioned or deprovisioned but is not yet enabled/disabled.
    - `external_pin` string, nullable, required — If someone attempts to port your phone number away from Telnyx and your phone number has an external PIN set, Telnyx will attempt to verify that you provided the correct external PIN to the winning carrier. Note that not all carriers cooperate with this security mechanism.
    - `hd_voice_enabled` boolean — Indicates whether HD voice is enabled for this number.
    - `id` string, required — Identifies the resource.
    - `inbound_call_screening` 'disabled' | 'reject_calls' | 'flag_calls' — The inbound_call_screening setting is a phone number configuration option variable that allows users to configure their settings to block or flag fraudulent calls. It can be set to disabled, reject_calls, or flag_calls. This feature has an additional per-number monthly cost associated with it.
    - `messaging_profile_id` string, nullable — Identifies the messaging profile associated with the phone number.
    - `messaging_profile_name` string, nullable — The name of the messaging profile associated with the phone number.
    - `phone_number` string, required — The +E.164-formatted phone number associated with this record.
    - `phone_number_type` 'local' | 'toll_free' | 'mobile' | 'national' | 'shared_cost' | 'landline' | 'tollfree' | 'shortcode' | 'longcode', required — The phone number's type. Note: For numbers purchased prior to July 2023 or when fetching a number's details immediately after a purchase completes, the legacy values `tollfree`, `shortcode` or `longcode` may be returned instead.
    - `purchased_at` string, required — ISO 8601 formatted date indicating when the resource was purchased.
    - `record_type` string, required — Identifies the type of the resource.
    - `source_type` 'number_order' | 'port_request', nullable — Indicates if the phone number was purchased or ported in. For some numbers this information may not be available.
    - `status` 'purchase-pending' | 'purchase-failed' | 'port-pending' | 'port-failed' | 'active' | 'deleted' | 'emergency-only' | 'ported-out' | 'port-out-pending' | 'requirement-info-pending' | 'requirement-info-under-review' | 'requirement-info-exception' | 'provision-pending', required — The phone number's current status.
    - `t38_fax_gateway_enabled` boolean — Indicates whether T38 Fax Gateway for inbound calls to this number.
    - `tags` string[], required — A list of user-assigned tags to help manage the phone number.
    - `updated_at` string — ISO 8601 formatted date indicating when the resource was updated.

## Other responses

- `400` — Bad request, the request was unacceptable, often due to missing a required parameter.
- `401` — Unauthorized
- `404` — The requested resource doesn't exist.
- `422` — Unprocessable entity. Check the 'detail' field in response for details.
- `500` — Unexpected error

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api-2/revisions/ec31f78cf002/schema)