---
title: "List phone-number batches for a DIR"
method: GET
path: "/dir/{dir_id}/phone_number_batches"
tags: ["Phone Number Batches"]
---

# List phone-number batches for a DIR

`GET /dir/{dir_id}/phone_number_batches`

## Request

- Base URL: `https://api.telnyx.com/v2`
- URL: `https://api.telnyx.com/v2/dir/{dir_id}/phone_number_batches`
- Auth: HTTP bearer

List the phone-number batches submitted under a DIR. The enterprise is resolved server-side from the DIR id.

## Path parameters

- `dir_id` string, uuid, required

## Query parameters

- `page[number]` integer
- `page[size]` integer
- `filter[status]` 'submitted' | 'in_review' | 'verified' | 'unsuccessful' | 'suspended' | 'expired' | 'permanently_rejected': Phone-number lifecycle status. - `submitted` / `in_review` - Telnyx is reviewing the batch this number belongs to. - `verified` - approved; the DIR's display identity will be shown on outbound calls from this number. - `unsuccessful` - Telnyx rejected this submission; the customer may re-add to retry. - `suspended` - temporarily disabled (e.g. by an active infringement claim on the DIR). - `expired` - verification expired; re-add to renew. - `permanently_rejected` - terminal; cannot be re-added on this or any other DIR you own.

## Response `200`

Paginated list of batches.

- PhoneNumberBatchList
  - `data` PhoneNumberBatch[], required
    - `batch_id` string, uuid
    - `dir_id` string, uuid
    - `dir_display_name` string: The DIR's display name at the time the batch was read.
    - `enterprise_id` string, uuid
    - `status` 'submitted' | 'in_review' | 'verified' | 'unsuccessful' | 'suspended' | 'expired' | 'permanently_rejected': Phone-number lifecycle status. - `submitted` / `in_review` - Telnyx is reviewing the batch this number belongs to. - `verified` - approved; the DIR's display identity will be shown on outbound calls from this number. - `unsuccessful` - Telnyx rejected this submission; the customer may re-add to retry. - `suspended` - temporarily disabled (e.g. by an active infringement claim on the DIR). - `expired` - verification expired; re-add to renew. - `permanently_rejected` - terminal; cannot be re-added on this or any other DIR you own.
    - `total_count` integer: Number of phone numbers in this batch (length of `phone_numbers`).
    - `submitted_at` string, date-time: When the batch was created (and implicitly submitted for vetting).
    - `documents` Document[]: Documents attached to this batch (e.g. a Letter of Authorization). Empty when none were supplied at add time.
      - `document_id` string, uuid, required: Id returned by the Telnyx Documents API after you upload the file (upload via `POST /v2/documents`; see https://developers.telnyx.com/api/documents).
      - `document_type` 'letter_of_authorization' | 'business_registration' | 'articles_of_incorporation' | 'certificate_of_good_standing' | 'tax_document' | 'ein_letter' | 'trademark_registration' | 'website_ownership' | 'business_license' | 'professional_license' | 'government_id' | 'utility_bill' | 'bank_statement' | 'business_credit_report' | 'bank_reference_letter' | 'other', required: Type of supporting document. Pick the closest match to what the file actually contains; `other` triggers manual vetting and may slow approval. The matching short_name reference list is at `GET /v2/dir/document_types`.
      - `description` string: An optional note describing this document, for example what it proves.
    - `phone_numbers` DirPhoneNumber[]: All phone numbers in this batch, with per-number status.
      - `id` string, uuid
      - `dir_id` string, uuid
      - `enterprise_id` string, uuid
      - `phone_number` string: E.164 with leading `+`.
      - `batch_id` string, uuid, nullable: Id of the batch this number was vetted as part of.
      - `loa_document_id` string, uuid, nullable: Id of the Letter of Authorization document attached to this number's batch.
      - `status` 'submitted' | 'in_review' | 'verified' | 'unsuccessful' | 'suspended' | 'expired' | 'permanently_rejected': Phone-number lifecycle status. - `submitted` / `in_review` - Telnyx is reviewing the batch this number belongs to. - `verified` - approved; the DIR's display identity will be shown on outbound calls from this number. - `unsuccessful` - Telnyx rejected this submission; the customer may re-add to retry. - `suspended` - temporarily disabled (e.g. by an active infringement claim on the DIR). - `expired` - verification expired; re-add to renew. - `permanently_rejected` - terminal; cannot be re-added on this or any other DIR you own.
      - `rejection_reason` RejectionReason
        - `code` string
        - `title` string
        - `detail` string
        - `message` string, nullable: Customer-visible free-text comment from the Telnyx vetting team. Only the first entry of `rejection_reasons` carries this; the rest are `null`.
      - `created_at` string, date-time
      - `updated_at` string, date-time
      - `verified_at` string, date-time, nullable
  - `meta` BrandedCallingPaginationMeta, required: JSON:API pagination metadata returned with every paginated list response. Page numbering is 1-based. `page_size` reports the number of items actually returned in `data` for this page; the requested size is taken from the `page[size]` query parameter.
    - `total_pages` integer, required: Total number of pages available given the current `page_size`.
    - `total_results` integer, required: Total number of items across all pages (excludes soft-deleted rows).
    - `page_number` integer, required: 1-based index of this page. Echoes the `page[number]` query parameter (default `1`).
    - `page_size` integer, required: Number of items returned in this page's `data` array. Capped at 250.

## Other responses

- `default`: An error occurred. The response carries the standard Telnyx error envelope.
- `4XX`: An error occurred. The response carries the standard Telnyx error envelope.

## Changes

- **2026-10-19** `5beddb7ab8af`: 3 warning
  - added the new `bank_reference_letter` enum value to the `data/items/documents/items/document_type` response property for the response status `200`
  - added the new `business_credit_report` enum value to the `data/items/documents/items/document_type` response property for the response status `200`
  - added the new `certificate_of_good_standing` enum value to the `data/items/documents/items/document_type` response property for the response status `200`
- **2026-06-05** `8a8c40f458c5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api/changes/dir/:dir_id/phone_number_batches/get.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)