---
title: "Update a batch of numbers"
method: POST
path: "/phone_numbers/jobs/update_phone_numbers"
tags: ["Bulk Phone Number Operations"]
---

# Update a batch of numbers

`POST /phone_numbers/jobs/update_phone_numbers`

## Request

- Base URL: `https://api.telnyx.com/v2`
- URL: `https://api.telnyx.com/v2/phone_numbers/jobs/update_phone_numbers`
- Auth: HTTP bearer

Creates a new background job to update a batch of numbers. At most one thousand numbers can be updated per API call. At least one of the updateable fields must be submitted. IMPORTANT: You must either specify filters (using the filter parameters) or specific phone numbers (using the phone_numbers parameter in the request body). If you specify filters, ALL phone numbers that match the given filters (up to 1000 at a time) will be updated. If you want to update only specific numbers, you must use the phone_numbers parameter in the request body. When using the phone_numbers parameter, ensure you follow the correct format as shown in the example (either phone number IDs or phone numbers in E164 format).

## Query parameters

- `filter` object
  - `has_bundle` string: Filter by phone number that have bundles.
  - `tag` string: Filter by phone number tags.
  - `connection_id` string: Filter by connection_id.
  - `phone_number` string: Filter by phone number. Requires at least three digits. Non-numerical characters will result in no values being returned.
  - `status` 'purchase-pending' | 'purchase-failed' | 'port-pending' | 'active' | 'deleted' | 'port-failed' | 'emergency-only' | 'ported-out' | 'port-out-pending': Filter by phone number status.
  - `voice.connection_name` object: Filter by voice connection name pattern matching.
    - `contains` string: Filter contains connection name. Requires at least three characters.
    - `starts_with` string: Filter starts with connection name. Requires at least three characters.
    - `ends_with` string: Filter ends with connection name. Requires at least three characters.
    - `eq` string: Filter by connection name.
  - `voice.usage_payment_method` 'pay-per-minute' | 'channel': Filter by usage_payment_method.
  - `billing_group_id` string: Filter by the billing_group_id associated with phone numbers. To filter to only phone numbers that have no billing group associated them, set the value of this filter to the string 'null'.
  - `emergency_address_id` string: Filter by the emergency_address_id associated with phone numbers. To filter only phone numbers that have no emergency address associated with them, set the value of this filter to the string 'null'.
  - `customer_reference` string: Filter numbers via the customer_reference set.

## Request body

- NumbersPhoneNumbersJobUpdatePhoneNumbersRequest
  - `phone_numbers` string[], required: Array of phone number ids and/or phone numbers in E164 format to update. This parameter is required if no filter parameters are provided. If you want to update specific numbers rather than all numbers matching a filter, you must use this parameter. Each item must be either a valid phone number ID or a phone number in E164 format (e.g., '+13127367254').
  - `tags` string[]: A list of user-assigned tags to help organize phone numbers.
  - `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.
  - `customer_reference` string: Sets the customer reference on the selected phone numbers and retains the supplied value on the job. Recover the job without its ID using GET /phone_numbers/jobs with filter[customer_reference] within 90 days of job creation. This body field updates the numbers; the separate filter[customer_reference] query parameter selects numbers by their current reference.
  - `connection_id` string: Identifies the connection associated with the phone number.
  - `billing_group_id` string: Identifies the billing group associated with the phone number.
  - `hd_voice_enabled` boolean: Indicates whether to enable or disable HD Voice on each phone number. HD Voice is a paid feature and may not be available for all phone numbers, more details about it can be found in the Telnyx support documentation.
  - `deletion_lock_enabled` boolean: Indicates whether to enable or disable the deletion lock on each phone number. When enabled, this prevents the phone number from being deleted via the API or Telnyx portal.
  - `voice` UpdatePhoneNumberVoiceSettingsRequest
    - `tech_prefix_enabled` boolean: Controls whether a tech prefix is enabled for this phone number.
    - `translated_number` string: This field allows you to rewrite the destination number of an inbound call before the call is routed to you. The value of this field may be any alphanumeric value, and the value will replace the number originally dialed.
    - `caller_id_name_enabled` boolean: Controls whether the caller ID name is enabled for this phone number.
    - `call_forwarding` CallForwarding: The call forwarding settings for a 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.
      - `forwards_to` string: The phone number to which inbound calls to this number are forwarded. Inbound calls will not be forwarded if this field is left blank. If set, must be a +E.164-formatted phone number.
      - `forwarding_type` 'always' | 'on-failure': Call forwarding type. 'forwards_to' must be set for this to have an effect.
    - `cnam_listing` CnamListing: The CNAM listing settings for a phone number.
      - `cnam_listing_enabled` boolean: Enables CNAM listings for this number. Requires cnam_listing_details to also be set.
      - `cnam_listing_details` string: The CNAM listing details for this number. Must be alphanumeric characters or spaces with a maximum length of 15. Requires cnam_listing_enabled to also be set to true.
    - `usage_payment_method` 'pay-per-minute' | 'channel': Controls whether a number is billed per minute or uses your concurrent channels.
    - `media_features` MediaFeatures: The media features settings for a phone number.
      - `rtp_auto_adjust_enabled` boolean: When RTP Auto-Adjust is enabled, the destination RTP address port will be automatically changed to match the source of the incoming RTP packets.
      - `accept_any_rtp_packets_enabled` boolean: When enabled, Telnyx will accept RTP packets from any customer-side IP address and port, not just those to which Telnyx is sending RTP.
      - `t38_fax_gateway_enabled` boolean: Controls whether Telnyx will accept a T.38 re-INVITE for this phone number. Note that Telnyx will not send a T.38 re-INVITE; this option only controls whether one will be accepted.
    - `call_recording` CallRecording: The call recording settings for a phone number.
      - `inbound_call_recording_enabled` boolean: When enabled, any inbound call to this number will be recorded.
      - `inbound_call_recording_format` 'wav' | 'mp3': The audio file format for calls being recorded.
      - `inbound_call_recording_channels` 'single' | 'dual': When using 'dual' channels, final audio file will be stereo recorded with the first leg on channel A, and the rest on channel B.
    - `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.

