Receive SMS
Retrieve SMS, caller-ID or voice results; HTTP 202 means the result is pending.
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 |
partnerkey | header | string | No | Optional partner key for referral accounting. It is used only when SMS is received successfully. |
Parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
orderid | path | integer | Yes | ID of order received in number response |
No request body is required.
How to use this method
Use the orderId from your number request or Current orders to retrieve the result. This method also returns caller-ID and voice-call results; the type was selected when ordering with voice=0, voice=1 or voice=2. Do not send another voice parameter here.
The provider’s text becomes data.sms.code, and its sms becomes data.sms.fullText. Both values pass through unchanged, so code may contain more than a numeric verification code.
HTTP 202 with statusCode=202 and error.type=SMS_NOT_YET_RECEIVED means the result is still pending. Handle it before general errors and wait before checking again. The same rule applies to all three message types. See the polling guide.
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_ORDER_ID:orderid(required).
: "${SMSPVA_API_KEY:?Set SMSPVA_API_KEY}"
: "${SMSPVA_ORDER_ID:?Set SMSPVA_ORDER_ID to your orderid}"
curl --fail-with-body --max-time 30 --request GET \
--url "https://api.smspva.com/activation/sms/${SMSPVA_ORDER_ID}" \
--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 |
| 202 | The result is not ready yet. Applies to SMS, voice-call and caller-ID orders alike; the API uses SMS_NOT_YET_RECEIVED and Waiting for SMS for all three types. |
| 405 | Invalid parameters |
| 406 | Order ID format is invalid or not found |
| 407 | We received SMS but your balance is not enough to pay it. |
| 410 | This order is closed and unavailable |
| 411 | API access limited by low karma or ratelimits |
| 500 | Failed to fetch SMS. |
| 501 | Server failed to process request. |
| 503 | The server is overloaded and experiencing performance issues. Please try later. |
HTTP 200
Successful operation
SMS (voice=0)
{
"statusCode": 200,
"data": {
"sms": {
"code": "123456",
"fullText": "Your verification code is 123456"
},
"orderId": 123456,
"orderExpireIn": 420
}
}Voice call (voice=2)
Illustrative voice-call result. fullText contains text and a recording link in the format VOICE: ...; The file: ....
The content of code depends on the provider and is not confirmed; a numeric verification code is not guaranteed.
{
"statusCode": 200,
"data": {
"sms": {
"code": "<provider text value>",
"fullText": "VOICE: Your code is 123456; The file: https://link.smspva.com/EXAMPLE_RECORD_ID"
},
"orderId": 123456,
"orderExpireIn": 420
}
}Voice call - link only (voice=2)
Possible format: fullText may contain only a recording link. This variant is not confirmed, so do not rely on a fixed text format.
code is a placeholder for the provider's unchanged text value.
{
"statusCode": 200,
"data": {
"sms": {
"code": "<provider text value>",
"fullText": "https://link.smspva.com/EXAMPLE_RECORD_ID"
},
"orderId": 123456,
"orderExpireIn": 420
}
}Caller-ID (voice=1)
The JSON structure is the same as for SMS. The field contents shown here are placeholders: the exact caller-ID format is not confirmed.
The provider may return a code or a caller number in code and a message in fullText. Do not assume that code always contains a verification code.
{
"statusCode": 200,
"data": {
"sms": {
"code": "<provider text: code or caller number>",
"fullText": "<provider sms: caller-ID message>"
},
"orderId": 123456,
"orderExpireIn": 420
}
}Response fields
| Name | Type | Description |
|---|---|---|
statusCode | integer | Result status code |
data | object | Response data |
data.sms | object | Received SMS content |
data.sms.code | string | Provider text field, passed through unchanged. Its content depends on the message type and provider; it is not always a verification code. |
data.sms.fullText | string | Provider sms field, passed through unchanged. May contain SMS text, voice-call text with a recording link, a recording link alone, or caller-ID content. |
data.orderId | integer | Order ID |
data.orderExpireIn | integer | Order expiration time in seconds |
HTTP 202
The result is not ready yet. Applies to SMS, voice-call and caller-ID orders alike; the API uses SMS_NOT_YET_RECEIVED and Waiting for SMS for all three types.
Illustrative response
{
"statusCode": 202,
"error": {
"type": "SMS_NOT_YET_RECEIVED",
"description": "Waiting for SMS"
}
}Response fields
| Name | Type | Description |
|---|---|---|
statusCode | integer | Result status code |
error | object | Error data |
error.type | string | |
error.description | string |
HTTP 405
Invalid parameters
Illustrative response
{
"statusCode": 405,
"error": {
"type": "INVALID_PARAMS",
"description": "Invalid params, please re-check the specified data."
}
}Response fields
| Name | Type | Description |
|---|---|---|
statusCode | integer | Result status code |
error | object | Error data |
error.type | string | |
error.description | string |
HTTP 406
Order ID format is invalid or not found
Illustrative response
{
"statusCode": 406,
"error": {
"type": "INVALID_ORDER_FORMAT",
"description": "Order should be integer."
}
}Response fields
| Name | Type | Description |
|---|---|---|
statusCode | integer | Result status code |
error | object | Error data |
error.type | string | |
error.description | string |
HTTP 407
We received SMS but your balance is not enough to pay it.
Illustrative response
{
"statusCode": 407,
"error": {
"type": "LOW_BALANCE",
"description": "Low balance"
}
}Response fields
| Name | Type | Description |
|---|---|---|
statusCode | integer | Result status code |
error | object | Error data |
error.type | string | |
error.description | string |
HTTP 410
This order is closed and unavailable
Illustrative response
{
"statusCode": 410,
"error": {
"type": "ORDER_CLOSED",
"description": "Order closed and unavailable"
}
}Response fields
| Name | Type | Description |
|---|---|---|
statusCode | integer | Result status code |
error | object | Error data |
error.type | string | |
error.description | string |
HTTP 411
API access limited by low karma or ratelimits
Illustrative response
{
"statusCode": 411,
"error": {
"type": "ACCESS_LIMITED",
"description": "Access is temporary limited"
}
}Response fields
| Name | Type | Description |
|---|---|---|
statusCode | integer | Result status code |
error | object | Error data |
error.type | string | |
error.description | string |
HTTP 500
Failed to fetch SMS.
Illustrative response
{
"statusCode": 500,
"error": {
"type": "SMS_FETCH_FAIL",
"description": "Failed to fetch SMS."
}
}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 501
Server failed to process request.
Illustrative response
{
"statusCode": 501,
"error": {
"type": "SERVER_FAIL",
"description": "Server failed to process request"
}
}Response fields
| Name | Type | Description |
|---|---|---|
statusCode | integer | Result status code |
error | object | Error data |
error.type | string | |
error.description | string |
HTTP 503
The server is overloaded and experiencing performance issues. Please try later.
Illustrative response
{
"statusCode": 503,
"error": {
"type": "SERVER_BUSY",
"description": "Server overload, try later."
}
}Response fields
| Name | Type | Description |
|---|---|---|
statusCode | integer | Result status code |
error | object | Error data |
error.type | string | Error type |
error.description | string | Error description |
Related guides
If a connection fails during an order-changing request, check the order before trying again.