Purchase Number - SMSOnline API Doc

Executes the purchase of a phone number for the specified country and service combination.
The purchase price will not exceed the amount specified by maximumPrice, and it may be lower depending on availability.

Hint:
If phone numbers are temporarily out of stock, a NO_NUMBERS error will be returned. However, numbers are typically restocked within a few minutes, so you can automatically retry the order after an interval of about 20–30 seconds.
There is no need to change the values of maximumPrice or Hash(m,n) when retrying the purchase.

If an Additional user action required error occurs, it usually means that the phone number price has been updated.
You can use the getServiceDetail endpoint again to retrieve the latest pricing information.
Typically, phone number prices are updated every 5 minutes based on demand.

Request

Body Params application/json

userId

string

required

User Id linked to API key

key

string

required

API key

country

string

required

Country Code

service

string

required

Service Code

maximumPrice

string

required

Minimum Order Price provided by the Lookup API.

string

required

Hash value (m) provided by the Lookup API.

string

required

Hash value (n) provided by the Lookup API.

carrier

string

required

Carrier Name, provided at /cs/getListByCountry

Example

{
    "userId": "string",
    "key": "string",
    "country": "string",
    "service": "string",
    "maximumPrice": "string",
    "m": "string",
    "n": "string",
    "carrier": "string"
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Success

application/json

If the request is completed successfully, a 200 response code is returned.

Body

error

boolean

required

If the request fails, the status will be true.

orderId

string

required

Order ID. It is required when you request refund / another SMS

phoneNumber

string

required

E.164 Phone number that assigned to you

expiredAtUTC

string

required

Estimated time to be expired

purchasePrice

number

required

Actual paid amount to get the number

Example

{
    "error": false,
    "orderId": "17934774",
    "phoneNumber": "447508190549",
    "expiredAtUTC": "2025-02-15 16:40:27",
    "purchasePrice": 0.16
}

🟠401Unauthorized

🟠403Forbidden

🔴500Server Error