Phone Numbers

Add phone numbers to a DIR

Changed on

Register phone numbers under a DIR. The enterprise is resolved server-side from the DIR id.

Pricing: Adding phone numbers is free. Branded Calling fees are charged per DIR and per branded call. See https://telnyx.com/pricing/branded-calling for current pricing.

post/dir/{dir_id}/phone_numbers

Request

  • Base URL: https://api.telnyx.com/v2
  • URL: https://api.telnyx.com/v2/dir/{dir_id}/phone_numbers
  • Auth: HTTP bearer

Path parameters

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

The DIR id. Lowercase UUID.

Request body

phone_numbersstring[] required

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

Example request

{
  "phone_numbers": [
    "+19493253498"
  ],
  "documents": [
    {
      "document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c",
      "document_type": "business_registration",
      "description": "Certificate of incorporation."
    }
  ]
}

Response

Bulk-add response. Inspect both added and errors.

Example response

{
  "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",
      "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"
    }
  ]
}

Changes

  • 3f89a75a499fRevision changes
    • info

      added the new bank_reference_letter enum value to the request property //

    • info

      added the new business_credit_report enum value to the request property //

    • info

      added the new certificate_of_good_standing enum value to the request property //