API documentation

SMS-Activate compatible style

Use platform API keys to automate number purchases, status polling, and balance checks. Numbers are sourced from multiple upstream providers while your customers interact with your PolarSMS branded API.

Your API key

Get balance

Check your current wallet balance.

GET /api/customer?action=getBalance&api_key=YOUR_KEY&format=json

Response: { "balance": 25.40 }

Request number

Purchase a temporary number for a service and country.

GET /api/customer?action=getNumber&api_key=YOUR_KEY&service=tg&country=us&maxPrice=1.00&format=json

Response: { "status": "ACCESS_NUMBER", "activationId": 12345, "phone": "+15551234567" }

Get status

Poll an activation for the received SMS code.

GET /api/customer?action=getStatus&api_key=YOUR_KEY&id=12345&format=json

Response: { "status": "STATUS_OK", "code": "123456" }
or { "status": "STATUS_WAIT_CODE" }

Set status

Control an activation lifecycle. Status codes: 1 = number ready, 3 = request another SMS, 6 = complete, 8 = cancel.

GET /api/customer?action=setStatus&api_key=YOUR_KEY&id=12345&status=8&format=json

Response: { "status": "ACCESS_CANCEL", "activationStatus": "cancelled" }

Active activations

List all currently active (allocated or waiting) activations.

GET /api/customer?action=getActiveActivations&api_key=YOUR_KEY&format=json

Response: { "activations": [{ "id": 12345, "status": "allocated", "phone_number": "+15551234567", "service_code": "tg", ... }] }

Error handling

All endpoints return standardized error codes.

{ "error": "BAD_KEY" }
{ "error": "NO_BALANCE" }
{ "error": "NO_NUMBERS" }
{ "error": "SERVICE_UNAVAILABLE" }
{ "error": "ACTIVATION_NOT_FOUND" }
{ "error": "BAD_STATUS" }
{ "error": "BAD_ACTION" }