Skip to main content
POST
JavaScript

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.