## Response `202`

Update job accepted. The response contains a background job; poll GET /phone_numbers/jobs/{id} with the job id until it completes.

- object
  - `data` NumbersPhoneNumbersJob
    - `parameters` object: Effective parameters saved when the job was created, not a snapshot of the original HTTP request or current phone-number settings. Update jobs include the saved update fields; emergency-settings jobs include the saved emergency fields; delete jobs include only targets. Absent fields are omitted, and saved false, null and empty values are preserved. Tags may be normalized to arrays; filter-created jobs contain resolved target identifiers rather than the original filters. Historical jobs with no saved arguments return an empty object.
      - `phone_numbers` union[]: Saved target phone numbers in E.164 format and/or identifiers. Jobs created using filters contain the resolved identifiers, not the original filter expression. Stored identifier types are preserved.
        - union
          - string
          - integer
      - `external_pin` string, nullable: Saved external_pin supplied for an update_phone_numbers job.
      - `connection_id` string, nullable: Saved connection_id supplied for an update_phone_numbers job.
      - `customer_reference` string, nullable: Saved customer_reference supplied for an update_phone_numbers job.
      - `billing_group_id` string, nullable: Saved billing_group_id supplied for an update_phone_numbers job.
      - `hd_voice_enabled` boolean, nullable: Saved hd_voice_enabled supplied for an update_phone_numbers job.
      - `deletion_lock_enabled` boolean, nullable: Saved deletion_lock_enabled supplied for an update_phone_numbers job.
      - `tags` string[], nullable: Saved tags for an update_phone_numbers job. Values reflect creation-time normalization.
      - `add_tags` string[], nullable: Saved add_tags for an update_phone_numbers job. Values reflect creation-time normalization.
      - `remove_tags` string[], nullable: Saved remove_tags for an update_phone_numbers job. Values reflect creation-time normalization.
      - `voice` object: Saved voice settings for an update_phone_numbers job, using the public field names and nesting. Only settings present at creation are returned.
        - `tech_prefix_enabled` boolean, nullable: Saved tech_prefix_enabled setting.
        - `caller_id_name_enabled` boolean, nullable: Saved caller_id_name_enabled setting.
        - `usage_payment_method` string, nullable: Saved usage_payment_method setting.
        - `inbound_call_screening` string, nullable: Saved inbound_call_screening setting.
        - `call_forwarding` object
          - `forwards_to` string, nullable: Saved forwards_to setting.
          - `forwarding_type` string, nullable: Saved forwarding_type setting.
          - `call_forwarding_enabled` boolean, nullable: Saved call_forwarding_enabled setting.
        - `call_recording` object
          - `inbound_call_recording_enabled` boolean, nullable: Saved inbound_call_recording_enabled setting.
          - `inbound_call_recording_channels` string, nullable: Saved inbound_call_recording_channels setting.
          - `inbound_call_recording_format` string, nullable: Saved inbound_call_recording_format setting.
          - `record_continue_on_hold` boolean, nullable: Saved record_continue_on_hold setting.
        - `media_features` object
          - `rtp_auto_adjust_enabled` boolean, nullable: Saved rtp_auto_adjust_enabled setting.
          - `accept_any_rtp_packets_enabled` boolean, nullable: Saved accept_any_rtp_packets_enabled setting.
          - `t38_fax_gateway_enabled` boolean, nullable: Saved t38_fax_gateway_enabled setting.
        - `cnam_listing` object
          - `cnam_listing_enabled` boolean, nullable: Saved cnam_listing_enabled setting.
          - `cnam_listing_details` string, nullable: Saved cnam_listing_details setting.
      - `emergency_enabled` boolean, nullable: Saved emergency-services setting for an update_emergency_settings job.
      - `emergency_address_id` string, nullable: Saved emergency address identifier for an update_emergency_settings job. An explicitly supplied null is preserved.
    - `id` string, uuid: Identifies the resource.
    - `record_type` string: Identifies the type of the resource.
    - `status` 'pending' | 'in_progress' | 'completed' | 'failed' | 'expired': Indicates the completion status of the background update.
    - `type` 'update_emergency_settings' | 'delete_phone_numbers' | 'update_phone_numbers': Identifies the type of the background job.
    - `etc` string, date-time: ISO 8601 formatted date indicating when the estimated time of completion of the background job.
    - `created_at` string: ISO 8601 formatted date indicating when the resource was created.
    - `updated_at` string: ISO 8601 formatted date indicating when the resource was updated.
    - `phone_numbers` PhoneNumbersJobPhoneNumber[]
      - `phone_number` string: The phone number in e164 format.
      - `id` string: The phone number's ID
    - `successful_operations` PhoneNumbersJobSuccessfulOperation[]
      - `phone_number` string: The phone number in e164 format.
      - `id` string: The phone number's ID
    - `pending_operations` PhoneNumbersJobPendingOperation[]
      - `phone_number` string: The phone number in e164 format.
      - `id` string: The phone number's ID
    - `failed_operations` NumbersPhoneNumbersJobFailedOperation[]
      - `phone_number` string: The phone number in e164 format.
      - `id` string: The phone number's ID
      - `errors` NumbersError73c9788e53[]
        - `code` string
        - `title` string
        - `detail` string
        - `source` object
          - `pointer` string: JSON pointer (RFC6901) to the offending entity.
          - `parameter` string: Indicates which query parameter caused the error.
        - `meta` object
          - `url` string: URL with additional information on the error.

