API Access

Get Balance

Endpoint:https://www.pvaotp.com/api/json/get_balance.php

Method: GET

Parameters:

• customer (required) - Your API key

Example Request:

https://www.pvaotp.com/api/json/get_balance.php?customer=YOUR_API_KEY

Success Response (200):

{
    "success": true,
    "data": {
        "id": "123",
        "full_name": "John Doe",
        "email": "[email protected]",
        "balance": "100.50"
    }
}

Error Responses:

• {"success": false, "error": "Customer Not Found."} (400) - Customer parameter missing or invalid
• {"success": false, "error": "Customer not found."} (404) - Customer does not exist
• {"success": false, "error": "Access denied."} (500) - IP address blocked
• {"success": false, "error": "Database connection failed."} (500) - Database error
• {"success": false, "error": "Database query failed."} (500) - Query error

Get History

Endpoint:https://www.pvaotp.com/api/json/get_history.php

Method: GET

Parameters:

• customer (required) - Your API key

Example Request:

https://www.pvaotp.com/api/json/get_history.php?customer=YOUR_API_KEY

Success Response (200):

{
    "success": true,
    "data": [
        {
            "id": "8666290",
            "number": "15717412873",
            "message": "Your code is 123456",
            "country_name": "USA",
            "app_name": "Google Voice",
            "timestamp": "2024-01-15 10:30:00"
        },
        {
            "id": "8666289",
            "number": "15717412874",
            "message": "",
            "country_name": "USA",
            "app_name": "WhatsApp",
            "timestamp": "2024-01-15 10:25:00"
        }
    ]
}

Error Responses:

• {"success": false, "error": "Customer Not Found."} (400) - Customer parameter missing
• {"success": false, "error": "Access denied."} (500) - IP address blocked
• {"success": false, "error": "Database connection failed."} (500) - Database error
• {"success": false, "error": "Database query failed."} (500) - Query error

Get Rates & Business Codes

Endpoint:https://www.pvaotp.com/api/json/get_rates.php

Method: GET

Parameters:

• customer (required) - Your API key
• country (required) - Country name (e.g., "USA")

Example Request:

https://www.pvaotp.com/api/json/get_rates.php?customer=YOUR_API_KEY&country=USA

Success Response (200):

{
    "success": true,
    "data": [
        {
            "app": "Google Voice",
            "business_code": "go",
            "rate": "0.50"
        },
        {
            "app": "WhatsApp",
            "business_code": "wa",
            "rate": "0.75"
        }
    ]
}

Error Responses:

• {"success": false, "error": "Customer Not Found."} (400) - Customer parameter missing
• {"success": false, "error": "Country Not Found."} (400) - Country parameter missing
• {"success": false, "error": "Country Not Found."} (404) - Country does not exist
• {"success": false, "error": "Access denied."} (500) - IP address blocked
• {"success": false, "error": "Database connection failed."} (500) - Database error
• {"success": false, "error": "Database query failed."} (500) - Query error
• {"success": false, "error": "Too many requests. Please wait."} (429) - Rate limit exceeded

Get All Countries

Endpoint:https://www.pvaotp.com/api/json/get_countries.php

Method: GET

Parameters:

• customer (required) - Your API key

Example Request:

https://www.pvaotp.com/api/json/get_countries.php?customer=YOUR_API_KEY

Success Response (200):

{
    "success": true,
    "data": [
        { "id": 1,   "country": "USA",               "short_code": "US" },
        { "id": 31,  "country": "Canada",            "short_code": "CA" },
        { "id": 52,  "country": "United kingdom UK", "short_code": "GB" },
        { "id": 745, "country": "USA Rent",          "short_code": "US" }
    ]
}

Use the country value when calling get_rates, get_number, etc.

Error Responses:

• {"success": false, "error": "Customer Not Found."} (400) - Customer parameter missing
• {"success": false, "error": "Access denied."} (500) - IP address blocked
• {"success": false, "error": "Database connection failed."} (500) - Database error

Get Number

Endpoint:https://www.pvaotp.com/api/json/get_number.php

Method: GET

Parameters:

• customer (required) - Your API key
• app (required) - App name (e.g., "Google Voice") or business code
• country (required) - Country name (e.g., "USA")
• number (optional) - Phone number to reuse. When provided, the API will reuse this existing number instead of assigning a new one. The number must belong to your account and match the specified country/app combination.
• area_code (optional) - 3-digit US area code filter. Example: 201.
• duration (optional) - Duration for number rental. Valid values: 15 minutes (default), 3 days, 7 days, 14 days, 25 days.

