Search Numbers

Search for available phone numbers by country, service, provider, and rental period.

Search Endpoint

Search for available numbers with flexible filters.

Endpoint

GET /api/v1/numbers/search/

Query Parameters

Parameter	Type	Required	Description
provider	string	Yes	Provider type: virtual, virtual_rent, or residential
period	string	Yes	Rental period: MIN_15, DAY, WEEK, or MONTH
country	string	No	Country code from /countries/ endpoint
service	string	No	Service code from /services/ endpoint

Provider Types

Provider	Description	Available Periods
virtual	Virtual numbers for one-time use	MIN_15 only
virtual_rent	Virtual numbers for extended periods	DAY, WEEK, MONTH
residential	Real residential mobile numbers	MIN_15 only

Request Examples

Search by country and service

curl -X 'GET' \
  'https://app.cyberyozh.com/api/v1/numbers/search/?provider=virtual&country=2&period=MIN_15&service=ok' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: your_api_key_here'

Search by provider only

curl -X 'GET' \
  'https://app.cyberyozh.com/api/v1/numbers/search/?provider=virtual_rent&period=MONTH' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: your_api_key_here'

Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 14897,
      "code": "ok",
      "name": "ok.ru",
      "slug": "okru-40",
      "icon": "/static/website/services/ok0.webp",
      "country_code": "2",
      "country_name": "Kazakhstan",
      "is_active": true,
      "count": "<1k",
      "cost": 0.09,
      "is_bookmark": false,
      "provider": "virtual",
      "period": null,
      "url": "http://sms.cyberyozh.com/reception-sms/virtual/kazakhstan/okru-40/",
      "country": {
        "id": 169,
        "slug": "kazakhstan",
        "name": "Kazakhstan",
        "code": "2",
        "country": "KZ",
        "flag": "/static/flags/kz.gif",
        "unicode_flag": "🇰🇿"
      }
    }
  ]
}

Response Fields

Field	Type	Description
count	integer	Total number of results
results	array	Array of available number offerings
id	integer	Offering identifier
code	string	Service code
name	string	Service name
country_code	string	Country code
country_name	string	Country name
is_active	boolean	Whether offering is active
count	string	Available numbers count
cost	number	Price in USD
provider	string	Provider type
country	object	Detailed country information

Search Strategies

Find all services in a country

Pass only provider, period, and country:

curl -X 'GET' \
  'https://app.cyberyozh.com/api/v1/numbers/search/?provider=virtual&country=666&period=MIN_15' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: your_api_key_here'

Find all countries for a service

Pass only provider, period, and service:

curl -X 'GET' \
  'https://app.cyberyozh.com/api/v1/numbers/search/?provider=residential&service=tg&period=MIN_15' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: your_api_key_here'

Usage Example

import requests

headers = {
    'accept': 'application/json',
    'X-Api-Key': 'your_api_key_here'
}

params = {
    'provider': 'residential',
    'period': 'MIN_15',
    'country': '666',  # USA residential
    'service': 'tg'    # Telegram
}

response = requests.get(
    'https://app.cyberyozh.com/api/v1/numbers/search/',
    headers=headers,
    params=params
)

results = response.json()
if results['count'] > 0:
    offering = results['results'][0]
    print(f"Available: {offering['name']} in {offering['country_name']}")
    print(f"Cost: ${offering['cost']}")
else:
    print("No numbers available for this combination")

Notes

• Availability changes frequently based on demand
• Pricing varies by country and service
• Use the returned id from results when ordering numbers