Sign in

v53

OpenAPI 3.1.0raw.githubusercontent.com2026-08-041,1941,9384.1 MB
Phone Number Batches

List phone-number batches for a DIR

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

get/dir/{dir_id}/phone_number_batches

Path parameters

dir_idstring uuid required
Example:16635d38-75a6-4481-82e8-69af60e05011

The DIR id. Lowercase UUID.

Query parameters

page[number]integer
Example:1

1-based page number. Out-of-range values return an empty page with correct meta.

page[size]integer
Example:20

Items per page. Maximum 250; values above are clamped to 250.

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.

Restrict to batches whose aggregate status equals this value.

Response

Paginated list of batches.

Example response

{
  "data": [
    {
      "batch_id": "ba74cfc6-d32b-467a-9b08-86fd154c23f7",
      "dir_display_name": "Acme Plumbing",
      "dir_id": "74e1d8ed-fbdb-45a7-bbb0-a09c1184eb3d",
      "documents": [
        {
          "description": "Certificate of incorporation.",
          "document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c",
          "document_type": "business_registration"
        }
      ],
      "enterprise_id": "5c987b82-2e3b-442a-afbc-0ba3c515f561",
      "phone_numbers": [
        {
          "batch_id": "0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62",
          "created_at": "2026-04-26T18:11:42.850928Z",
          "dir_id": "16635d38-75a6-4481-82e8-69af60e05011",
          "enterprise_id": "4a6192a4-573d-446d-b3ce-aff9117272a6",
          "id": "1f56eb76-4078-4af7-ad4d-564b027256ee",
          "phone_number": "+19493253498",
          "rejection_reason": {
            "code": "documentation_incomplete",
            "detail": "Provided documents do not establish business identity.",
            "message": "Please re-upload a clearer scan of the certificate.",
            "title": "Documentation incomplete"
          },
          "updated_at": "2026-04-26T18:12:11.123456Z",
          "verified_at": "2026-04-26T18:12:11.123456Z"
        }
      ],
      "submitted_at": "2026-04-26T18:14:37.065870Z",
      "total_count": 1
    }
  ],
  "meta": {
    "page_number": 1,
    "page_size": 20,
    "total_pages": 3,
    "total_results": 42
  }
}