## Other responses

- `400`: Bad request, the request was unacceptable, often due to missing a required parameter.
- `401`: Unauthorized
- `403`: Forbidden
- `422`: Unprocessable Entity
- `500`: Unexpected error

## Changes

- **2026-10-21** `67df31283a8a`: 5 breaking, 5 info
  - the `errors/items/code` response's property type changed from `integer` to `string`, and format from `int32` to no format for status `400`
  - the `errors/items/code` response's property type changed from `integer` to `string`, and format from `int32` to no format for status `401`
  - the `errors/items/code` response's property type changed from `integer` to `string`, and format from `int32` to no format for status `403`
  - the `errors/items/code` response's property type changed from `integer` to `string`, and format from `int32` to no format for status `422`
  - …6 more
- **2026-10-15** `a72569d69430`: 5 breaking, 5 warning, 11 info
  - the `errors/items/code` response's property type changed from `string` to `integer`, and format from no format to `int32` for status `400`
  - the `errors/items/code` response's property type changed from `string` to `integer`, and format from no format to `int32` for status `401`
  - the `errors/items/code` response's property type changed from `string` to `integer`, and format from no format to `int32` for status `403`
  - the `errors/items/code` response's property type changed from `string` to `integer`, and format from no format to `int32` for status `422`
  - …17 more

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api/changes/phone_numbers/jobs/update_phone_numbers/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api/revisions/0f17b8167873?raw)