Getting started
The YoungPG Virtual API is drop-in compatible with SMS-Activate-style tooling. Point your client at our host and keep your existing code.
Base URL:
https://youngpgvirtual.com/stubs/handler_api.php
Every call is a plain GET with an api_key and an action. Responses are plain text for the classic actions and JSON for the catalog actions.
1. Get a key
Request a key from your dashboard under API. An admin approves it (usually within 24 hours) and the secret is emailed to you once. Store it safely — it is never shown again.
2. Check your balance
curl "https://youngpgvirtual.com/stubs/handler_api.php?api_key=YOUR_KEY&action=getBalance"
# ACCESS_BALANCE:1250.00
3. Rent a number
curl "https://youngpgvirtual.com/stubs/handler_api.php?api_key=YOUR_KEY&action=getNumber&service=wa&country=0"
# ACCESS_NUMBER:12345:79991234567
4. Poll for the code
curl "https://youngpgvirtual.com/stubs/handler_api.php?api_key=YOUR_KEY&action=getStatus&id=12345"
# STATUS_OK:123456
5. Finish the activation
curl "https://youngpgvirtual.com/stubs/handler_api.php?api_key=YOUR_KEY&action=setStatus&id=12345&status=6"
# ACCESS_ACTIVATION
That is the whole loop. See the Endpoints page for every action.
Authentication
Authenticate every request with your API key passed as the api_key query parameter.
curl "https://youngpgvirtual.com/stubs/handler_api.php?api_key=ypv_xxx&action=getBalance"
Key format
Keys look like ypv_ followed by 64 hex characters. The first 16 characters are the prefix shown in your dashboard so you can tell keys apart; the rest is the secret.
Shown once
The full key is emailed to you the moment an admin approves your request. For security we store only a SHA-256 hash — we can never show or recover the plaintext again. Lost it? Revoke the key and request a new one.
Scopes
Each key carries a set of scopes that limit what it can do:
balance — read your wallet balanceprices — read services, countries, and pricespurchase — rent numberscancel — cancel or finish rentals
Rate limits
Each key is limited per minute (default 600). Exceeding it returns TOO_MANY_REQUESTS with a Retry-After header.
Revocation
Revoke a key from your dashboard at any time. Revoked keys stop working immediately and return BAD_KEY.
Endpoints
Every action hits the single endpoint GET /stubs/handler_api.php with an action parameter.
| Action | Parameters | Returns |
|---|
| getBalance | — | ACCESS_BALANCE:<amount> |
| getServicesList | — | JSON services |
| getCountries | — | JSON countries |
| getPrices | service, country | JSON price map |
| getNumber | service, country | ACCESS_NUMBER:<id>:<phone> |
| getStatus | id | STATUS_OK:<code> |
| setStatus | id, status | ACCESS_* |
getNumber
Rents a number for the given service and country. Returns the rental id and phone number.
curl "...?api_key=KEY&action=getNumber&service=wa&country=0"
# ACCESS_NUMBER:12345:79991234567
getStatus
Poll until you receive the code.
STATUS_WAIT_CODE — no SMS yet, keep pollingSTATUS_OK:123456 — code receivedSTATUS_CANCEL — rental was cancelled or expired
setStatus
Drive the rental lifecycle:
status=6 — mark completestatus=8 — cancel and refund
Errors and limits
Classic actions return plain-text error tokens; catalog actions return a JSON object with status: error.
| Token | Meaning |
|---|
| BAD_KEY | Missing, unknown, or revoked key |
| BAD_ACTION | Unknown or missing action |
| BAD_SERVICE | Unknown service code |
| BAD_COUNTRY | Unknown country code |
| NO_NUMBERS | No stock for that combination |
| NO_BALANCE | Insufficient wallet balance |
| TOO_MANY_REQUESTS | Rate limit exceeded — see Retry-After |
Rate limits
Each key has a per-minute ceiling (default 600). On overflow you get TOO_MANY_REQUESTS and a Retry-After: 60 header. Back off and retry.
Idempotency
getNumber is not retry-safe — each successful call rents (and charges for) a new number. If a request times out, poll getStatus before retrying.