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
JavaScript
import Telnyx from 'telnyx';
const client = new Telnyx({
apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});
const response = await client.phoneNumbers.jobs.updateBatch({
phone_numbers: ['1583466971586889004', '+13127367254'],
});
console.log(response.data);import os
from telnyx import Telnyx
client = Telnyx(
api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted
)
response = client.phone_numbers.jobs.update_batch(
phone_numbers=["1583466971586889004", "+13127367254"],
)
print(response.data)
package main
import (
"context"
"fmt"
"github.com/team-telnyx/telnyx-go"
"github.com/team-telnyx/telnyx-go/option"
)
func main() {
client := telnyx.NewClient(
option.WithAPIKey("My API Key"),
)
response, err := client.PhoneNumbers.Jobs.UpdateBatch(context.TODO(), telnyx.PhoneNumberJobUpdateBatchParams{
PhoneNumbers: []string{"1583466971586889004", "+13127367254"},
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.Data)
}
package com.telnyx.sdk.example;
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.phonenumbers.jobs.JobUpdateBatchParams;
import com.telnyx.sdk.models.phonenumbers.jobs.JobUpdateBatchResponse;
public final class Main {
private Main() {}
public static void main(String[] args) {
TelnyxClient client = TelnyxOkHttpClient.fromEnv();
JobUpdateBatchParams params = JobUpdateBatchParams.builder()
.addPhoneNumber("1583466971586889004")
.addPhoneNumber("+13127367254")
.build();
JobUpdateBatchResponse response = client.phoneNumbers().jobs().updateBatch(params);
}
}require "telnyx"
telnyx = Telnyx::Client.new(api_key: "My API Key")
response = telnyx.phone_numbers.jobs.update_batch(phone_numbers: ["1583466971586889004", "+13127367254"])
puts(response)<?php
require_once dirname(__DIR__) . '/vendor/autoload.php';
use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;
$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');
try {
$response = $client->phoneNumbers->jobs->updateBatch(
phoneNumbers: ['1583466971586889004', '+13127367254'],
filter: [
'billingGroupID' => '62e4bf2e-c278-4282-b524-488d9c9c43b2',
'connectionID' => '1521916448077776306',
'customerReference' => 'customer_reference',
'emergencyAddressID' => '9102160989215728032',
'hasBundle' => 'has_bundle',
'phoneNumber' => 'phone_number',
'status' => 'active',
'tag' => 'tag',
'voiceConnectionName' => [
'contains' => 'test',
'endsWith' => 'test',
'eq' => 'test',
'startsWith' => 'test',
],
'voiceUsagePaymentMethod' => 'channel',
],
billingGroupID: 'dc8e4d67-33a0-4cbb-af74-7b58f05bd494',
connectionID: 'dc8e4d67-33a0-4cbb-af74-7b58f05bd494',
customerReference: 'customer-reference',
deletionLockEnabled: true,
externalPin: '123456',
hdVoiceEnabled: true,
tags: ['tag'],
voice: [
'callForwarding' => [
'callForwardingEnabled' => true,
'forwardingType' => 'always',
'forwardsTo' => '+13035559123',
],
'callRecording' => [
'inboundCallRecordingChannels' => 'single',
'inboundCallRecordingEnabled' => true,
'inboundCallRecordingFormat' => 'wav',
],
'callerIDNameEnabled' => true,
'cnamListing' => [
'cnamListingDetails' => 'example', 'cnamListingEnabled' => true
],
'inboundCallScreening' => 'disabled',
'mediaFeatures' => [
'acceptAnyRtpPacketsEnabled' => true,
'rtpAutoAdjustEnabled' => true,
't38FaxGatewayEnabled' => true,
],
'techPrefixEnabled' => true,
'translatedNumber' => '+13035559999',
'usagePaymentMethod' => 'pay-per-minute',
],
);
var_dump($response);
} catch (APIException $e) {
echo $e->getMessage();
}telnyx phone-numbers:jobs update-batch \
--api-key 'My API Key' \
--phone-number "'1583466971586889004'" \
--phone-number "'+13127367254'"curl --request POST \
--url https://api.telnyx.com/v2/phone_numbers/jobs/update_phone_numbers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"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"
}
}
}
'{
"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"
}
}
]
}
]
}
}
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
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]
Show child attributes
Show child attributes
Body
application/json
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').
A list of user-assigned tags to help organize phone numbers.
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.
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.
Example:
"MY REF 001"
Identifies the connection associated with the phone number.
Identifies the billing group associated with the phone number.
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.
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.
Show child attributes
Show child attributes
Example:
{ "tech_prefix_enabled": true, "translated_number": "+13035559999", "caller_id_name_enabled": true, "call_forwarding": { "call_forwarding_enabled": true, "forwards_to": "+13035559123", "forwarding_type": "always" }, "cnam_listing": { "cnam_listing_enabled": true, "cnam_listing_details": "example" }, "usage_payment_method": "pay-per-minute", "media_features": { "rtp_auto_adjust_enabled": true, "accept_any_rtp_packets_enabled": true, "t38_fax_gateway_enabled": true }, "call_recording": { "inbound_call_recording_enabled": true, "inbound_call_recording_format": "wav", "inbound_call_recording_channels": "single" }, "inbound_call_screening": "disabled" }
Response
Update job accepted. The response contains a background job; poll GET /phone_numbers/jobs/{id} with the job id until it completes.
Show child attributes
Show child attributes
Example:
{ "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" } } ] } ] }
Was this page helpful?
JavaScript
import Telnyx from 'telnyx';
const client = new Telnyx({
apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});
const response = await client.phoneNumbers.jobs.updateBatch({
phone_numbers: ['1583466971586889004', '+13127367254'],
});
console.log(response.data);import os
from telnyx import Telnyx
client = Telnyx(
api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted
)
response = client.phone_numbers.jobs.update_batch(
phone_numbers=["1583466971586889004", "+13127367254"],
)
print(response.data)
package main
import (
"context"
"fmt"
"github.com/team-telnyx/telnyx-go"
"github.com/team-telnyx/telnyx-go/option"
)
func main() {
client := telnyx.NewClient(
option.WithAPIKey("My API Key"),
)
response, err := client.PhoneNumbers.Jobs.UpdateBatch(context.TODO(), telnyx.PhoneNumberJobUpdateBatchParams{
PhoneNumbers: []string{"1583466971586889004", "+13127367254"},
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.Data)
}
package com.telnyx.sdk.example;
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.phonenumbers.jobs.JobUpdateBatchParams;
import com.telnyx.sdk.models.phonenumbers.jobs.JobUpdateBatchResponse;
public final class Main {
private Main() {}
public static void main(String[] args) {
TelnyxClient client = TelnyxOkHttpClient.fromEnv();
JobUpdateBatchParams params = JobUpdateBatchParams.builder()
.addPhoneNumber("1583466971586889004")
.addPhoneNumber("+13127367254")
.build();
JobUpdateBatchResponse response = client.phoneNumbers().jobs().updateBatch(params);
}
}require "telnyx"
telnyx = Telnyx::Client.new(api_key: "My API Key")
response = telnyx.phone_numbers.jobs.update_batch(phone_numbers: ["1583466971586889004", "+13127367254"])
puts(response)<?php
require_once dirname(__DIR__) . '/vendor/autoload.php';
use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;
$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');
try {
$response = $client->phoneNumbers->jobs->updateBatch(
phoneNumbers: ['1583466971586889004', '+13127367254'],
filter: [
'billingGroupID' => '62e4bf2e-c278-4282-b524-488d9c9c43b2',
'connectionID' => '1521916448077776306',
'customerReference' => 'customer_reference',
'emergencyAddressID' => '9102160989215728032',
'hasBundle' => 'has_bundle',
'phoneNumber' => 'phone_number',
'status' => 'active',
'tag' => 'tag',
'voiceConnectionName' => [
'contains' => 'test',
'endsWith' => 'test',
'eq' => 'test',
'startsWith' => 'test',
],
'voiceUsagePaymentMethod' => 'channel',
],
billingGroupID: 'dc8e4d67-33a0-4cbb-af74-7b58f05bd494',
connectionID: 'dc8e4d67-33a0-4cbb-af74-7b58f05bd494',
customerReference: 'customer-reference',
deletionLockEnabled: true,
externalPin: '123456',
hdVoiceEnabled: true,
tags: ['tag'],
voice: [
'callForwarding' => [
'callForwardingEnabled' => true,
'forwardingType' => 'always',
'forwardsTo' => '+13035559123',
],
'callRecording' => [
'inboundCallRecordingChannels' => 'single',
'inboundCallRecordingEnabled' => true,
'inboundCallRecordingFormat' => 'wav',
],
'callerIDNameEnabled' => true,
'cnamListing' => [
'cnamListingDetails' => 'example', 'cnamListingEnabled' => true
],
'inboundCallScreening' => 'disabled',
'mediaFeatures' => [
'acceptAnyRtpPacketsEnabled' => true,
'rtpAutoAdjustEnabled' => true,
't38FaxGatewayEnabled' => true,
],
'techPrefixEnabled' => true,
'translatedNumber' => '+13035559999',
'usagePaymentMethod' => 'pay-per-minute',
],
);
var_dump($response);
} catch (APIException $e) {
echo $e->getMessage();
}telnyx phone-numbers:jobs update-batch \
--api-key 'My API Key' \
--phone-number "'1583466971586889004'" \
--phone-number "'+13127367254'"curl --request POST \
--url https://api.telnyx.com/v2/phone_numbers/jobs/update_phone_numbers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"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"
}
}
}
'{
"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"
}
}
]
}
]
}
}