Skip to main content
POST
/
dir
/
{dir_id}
/
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.dir.phoneNumbers.add('16635d38-75a6-4481-82e8-69af60e05011', {
  documents: [
    {
      document_id: '2a7e8337-e803-4057-a4ae-26c40eb0bc6c',
      document_type: 'letter_of_authorization',
      description: 'LOA authorising Telnyx to register these numbers under the DIR.',
    },
  ],
  phone_numbers: ['+19493253498', '+12134445566'],
});

console.log(response.data);
{
  "data": [
    {
      "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

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
dir_id
string<uuid>
required

The DIR id. Lowercase UUID.

Example:

"16635d38-75a6-4481-82e8-69af60e05011"

Body

application/json
​
phone_numbers
string[]
required

1–15 phone numbers in E.164 format. 10-digit US numbers are auto-prefixed with 1.

Required array length: 1 - 15 elements
​
documents
object[]
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.

Required array length: 1 - 20 elements

Response

Bulk-add response. Inspect both added and errors.

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
object[]
required

Phone numbers accepted into the new batch. List order mirrors the request order. Each element shares the same batch_id.