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.

Endpoint

POST /api/v1/numbers/

Request Body

{
  "provider": "virtual" | "virtual_rent" | "residential",
  "period": "MIN_15" | "DAY" | "WEEK" | "MONTH",
  "service_code": "tg",
  "country_code": "2",
  "need_fraud_score": false
}

Request Fields

Field	Type	Required	Description
`provider`	string	Yes	Provider type
`period`	string	Yes	Rental period
`service_code`	string	Yes	Service code from `/services/`
`country_code`	string	Yes	Country code from `/countries/`
`need_fraud_score`	boolean	No	Request fraud score check

Provider and Period Rules

virtual: Only MIN_15 period
virtual_rent: Only DAY, WEEK, MONTH periods
residential: Only MIN_15 period

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
  }'

Request Example (Virtual Rent, Day)

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_rent",
    "period": "DAY",
    "service_code": "tg",
    "country_code": "1",
    "need_fraud_score": false
  }'

Success Response (201)

{
  "id": "71066120515e427ea147fc090fe395ce",
  "pk": "71066120-515e-427e-a147-fc090fe395ce",
  "provider": "virtual",
  "period": "MIN_15",
  "service": "tg",
  "country": "2",
  "need_fraud_score": false,
  "status": "new"
}

Error Responses

Rate Limited (429)

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

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

Retrieve all active numbers in "waiting" status.

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": "2025-12-09T10:28:08Z",
    "report": null,
    "history_sms_code": [],
    "can_replay": false,
    "can_extend": false,
    "can_cancel": true,
    "expenses": 2.84,
    "fraud_score": null
  }
]

Response Fields

Field	Type	Description
`id`	string	Number order identifier
`status`	string	Current status (waiting, success, canceled)
`provider`	string	Provider type
`price_usd`	string	Price paid
`phone_number`	string	The phone number
`expiration_time`	string	When access expires
`report`	string	Link to fraud report (if requested)
`history_sms_code`	array	Received SMS codes
`can_replay`	boolean	Whether can request new SMS
`can_extend`	boolean	Whether can extend rental
`can_cancel`	boolean	Whether can cancel
`expenses`	number	Total expenses
`fraud_score`	integer	Fraud score (0-100, if requested)

Get Number History

Retrieve all numbers except active ones.

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

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

Get Number Details

Get detailed information about a specific number order.

Endpoint

GET /api/v1/numbers/{id}/

Request

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

Response

{
  "id": "bb157566-8003-49f3-9e74-c1488acb9625",
  "status": "waiting",
  "provider": "virtual",
  "price_usd": "0.43",
  "phone_number": "+15555555555",
  "expiration_time": "2024-09-25T08:42:02Z",
  "report": "/checkers/phone/5d7d117db605422db6cbb5afcb290433/",
  "history_sms_code": [],
  "can_replay": true,
  "can_extend": false,
  "expenses": 0.43,
  "fraud_score": 85
}

Cancel a Number

Cancel an active number order.

Endpoint

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

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

{
  "detail": "Cancel processed"
}

Error Responses

Already Received SMS (400)

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

Too Soon (400)

{
  "detail": "You can cancel the phone number 2 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': '666',
        '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)​

Request Example (Virtual Rent, Day)​

Success Response (201)​

Error Responses​

Rate Limited (429)​

Insufficient Stock (400)​

Missing Field (400)​

Bad Service Code (400)​

Get Active Numbers​

Endpoint​

Request​

Response​

Response Fields​

Get Number History​

Endpoint​

Request​

Response​

Get Number Details​

Endpoint​

Request​

Response​

Cancel a Number​

Endpoint​

Request​

Success Response​

Error Responses​

Already Received SMS (400)​

Too Soon (400)​

Usage Example​

Buy a Number

Endpoint

Request Body

Request Fields

Provider and Period Rules

Request Example (Virtual, 15 minutes)

Request Example (Virtual Rent, Day)

Success Response (201)

Error Responses

Rate Limited (429)

Insufficient Stock (400)

Missing Field (400)

Bad Service Code (400)

Get Active Numbers

Endpoint

Request

Response

Response Fields

Get Number History

Endpoint

Request

Response

Get Number Details

Endpoint

Request

Response

Cancel a Number

Endpoint

Request

Success Response

Error Responses

Already Received SMS (400)

Too Soon (400)

Usage Example