> ## Documentation Index > Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt > Use this file to discover all available pages before exploring further. # Add phone numbers to a DIR > 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. ## OpenAPI ````yaml https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/branded-calling/phone-numbers.yml post /dir/{dir_id}/phone_numbers openapi: 3.1.0 info: title: Telnyx Branded Calling Phone Numbers API version: 2.0.0 description: >- Register and deregister phone numbers under a verified DIR, and track their vetting batches. contact: email: support@telnyx.com servers: - url: https://api.telnyx.com/v2 security: - bearerAuth: [] paths: /dir/{dir_id}/phone_numbers: post: tags: - Phone Numbers summary: Add phone numbers to a DIR description: >- 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. operationId: addDirPhoneNumbersSimplified parameters: - $ref: '#/components/parameters/DirId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BulkAddPhoneNumbersRequest' example: phone_numbers: - '+19493253498' - '+12134445566' documents: - document_id: 2a7e8337-e803-4057-a4ae-26c40eb0bc6c document_type: letter_of_authorization description: >- LOA authorising Telnyx to register these numbers under the DIR. responses: '201': description: Bulk-add response. Inspect both `added` and `errors`. content: application/json: schema: $ref: '#/components/schemas/PhoneNumberBulkResponse' default: $ref: '#/components/responses/branded-calling_GenericErrorResponse' 4XX: $ref: '#/components/responses/branded-calling_GenericErrorResponse' x-codeSamples: - lang: JavaScript source: >- 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); - lang: Python source: |- import os from telnyx import Telnyx client = Telnyx( api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted ) response = client.dir.phone_numbers.add( dir_id="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"], ) print(response.data) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/team-telnyx/telnyx-go\"\n\t\"github.com/team-telnyx/telnyx-go/option\"\n)\n\nfunc main() {\n\tclient := telnyx.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Dir.PhoneNumbers.Add(\n\t\tcontext.TODO(),\n\t\t\"16635d38-75a6-4481-82e8-69af60e05011\",\n\t\ttelnyx.DirPhoneNumberAddParams{\n\t\t\tDocuments: []telnyx.DirPhoneNumberAddParamsDocument{{\n\t\t\t\tDocumentID: \"2a7e8337-e803-4057-a4ae-26c40eb0bc6c\",\n\t\t\t\tDocumentType: \"letter_of_authorization\",\n\t\t\t\tDescription: telnyx.String(\"LOA authorising Telnyx to register these numbers under the DIR.\"),\n\t\t\t}},\n\t\t\tPhoneNumbers: []string{\"+19493253498\", \"+12134445566\"},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n" - lang: Java source: >- package com.telnyx.sdk.example; import com.telnyx.sdk.client.TelnyxClient; import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient; import com.telnyx.sdk.models.dir.phonenumbers.PhoneNumberAddParams; import com.telnyx.sdk.models.dir.phonenumbers.PhoneNumberAddResponse; public final class Main { private Main() {} public static void main(String[] args) { TelnyxClient client = TelnyxOkHttpClient.fromEnv(); PhoneNumberAddParams params = PhoneNumberAddParams.builder() .dirId("16635d38-75a6-4481-82e8-69af60e05011") .addDocument(PhoneNumberAddParams.Document.builder() .documentId("2a7e8337-e803-4057-a4ae-26c40eb0bc6c") .documentType(PhoneNumberAddParams.Document.DocumentType.LETTER_OF_AUTHORIZATION) .build()) .addPhoneNumber("+19493253498") .addPhoneNumber("+12134445566") .build(); PhoneNumberAddResponse response = client.dir().phoneNumbers().add(params); } } - lang: Ruby source: |- require "telnyx" telnyx = Telnyx::Client.new(api_key: "My API Key") response = telnyx.dir.phone_numbers.add( "16635d38-75a6-4481-82e8-69af60e05011", documents: [{document_id: "2a7e8337-e803-4057-a4ae-26c40eb0bc6c", document_type: :letter_of_authorization}], phone_numbers: ["+19493253498", "+12134445566"] ) puts(response) - lang: PHP source: >- dir->phoneNumbers->add( '16635d38-75a6-4481-82e8-69af60e05011', documents: [ [ 'documentID' => '2a7e8337-e803-4057-a4ae-26c40eb0bc6c', 'documentType' => 'letter_of_authorization', 'description' => 'LOA authorising Telnyx to register these numbers under the DIR.', ], ], phoneNumbers: ['+19493253498', '+12134445566'], ); var_dump($response); } catch (APIException $e) { echo $e->getMessage(); } - lang: CLI source: |- telnyx dir:phone-numbers add \ --api-key 'My API Key' \ --dir-id 16635d38-75a6-4481-82e8-69af60e05011 \ --document '{document_id: 2a7e8337-e803-4057-a4ae-26c40eb0bc6c, document_type: letter_of_authorization}' \ --phone-number "'+19493253498'" \ --phone-number "'+12134445566'" components: parameters: DirId: name: dir_id in: path description: The DIR id. Lowercase UUID. required: true schema: type: string format: uuid example: 16635d38-75a6-4481-82e8-69af60e05011 schemas: BulkAddPhoneNumbersRequest: type: object required: - phone_numbers - documents additionalProperties: false properties: phone_numbers: type: array items: type: string example: '+19493253498' minItems: 1 maxItems: 15 description: >- 1–15 phone numbers in E.164 format. 10-digit US numbers are auto-prefixed with `1`. documents: type: array items: $ref: '#/components/schemas/Document' minItems: 1 maxItems: 20 description: >- 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. PhoneNumberBulkResponse: type: object description: >- 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. required: - data properties: data: type: array description: >- Phone numbers accepted into the new batch. List order mirrors the request order. Each element shares the same `batch_id`. items: $ref: '#/components/schemas/DirPhoneNumber' Document: type: object required: - document_id - document_type properties: document_id: type: string format: uuid description: >- Id returned by the Telnyx Documents API after you upload the file (upload via `POST /v2/documents`; see https://developers.telnyx.com/api/documents). example: 2a7e8337-e803-4057-a4ae-26c40eb0bc6c document_type: type: string enum: - 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 example: business_registration description: >- 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: type: string maxLength: 255 example: Certificate of incorporation. DirPhoneNumber: type: object properties: id: type: string format: uuid example: 1f56eb76-4078-4af7-ad4d-564b027256ee readOnly: true dir_id: type: string format: uuid example: 16635d38-75a6-4481-82e8-69af60e05011 enterprise_id: type: string format: uuid example: 4a6192a4-573d-446d-b3ce-aff9117272a6 phone_number: type: string description: E.164 with leading `+`. example: '+19493253498' batch_id: type: string format: uuid nullable: true description: Id of the batch this number was vetted as part of. example: 0a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62 loa_document_id: type: string format: uuid nullable: true description: >- Id of the Letter of Authorization document attached to this number's batch. example: null status: $ref: '#/components/schemas/PhoneNumberStatus' rejection_reason: $ref: '#/components/schemas/RejectionReason' nullable: true description: Populated when `status` is `unsuccessful` or `permanently_rejected`. created_at: type: string format: date-time example: '2026-04-26T18:11:42.850928Z' readOnly: true updated_at: type: string format: date-time example: '2026-04-26T18:12:11.123456Z' readOnly: true verified_at: type: string format: date-time nullable: true example: '2026-04-26T18:12:11.123456Z' readOnly: true branded-calling_Errors: type: object required: - errors properties: errors: type: array items: $ref: '#/components/schemas/branded-calling_Error' description: List of one or more error entries. Order is not significant. description: >- Canonical Telnyx error envelope. Returned on every 4xx and 5xx response from this service. `errors` is non-empty; multiple entries indicate multiple distinct problems with the same request (e.g. one entry per invalid phone number on a bulk operation). PhoneNumberStatus: type: string enum: - submitted - in_review - verified - unsuccessful - suspended - expired - permanently_rejected description: >- 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. RejectionReason: type: object properties: code: type: string example: documentation_incomplete title: type: string example: Documentation incomplete detail: type: string example: Provided documents do not establish business identity. message: type: string nullable: true description: >- Customer-visible free-text comment from the Telnyx vetting team. Only the first entry of `rejection_reasons` carries this; the rest are `null`. example: Please re-upload a clearer scan of the certificate. branded-calling_Error: type: object required: - code - title - detail - meta properties: code: type: string example: '10005' description: >- Stable numeric Telnyx error catalog id. See `meta.url` for the full catalog entry. title: type: string example: Invalid parameters description: >- Short human-readable category, e.g. `Bad Request`, `Duplicate resource`, `Not Found`, `Forbidden`. Treat as advisory only - the stable identifier is `code`. detail: type: string example: field required description: >- Context-specific message describing what went wrong on this particular request. May embed offending values; do not rely on it for programmatic matching - branch on `code`. meta: type: object required: - url properties: url: type: string format: uri example: https://developers.telnyx.com/docs/overview/errors/10005 pending_check_ids: type: array items: type: string format: uuid description: >- Set on `422 vetting_checks_incomplete` responses from `/admin/dir/{id}/approve` and `/admin/phone-number-batches/approve`. Lists the still-pending vetting check ids. pending_check_codes: type: array items: type: string description: >- Codes of the pending vetting checks (e.g. `loa_signature_valid`). pending_check_labels: type: array items: type: string description: Human-readable labels of the pending vetting checks. description: >- Carries `url` linking to the Telnyx error catalog entry for this `code`. Useful for forwarding the user to documentation. source: type: object description: Optional pointer at the offending field of the request. properties: pointer: type: string example: /body/legal_name parameter: type: string example: page[size] description: >- A single entry in the canonical Telnyx error envelope. `code` is the stable Telnyx error catalog id; the human-readable explanation lives at `meta.url`. `detail` is a context-specific message; `source.pointer` (when present) names the offending field of the request. responses: branded-calling_GenericErrorResponse: description: >- An error occurred. The response carries the standard Telnyx error envelope. content: application/json: schema: $ref: '#/components/schemas/branded-calling_Errors' examples: validation_error: summary: 422 - request body failed validation value: errors: - code: '10005' title: Invalid parameters detail: field required meta: url: https://developers.telnyx.com/docs/overview/errors/10005 source: pointer: /body/legal_name bad_request: summary: 400 - request rejected by a state guard description: >- Returned when the request itself is well-formed but the resource is in a state that disallows this action (e.g. updating a DIR while it is being vetted, or deleting an enterprise that still has DIRs in vetting). value: errors: - code: '10015' title: Bad Request detail: Cannot update DIR in 'verified' status meta: url: https://developers.telnyx.com/docs/overview/errors/10015 not_found: summary: 404 - resource does not exist or is not yours value: errors: - code: '10009' title: Resource not found detail: Enterprise not found. meta: url: https://developers.telnyx.com/docs/overview/errors/10009 conflict: summary: 409 - request conflicts with current resource state value: errors: - code: '10021' title: Resource in use detail: >- DIR has 1 active infringement claim(s). Resolve the claim before making this change. meta: url: https://developers.telnyx.com/docs/overview/errors/10021 securitySchemes: bearerAuth: scheme: bearer type: http ````