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

Obtain your API key from the bot or dashboard.
Send a GET request to one of the endpoints below.
Check ok and error/msg in the response.

🔗 Base URL 🧩 Endpoints 🛡️ Errors

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?apiKey=APIKEY&action=getBalance ›

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?apiKey=APIKEY&action=getCountries ›

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

Successful response

{
  "ok": true,
  "countries": ["US", "AE", "DE", "..."]
}

Error response

{
  "ok": false,
  "error": "please_try_again"
}

GET Buy Number /api/user?apiKey=APIKEY&action=getNumber&country=COUNTRY ›

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?apiKey=APIKEY&action=getCode&number=NUMBER ›

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?apiKey=APIKEY&action=getLogout&number=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"
}

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