Buy and Manage Numbers

Order phone numbers for SMS reception and manage active numbers.

Buy a Number

Purchase a phone number to receive SMS codes. The price is immediately deducted from the user's balance and the order starts in waiting status.

Endpoint

POST /api/v1/numbers/

Request Body

{
  "provider": "virtual",
  "period": "MIN_15",
  "service_code": "tg",
  "country_code": "2",
  "need_fraud_score": false,
  "markup_percent": 0,
  "promo_code": "DISCOUNT10"
}

Request Fields

Field	Type	Required	Description
`provider`	string	Yes	Provider type: `virtual`, `residential`, `residential_rent`
`period`	string	Yes	Rental period (see rules below)
`service_code`	string	Yes	Service code from `GET /services/` (e.g. `tg`, `google`)
`country_code`	string	Yes	Numeric country code from `GET /countries/`
`need_fraud_score`	boolean	No	Request a fraud-score check for the phone number (default `false`)
`markup_percent`	integer	No	Markup over base price in %. Allowed: `0`, `50`, `100`, `200`, `300`, `400`, `500`, `1000`, `2000` (default `0`)
`promo_code`	string	No	Promo code to apply a discount to this order

Provider and Period Rules

Provider	Available Periods
`virtual`	`MIN_15` only
`residential`	`MIN_15` only
`residential_rent`	`DAY_3`, `WEEK`, `WEEK_2`, `DAY_25`

Request Example (Virtual, 15 minutes)

curl -X 'POST' \
  'https://app.cyberyozh.com/api/v1/numbers/' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "virtual",
    "period": "MIN_15",
    "service_code": "tg",
    "country_code": "2",
    "need_fraud_score": false
  }'

Success Response (201)

Returns the full order object:

{
  "id": "71066120515e427ea147fc090fe395ce",
  "status": "waiting",
  "provider": "virtual",
  "price_usd": "0.15",
  "phone_number": "+15555555555",
  "expiration_time": null,
  "history_sms_code": [],
  "can_replay": false,
  "can_extend": false,
  "can_cancel": true
}

Error Responses

Rate Limited (429)

{
  "detail": "Request was throttled. Expected available in 50 seconds."
}

Insufficient Balance (402)

{
  "detail": "You can top up your account balance."
}

Insufficient Stock (400)

{
  "count": [
    "There are no available phone numbers, try again later!"
  ]
}

Missing Field (400)

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

Bad Service Code (400)

{
  "non_field_errors": [
    "Bad service_code"
  ]
}

Get Active Numbers

Returns all active phone number orders (status waiting) — orders currently awaiting an SMS code. For completed orders use GET /history/.

Endpoint

GET /api/v1/numbers/

Request

curl -X 'GET' \
  'https://app.cyberyozh.com/api/v1/numbers/' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: your_api_key_here'

Response

[
  {
    "id": "71066120515e427ea147fc090fe395ce",
    "status": "waiting",
    "provider": "virtual",
    "price_usd": "2.84",
    "phone_number": "+15555555555",
    "expiration_time": null,
    "history_sms_code": [],
    "can_replay": false,
    "can_extend": false,
    "can_cancel": true
  }
]

Response Fields

Field	Type	Description
`id`	string	Order UUID
`status`	string	Current order status (`waiting`)
`provider`	string	Provider type (`virtual` / `residential` / `residential_rent`)
`price_usd`	string	Amount charged in USD
`phone_number`	string	Assigned phone number
`expiration_time`	string\|null	Order expiration datetime (UTC); `null` for one-time numbers
`history_sms_code`	array	List of SMS codes received for this order
`can_replay`	boolean	Whether re-requesting an SMS is currently allowed
`can_extend`	boolean	Whether extending the rental period is currently allowed
`can_cancel`	boolean	Whether cancelling the order is currently allowed

Get Number History

Returns all orders that have reached a terminal state. Active orders (waiting) are excluded — use GET /numbers/ for those.

Endpoint

GET /api/v1/numbers/history/

Request

curl -X 'GET' \
  'https://app.cyberyozh.com/api/v1/numbers/history/' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: your_api_key_here'

Response