Example Request (Get New Number):

https://www.pvaotp.com/api/json/get_number.php?customer=YOUR_API_KEY&app=Google+Voice&country=USA&duration=3 days

Example Request (Filter by US Area Code):

https://www.pvaotp.com/api/json/get_number.php?customer=YOUR_API_KEY&app=Google+Voice&country=USA&area_code=201&duration=3 days

Example Request (Reuse Number):

https://www.pvaotp.com/api/json/get_number.php?customer=YOUR_API_KEY&app=Google+Voice&country=USA&number=15717412873

How to request a specific number again: To get the same number again (like the “Specific Number” option on the homepage), call Get Number with the number parameter set to the full phone number (e.g. number=16143548416). Use the same app and country as when you first received that number. The number must belong to your account; reuse may be free within the app’s reuse window.

Area code + specific number: You can pass both number and area_code. If the requested number does not match the selected area code, the API returns an error.

Success Response (200):

{
    "success": true,
    "data": {
        "id": "8666290",
        "number": "15717412873",
        "deduction": "0.45"
    }
}

Error Responses:

• {"success": false, "error": "Customer Not Found."} (400) - Customer parameter missing
• {"success": false, "error": "App Not Found."} (400) - App parameter missing
• {"success": false, "error": "Country Not Found."} (400) - Country parameter missing
• {"success": false, "error": "Not Enough balance"} (400) - Insufficient balance
• {"success": false, "error": "Customer Not Found."} (404) - Customer does not exist
• {"success": false, "error": "App or Country Not Found."} (404) - App or country not found
• {"success": false, "error": "Number is not available."} (403) - App restricted for user
• {"success": false, "error": "No free channels available check after sometime."} (503) - No numbers available
• {"success": false, "error": "Too many unused numbers. Service blocked for next 6 hours."} (429) - User blocked due to unused numbers
• {"success": false, "error": "Access denied."} (500) - IP address blocked
• {"success": false, "error": "Database connection failed."} (500) - Database error
• {"success": false, "error": "Database query failed."} (500) - Query error
• {"success": false, "error": "Error 102, check back later."} (500) - Provider not supported
• {"success": false, "error": "Your balance is expired."} (400) - Account expired
• {"success": false, "error": "SMS service error"} (503) - External SMS service error

Note: Rate limit: 5 numbers per minute

Get SMS

Endpoint:https://www.pvaotp.com/api/json/get_sms.php

Method: GET

Parameters:

• customer (required) - Your API key
• n_id (required) - Number ID (from get_number response or history)

Example Request:

https://www.pvaotp.com/api/json/get_sms.php?customer=YOUR_API_KEY&n_id=8666290

Success Response (200):

{
    "success": true,
    "message": "Your verification code is 123456"
}

Error Responses:

• {"success": false, "error": "Customer Not Found."} (400) - Customer parameter missing
• {"success": false, "error": "Number ID (n_id) is required."} (400) - n_id parameter missing
• {"success": false, "error": "Number record not found."} (404) - Number ID does not exist
• {"success": false, "error": "App or Country Not Found."} (404) - App or country not found
• {"success": false, "error": "You have not received any code yet."} (400) - No SMS received yet
• {"success": false, "error": "Too many requests. Please wait."} (429) - Rate limit exceeded (3 minutes per number)
• {"success": false, "error": "Access denied."} (500) - IP address blocked
• {"success": false, "error": "Database connection failed."} (500) - Database error
• {"success": false, "error": "Database query failed."} (500) - Query error
• {"success": false, "error": "SMS service error"} (503) - External SMS service error

Note: Rate limit: 3 minutes per number

Reject Number

Endpoint:https://www.pvaotp.com/api/json/reject_code.php

Method: GET

Parameters:

• customer (required) - Your API key
• n_id (required) - Number ID (from get_number response or history)

Example Request:

https://www.pvaotp.com/api/json/reject_code.php?customer=YOUR_API_KEY&n_id=8666290

Success Response (200):

{
    "success": true,
    "message": "Number Rejected."
}

Error Responses:

• {"success": false, "error": "Customer Not Found."} (400) - Customer parameter missing
• {"success": false, "error": "Number ID (n_id) is required."} (400) - n_id parameter missing
• {"success": false, "error": "Number record not found."} (404) - Number ID does not exist
• {"success": false, "error": "App or Country Not Found."} (404) - App or country not found
• {"success": false, "error": "Cant Reject."} (400) - Cannot reject (number already used or time expired)
• {"success": false, "error": "You have not received any code yet."} (400) - Cannot reject without SMS
• {"success": false, "error": "Access denied."} (500) - IP address blocked
• {"success": false, "error": "Database connection failed."} (500) - Database error
• {"success": false, "error": "Database query failed."} (500) - Query error
• {"success": false, "error": "SMS service error"} (503) - External SMS service error

