Partner API documentation
Free Numbers Partner API
Offer SMSTwins free temporary phone numbers for SMS verification on your own website. List apps and countries, claim numbers, and poll OTP codes automatically — the same free pool powering SMSTwins free numbers.
How to get API access
There is no self-serve signup for this API. Request access through SMSTwins support chat. An admin must approve your account before any live API key can call these endpoints.
- Create an SMSTwins customer account and verify your email.
- Open support chat (signed in) and request Free Numbers Partner API access. Include your website (e.g. proxnum.com) and intended use.
- Wait for admin approval. Until then, calls return 403 even with a valid API key.
- After approval, create a live API key under Dashboard → API Keys (2FA required) and integrate the endpoints below.
This API is separate from the main SMSTwins API
The Free Numbers Partner API is a dedicated integration for free public OTP numbers only. It is not the same as the main SMSTwins Integration API used for paid activations, rentals, webhooks, and developer automation.
The main API is open to everyone — create an account, generate a live API key, and start buying temporary numbers. No special Free Numbers Partner approval is required for the main API.
Use this Partner API only when you want to offer SMSTwins free phone numbers on your website. For paid private numbers, higher success rates, rentals, and production OTP automation, use the main API at https://smstwins.com/docs
Open main API documentation →https://smstwins.com/docs
Authentication
Send a live API key (sk_live_…). Sandbox keys and JWT session cookies are rejected. Unapproved accounts receive 403 Forbidden.
Authorization: Bearer sk_live_YOUR_KEY # or X-API-Key: sk_live_YOUR_KEY
Base URL
https://smstwins.com/v1/partner/free-numbersTypical integration flow
- GET /apps — show selectable services (WhatsApp, etc.) that currently have free stock.
- GET /?app=… — load countries and available numbers for that app (same filtering UX as SMSTwins).
- POST /claim — reserve a number for your visitor; store id + token client-side.
- Poll GET /sessions/:id every 1–2 seconds until sms.code appears.
- Show the OTP on your site. Optionally POST /sessions/:id/release when done.
Endpoints
List free apps
GET /apps
Returns apps/services currently available in the free pool.
curl -H "Authorization: Bearer sk_live_…" \ https://smstwins.com/v1/partner/free-numbers/apps
List numbers & countries
GET /?app=WhatsApp&countryId=2&page=1
Requires app query. Returns totalAvailable, countries[{id,code,name,flag,available}], numbers[], pagination, and dailyRemaining. Pass X-End-User-Id (or endUserId) for fair per-visitor limits.
curl -H "Authorization: Bearer sk_live_…" \ -H "X-End-User-Id: visitor_stable_id_abc12345" \ "https://smstwins.com/v1/partner/free-numbers?app=WhatsApp&countryId=2"
Claim a free number
POST /claim
Body: { appName, countryId?, simNumberId?, endUserId?, endUserIp?, endUserAgent? }. Returns phone, token, status WAITING_SMS, remainingSeconds. Prefer forwarding a stable endUserId for each visitor.
curl -X POST https://smstwins.com/v1/partner/free-numbers/claim \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"appName":"WhatsApp","countryId":2,"endUserId":"visitor_stable_id_abc12345"}'Poll for OTP
GET /sessions/:id?token=…
Returns current status and sms { code, text } when the verification message arrives. You may omit token if the same API key that claimed the session is used.
curl -H "Authorization: Bearer sk_live_…" \ "https://smstwins.com/v1/partner/free-numbers/sessions/SESSION_ID?token=CLAIM_TOKEN"
Release early
POST /sessions/:id/release
Returns the number to the free pool and deletes the free session.
curl -X POST https://smstwins.com/v1/partner/free-numbers/sessions/SESSION_ID/release \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"token":"CLAIM_TOKEN"}'Automatic OTP delivery
After claim, SMSTwins assigns the number to a live SIM. When the SMS arrives, polling the session returns the OTP in sms.code — no webhook required for free partner sessions (you can still poll from your backend).
{
"id": "clx…",
"token": "a1b2c3…",
"phone": "+1…",
"status": "WAITING_SMS",
"sms": null,
"appName": "WhatsApp",
"country": { "code": "US", "name": "United States", "flag": "🇺🇸" },
"remainingSeconds": 1800,
"dailyLimit": 15,
"dailyRemaining": 14
}
# After OTP arrives, sms becomes:
# "sms": { "code": "482913", "text": "Your code is 482913" }Limits & expectations
Free numbers are public pool lines — success rates can be lower than paid private numbers. Approved Free Numbers Partner API accounts have no daily claim cap (API and partner web UIs). Always pass a stable endUserId for session attribution. The public SMSTwins /free-numbers page still applies a 15/day visitor limit. For higher success rates, privacy, and rentals, use the paid activation API.
Need paid numbers instead?
Paid SMSTwins activations and rentals use separate documented endpoints with private routing, automatic refunds, and developer webhooks.
Open main API docs →FAQ
How do I get a Free Numbers Partner API key?
Request access via support chat. After an admin enables Free Numbers Partner API on your account, create a live API key under API Keys.
Can I offer these free numbers on my website?
Yes. Build UI that lists apps/countries from the API, claims a number, and polls until sms.code is present — same experience as SMSTwins free numbers.
Why do I get 403 with a valid key?
Your account is not approved yet, you used a sandbox key, or you authenticated with JWT instead of a live API key. Ask support to confirm Free Numbers API access is enabled.