Get number by operator
Request an activation number from a selected operator.
This request can change an order or incur charges. The examples do not retry it automatically. Reading a newly received SMS can trigger payment, even though the method uses GET.
Authentication
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
apikey | header | string | Yes | Your API key |
Parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
country | path | string | Yes | Country 2 symbols name in ISO 3166-2 format, uppercase. Countries list |
service | path | string | Yes | Service code. Services list |
operator | path | string | Yes | Operator code. Regular and donor operators are accepted. |
voice | query | integer | No | Number type: 0 - SMS, 1 - caller-ID, 2 - voice call. Defaults to 0. (enum: [0,1,2]; default: 0) |
No request body is required.
How to use this method
Request a number from a specific operator for your chosen country and service. Regular and donor operator codes are accepted.
Choose codes from the reference lists. Check prices, number counts and message type settings before ordering. You can also compare operator prices and prices by country.
Save data.orderId for Receive SMS and other order requests. Use data.orderExpireIn to calculate the order deadline. If the request times out, check Current orders before requesting another number: the first order may already exist.
Get valid operator codes from Operators. Donor operators, such as DonorAlpha_UK, supply numbers through external providers. They use the same request format, but their numbers may be less consistent than SMSPVA’s own real SIM cards.
Request examples
Runtime requirements and environment setup. cURL uses a POSIX shell. JavaScript and TypeScript run in Node.js. Java uses the standard HTTP client and prints raw JSON; use your application’s JSON library to inspect the body.
: "${SMSPVA_API_KEY:?Set SMSPVA_API_KEY}"
curl --fail-with-body --max-time 30 --request GET \
--url "https://api.smspva.com/activation/number/BD/opt20/Grameenphone_BD?voice=0" \
--header "apikey: $SMSPVA_API_KEY"Responses
The examples below show the response format. Prices, stock and account values are sample data; use the API response for current values.
| HTTP | Description |
|---|---|
| 200 | Successful operation |
| 405 | Invalid parameters |
| 407 | Your balance is too low to receive sms for selected country and service. |
| 411 | API access limited by low karma or ratelimits |
| 500 | Failed to fetch number |
| 501 | Number not found |
| 502 | Number not found. |
| 503 | Server overload, try later. |
HTTP 200
Successful operation
Illustrative response
{
"statusCode": 200,
"data": {
"orderId": 123456,
"phoneNumber": 9876544321,
"countryCode": "BD",
"orderExpireIn": 600
}
}Response fields
| Name | Type | Description |
|---|---|---|
statusCode | integer | Result status code |
data | object | Response data |
data.orderId | integer | Order ID |
data.phoneNumber | integer | Phone number without country code |
data.countryCode | string | Country code according ITU-T E.123 & E.164 Countries list |
data.orderExpireIn | integer | Order expiration time in seconds |
HTTP 405
Invalid parameters
Illustrative response
{
"statusCode": 405,
"error": {
"type": "INVALID_PARAMS",
"description": "Invalid params."
}
}Response fields
| Name | Type | Description |
|---|---|---|
statusCode | integer | Result status code |
error | object | Error data |
error.type | string | Error type |
error.description | string | Error description |
HTTP 407
Your balance is too low to receive sms for selected country and service.
HTTP 411
API access limited by low karma or ratelimits
HTTP 500
Failed to fetch number
HTTP 501
Number not found
HTTP 502
Number not found.
HTTP 503
Server overload, try later.
Related guides
If a connection fails during an order-changing request, check the order before trying again.