Sign in

v52

OpenAPI 3.1.0raw.githubusercontent.com2026-07-311,1941,9384.1 MB
Bulk Phone Number Operations

Update a batch of numbers

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

post/phone_numbers/jobs/update_phone_numbers

Query parameters

billing_group_idstring

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

connection_idstring

Filter by connection_id.

customer_referencestring

Filter numbers via the customer_reference set.

emergency_address_idstring

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

has_bundlestring

Filter by phone number that have bundles.

phone_numberstring

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.

tagstring

Filter by phone number tags.

voice.usage_payment_method'pay-per-minute' | 'channel'

Filter by usage_payment_method.

Consolidated filter parameter (deepObject style). Originally: filter[has_bundle], filter[tag], filter[connection_id], filter[phone_number], filter[status], filter[voice.connection_name], filter[voice.usage_payment_method], filter[billing_group_id], filter[emergency_address_id], filter[customer_reference]

{
  "billing_group_id": "62e4bf2e-c278-4282-b524-488d9c9c43b2",
  "connection_id": "1521916448077776306",
  "emergency_address_id": "9102160989215728032",
  "status": "active",
  "voice.connection_name": {
    "contains": "test",
    "ends_with": "test",
    "eq": "test",
    "starts_with": "test"
  },
  "voice.usage_payment_method": "channel"
}

Request body

billing_group_idstring

Identifies the billing group associated with the phone number.

connection_idstring

Identifies the connection associated with the phone number.

customer_referencestring

A customer reference string for customer look ups.

deletion_lock_enabledboolean

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.

external_pinstring

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_enabledboolean

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.

phone_numbersstring[] 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').

tagsstring[]

A list of user-assigned tags to help organize phone numbers.

Example request

{
  "billing_group_id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
  "connection_id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
  "customer_reference": "customer-reference",
  "deletion_lock_enabled": true,
  "external_pin": "123456",
  "phone_numbers": [
    "1583466971586889004",
    "+13127367254"
  ],
  "tags": [
    "tag"
  ],
  "voice": {
    "call_forwarding": {
      "call_forwarding_enabled": true,
      "forwarding_type": "always",
      "forwards_to": "+13035559123"
    }
  }
}

Response

Phone numbers job update phone numbers requested.

Example response

{
  "data": {
    "created_at": "2020-10-23T18:10:00.000Z",
    "etc": "2020-10-30T18:10:00.000Z",
    "failed_operations": [
      {
        "errors": [
          {
            "code": "10015",
            "detail": "The field is invalid.",
            "source": {
              "pointer": "/emergency_address_id"
            },
            "title": "Bad Request"
          }
        ],
        "id": "3388768018273",
        "phone_number": "+19705551234"
      }
    ],
    "id": "42587e44-3a3e-46de-9255-0c9a7a1d1ec7",
    "pending_operations": [
      {
        "id": "2637816387126861837",
        "phone_number": "+19705555099"
      }
    ],
    "phone_numbers": [
      {
        "id": "2637816387126861836"
      },
      {
        "phone_number": "+19715555098"
      },
      {
        "phone_number": "+19705555099"
      },
      {
        "id": "3388768018273"
      }
    ],
    "record_type": "phone_numbers_job",
    "status": "pending",
    "successful_operations": [
      {
        "id": "2637816387126861836",
        "phone_number": "+19705555098"
      },
      {
        "id": "33081887126861836",
        "phone_number": "+19715555098"
      }
    ],
    "type": "update_emergency_settings",
    "updated_at": "2020-10-23T18:10:01.000Z"
  }
}