[
  {
    "pk": "97f39164-512f-4ccb-9b1a-22cbdee0c47f",
    "id": "97f39164-512f-4ccb-9b1a-22cbdee0c47f",
    "status": "success",
    "provider": "virtual",
    "price_usd": "0.15",
    "phone_number": "+15555555555",
    "expiration_time": null,
    "history_sms_code": ["79373"],
    "fraud_score": null,
    "expenses": "0.15",
    "report": null,
    "can_replay": false,
    "can_extend": false,
    "can_cancel": false
  }
]

Possible Statuses

Status	Description
`success`	SMS code was received
`canceled`	Order was cancelled by the user
`refund`	Order was refunded
`not_sms_code`	No SMS code arrived within the rental period
`calculation`	Order is being post-processed / calculated

Cancel a Number

Cancel an active phone number order. The charged amount is refunded to the user's balance. Cancellation is only available within a specific time window and only if no SMS has been received.

Endpoint

PUT /api/v1/numbers/{id}/cancel/

Cancellation Rules by Provider

Provider	Window	Condition
`virtual`	2–15 minutes after purchase	No SMS received
`residential`	2–15 minutes after purchase	No SMS received
`residential_rent`	Cannot be cancelled	—

Request

curl -X 'PUT' \
  'https://app.cyberyozh.com/api/v1/numbers/bb157566-8003-49f3-9e74-c1488acb9625/cancel/' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: your_api_key_here'

Success Response (200)

{
  "detail": "Cancel processed"
}

Error Responses

Already Received SMS (400)

{
  "detail": "You can't cancel if you've already received a text message."
}

Too Soon — Window Not Opened Yet (400)

{
  "detail": "You can cancel the phone number 2 minutes after you bought it."
}

Too Late — Window Expired (400)

{
  "detail": "You can cancel the phone number 20 minutes after you bought it."
}

Usage Example

import requests
import time

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

# Buy a number
order_response = requests.post(
    'https://app.cyberyozh.com/api/v1/numbers/',
    headers=headers,
    json={
        'provider': 'residential',
        'period': 'MIN_15',
        'service_code': 'tg',
        'country_code': '667',
        'need_fraud_score': True
    }
)

order = order_response.json()
order_id = order['id']
print(f"Ordered number with ID: {order_id}")

# Poll for SMS codes
for _ in range(30):  # Check for 5 minutes
    details = requests.get(
        f'https://app.cyberyozh.com/api/v1/numbers/{order_id}/',
        headers=headers
    ).json()

    if details['history_sms_code']:
        print(f"Received SMS code: {details['history_sms_code'][0]}")
        break

    time.sleep(10)
else:
    print("No SMS received, canceling...")
    requests.put(
        f'https://app.cyberyozh.com/api/v1/numbers/{order_id}/cancel/',
        headers=headers
    )

Buy a Number​

Endpoint​

Request Body​

Request Fields​

Provider and Period Rules​

Request Example (Virtual, 15 minutes)​

Success Response (201)​

Error Responses​

Rate Limited (429)​

Insufficient Balance (402)​

Insufficient Stock (400)​

Missing Field (400)​

Bad Service Code (400)​

Get Active Numbers​

Endpoint​

Request​

Response​

Response Fields​

Get Number History​

Endpoint​

Request​

Response​

Possible Statuses​

Cancel a Number​

Endpoint​

Cancellation Rules by Provider​

Request​

Success Response (200)​

Error Responses​

Already Received SMS (400)​

Too Soon — Window Not Opened Yet (400)​

Too Late — Window Expired (400)​

Usage Example​

Buy a Number

Endpoint

Request Body

Request Fields

Provider and Period Rules

Request Example (Virtual, 15 minutes)

Success Response (201)

Error Responses

Rate Limited (429)

Insufficient Balance (402)

Insufficient Stock (400)

Missing Field (400)

Bad Service Code (400)

Get Active Numbers

Endpoint

Request

Response

Response Fields

Get Number History

Endpoint

Request

Response

Possible Statuses

Cancel a Number

Endpoint

Cancellation Rules by Provider

Request

Success Response (200)

Error Responses

Already Received SMS (400)

Too Soon — Window Not Opened Yet (400)

Too Late — Window Expired (400)

Usage Example