Telnyx

Hosted SMS lets you add messaging capabilities to phone numbers that stay with your current voice provider. Your existing voice service continues uninterrupted — Telnyx handles only the SMS and MMS routing. This is ideal for:

Landline numbers that need texting capabilities
Business numbers where you want to keep your voice provider but add programmable messaging
Gradual migration — test Telnyx messaging before a full port

Hosting a number is not the same as porting. Your voice service stays with your current provider. Only SMS/MMS traffic routes through Telnyx.

How it works

Step	What happens	Timeline
1. Eligibility check	Verify your numbers can be hosted	Instant
2. Create order	Submit a hosted SMS order	Instant
3. Verify ownership	Confirm you own the numbers via SMS code	5 minutes
4. Upload documents	Submit LOA and recent provider bill	Instant
5. Telnyx review	Our team reviews and activates	1-3 business days

Step 1: Check number eligibility

Not all numbers can be hosted. Check eligibility before creating an order.

API
Portal

curl -X POST https://api.telnyx.com/v2/messaging_hosted_number_orders/eligibility_numbers_check \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "phone_numbers": ["+13125550001", "+13125550002"]
  }'

Eligibility statuses

Status	Description	Action
`eligible`	Number can be hosted	Proceed with order
`number_is_not_a_us_number`	Only US numbers supported	Use a US number
`number_can_not_be_wireless`	Wireless numbers not supported	Use a landline or VoIP number
`number_can_not_be_in_telnyx`	Already on Telnyx platform	No hosting needed — number already works
`number_can_not_hosted_with_a_telnyx_subscriber`	Already hosted by another Telnyx user	Contact support
`number_can_not_be_active_in_your_account`	Active in your account already	Check your number inventory
`number_is_not_a_valid_routing_number`	Invalid routing number	Verify the number with your provider
`number_is_not_in_e164_format`	Wrong format	Use E.164: `+1` followed by 10 digits
`billing_account_check_failed`	Billing issue	Check your account billing status
`billing_account_is_abolished`	Account closed	Contact support

Step 2: Create a hosted SMS order

API
Portal

curl -X POST https://api.telnyx.com/v2/messaging_hosted_number_orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "messaging_profile_id": "YOUR_MESSAGING_PROFILE_ID",
    "phone_numbers": ["+13125550001"]
  }'

Numbers are created in pending status. They stay pending until you complete verification and document upload.

Navigate to Hosted SMS

Go to Numbers → Hosted SMS in Mission Control.

Create new order

Click Add New Order.

Enter numbers

Enter the phone number(s) you want to host in E.164 format (e.g., +13125550001). The system automatically checks eligibility.

Select messaging profile

Choose the messaging profile for these numbers.

Create order

Click Create Order to proceed to document upload.

Step 3: Verify phone number ownership

Prove you own the numbers by receiving and entering SMS verification codes.

3a. Request verification codes

curl -X POST \
  "https://api.telnyx.com/v2/messaging_hosted_number_orders/{order_id}/verification_codes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verification_method": "sms",
    "phone_numbers": ["+13125550001"]
  }'

3b. Submit verification codes

curl -X POST \
  "https://api.telnyx.com/v2/messaging_hosted_number_orders/{order_id}/validation_codes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verification_codes": [
      {"phone_number": "+13125550001", "code": "87643"}
    ]
  }'

A successful verification returns verified status. The number status then changes to ownership_successful.

Step 4: Upload authorization documents

After verification, upload two PDF documents:

Letter of Authorization (LOA) — signed authorization to host the number
Recent bill — from your current voice provider showing the number

curl -X POST \
  "https://api.telnyx.com/v2/messaging_hosted_number_orders/{order_id}/actions/file_upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --form "loa=@/path/to/loa.pdf" \
  --form "bill=@/path/to/bill.pdf"

After upload, the Telnyx team reviews your order and activates the number(s). This typically takes 1-3 business days.

Check order status

curl -s "https://api.telnyx.com/v2/messaging_hosted_number_orders/{order_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq '{status, phone_numbers: [.phone_numbers[] | {phone_number, status}]}'

Order statuses

Status	Meaning
`pending`	Order created, awaiting verification and documents
`loa_file_successful`	Documents uploaded successfully
`successful`	Order complete — numbers are active
`failed`	Activation failed (see failure statuses)
`deleted`	Order was cancelled

Webhook notifications

Hosted SMS orders trigger webhooks to your messaging profile’s configured webhook URL. Set up a handler to track order progress in real time.

from flask import Flask, request

app = Flask(__name__)

@app.route("/webhooks/hosted-sms", methods=["POST"])
def hosted_sms_webhook():
    event = request.json["data"]
    event_type = event["event_type"]
    payload = event["payload"]

    order_id = payload["order_id"]
    order_status = payload["order_status"]

    print(f"Event: {event_type}")
    print(f"Order {order_id}: {order_status}")

    for num in payload.get("numbers", []):
        print(f"  {num['value']}: {num['status']}")

    # Handle specific events
    if order_status == "successful":
        print("Numbers are active! Ready to send messages.")
    elif order_status == "failed":
        print("Order failed. Check number statuses for details.")

    return "", 200

Webhook event types

Event	Triggered when
`messaging_hosted_numbers_orders.created`	Order is created
`messaging_hosted_numbers_orders.updated`	Status changes (verification, LOA upload, activation, failure)
`messaging_hosted_numbers_orders.deleted`	Order is deleted

