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.

Note

Hosting numbers with Telnyx is not the same as porting a number, but they both have a similar process.

Note

Not all numbers are capable of being Hosted with Telnyx.

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"

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

Note

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.

eligible_status	description
billing_account_check_failed	Billing check failed. Try again or check billing.
billing_account_is_abolished	Account is abolished in billing.
eligible	Number is eligible for creating a Hosted SMS order.
number_can_not_be_active_in_your_account	Active numbers in your account are not allowed.
number_can_not_be_in_telnyx	Number already exists on the Telnyx platform and cannot be hosted.
number_can_not_be_repeated	Duplicate numbers are not allowed.
number_can_not_be_wireless	Wireless numbers are not allowed.
number_can_not_hosted_with_a_telnyx_subscriber	Number is already hosted with a Telnyx subscriber and cannot be hosted again.
number_is_not_a_us_number	Numbers outside the United States are not allowed.
number_is_not_a_valid_routing_number	Number is not a valid local routing number.
number_is_not_in_e164_format	Number must be in E.164 format.
numbers_can_not_be_validated	Numbers could not be validated. Try again or contact support.

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"

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

Note

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.

Note

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.

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.

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.

Note

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"

{
    "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.

Note

Right now, these numbers will not be visible in the Telnyx Portal. They will however be visible when using the Telnyx API.

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.

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

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.

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.

You can have failed statuses for both the order and its numbers. The possible failed statuses are:

Order Status	Description
carrier_rejected	Losing carrier rejected a number porting request.
failed	Order has been closed. Contact support for more information.
ineligible_carrier	A number from the losing carrier cannot be ported to Telnyx.

Number Status	Description
failed	Number has been closed. Contact support for more information.
failed_carrier_rejected	Losing carrier rejected a number porting request.
failed_ineligible_carrier	Number from the losing carrier cannot be ported to Telnyx.
failed_number_already_hosted	Number is already in Telnyx and cannot be hosted.
failed_number_not_found	Number is not in Telnyx and cannot be hosted.
failed_timeout	Timed out while activating the number.

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"

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

Note

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.

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"

{
    "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.

Note

Right now, these numbers will not be visible in the Telnyx Portal. They will however be visible when using the Telnyx API.

1. On the Mission Control Portal, click on to Numbers.

2. Navigate to Hosted SMS

3. Click on Add New Order

4. Enter the number(s) you wish to host with Telnyx in +E.164 format

5. The system will automatically check the eligibility of the entered phone numbers. Only eligible numbers can be used for hosted messaging.

6. Choose the Message Profile you'd like to add to the number(s)

7. Click on Create Order. You will automatically route to the next page where you need to upload your Authorization Documentation.

8. Upload your LOA

9. Upload your Bill

10. Click on Submit

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.

Note

Right now, these numbers will not be visible in the Telnyx Portal. They will however be visible when using the Telnyx API.