Get a phone-number batch
Get a single phone-number batch by id. The enterprise is resolved server-side from the DIR id.
GET
/
dir
/
{dir_id}
/
phone_number_batches
/
{batch_id}
JavaScript
import Telnyx from 'telnyx';
const client = new Telnyx({
apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});
const phoneNumberBatch = await client.dir.phoneNumberBatches.retrieve(
'0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62',
{ dir_id: '16635d38-75a6-4481-82e8-69af60e05011' },
);
console.log(phoneNumberBatch.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
)
phone_number_batch = client.dir.phone_number_batches.retrieve(
batch_id="0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62",
dir_id="16635d38-75a6-4481-82e8-69af60e05011",
)
print(phone_number_batch.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"),
)
phoneNumberBatch, err := client.Dir.PhoneNumberBatches.Get(
context.TODO(),
"0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62",
telnyx.DirPhoneNumberBatchGetParams{
DirID: "16635d38-75a6-4481-82e8-69af60e05011",
},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", phoneNumberBatch.Data)
}
package com.telnyx.sdk.example;
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.dir.phonenumberbatches.PhoneNumberBatchRetrieveParams;
import com.telnyx.sdk.models.dir.phonenumberbatches.PhoneNumberBatchRetrieveResponse;
public final class Main {
private Main() {}
public static void main(String[] args) {
TelnyxClient client = TelnyxOkHttpClient.fromEnv();
PhoneNumberBatchRetrieveParams params = PhoneNumberBatchRetrieveParams.builder()
.dirId("16635d38-75a6-4481-82e8-69af60e05011")
.batchId("0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62")
.build();
PhoneNumberBatchRetrieveResponse phoneNumberBatch = client.dir().phoneNumberBatches().retrieve(params);
}
}require "telnyx"
telnyx = Telnyx::Client.new(api_key: "My API Key")
phone_number_batch = telnyx.dir.phone_number_batches.retrieve(
"0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62",
dir_id: "16635d38-75a6-4481-82e8-69af60e05011"
)
puts(phone_number_batch)<?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 {
$phoneNumberBatch = $client->dir->phoneNumberBatches->retrieve(
'0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62',
dirID: '16635d38-75a6-4481-82e8-69af60e05011',
);
var_dump($phoneNumberBatch);
} catch (APIException $e) {
echo $e->getMessage();
}telnyx dir:phone-number-batches retrieve \
--api-key 'My API Key' \
--dir-id 16635d38-75a6-4481-82e8-69af60e05011 \
--batch-id 0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62curl --request GET \
--url https://api.telnyx.com/v2/dir/{dir_id}/phone_number_batches/{batch_id} \
--header 'Authorization: Bearer <token>'{
"data": {
"batch_id": "ba74cfc6-d32b-467a-9b08-86fd154c23f7",
"dir_id": "74e1d8ed-fbdb-45a7-bbb0-a09c1184eb3d",
"dir_display_name": "Acme Plumbing",
"enterprise_id": "5c987b82-2e3b-442a-afbc-0ba3c515f561",
"total_count": 1,
"submitted_at": "2026-04-26T18:14:37.065870Z",
"documents": [
{
"document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c",
"document_type": "business_registration",
"description": "Certificate of incorporation."
}
],
"phone_numbers": [
{
"id": "1f56eb76-4078-4af7-ad4d-564b027256ee",
"dir_id": "16635d38-75a6-4481-82e8-69af60e05011",
"enterprise_id": "4a6192a4-573d-446d-b3ce-aff9117272a6",
"phone_number": "+19493253498",
"batch_id": "0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62",
"loa_document_id": null,
"rejection_reason": {
"code": "documentation_incomplete",
"title": "Documentation incomplete",
"detail": "Provided documents do not establish business identity.",
"message": "Please re-upload a clearer scan of the certificate."
},
"created_at": "2026-04-26T18:11:42.850928Z",
"updated_at": "2026-04-26T18:12:11.123456Z",
"verified_at": "2026-04-26T18:12:11.123456Z"
}
]
}
}
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The DIR id. Lowercase UUID.
Example:
"16635d38-75a6-4481-82e8-69af60e05011"
The batch id (lowercase UUID).
Example:
"0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62"
Response
Batch.
A phone-number batch groups all numbers added in a single bulk-add request. Telnyx vets the batch as a unit. The response embeds the full phone_numbers array so you can read per-number status without a separate call, plus a batch-level status summarising the unit's progress.
Show child attributes
Show child attributes
Was this page helpful?
⌘I
JavaScript
import Telnyx from 'telnyx';
const client = new Telnyx({
apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});
const phoneNumberBatch = await client.dir.phoneNumberBatches.retrieve(
'0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62',
{ dir_id: '16635d38-75a6-4481-82e8-69af60e05011' },
);
console.log(phoneNumberBatch.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
)
phone_number_batch = client.dir.phone_number_batches.retrieve(
batch_id="0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62",
dir_id="16635d38-75a6-4481-82e8-69af60e05011",
)
print(phone_number_batch.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"),
)
phoneNumberBatch, err := client.Dir.PhoneNumberBatches.Get(
context.TODO(),
"0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62",
telnyx.DirPhoneNumberBatchGetParams{
DirID: "16635d38-75a6-4481-82e8-69af60e05011",
},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", phoneNumberBatch.Data)
}
package com.telnyx.sdk.example;
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.dir.phonenumberbatches.PhoneNumberBatchRetrieveParams;
import com.telnyx.sdk.models.dir.phonenumberbatches.PhoneNumberBatchRetrieveResponse;
public final class Main {
private Main() {}
public static void main(String[] args) {
TelnyxClient client = TelnyxOkHttpClient.fromEnv();
PhoneNumberBatchRetrieveParams params = PhoneNumberBatchRetrieveParams.builder()
.dirId("16635d38-75a6-4481-82e8-69af60e05011")
.batchId("0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62")
.build();
PhoneNumberBatchRetrieveResponse phoneNumberBatch = client.dir().phoneNumberBatches().retrieve(params);
}
}require "telnyx"
telnyx = Telnyx::Client.new(api_key: "My API Key")
phone_number_batch = telnyx.dir.phone_number_batches.retrieve(
"0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62",
dir_id: "16635d38-75a6-4481-82e8-69af60e05011"
)
puts(phone_number_batch)<?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 {
$phoneNumberBatch = $client->dir->phoneNumberBatches->retrieve(
'0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62',
dirID: '16635d38-75a6-4481-82e8-69af60e05011',
);
var_dump($phoneNumberBatch);
} catch (APIException $e) {
echo $e->getMessage();
}telnyx dir:phone-number-batches retrieve \
--api-key 'My API Key' \
--dir-id 16635d38-75a6-4481-82e8-69af60e05011 \
--batch-id 0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62curl --request GET \
--url https://api.telnyx.com/v2/dir/{dir_id}/phone_number_batches/{batch_id} \
--header 'Authorization: Bearer <token>'{
"data": {
"batch_id": "ba74cfc6-d32b-467a-9b08-86fd154c23f7",
"dir_id": "74e1d8ed-fbdb-45a7-bbb0-a09c1184eb3d",
"dir_display_name": "Acme Plumbing",
"enterprise_id": "5c987b82-2e3b-442a-afbc-0ba3c515f561",
"total_count": 1,
"submitted_at": "2026-04-26T18:14:37.065870Z",
"documents": [
{
"document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c",
"document_type": "business_registration",
"description": "Certificate of incorporation."
}
],
"phone_numbers": [
{
"id": "1f56eb76-4078-4af7-ad4d-564b027256ee",
"dir_id": "16635d38-75a6-4481-82e8-69af60e05011",
"enterprise_id": "4a6192a4-573d-446d-b3ce-aff9117272a6",
"phone_number": "+19493253498",
"batch_id": "0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62",
"loa_document_id": null,
"rejection_reason": {
"code": "documentation_incomplete",
"title": "Documentation incomplete",
"detail": "Provided documents do not establish business identity.",
"message": "Please re-upload a clearer scan of the certificate."
},
"created_at": "2026-04-26T18:11:42.850928Z",
"updated_at": "2026-04-26T18:12:11.123456Z",
"verified_at": "2026-04-26T18:12:11.123456Z"
}
]
}
}