User API documentation
Use your API key to read account information, browse the catalog, purchase numbers, and renew rentals.
Authentication and general rules
Send your API key in one of the following headers. Do not send both.
Authorization: Bearer smsu_your_api_key
# or
X-API-Key: smsu_your_api_keyEvery response uses a JSON envelope {code, msg, data}. Errors return {code, msg}. Prices and balances are decimal strings to preserve precision.
- General limit: 30 requests per 60 seconds per user, shared across the User API.
- Purchase: an additional limit of 3 requests per 60 seconds per user.
- Renewal: an additional limit of 5 requests per 60 seconds per user.
- When rate limited, the API returns HTTP 429 and a Retry-After header in seconds.
- Counters are shared within one Node.js process. Separate instances have separate counters.
- Purchase requires duration because pricing depends on the rental period. The server generates an internal processing key; clients do not need to send requestKey.
- Do not repeat a purchase request until the previous order's outcome is known. A new request after the order completes creates a new order.
User information
GETURL
/api/user-api/userParameters
No parameters.Request
No request body.Example response
{
"code": 200,
"msg": "Success",
"data": {
"name": "Example User",
"email": "[email protected]",
"balance": "12.500000"
}
}Response codes
200Success.202Request accepted; the order or renewal is processing or awaiting admin review.400Missing or invalid parameters.401Missing or invalid API key, or the account is no longer active.403The account is not allowed to perform this action.404Server, country, service, or number not found.409Business conflict, insufficient balance or stock, or provider-reported failure.415Write requests must use Content-Type: application/json.429Request limit exceeded; the response includes a Retry-After header.500Unexpected system error.503Temporarily unavailable because configuration, the provider, or renewal is not ready.
Server list
GETURL
/api/user-api/serversParameters
No parameters.Request
No request body.Example response
{
"code": 200,
"msg": "Success",
"data": [
{
"server_id": "server_1",
"server_name": "Server 1",
"status": "available"
},
{
"server_id": "server_2",
"server_name": "Server 2",
"status": "unavailable"
}
]
}Response codes
200Success.202Request accepted; the order or renewal is processing or awaiting admin review.400Missing or invalid parameters.401Missing or invalid API key, or the account is no longer active.403The account is not allowed to perform this action.404Server, country, service, or number not found.409Business conflict, insufficient balance or stock, or provider-reported failure.415Write requests must use Content-Type: application/json.429Request limit exceeded; the response includes a Retry-After header.500Unexpected system error.503Temporarily unavailable because configuration, the provider, or renewal is not ready.
Country list
GETURL
/api/user-api/countries?serverId=server_1Parameters
Query parameters:
serverId: string — required; server_1 or server_2.Request
No request body.Example response
{
"code": 200,
"msg": "Success",
"data": [
{
"id": "1",
"name": "United States"
},
{
"id": "2",
"name": "United Kingdom"
}
]
}Response codes
200Success.202Request accepted; the order or renewal is processing or awaiting admin review.400Missing or invalid parameters.401Missing or invalid API key, or the account is no longer active.403The account is not allowed to perform this action.404Server, country, service, or number not found.409Business conflict, insufficient balance or stock, or provider-reported failure.415Write requests must use Content-Type: application/json.429Request limit exceeded; the response includes a Retry-After header.500Unexpected system error.503Temporarily unavailable because configuration, the provider, or renewal is not ready.
Card type list
GETURL
/api/user-api/card-types?serverId=server_1Parameters
Query parameters:
serverId: string — required; server_1 or server_2.Request
No request body.Example response
{
"code": 200,
"msg": "Success",
"data": [
{
"id": 0,
"name": "First-time card"
},
{
"id": 1,
"name": "Secondary card"
},
{
"id": 2,
"name": "Renewal card purchase"
}
]
}Response codes
200Success.202Request accepted; the order or renewal is processing or awaiting admin review.400Missing or invalid parameters.401Missing or invalid API key, or the account is no longer active.403The account is not allowed to perform this action.404Server, country, service, or number not found.409Business conflict, insufficient balance or stock, or provider-reported failure.415Write requests must use Content-Type: application/json.429Request limit exceeded; the response includes a Retry-After header.500Unexpected system error.503Temporarily unavailable because configuration, the provider, or renewal is not ready.
Service list
GETURL
/api/user-api/services?serverId=server_1&countryId=1&cardType=0Parameters
Query parameters:
serverId: string — required
countryId: string — required
cardType: integer — optional, defaults to 0
serviceId: string — optional, filter by IDRequest
No request body.Example response
{
"code": 200,
"msg": "Success",
"data": [
{
"id": "service-123",
"name": "Example Service"
}
]
}Response codes
200Success.202Request accepted; the order or renewal is processing or awaiting admin review.400Missing or invalid parameters.401Missing or invalid API key, or the account is no longer active.403The account is not allowed to perform this action.404Server, country, service, or number not found.409Business conflict, insufficient balance or stock, or provider-reported failure.415Write requests must use Content-Type: application/json.429Request limit exceeded; the response includes a Retry-After header.500Unexpected system error.503Temporarily unavailable because configuration, the provider, or renewal is not ready.
Prices
GETURL
/api/user-api/prices?serverId=server_1&countryId=1&serviceId=service-123Parameters
Query parameters:
serverId: string — required
countryId: string — required
serviceId: string — optional, filter by ID
cardType: integer — optional, defaults to 0Request
No request body.Example response
{
"code": 200,
"msg": "Success",
"data": {
"countryId": "1",
"countryName": "United States",
"services": [
{
"serviceId": "service-123",
"serviceName": "Example Service",
"price": {
"10": "0.50",
"30": "1.20",
"60": "2.00"
}
}
]
}
}Response codes
200Success.202Request accepted; the order or renewal is processing or awaiting admin review.400Missing or invalid parameters.401Missing or invalid API key, or the account is no longer active.403The account is not allowed to perform this action.404Server, country, service, or number not found.409Business conflict, insufficient balance or stock, or provider-reported failure.415Write requests must use Content-Type: application/json.429Request limit exceeded; the response includes a Retry-After header.500Unexpected system error.503Temporarily unavailable because configuration, the provider, or renewal is not ready.
Purchase
POSTURL
/api/user-api/purchaseParameters
JSON body:
serverId: string — required
countryId: string — required
cardType: integer — required
serviceId: string — required
quantity: integer — required, from 1 to 20
duration: integer — required, 10, 30 or 60Request
{
"serverId": "server_1",
"countryId": "1",
"cardType": 0,
"serviceId": "service-123",
"quantity": 1,
"duration": 10
}Example response
{
"code": 200,
"msg": "Success",
"data": {
"order_code": "20261109123456789",
"status": "completed",
"order_url": "https://smsus.cc/api/links?code=20261109123456789"
}
}Response codes
200Success.202Request accepted; the order or renewal is processing or awaiting admin review.400Missing or invalid parameters.401Missing or invalid API key, or the account is no longer active.403The account is not allowed to perform this action.404Server, country, service, or number not found.409Business conflict, insufficient balance or stock, or provider-reported failure.415Write requests must use Content-Type: application/json.429Request limit exceeded; the response includes a Retry-After header.500Unexpected system error.503Temporarily unavailable because configuration, the provider, or renewal is not ready.
Renewal
POSTURL
/api/user-api/renewalParameters
JSON body:
api_token: string — required; API token of a number owned by the userRequest
{
"api_token": "abcdefghij123456"
}Example response
{
"code": 200,
"msg": "Success",
"data": {
"renewal_id": "67890",
"api_token": "abcdefghij123456",
"status": "completed"
}
}Response codes
200Success.202Request accepted; the order or renewal is processing or awaiting admin review.400Missing or invalid parameters.401Missing or invalid API key, or the account is no longer active.403The account is not allowed to perform this action.404Server, country, service, or number not found.409Business conflict, insufficient balance or stock, or provider-reported failure.415Write requests must use Content-Type: application/json.429Request limit exceeded; the response includes a Retry-After header.500Unexpected system error.503Temporarily unavailable because configuration, the provider, or renewal is not ready.