Bulk Phone Number Operations

Update a batch of numbers

Changed on

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

Request

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

Query parameters

has_bundlestring

Filter by phone number that have bundles.

tagstring

Filter by phone number tags.

connection_idstring

Filter by connection_id.

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.

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

Filter by usage_payment_method.

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

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

customer_referencestring

Filter numbers via the customer_reference set.

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]

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

Request body

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.

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.

customer_referencestring

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_idstring

Identifies the connection associated with the phone number.

billing_group_idstring

Identifies the billing group associated with the phone number.

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.

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.

Example request

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

Response

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

Example response

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

Changes

  • 19db5ee4ec59Revision changes
    • breaking

      the // response's property type changed from integer to string, and format from int32 to no format for status

    • breaking

      the // response's property type changed from integer to string, and format from int32 to no format for status

    • breaking

      the // response's property type changed from integer to string, and format from int32 to no format for status

    • breaking

      the // response's property type changed from integer to string, and format from int32 to no format for status

    • breaking

      the // response's property type changed from integer to string, and format from int32 to no format for status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

  • da303e40b51eRevision changes
    • info

      added the optional property / to the response with the status