Buy virtual phone numbers, receive SMS verification codes, check your balance and stream realtime events. Authenticate every request with a personal Bearer API key (Authorization: Bearer vpn_xxx) created in the account dashboard. Money values are integer USD cents.
Base URL and authentication
All endpoints are relative to https://api.sms-activate.app/v1.
Authenticate with a bearer token: send Authorization: Bearer <your-api-key> on every request. Endpoints under /me require it; the catalog endpoints do not.
Endpoints (14)
GET /countries
List available countries with availability and price range
GET /numbers
List live numbers for a country
Per-number priceCents is populated only for an authenticated principal; anonymous callers get availability and the price range.
- country (query, string, required) - ISO-2 country code (uppercase).
- type (query, string, optional)
- limit (query, integer, optional)
- offset (query, integer, optional)
GET /numbers/search
Search numbers by pattern
- country (query, string, required)
- pattern (query, string, required)
GET /me
Get the authenticated profile
GET /me/balance
Get account balance
GET /me/transactions
List transactions (cursor-paginated)
- limit (query, integer, optional)
- cursor (query, string, optional)
GET, POST /me/numbers
GET: List your numbers
POST: Purchase a number
Send an Idempotency-Key header so retries never double-charge. Returns 201 with the number plus chargedCents and balanceCents.
- Idempotency-Key (header, string, optional) - UUID; replays return the original result.
GET, PATCH, DELETE /me/numbers/{id}
GET: Get a number
- id (path, string, required)
PATCH: Update a number
- id (path, string, required)
DELETE: Release a number
- id (path, string, required)
GET /me/numbers/{id}/sms
Inbound SMS for a number (cursor-paginated)
- id (path, string, required)
- limit (query, integer, optional)
- cursor (query, string, optional)
GET /me/numbers/{id}/calls
Call logs for a number (cursor-paginated)
- id (path, string, required)
- limit (query, integer, optional)
- cursor (query, string, optional)
GET /me/sms
Unified inbound SMS feed across your numbers (cursor-paginated)
- limit (query, integer, optional)
- cursor (query, string, optional)
GET /me/events
Server-Sent Events stream (25s heartbeat)
Emits inbound SMS, balance changes and number events. Connect with an EventSource-style client and the Authorization header.
GET, POST /me/watches
GET: List your number watches
Availability watches (digit pattern or exact number) with optional auto-buy.
POST: Create a watch
First watch is free; each additional active watch is billed monthly (debited from balance).
PATCH, DELETE /me/watches/{id}
PATCH: Pause/resume a watch, toggle auto-buy, or change the cap
- id (path, string, required)
DELETE: Delete a watch
- id (path, string, required)
Response objects
The API returns 7 object types: Error, Country, Number, Watch, Sms, SmsFeed, Me.