Search Numbers

Search for available services with pricing and availability.

• Passing only country → all services available in that country
• Passing only service → all countries where that service is offered
• Passing both → data for that specific service/country combination

Search Endpoint

Endpoint

GET /api/v1/numbers/search/

Query Parameters

Parameter	Required	Description
provider	Yes	virtual, virtual_rent, residential, residential_rent
period	Yes	Period valid for the chosen provider (see table below)
country	No	Numeric country code from GET /countries/
service	No	Service code or slug from GET /services/

Provider and Period Rules

Provider	Available Periods
virtual	MIN_15 only
virtual_rent	HOUR_4, HOUR_12, DAY, DAY_3, WEEK
residential	MIN_15 only
residential_rent	DAY_3, WEEK, WEEK_2, DAY_25

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'

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/"
    }
  ]
}

Response Fields

Field	Type	Description
count	integer	Total number of results
results	array	Array of available service 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

Error Responses

Status	Description
400	Invalid or incompatible parameter combination
401	Invalid or missing API key
429	Rate limit exceeded

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=667&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': '667',  # 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
• The count here is the total availability for a country/service — there is no operator filter in search. For the per-operator breakdown use GET /operators/