Operators

Get the mobile operators available for a specific purchase.

Get Operators List

Returns the operators that can be bought right now for a given provider, country and service (and rental period for virtual_rent). This is exactly the availability slice that POST /api/v1/numbers/ validates against, so any code returned here is accepted as operator_code when buying a number.

Endpoint

GET /api/v1/numbers/operators/

Query Parameters

Parameter	Type	Required	Description
provider	string	Yes	virtual or virtual_rent. Residential providers have no operators
country_code	string	Yes	Numeric country code from GET /countries/
service_code	string	Yes	Service code from GET /services/ (e.g. tg, google)
period	string	For virtual_rent	Rental period: HOUR_4, HOUR_12, DAY, DAY_3, WEEK. Not used for virtual

Rental availability is tracked per duration, which is why period is required for virtual_rent: the returned count is the availability for that exact period. For virtual (one-time activation) there is no period.

Request Example (Virtual)

curl -X 'GET' \
  'https://app.cyberyozh.com/api/v1/numbers/operators/?provider=virtual&country_code=2&service_code=tg' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: your_api_key_here'

Request Example (Virtual Rent, 1 day)

curl -X 'GET' \
  'https://app.cyberyozh.com/api/v1/numbers/operators/?provider=virtual_rent&country_code=2&service_code=tg&period=DAY' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: your_api_key_here'

Response

[
  {
    "code": "any",
    "name": "Any operator",
    "count": 374
  },
  {
    "code": "beeline",
    "name": "Beeline",
    "count": 43
  },
  {
    "code": "mts",
    "name": "Mts",
    "count": 6
  }
]

The pseudo-operator any ("any operator") comes first, the remaining operators are ordered by descending availability.

Response Fields

Field	Type	Description
code	string	Operator code — pass it as operator_code to POST /numbers/
name	string	Human-readable operator name
count	integer	Numbers currently available for this operator. Always > 0 — operators without stock are not returned

Error Responses

Missing Parameter (400)

{
  "service_code": [
    "This field is required."
  ]
}

Missing Period for Rent (400)

{
  "period": [
    "This query parameter is required for virtual_rent."
  ]
}

Unsupported Provider (400)

{
  "provider": [
    "\"residential\" is not a valid choice."
  ]
}

Status	Description
400	Missing or invalid parameters
401	Invalid or missing API key
429	Rate limit exceeded

Important Notes

• Always request operators for the exact combination you are going to buy. Availability is tracked per (provider, country_code, service_code, period); a code taken from a different combination is rejected with Bad operator_code on purchase.
• An empty [] does not mean "no operators". The list is refreshed in the background, so the first request for a new country/service pair may come back empty while the data is being fetched. Repeat the request after 1–3 seconds. Repeated requests within ~30 seconds do not trigger a new refresh, so polling is safe.
• Operators apply to virtual and virtual_rent only. For residential and residential_rent the endpoint returns 400, and operator_code is ignored on purchase.
• Operator selection can be disabled for an account. In that case the endpoint returns the single entry {"code": "any", "name": "Any operator", "count": 2}, and an explicit operator_code sent to POST /numbers/ is ignored — the purchase still succeeds, just without operator targeting.
• Choosing any explicitly is a valid strategy: it tells the service that the operator does not matter.
• Availability changes frequently — re-request the list right before buying instead of caching it.

Usage Example

import requests

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

purchase = {
    'provider': 'virtual',
    'period': 'MIN_15',
    'service_code': 'tg',
    'country_code': '2'
}

# List operators for this exact purchase
operators = requests.get(
    'https://app.cyberyozh.com/api/v1/numbers/operators/',
    headers=headers,
    params={
        'provider': purchase['provider'],
        'country_code': purchase['country_code'],
        'service_code': purchase['service_code']
    }
).json()

for operator in operators:
    print(f"{operator['name']} (code: {operator['code']}, available: {operator['count']})")

# Buy a number from the operator with the best availability
if operators:
    purchase['operator_code'] = max(operators, key=lambda item: item['count'])['code']

order = requests.post(
    'https://app.cyberyozh.com/api/v1/numbers/',
    headers=headers,
    json=purchase
).json()

print(f"Bought {order['id']} from operator {order['operator_code']}")