Get Bulk Status of Numbers With Conditions

This endpoint allows you to filter phone numbers by criteria such as country, service, status, and expiration date, and retrieve the current status of multiple phone numbers in a single response as an array. Ideal for use cases that require simultaneous use and management of a large number of phone numbers.

All parameters except userId and key are optional. Omit any parameter from the query if you do not wish to filter by it.

Request

Query Params

userId

string

required

Specify the userId of the user who purchased the phone number

Example:

key

string

required

Specify the API key

Example:

country

string

optional

Country name. Must match one returned by Lookup API / Get Available Countries.

Example:

Hong Kong

service

string

optional

Service name. Must match one returned by Lookup API / Get Available Services.

Example:

Facebook

status

string

optional

Phone number status. One of: waitingForSMS, completed, refunded, expired, or orderFailed.

Example:

completed

since

string <date-time>

optional

Start date of the time range.

Example:

2025-01-01

until

string <date-time>

optional

End date of the time range.

Example:

2025-04-01

dateOrder

string

optional

Sort result set by date, either ascending or descending.

Example:

asc

limit

integer

optional

Set the maximum number of results to return.

Example:

isError

boolean

optional

Set to true or 1 to retrieve only failed purchases.

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Success

application/json

If a phone number matching the orderId exists, the status will be returned.

Body

error

boolean

required

body

array [object {11}]

required

orderId

string

required

phoneNumber

string

required

receivedSMS

string

required

status

string

required

country

string

required

service

string

required

orderedAt

string

required

expiredAt

string

required

lastCheckedAt

string

required

purchasePrice

integer

required

failedReason

null

required

Example

{
    "error": false,
    "body": [
        {
            "orderId": "123456789",
            "phoneNumber": "8512345667",
            "receivedSMS": "123456",
            "status": "completed",
            "country": "Hong Kong",
            "service": "Foo",
            "orderedAt": "2025-01-24 18:00:00",
            "expiredAt": "2025-01-24 19:00:00",
            "lastCheckedAt": "2025-01-24 18:01:00",
            "purchasePrice": 20,
            "failedReason": null
        }
    ]
}

🟠401Unauthorized