Renew Number

Endpoint:https://www.pvaotp.com/api/json/renew_number.php

Method: GET

Parameters:

• customer (required) - Your API key
• number (required) - Phone number to renew
• duration (required) - Duration for renewal. Valid values: 15 minutes, 3 days, 7 days, 14 days, 25 days.

Example Request:

https://www.pvaotp.com/api/json/renew_number.php?customer=YOUR_API_KEY&number=15717412873&duration=3 days

Success Response (200):

{
    "success": true,
    "message": "Number renewed successfully.",
    "data": {
        "new_expiry": "2024-01-18",
        "new_balance": "95.50"
    }
}

Error Responses:

• {"success": false, "error": "Customer Not Found."} (400) - Customer parameter missing
• {"success": false, "error": "Number is required."} (400) - Number parameter missing
• {"success": false, "error": "Invalid duration parameter."} (400) - Duration parameter invalid
• {"success": false, "error": "Insufficient balance."} (400) - Not enough balance
• {"success": false, "error": "Renewal is only available after a message has been received."} (400) - No SMS received yet
• {"success": false, "error": "Number not found."} (404) - Number does not belong to user
• {"success": false, "error": "Access denied."} (500) - IP address blocked

Note: Available for selected numbers only.

eSIM Endpoints

Travel eSIMs are bought and managed over JSON as well, but these three endpoints sit under https://www.pvaotp.com/api/user/ instead of https://www.pvaotp.com/api/json/, and they carry an extra error_code field alongside error so your code can branch on the exact reason a purchase failed. The customer parameter is the same API key.

Errors returned by all three: NO_CUSTOMER (401) missing key, BAD_CUSTOMER (401) invalid or inactive key, IP_BLOCKED (403), SERVER_ERROR (500).

eSIM: Browse Plans & Prices

Endpoint:https://www.pvaotp.com/api/user/esim_plans.php

Method: GET

Parameters:

• customer (required) - Your API key
• country (optional) - 2-letter ISO code such as US. Also matches regional bundles that include it.
• search (optional) - Free text on the plan or region name
• package_code (optional) - One exact plan, to re-check a price before ordering
• max_price, min_data_gb, days (optional) - Filters
• sort (optional) - price, data or days; order - asc or desc
• page, per_page (optional) - per_page maximum is 100

Example Request:

https://www.pvaotp.com/api/user/esim_plans.php?customer=YOUR_API_KEY&country=US&sort=price&per_page=10

Success Response (200):price is what you pay, in USD.

{
    "success": true,
    "balance": "102.87",
    "paging": {"page": 1, "per_page": 10, "total": 37, "total_pages": 4},
    "count": 1,
    "plans": [
        {
            "package_code": "P3YTYXBRV",
            "name": "United States 100MB 7Days",
            "price": "0.60",
            "currency": "USD",
            "data_bytes": 104857600,
            "data": "100MB",
            "validity_days": 7,
            "validity_unit": "DAY",
            "countries": [{"code": "US", "name": "United States"}],
            "speed": "3G/4G/5G",
            "topup_support": true,
            "networks": [{"code": "US", "carriers": ["Verizon", "AT&T"], "types": ["5G"]}]
        }
    ]
}

Error Responses:

• {"success": false, "error_code": "BAD_COUNTRY", ...} (400) - country is not a 2-letter ISO code
• {"success": false, "error_code": "ESIM_UNAVAILABLE", ...} (503) - eSIM service is down

eSIM: Order

Endpoint:https://www.pvaotp.com/api/user/esim_buy.php

Method: GET

Parameters:

• customer (required) - Your API key
• package_code (required) - Plan to buy, from esim_plans.php
• request_id (optional) - Your own id for this purchase, up to 64 characters of letters, digits, dot, underscore, colon or hyphen. Repeating a call with the same request_id returns the original order instead of buying a second eSIM. Use this if your code can retry.
• expected_price (optional) - The order is refused if the price is no longer this, so a catalogue update cannot charge you more than you expected

Example Request:

https://www.pvaotp.com/api/user/esim_buy.php?customer=YOUR_API_KEY&package_code=P3YTYXBRV&request_id=my-order-1001&expected_price=0.60

