Skip to main content

​
Hosted SMS

| cURL | .NET | Portal |
Overview Hosted SMS allows you to bring your own number onto the Telnyx platform for SMS and MMS use only. The number remains with your current voice provider for voice services, but routes all inbound and outbound SMS and MMS messages through the Telnyx network. This is especially useful for landline numbers that normally would not have messaging capabilities. Telnyx can supplement the voice capabilities of that number by adding messaging functionality without affecting voice services. Hosted numbers must go through a verification process to ensure that you are the authorized user for that number and have the authority to make changes to the number’s messaging routing. To complete the verification, we need two documents: a signed Letter of Authorization (LOA) and the most recent bill from your current voice provider clearly showing your information and the number to be hosted with Telnyx.
Hosting numbers with Telnyx is not the same as porting a number, but they both have a similar process.
Not all numbers are capable of being Hosted with Telnyx.

​
cURL

​
Setting up your first Hosted SMS number

​
Check phone number eligibility for hosted messaging

Before creating a hosted SMS order, you can check if your phone numbers are eligible for hosted messaging. 
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"phone_numbers": ["+13125550001", "+553125550002"]}' \
  "https://api.telnyx.com/v2/messaging_hosted_number_orders/eligibility_numbers_check"

​
Example response

{
  "phone_numbers": [
    {
      "detail": "Phone number is eligible for hosted messaging",
      "phone_number": "+13125550001",
      "eligible": true,
      "eligible_status": "eligible"
    },
    {
      "detail": "Phone number is not a valid US number",
      "phone_number": "+553125550002",
      "eligible": false,
      "eligible_status": "number_is_not_a_us_number"
    }
  ]
}
The eligibility check returns a status for each phone number. Only numbers with "eligible": true and "eligible_status": "eligible" can be used for hosted messaging. Possible status values and descriptions are included in the eligibility check table.

​
Table of eligible statuses for Hosted SMS Order

eligible_statusdescription
billing_account_check_failedBilling check failed. Try again or check billing.
billing_account_is_abolishedAccount is abolished in billing.
eligibleNumber is eligible for creating a Hosted SMS order.
number_can_not_be_active_in_your_accountActive numbers in your account are not allowed.
number_can_not_be_in_telnyxNumber already exists on the Telnyx platform and cannot be hosted.
number_can_not_be_repeatedDuplicate numbers are not allowed.
number_can_not_be_wirelessWireless numbers are not allowed.
number_can_not_hosted_with_a_telnyx_subscriberNumber is already hosted with a Telnyx subscriber and cannot be hosted again.
number_is_not_a_us_numberNumbers outside the United States are not allowed.
number_is_not_a_valid_routing_numberNumber is not a valid local routing number.
number_is_not_in_e164_formatNumber must be in E.164 format.
numbers_can_not_be_validatedNumbers could not be validated. Try again or contact support.

​
Create a hosted SMS order

This creates a new hosted sms number order: 

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  -d '{"messaging_profile_id":"16fd2706-8baf-433b-82eb-8c7fada847da", "phone_numbers":["+13125550001"]}' \
  "https://api.telnyx.com/v2/messaging_hosted_number_orders"

​
Example response

{
    "record_type": "messaging_hosted_number_order",
    "id": "7d9b9fdc-d073-4c3d-9c74-bf0622b3830c",
    "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "status": "pending",
    "phone_numbers": [
        {
            "record_type": "messaging_hosted_number",
            "id": "bda67701-2c08-47ba-8242-f6e6b235cca8",
            "phone_number": "+13125550001",
            "status": "pending"
        }
    ]
}
The numbers in this order are created in a pending status. They will remain that way until you validate the phone numbers and submit the necessary authorization documents. Once the Telnyx team reviews and approves your order, the status will change to successful.
If there is a problem with the order request, the error statuses are the same as those in the eligibility check table. You can check the eligible_status field in the response to see the reason for the error.

​
Validate phone numbers

This is a prerequisite for Uploading authorization documents.
You need to validate the phone numbers in your order. This is done by sending two requests (API references: 1, 2), one to create the verification codes and the other to validate the verification codes.

​
1. Create the verification codes

The first request generates the verification codes for the phone numbers in your order. The verification codes are sent to the respective phone numbers. Request: 
curl --request POST \
  --url https://api.telnyx.com/v2/messaging_hosted_number_orders/5fcf6884-6c1b-45e4-89b8-5fba9e6c60be/verification_codes \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "content-type: application/json" \
  --data '{
  "verification_method": "sms",
  "phone_numbers": ["+15005550108", "+15005550921"]
}'
You will receive a 201 without content if everything is successful and the verification codes are sent to the phone numbers. In this example, SMS codes will be sent to +15005550108 and +15005550921.

