BEE-SMS Rental Number API Documentation

The Rental Number API lets you programmatically purchase and manage long-term virtual numbers. All requests are GET-based and require your API Token.

Protocol Description

All requests should go to https://api.bee-sms.com

All requests must have an API Token as a parameter "token"

Search for country and service code

List country code

List service code

List available rental services

GET - https://api.bee-sms.com/v1/rental/services?token=$token

Parameters

Field	Location	Type	Required	Description
token	query	String	Yes	Your API Token

Result

Field	Type	Description
code	Number	Response status
message	String	Response description
data	Array	List of available services

Columns of data

Field	Type	Description
code	String	Service code
name	String	Service name
image	String	Service image

Success

{
  "code": 200,
  "message": "Operation Success",
  "data": [
    {
      "code": "tg",
      "name": "Telegram",
      "image": "https://example.com/telegram.png"
    }
  ]
}

Possible Errors

{
  "code": 401,
  "message": "Not yet logged in or certificate has expired"
}

List rental prices

GET - https://api.bee-sms.com/v1/rental/prices?token=$token&service=$service_code&area=$area_code

Parameters

Field	Location	Type	Required	Description
token	query	String	Yes	Your API Token
service	query	String	Optional	Service Code
area	query	String	Optional	Country / Area Code

The service and area parameters must have at least one

Result

Field	Type	Description
code	Number	Response status
message	String	Response description
data	Array	List of price data

Columns of data

Field	Type	Description
service_code	String	Service code
service_name	String	Service name
service_image	String	Service image
area_code	String	Area code
area_name	String	Area name
area_image	String	Area image
durations	Array	Rental duration options for this service-area

Columns of durations

Field	Type	Description
days	Number	Duration in days
amount	Number	Base price in cents (e.g., 100 cents = $1.00)
actual_amount	Number	Your price after loyalty discount, in cents
qty	Number	Available number count

Success

{
  "code": 200,
  "message": "Operation Success",
  "data": [
    {
      "service_code": "tg",
      "service_name": "Telegram",
      "service_image": "https://example.com/telegram.png",
      "area_code": "us",
      "area_name": "United States",
      "area_image": "https://example.com/us.png",
      "durations": [
        {
          "days": 30,
          "amount": 1500,
          "actual_amount": 1425,
          "qty": 24
        }
      ]
    }
  ]
}

Possible Errors

// Both the service and area parameters are missing.
{
  "code": 400,
  "message": "Invalid Parameter"
}
{
  "code": 401,
  "message": "Not yet logged in or certificate has expired"
}

Purchase a rental number

GET - https://api.bee-sms.com/v1/rental/purchase?token=$token&service=$service_code&area=$area_code&duration=$duration

Parameters

Field	Location	Type	Required	Description
token	query	String	Yes	Your API Token
service	query	String	Yes	Service Code
area	query	String	Yes	Country / Area Code
duration	query	String	Yes	Rental duration in days
auto_renew	query	Boolean	No	Enable automatic renewal before expiry
max_amount	query	String	No	No number will be purchased if the price exceeds this amount, unit cents (e.g., 100 cents = $1.00)

Result

Field	Type	Description
code	Number	Response status
message	String	Response description
data	Object	Rental order data

Columns of data

Field	Type	Description
order_id	String	Rental order ID
dialing_code	String	Country dialing code
mobile_number	String	Assigned phone number (without dialing code)
area_code	String	Area code
area_name	String	Area name
service_code	String	Service code
service_name	String	Service name
duration	Number	Rental duration in days
rental_start_at	String	Rental start time (ISO 8601)
rental_end_at	String	Rental expiry time (ISO 8601)
actual_amount	Number	Amount actually charged after discount, in cents
amount	Number	Original price before discount, in cents
is_auto_renew	Boolean	Whether auto-renewal is enabled
create_at	String	Order creation time (ISO 8601)

Success

{
  "code": 200,
  "message": "Operation Success",
  "data": {
    "order_id": "3541517119212500001",
    "dialing_code": "1",
    "mobile_number": "4155552671",
    "area_code": "us",
    "area_name": "United States",
    "service_code": "tg",
    "service_name": "Telegram",
    "duration": 30,
    "rental_start_at": "2025-01-01T00:00:00Z",
    "rental_end_at": "2025-01-31T00:00:00Z",
    "actual_amount": 1425,
    "amount": 1500,
    "is_auto_renew": false,
    "create_at": "2025-01-01T00:00:00Z"
  }
}

Possible Errors

{
  "code": 401,
  "message": "Not yet logged in or certificate has expired"
}
{
  "code": 50001,
  "message": "Balance not enough"
}
{
  "code": 50111,
  "message": "No number available, please try again later."
}
{
  "code": 50115,
  "message": "Failed to order because the price exceeded the maximum price."
}
{
  "code": 50302,
  "message": "Rental order not found."
}

List your rental numbers

GET - https://api.bee-sms.com/v1/rental/numbers?token=$token&status=$status&mobile_number=$mobile_number&page_num=$page_num&page_size=$page_size

Parameters

Field	Location	Type	Required	Description
token	query	String	Yes	Your API Token
status	query	String	No	Filter by status (ACTIVE, EXPIRED, CANCELLED)
mobile_number	query	String	No	Filter by phone number
page_num	query	String	No	Page number (default: 1)
page_size	query	String	No	Page size (default: 20)

Result

Field	Type	Description
code	Number	Response status
message	String	Response description
data	Object	Paginated order list

Columns of data