Email and Portal notifications

You can also receive email notifications:

Create notification profile

Go to Advanced Features → Notifications and click New Profile.

Add email channel

Click New Channel, select your profile, choose Email, and enter your address.

Configure settings

Click New Settings, select Messaging Hosted SMS Activity, and link to your profile.

Troubleshooting failed orders

Order status: carrier_rejected

Cause: The losing carrier (your current voice provider) rejected the hosting request.Common reasons:

Number is under contract with restrictions on SMS routing changes
Provider doesn’t support hosted SMS arrangements
Account information mismatch between LOA and provider records

Fix:

Contact your voice provider to understand the rejection
Verify your LOA matches the account holder name exactly
Some carriers require you to call and authorize the SMS routing change

Order status: ineligible_carrier

Cause: The number’s carrier does not support hosted SMS with Telnyx.Fix:

Consider porting the number fully to Telnyx instead
Contact Telnyx support to check if the carrier has been added since your last attempt

Number status: failed_carrier_rejected

Cause: Specific number was rejected by the losing carrier while other numbers in the order may have succeeded.Fix:

Check if this specific number has different account ownership
Create a separate order for this number after resolving with your provider

Number status: failed_number_already_hosted

Cause: The number is already hosted on Telnyx by another account.Fix:

If you own both accounts, remove the hosting from the other account first
If not, contact Telnyx support to resolve the conflict

Number status: failed_timeout

Cause: The activation process timed out waiting for carrier response.Fix:

Create a new order for the same number
If it fails again, contact Telnyx support — the carrier may need manual intervention

Verification code not received

Cause: The SMS verification code wasn’t delivered to the phone number.Fix:

Ensure the number can receive SMS (landlines may need the current provider to enable it)
Check if the number has any SMS blocking enabled
Request the code again — you can retry multiple times
If the number truly cannot receive SMS, contact Telnyx support for alternative verification

LOA rejected

Cause: The Letter of Authorization didn’t meet requirements.Common issues:

LOA not signed
Name on LOA doesn’t match the voice provider account
LOA template is outdated

Fix:

Download the latest LOA template from Telnyx support
Ensure the authorized signer matches the account holder
Upload a new LOA via the API or Portal

Hosted numbers not visible in Portal

Known limitation: Hosted numbers may not appear in the Portal number inventory. They are accessible via the API.

# List your hosted numbers
curl -s "https://api.telnyx.com/v2/messaging_hosted_number_orders" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq '.data[] | select(.status == "successful")'

Failed order and number statuses reference

Order statuses

Status	Description
`carrier_rejected`	Losing carrier rejected the porting request
`failed`	Order closed — contact support
`ineligible_carrier`	Number’s carrier doesn’t support hosted SMS

Number statuses

Status	Description
`failed`	Number closed — contact support
`failed_carrier_rejected`	Losing carrier rejected this number
`failed_ineligible_carrier`	Number’s carrier doesn’t support hosted SMS
`failed_number_already_hosted`	Already hosted by another Telnyx user
`failed_number_not_found`	Number not found in routing database
`failed_timeout`	Activation timed out

Next steps

Internal Transfer

Transfer hosted numbers between Telnyx accounts.

Messaging Profiles

Configure webhooks, opt-out settings, and number assignment.

Send Your First Message

Start sending SMS and MMS once your hosted numbers are active.

Choosing Your Sender Type

Compare hosted SMS with other number types (10DLC, toll-free, short code).

Sending Messages

Messaging Profiles

Short Code

RCS

Hosted Numbers

Opt Outs

Phone Numbers

Toll Free Verification

10 DLC

Hosted SMS

How it works

Step 1: Check number eligibility

Eligibility statuses

Step 2: Create a hosted SMS order

Step 3: Verify phone number ownership

3a. Request verification codes

3b. Submit verification codes

Step 4: Upload authorization documents

Check order status

Order statuses

Webhook notifications

Webhook event types

Email and Portal notifications

Troubleshooting failed orders

Failed order and number statuses reference

Order statuses

Number statuses

Next steps

Internal Transfer

Messaging Profiles

Send Your First Message

Choosing Your Sender Type

Sending Messages

Messaging Profiles

Short Code

RCS

Hosted Numbers

Opt Outs

Phone Numbers

Toll Free Verification

10 DLC

​How it works

​Step 1: Check number eligibility

​Eligibility statuses

​Step 2: Create a hosted SMS order

​Step 3: Verify phone number ownership

​3a. Request verification codes

​3b. Submit verification codes

​Step 4: Upload authorization documents

​Check order status

​Order statuses

​Webhook notifications

​Webhook event types

​Email and Portal notifications

​Troubleshooting failed orders

​Failed order and number statuses reference

​Order statuses

​Number statuses

​Next steps

Internal Transfer

Messaging Profiles

Send Your First Message

Choosing Your Sender Type

How it works

Step 1: Check number eligibility

Eligibility statuses

Step 2: Create a hosted SMS order

Step 3: Verify phone number ownership

3a. Request verification codes

3b. Submit verification codes

Step 4: Upload authorization documents

Check order status

Order statuses

Webhook notifications

Webhook event types

Email and Portal notifications

Troubleshooting failed orders

Failed order and number statuses reference

Order statuses

Number statuses

Next steps