TGPVA logo
TGPVA API Documentation
💬 Support 🤖 Open bot

TGPVA API — Simple & Token-based

Use these endpoints to check balance, list countries, buy a number, fetch the verification code, and logout. All requests are GET with your API key as a query parameter (apiKey).

Quick start

  1. Obtain your API key from the bot or dashboard.
  2. Send a GET request to one of the endpoints below.
  3. Check ok and error/msg in the response.
🔗 Base URL 🧩 Endpoints 🚀 Playground

Base URL

Example 
https://tgpva.com/api/user
getBalance getCountries getNumber getCode getLogout

Always use HTTPS and keep your apiKey private.

Endpoints

Tap any endpoint to expand the details (mobile-friendly).

GET Get Balance /api/user/getBalance?apiKey=APIKEY ›

Returns your current account balance.

Successful response
{
  "ok": true,
  "balance": "12.50",
  "currency": "USD"
}
Error response
{
  "ok": false,
  "error": "INVALID_API_KEY"
}
GET Get Countries /api/user/getCountries?apiKey=APIKEY ›

Returns a list of available country codes (2-letter ISO).

Successful response 
{
  "ok": true,
  "result": {
    "currency": "USD",
    "countries": {
      "1": {
        "AR": "0.75",
        "AZ": "1",
        "BF": "0.55",
        "BG": "1.2",
        "BN": "5",
        "CM": "0.45",
        "CO": "0.25",
        "CZ": "2.5"
      }
    },
    "availability": {
      "1": {
        "AR": 16,
        "AZ": 0,
        "BF": 0,
        "BG": 0,
        "BN": 0,
        "CM": 0,
        "CO": 0,
        "CZ": 0
      }
    }
  }
}
Error response
{
  "ok": false,
  "error": "please_try_again"
}
GET Buy Number /api/user/getNumber?apiKey=...&country=US ›

Purchases a number for the requested country. COUNTRY is a 2-letter ISO code (e.g., US).

Successful response
{"ok":true,"msg":"success","result":{"phone":"+123456789","hash":"35d2c16ee247","price":"0.55"}}
Error response
{
  "ok": false,
  "error": "no_available_numbers"
}
GET Get Code /api/user/getCode?apiKey=...&number=...&hash=... ›

Fetches the one-time login code for the purchased number.

Successful response
{"ok":true,"msg":"success","result":{"status":"Received","number":"+123456789","code":"12345","password":"shdgbdy23","output":"done"}}
Error response
{
  "ok": false,
  "error": "WAITING"
}
GET Logout /api/user/getLogout?apiKey=...&number=... ›

Releases the number from your session.

Successful response
{"ok":true,"msg":"success","result":{"status":"Logged out successfully"}}
Error response
{
  "ok": false,
  "error": "NUMBER_NOT_FOUND"
}

API Playground

Test endpoints directly from your browser.

Response

JSON Output 
// Result will appear here...

Errors & Best Practices

Common error codes and tips for stable integration.

Common error codes

  • INVALID_API_KEY — API key is invalid or missing.
  • MISSING_PARAM — A required query parameter is missing.
  • NO_NUMBERS — No numbers currently available.
  • WAITING — Code not received yet; retry later.
  • NUMBER_NOT_FOUND — Number not active for this key.

Best practices

  • Always use HTTPS and keep your apiKey private.
  • For WAITING, poll every 5–10s with a reasonable timeout.
  • Handle out-of-stock by offering alternative countries.
🏠 Home 💬 Support 🤖 Open bot
© TGPVA