Field	Type	Description
order_id	String	Rental order ID
status	String	Order status (ACTIVE, EXPIRED, CANCELLED)
dialing_code	String	Country dialing code
mobile_number	String	Assigned phone number (without dialing code)
area_code	String	Area code
area_name	String	Area name
service_code	String	Service code
service_name	String	Service name
duration	Number	Rental duration in days
rental_end_at	String	Rental expiry time (ISO 8601)
actual_amount	Number	Amount actually charged after discount, in cents
amount	Number	Original price before discount, in cents
sms_received_count	Number	Total SMS received

Success

{
  "code": 200,
  "message": "Operation Success",
  "data": {
    "page_num": 1,
    "page_size": 20,
    "total": 3,
    "total_page": 1,
    "list": [
      {
        "order_id": "3541517119212500001",
        "status": "ACTIVE",
        "mobile_number": "4155552671",
        "dialing_code": "1",
        "area_code": "us",
        "area_name": "United States",
        "service_code": "tg",
        "service_name": "Telegram",
        "duration": 30,
        "rental_end_at": "2025-01-31T00:00:00Z",
        "actual_amount": 1425,
        "amount": 1500,
        "sms_received_count": 5
      }
    ]
  }
}

Possible Errors

{
  "code": 401,
  "message": "Not yet logged in or certificate has expired"
}

Get rental order detail

GET - https://api.bee-sms.com/v1/rental/order?token=$token&order_id=$order_id

Returns the order record for the given order_id (purchase or renewal transaction). For the rented number lifecycle (status, expiry, SMS count), use List your rental numbers.

Parameters

Field	Location	Type	Required	Description
token	query	String	Yes	Your API Token
order_id	query	String	Yes	Order ID (purchase or renewal)

Result

Field	Type	Description
code	Number	Response status
message	String	Response description
data	Object	Order record

Columns of data

Field	Type	Description
order_id	String	Order ID
order_type	String	Order type: `PURCHASE` or `RENEWAL`
status	String	Order status: `COMPLETED`, `CANCELLED`
dialing_code	String	Country dialing code
mobile_number	String	Phone number (without dialing code)
area_code	String	Area code
area_name	String	Area name
service_code	String	Service code
service_name	String	Service name
duration	Number	Order duration in days
actual_amount	Number	Amount actually charged after discount, in cents
amount	Number	Original price before discount, in cents
create_at	String	Order creation time (ISO 8601)

Success

{
  "code": 200,
  "message": "Operation Success",
  "data": {
    "order_id": "3541517119212500001",
    "order_type": "PURCHASE",
    "status": "COMPLETED",
    "dialing_code": "1",
    "mobile_number": "4155552671",
    "area_code": "us",
    "area_name": "United States",
    "service_code": "tg",
    "service_name": "Telegram",
    "duration": 30,
    "actual_amount": 1425,
    "amount": 1500,
    "create_at": "2025-01-01T00:00:00Z"
  }
}

Possible Errors

{
  "code": 401,
  "message": "Not yet logged in or certificate has expired"
}
{
  "code": 404,
  "message": "Not Found"
}

Get SMS received on a rental number

GET - https://api.bee-sms.com/v1/rental/sms?token=$token&order_id=$order_id&page_num=$page_num&page_size=$page_size

Parameters

Field	Location	Type	Required	Description
token	query	String	Yes	Your API Token
order_id	query	String	Yes	Rental Order ID
page_num	query	String	No	Page number (default: 1)
page_size	query	String	No	Page size (default: 20)

Result

Field	Type	Description
code	Number	Response status
message	String	Response description
data	Array	List of SMS messages

Columns of data

Field	Type	Description
id	String	SMS record ID
from	String	Sender number
sms_content	String	SMS message body
received_at	String	Received time (ISO 8601)

Success

{
  "code": 200,
  "message": "Operation Success",
  "data": [
    {
      "id": "1234567890",
      "from": "+12125551234",
      "sms_content": "Your verification code is 482901",
      "received_at": "2025-01-15T10:30:00Z"
    }
  ]
}

Possible Errors

{
  "code": 401,
  "message": "Not yet logged in or certificate has expired"
}
{
  "code": 404,
  "message": "Not Found"
}

Renew a rental number

GET - https://api.bee-sms.com/v1/rental/renew?token=$token&order_id=$order_id&duration=$duration

Parameters

Field	Location	Type	Required	Description
token	query	String	Yes	Your API Token
order_id	query	String	Yes	Rental Order ID
duration	query	String	Yes	Extension duration days

Result

Field	Type	Description
code	Number	Response status
message	String	Response description

Success

{
  "code": 200,
  "message": "Operation Success"
}

Possible Errors

{
  "code": 401,
  "message": "Not yet logged in or certificate has expired"
}
{
  "code": 404,
  "message": "Not Found"
}
{
  "code": 50001,
  "message": "Balance not enough"
}
{
  "code": 50304,
  "message": "Rental renewal failed, please try again."
}

Cancel a rental number

Cancels the rental number and refunds the remaining balance if no SMS has been received within 24 hours of the last renewal.

GET - https://api.bee-sms.com/v1/rental/cancel?token=$token&order_id=$order_id

Parameters

Field	Location	Type	Required	Description
token	query	String	Yes	Your API Token
order_id	query	String	Yes	Rental Order ID

Result

Field	Type	Description
code	Number	Response status
message	String	Response description

Success

{
  "code": 200,
  "message": "Operation Success"
}

Possible Errors

{
  "code": 401,
  "message": "Not yet logged in or certificate has expired"
}
{
  "code": 404,
  "message": "Not Found"
}
{
  "code": 50303,
  "message": "This order is not eligible for refund."
}