API Documentation

Introduction

The V3SIM API lets you programmatically buy virtual phone numbers, receive SMS codes, and manage orders. It is fully compatible with the 5SIM API format — any 5SIM-compatible software works out of the box.

Base URL: https://v3sim.com

💡

5SIM compatible Replace https://5sim.net with your V3SIM base URL in any existing integration — no other changes needed.

Authentication

All user endpoints require a JWT Bearer token in the Authorization header:

Authorization: Bearer <your_api_key>

Get your API key from Settings → API Key. Keys are valid for 1 year and can be regenerated at any time.

⚠️

Keep your key private Never expose your API key in frontend JavaScript or public repositories. Treat it like a password.

Guest Endpoints

These endpoints require no authentication and are safe to call from public-facing applications.

Get Products (Services)

GET /v1/guest/products/{country}/{operator}

Parameter	Type	Description
`country`	string	Country ISO code (e.g. `gb`, `us`) or `any`
`operator`	string	Operator name or `any`

GET /v1/guest/products/gb/any

{
  "facebook": { "Category": "activation", "Qty": 1250, "Price": 0.11 },
  "telegram":  { "Category": "activation", "Qty": 890,  "Price": 0.08 },
  "instagram": { "Category": "activation", "Qty": 2100, "Price": 0.09 }
}

Get Prices

GET /v1/guest/prices/{country}/{product}/{operator}

Returns per-operator pricing and stock for a specific country + service combination.

GET /v1/guest/prices/gb/facebook/any

{
  "virtual8": { "name": "virtual8", "cost": 0.07, "count": 450 },
  "any":       { "name": "any",      "cost": 0.11, "count": 1250 }
}

Get Countries

GET /v1/guest/countries

Returns a list of all available countries with ISO codes.

GET /v1/guest/countries

{
  "gb": { "name": "England", "iso": "gb", "prefix": "+44" },
  "us": { "name": "USA",     "iso": "us", "prefix": "+1"  }
}

User Endpoints

Get Profile

GET /v1/user/profile

GET /v1/user/profile
Authorization: Bearer <token>

{
  "id": 3907866,
  "email": "user@example.com",
  "balance": "9.91000",
  "rating": 100
}

Get Payment History

GET /v1/user/profile/payments

Query Param	Type	Description
`category`	string	`buy` or `deposit`
`limit`	int	Max records (default 15, max 100)
`offset`	int	Pagination offset (default 0)
`order`	string	Sort field: `id`, `created_at`
`reverse`	bool	Reverse sort order (default `true`)

Order Endpoints

Buy Number

GET /v1/user/buy/activation/{country}/{operator}/{product}

Param	Type	Description
`country`	string	Country ISO (e.g. `gb`, `us`)
`operator`	string	Operator slug or `any`
`product`	string	Service slug (e.g. `instagram`, `facebook`)
`maxPrice`	float	(optional) Max price in USD — rejects if cheapest exceeds this
`reuse`	int	(optional) `1` = allow reuse of previously assigned numbers

GET /v1/user/buy/activation/gb/any/instagram?maxPrice=0.5

{
  "id": 123456789,
  "phone": "+447337098930",
  "operator": "virtual53",
  "product": "instagram",
  "price": 0.09,
  "status": "PENDING",
  "expires": "2026-06-12T20:05:00Z"
}

ℹ️

After buying Start polling /v1/user/check/{id} every 5–10 seconds until status becomes RECEIVED or the number expires.

Check / Poll SMS

GET /v1/user/check/{id}

Poll this endpoint to check if an SMS has arrived. Recommended interval: every 5–10 seconds.

GET /v1/user/check/123456789
Authorization: Bearer <token>

{
  "id": 123456789,
  "phone": "+447337098930",
  "status": "RECEIVED",
  "sms": [
    {
      "text": "Your Instagram code is 847291",
      "code": "847291",
      "created_at": "2026-06-12T19:52:14Z"
    }
  ]
}

Cancel Order

GET /v1/user/cancel/{id}

Cancels a PENDING order. Balance is refunded to your account instantly.

✅

Cancel = full refund Always cancel a PENDING order if no SMS arrives before the timer expires. Once the order status becomes EXPIRED, no automatic refund is issued.

Finish Order

GET /v1/user/finish/{id}

Mark a RECEIVED order as finished after you've used the SMS code. This releases the number back to the pool.

Ban Number

GET /v1/user/ban/{id}

Report a number as already registered or banned on the target service. The number is blacklisted for your account and you receive a full refund.

⚠️

Ban ≠ Cancel Use Ban only when the target service rejects the number as already used. Use Cancel when you simply don't need the number anymore or SMS is not arriving.

Order Statuses

Status	Meaning	Refund?
PENDING	Waiting for SMS — number assigned, timer running	Cancel to refund
RECEIVED	SMS arrived — code available	No
FINISHED	Order completed by user	No
EXPIRED	Timer ran out — no SMS received	No (cancel before expiry)
BANNED	Number reported as already used	Yes — auto refund
CANCELED	Cancelled by user before expiry	Yes — auto refund

Can't Receive OTP?

🌐

IP country must match number country Your IP address country should match the country of the phone number you bought. Be sure to use a proxy or VPN from the same country.

Use a matching VPN / proxy If you bought a UK number (gb), connect to a UK VPN server before triggering the OTP.

Check the number format Some services require the number with country code prefix (e.g. +447337098930). Others want just the local digits (7337098930).

Try a different operator If no SMS arrives within 2 minutes, cancel the order (get refund) and try again with a different operator — some operators are blocked by certain services.

Cancel before expiry If the SMS is still not arriving, click Cancel before the 20-minute timer runs out to get your money back. Expired orders are not refunded automatically.

Refund Policy

Situation	How to get refund
No SMS received, timer still running	Click Cancel in the activation window — instant refund
Number was already used / banned on target app	Click Ban — instant refund + number blacklisted
Timer expired, no SMS received	Contact support with order ID — manual review
SMS received, code was wrong	No refund — number delivered as expected

🚫

Expired orders are not auto-refunded Once a number expires, balance is not returned automatically. Always cancel PENDING orders before the timer runs out if SMS hasn't arrived.

Error Codes

HTTP	Code	Meaning
400	`bad_request`	Invalid or missing parameters
401	`unauthorized`	Missing or invalid Bearer token
403	`forbidden`	Account suspended or insufficient access
404	`not_found`	Order or resource not found
409	`conflict`	Order already in a terminal state
422	`validation_error`	Validation failed — see `errors` field
429	`rate_limited`	Too many requests — see `Retry-After` header
500	`server_error`	Internal server error

// Error response shape
{
  "error": "validation_error",
  "message": "The country field is required.",
  "errors": { "country": ["The country field is required."] }
}

Rate Limits

Endpoint type	Limit
Guest endpoints	120 requests / minute / IP
User read endpoints	60 requests / minute
Buy number	30 requests / minute
Check / Poll	60 requests / minute

When rate-limited, the API returns HTTP 429. Wait the number of seconds in the Retry-After response header before retrying.

💡

Polling tip Poll /v1/user/check/{id} every 5–10 seconds, not faster. Aggressive polling wastes your rate limit and delays results.