Success Response (200):

{
    "success": true,
    "charged": "0.60",
    "balance": "102.27",
    "order": {
        "order_id": 51,
        "order_no": "B26091314150018",
        "package_name": "United States 100MB 7Days",
        "price_paid": "0.60",
        "status": "ready",
        "activation_code": "LPA:1$rsp-eu.simlessly.com$7311A7EB...",
        "qr_code_url": "https://p.qrsim.net/...",
        "install_url": "https://p.qrsim.net/...",
        "iccid": "8932042000024918296",
        "data": "100MB",
        "expires_at": "2027-03-12T14:15:24+0000"
    },
    "note": "The eSIM is ready to install."
}

If status is processing the operator is still releasing the profile: poll esim_order.php for the QR code and activation code. A repeated request_id returns the original order with "duplicate": true and charges nothing.

Error Responses:

• {"success": false, "error_code": "NO_PACKAGE", ...} (400) - package_code missing
• {"success": false, "error_code": "BAD_REQUEST_ID", ...} (400) - request_id too long or has invalid characters
• {"success": false, "error_code": "INSUFFICIENT_BALANCE", ...} (402) - Not charged; add funds and retry
• {"success": false, "error_code": "PACKAGE_NOT_FOUND", ...} (404) - Plan is not on sale
• {"success": false, "error_code": "PRICE_CHANGED", ...} (409) - expected_price no longer matches
• {"success": false, "error_code": "PRICE_UNAVAILABLE", ...} (409) - Plan has no price configured
• {"success": false, "error_code": "BUSY", ...} (409) - Another order for your account is mid-flight; retry shortly
• {"success": false, "error_code": "RATE_LIMITED", ...} (429) - More than 10 orders in a minute
• {"success": false, "error_code": "ORDER_RECORD_FAILED", ...} (500) - Bought but not saved; contact support with the order number
• {"success": false, "error_code": "SUPPLIER_ERROR", ...} (503) - Not charged; the operator refused the order

Note: Your balance is only spent on a successful order. If the supplier fails, the charge is returned. Limit is 10 orders per minute.

eSIM: Order Info & Usage

Endpoint:https://www.pvaotp.com/api/user/esim_order.php

Method: GET

Parameters:

• customer (required) - Your API key
• order_id, order_no or iccid (optional) - Look up one order. Pass none of them to list your orders.
• page, per_page (optional) - When listing; per_page maximum is 50
• refresh (optional) - 1 forces a supplier read. A plan that is not ready yet is always read live, and forced refreshes are limited to once a minute per order.

Example Request:

https://www.pvaotp.com/api/user/esim_order.php?customer=YOUR_API_KEY&order_id=51&refresh=1

Success Response (200): the install details plus everything the operator reports about the SIM.

{
    "success": true,
    "order": {
        "order_id": 51,
        "status": "ready",
        "activation_code": "LPA:1$rsp-eu.simlessly.com$7311A7EB...",
        "qr_code_url": "https://p.qrsim.net/...",
        "iccid": "8932042000024918296",
        "imsi": "206018226618296",
        "data": "100MB",
        "expires_at": "2027-03-12T14:15:24+0000",
        "smdp_status": "RELEASED",
        "esim_status": "GOT_RESOURCE",
        "usage": {
            "used_bytes": 0, "used": "",
            "remaining_bytes": 104857600, "remaining": "100MB"
        },
        "sim": {
            "apn": "bicsapn", "pin": "7639", "puk": "91625444",
            "ip_export": "US", "activated_at": "", "installed_at": "",
            "validity_days": 7, "validity_unit": "DAY", "topup_support": true
        }
    }
}

Error Responses:

• {"success": false, "error_code": "ORDER_NOT_FOUND", ...} (404) - No such order on your account

Response Format Details

Success Responses:

• All successful responses include "success": true
• get_balance, get_history, get_rates, get_number return data in "data" field
• get_sms, reject_code return message in "message" field
• HTTP status code: 200

Error Responses:

• All error responses include "success": false and "error" field with error message
• The eSIM endpoints add an "error_code" field with a fixed machine-readable code
• HTTP status codes:
  • 400 - Bad Request (missing/invalid parameters)
  • 403 - Forbidden (access denied)
  • 404 - Not Found (resource not found)
  • 429 - Too Many Requests (rate limited)
  • 500 - Internal Server Error (server/database errors)
  • 503 - Service Unavailable (no numbers available, service errors)

Content-Type: All responses return Content-Type: application/json