​
2. Validate the verification codes

The second request validates the verification codes for the phone numbers in your order. The verification codes must be created in step 1. They will be sent to the phone numbers using the specified verification method. Request: 
curl --request POST \
  --url https://api.telnyx.com/v2/messaging_hosted_number_orders/5fcf6884-6c1b-45e4-89b8-5fba9e6c60be/validation_codes \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "content-type: application/json" \
  --data '{
  "verification_codes": [
    {"phone_number": "+15005550108", "code": "87643"}, {"phone_number": "+15005550921", "code": "98276"}
  ]
}'
Response: 
{
  "phone_numbers": [
    {
      "phone_number": "+15005550108",
      "status": "verified"
    },
    {
      "phone_number": "+15005550921",
      "status": "verified"
    }
  ],
  "order_id": "5fcf6884-6c1b-45e4-89b8-5fba9e6c60be"
}
You can receive either verified or rejected status for each phone number. If you receive a rejected status, please check the phone number and the verification code. If everything is correct, the status of your phone numbers will be ownership_successful.

​
Uploading authorization documents

Validate phone numbers is a prerequisite for this.
You need to upload two documents in PDF format:
  1. Letter of Authorization
  2. The most recent bill from your voice provider 
curl -X POST \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --form "loa=@/path/to/loa" \
  --form "bill=@/path/to/bill" \
  "https://api.telnyx.com/v2/messaging_hosted_number_orders/{id}/actions/file_upload"

​
Example response

{
    "record_type": "messaging_hosted_number_order",
    "id": "7d9b9fdc-d073-4c3d-9c74-bf0622b3830c",
    "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "status": "pending"
}
Now that your order request has all the information needed, our team will review and activate the number(s) for you on the Telnyx platform.
Right now, these numbers will not be visible in the Telnyx Portal. They will however be visible when using the Telnyx API.

​
Notifications

This section describes how the notifications are handled for Hosted SMS Orders.
  • All notifications are sent to the Webhook URLs configured in your Messaging Profile.
  • Any change in the status of your Hosted SMS Order will trigger a notification. These changes include:
    • Order created
    • Order deleted
    • Phone number ownership verified
    • Phone number deleted
    • LOA uploaded
    • Order activated successfully
    • Order activation failed: failed statuses are described in order and numbers failed statuses
  • Add user configured notifications for email and portal to receive email and portal notifications.

​
Webhooks notifications

