---
title: "Add phone numbers to a DIR"
method: POST
path: "/dir/{dir_id}/phone_numbers"
tags: ["Phone Numbers"]
---

# Add phone numbers to a DIR

`POST /dir/{dir_id}/phone_numbers`

Register phone numbers under a DIR. The enterprise is resolved server-side from the DIR id. Same body, failure modes, and batch semantics whichever path form you use.

**Pricing:** This is a billable action. See https://telnyx.com/pricing/numbers for current pricing.

## Path parameters

- `dir_id` string, uuid, required

## Request body

- BulkAddPhoneNumbersRequest
  - `phone_numbers` string[], required — 1–15 phone numbers in E.164 format. 10-digit US numbers are auto-prefixed with `1`.
  - `documents` Document[], required — Supporting documents covering this batch. At least one entry with `document_type: letter_of_authorization` is required - the LOA authorises Telnyx to register these numbers under the DIR. Each `document_id` must come from the Telnyx Documents API. Additional document types (e.g. business registration) may be included alongside the LOA.
    - `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' | 'tax_document' | 'ein_letter' | 'trademark_registration' | 'website_ownership' | 'business_license' | 'professional_license' | 'government_id' | 'utility_bill' | 'bank_statement' | '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

## Response `201`

Bulk-add response. Inspect both `added` and `errors`.

- PhoneNumberBulkResponse — Bulk-add success response (HTTP 201). All numbers in the request were accepted into a single new batch. Every entry in `data` shares the same `batch_id` - read it from any element to obtain the batch id for subsequent `GET .../phone_number_batches/{batch_id}` calls. If any number in the request fails (schema-invalid, not in inventory, already attached to another DIR, etc.) the entire request is rejected with HTTP 400 and the canonical Telnyx error envelope; the success body described here is therefore an all-or-nothing payload.
  - `data` DirPhoneNumber[], required — Phone numbers accepted into the new batch. List order mirrors the request order. Each element shares the same `batch_id`.
    - `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

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

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api-2/versions/8f5f4e537994/schema)