The JSON structure received in the webhooks is the following: 
{
  "data": {
    "event_type": "messaging_hosted_numbers_orders.created",
    "id": "ce7a1221-d9dd-4015-bca0-31856a7a3844",
    "occurred_at": "2025-09-25T01:55:17.373+00:00",
    "payload": {
      "event_type": "created",
      "numbers": [
        {
          "status": "pending",
          "value": "+15035550543"
        },
        {
          "status": "pending",
          "value": "+15035550844"
        }
      ],
      "order_id": "22afcb61-6e9f-449d-a19f-38d67816f3e8",
      "order_status": "pending",
      "profile_id": "6a3ec0cb-95bb-485b-a185-7c35937b7eac",
      "user_id": "37fe3acf-411a-488e-a919-91f726f7726b"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "http://webhook-url-example.com"
  }
}
The simplified JSONs for the order and its numbers statuses are: Created order: order is created and pending, numbers are in pending status. 
{
  "data": {
    "event_type": "messaging_hosted_numbers_orders.created",
    "payload": {
      "order_status": "pending",
      "numbers": [{"status": "pending"}]
    }
  }
}
Deleted order: order and its numbers are deleted. 
{
  "data": {
    "event_type": "messaging_hosted_numbers_orders.deleted",
    "payload": {
      "order_status": "deleted",
      "numbers": [{"status": "deleted"}]
    }
  }
}
Ownership verified: the phone number ownership is verified, order is still pending, waiting for LOA and bill upload. 
{
  "data": {
    "event_type": "messaging_hosted_numbers_orders.updated",
    "payload": {
      "order_status": "pending",
      "numbers": [{"status": "ownership_successful"}]
    }
  }
}
Deleted number: deletes a single number, order is pending. 
{
  "data": {
    "event_type": "messaging_hosted_numbers_orders.updated",
    "payload": {
      "order_status": "pending",
      "numbers": [{"status": "deleted"}]
    }
  }
}
LOA uploaded: this case does not update any number status. 
{
  "data": {
    "event_type": "messaging_hosted_numbers_orders.updated",
    "payload": {"order_status": "loa_file_successful"}
  }
}
Activated order: order is activated and successful, numbers are in successful status. 
{
  "data": {
    "event_type": "messaging_hosted_numbers_orders.updated",
    "payload": {
      "order_status": "successful",
      "numbers": [{"status": "successful"}]
    }
  }
}
Activation failed: order and its numbers failed activation. 
{
  "data": {
    "event_type": "messaging_hosted_numbers_orders.updated",
    "payload": {
      "order_status": "failed",
      "numbers": [{"status": "failed"}]
    }
  }
}

​
User configured notifications for Email and Portal

In the Advanced Features - Notifications page you can configure email and portal notifications for Hosted SMS Orders status changes.
  1. Create a New Notification Profile with a name using the “New Profile” button.
  2. Create a New Channel with Email: click the “New Channel” button, select the above profile, select email, and enter your notification email address.
  3. Create Notification Settings: click the “New Settings” button, select “Messaging Hosted SMS Activity”, and select the above profile.
Future notifications will be sent to your email address and will be visible in the portal bell icon. The list of notifications is in the Notifications section.

​
Example of email and portal notification for Hosted SMS Order deleted (only text)

Hosted SMS Order deleted notification

A deleted event for Hosted SMS Order has been detected on your Telnyx account.

ID: 18d630df-728e-4a5e-a656-9a81a8237620
Profile ID: 10f72731-783d-4218-80f5-d61dafcd6a36
Order status: deleted
Numbers' status change (if any):
- +16004453991: deleted

You can view and manage your Hosted SMS Orders in the Telnyx Portal.
If you did not expect this change or have any questions, please contact our support team.

​
Order and Numbers activation failed statuses

You can have failed statuses for both the order and its numbers. The possible failed statuses are:
Order StatusDescription
carrier_rejectedLosing carrier rejected a number porting request.
failedOrder has been closed. Contact support for more information.
ineligible_carrierA number from the losing carrier cannot be ported to Telnyx.
Number StatusDescription
failedNumber has been closed. Contact support for more information.
failed_carrier_rejectedLosing carrier rejected a number porting request.
failed_ineligible_carrierNumber from the losing carrier cannot be ported to Telnyx.
failed_number_already_hostedNumber is already in Telnyx and cannot be hosted.
failed_number_not_foundNumber is not in Telnyx and cannot be hosted.
failed_timeoutTimed out while activating the number.

​
.NET

​
Setting up your first Hosted SMS number

​
Create a hosted SMS order

This creates a new hosted sms number order: 

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  -d '{"messaging_profile_id":"16fd2706-8baf-433b-82eb-8c7fada847da", "phone_numbers":["+13125550001"]}' \
  "https://api.telnyx.com/v2/messaging_hosted_number_orders"

​
Example response

{
    "record_type": "messaging_hosted_number_order",
    "id": "7d9b9fdc-d073-4c3d-9c74-bf0622b3830c",
    "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "status": "pending",
    "phone_numbers": [
        {
            "record_type": "messaging_hosted_number",
            "id": "bda67701-2c08-47ba-8242-f6e6b235cca8",
            "phone_number": "+13125550001",
            "status": "pending"
        }
    ]
}
The numbers in this order are created in a pending status. They will remain that way until you submit the necessary authorization documents. Once the Telnyx team reviews your order and approves it, the status will change to successful.

​
Uploading authorization documents

You need to upload two documents in PDF format:
  1. Letter of Authorization
  2. The most recent bill from your voice provider 
curl -X POST \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --form "loa=@/path/to/loa" \
  --form "bill=@/path/to/bill" \
  "https://api.telnyx.com/v2/messaging_hosted_number_orders/{id}/actions/file_upload"

​
Example response

{
    "record_type": "messaging_hosted_number_order",
    "id": "7d9b9fdc-d073-4c3d-9c74-bf0622b3830c",
    "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "status": "pending"
}
Now that your order request has all the information needed, our team will review and activate the number(s) for you on the Telnyx platform.
Right now, these numbers will not be visible in the Telnyx Portal. They will however be visible when using the Telnyx API.

​
Portal

​
Setting up your first Hosted SMS Number

​
Create a hosted SMS order

  1. On the Mission Control Portal, click on to Numbers.
  2. Navigate to Hosted SMS
  3. Click on Add New Order
new hosted sms order
  1. Enter the number(s) you wish to host with Telnyx in +E.164 format
  2. The system will automatically check the eligibility of the entered phone numbers. Only eligible numbers can be used for hosted messaging.
  3. Choose the Message Profile you’d like to add to the number(s)
  4. Click on Create Order. You will automatically route to the next page where you need to upload your Authorization Documentation.
create hosted sms order
  1. Upload your LOA
  2. Upload your Bill
  3. Click on Submit
upload files hosted sms order Now that your order request has all the information needed, our team will review and activate the number(s) for you on the Telnyx platform.
Right now, these numbers will not be visible in the Telnyx Portal. They will however be visible when using the Telnyx API.