API — PolarSMS

PolarSMS API

Automate number purchases and check for incoming codes from your own scripts or bots. Every account gets its own API key.

GET  /api/v1/account
GET  /api/v1/countries
GET  /api/v1/services
GET  /api/v1/prices?service=&country=
GET  /api/v1/availability?service=&country=
POST /api/v1/orders                { service, country }
GET  /api/v1/orders/:id
GET  /api/v1/orders/:id/messages
POST /api/v1/orders/:id/cancel
GET  /api/v1/orders                ?status=&service=&page=&limit=

Register to get your key.

API Documentation

On this page: Authentication · Quick Start · Rate Limits · Error Codes · GET /api/v1/account · GET /api/v1/countries · GET /api/v1/services · GET /api/v1/prices · GET /api/v1/availability · POST /api/v1/orders · GET /api/v1/orders/{id} · GET /api/v1/orders/{id}/messages · POST /api/v1/orders/{id}/cancel · GET /api/v1/orders

Authentication

Every request must include your API key as a Bearer token in the Authorization header. Requests without a valid key get a 401.

Authorization: Bearer YOUR_API_KEY

Quick Start

Check availability, then buy a number:

curl "https://polar-sms.com/api/v1/availability?service=tg&country=CA" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST https://polar-sms.com/api/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service":"tg","country":"CA"}'

Rate Limits

Each API key is limited to 60 requests per minute. Exceeding it returns a 429 with a Retry-After header (seconds until the window resets).

Error Codes

Errors are returned as { "error": { "code", "message" } }.

HTTP	Code	Meaning
400	`bad_request`	Missing or invalid parameters.
401	`unauthorized`	Missing or invalid API key.
402	`insufficient_balance`	Not enough balance to complete a purchase.
404	`not_found`	Unknown service, country, or order — or an order that isn’t yours.
409	`conflict / out_of_stock`	The action can’t be performed in the resource’s current state (e.g. cancelling a completed order, or no stock left).
429	`rate_limited`	Too many requests — see Rate Limits below.
500	`internal_error`	Something went wrong on our end.

GET /api/v1/account

Returns the authenticated user's account information, balance, currency, and status.

Parameters

No parameters.

Example request

curl https://polar-sms.com/api/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "email": "you@example.com",
  "username": "yourusername",
  "balance_cents": 5000,
  "currency": "USD",
  "status": "active",
  "vip": false
}

GET /api/v1/countries

Returns every country PolarSMS supports.

Parameters

No parameters.

Example request

curl https://polar-sms.com/api/v1/countries \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "countries": [
    { "code": "US", "name": "United States", "flag": "https://api.iconify.design/circle-flags/us.svg" },
    { "code": "GB", "name": "United Kingdom", "flag": "https://api.iconify.design/circle-flags/gb.svg" }
  ]
}

GET /api/v1/services

Returns every supported service (Telegram, Google, Discord, WhatsApp, etc.).

Parameters

No parameters.

Example request

curl https://polar-sms.com/api/v1/services \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "services": [
    { "code": "tg", "name": "Telegram", "slug": "telegram", "category": "Messaging", "basePrice": 25, "inStock": true }
  ]
}

GET /api/v1/prices

Returns current prices. Supports filtering by service and/or country — at least one is required.

Parameters

Name	In	Type	Required	Description
`service`	query	string	No	Service code, e.g. tg. Required if country is omitted.
`country`	query	string	No	Country code, e.g. US. Required if service is omitted.

Example request

curl "https://polar-sms.com/api/v1/prices?service=tg&country=US" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "prices": [
    { "service": "tg", "country": "US", "price_cents": 25 }
  ]
}

GET /api/v1/availability

Returns whether numbers are currently available for a given service and country.

Parameters

Name	In	Type	Required	Description
`service`	query	string	Yes	Service code, e.g. tg.
`country`	query	string	Yes	Country code, e.g. CA.

Example request

curl "https://polar-sms.com/api/v1/availability?service=tg&country=CA" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "service": "tg",
  "country": "CA",
  "available": true,
  "quantity": 37
}

POST /api/v1/orders

Creates a new order (purchases a phone number) and returns the allocated number and order information. Charges your balance immediately — 402 if you don’t have enough.

Parameters

Name	In	Type	Required	Description
`service`	body	string	Yes	Service code, e.g. tg.
`country`	body	string	Yes	Country code, e.g. CA.

Example request

curl -X POST https://polar-sms.com/api/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service":"tg","country":"CA"}'

Example response

{
  "id": 1042,
  "service": "tg",
  "country": "CA",
  "phone_number": "+15145551234",
  "price_cents": 25,
  "status": "pending",
  "code": null,
  "created_at": "2026-08-06 12:00:00"
}

GET /api/v1/orders/{id}

Returns the current status of an order (pending, received, cancelled).

Parameters

Name	In	Type	Required	Description
`id`	path	integer	Yes	Order ID.

Example request

curl https://polar-sms.com/api/v1/orders/1042 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "id": 1042,
  "service": "tg",
  "country": "CA",
  "phone_number": "+15145551234",
  "price_cents": 25,
  "status": "received",
  "code": "482913",
  "created_at": "2026-08-06 12:00:00"
}

GET /api/v1/orders/{id}/messages

Returns the SMS message(s) received for that order. Empty array if no code has arrived yet.

Parameters

Name	In	Type	Required	Description
`id`	path	integer	Yes	Order ID.

Example request

curl https://polar-sms.com/api/v1/orders/1042/messages \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "messages": [
    { "code": "482913" }
  ]
}

POST /api/v1/orders/{id}/cancel

Cancels an order and refunds its price to your balance. Only works while status is still "pending" — 409 if a code has already been received.

Parameters

Name	In	Type	Required	Description
`id`	path	integer	Yes	Order ID.

Example request

curl -X POST https://polar-sms.com/api/v1/orders/1042/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "id": 1042,
  "status": "cancelled",
  "refunded_cents": 25
}

GET /api/v1/orders

Returns the authenticated user's order history, with optional filtering and pagination.

Parameters

Name	In	Type	Required	Description
`status`	query	string	No	Filter by pending, received, or cancelled.
`service`	query	string	No	Filter by service code.
`page`	query	integer	No	Page number, default 1.
`limit`	query	integer	No	Results per page, default 20, max 100.

Example request

curl "https://polar-sms.com/api/v1/orders?status=received&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "orders": [
    { "id": 1042, "service": "tg", "country": "CA", "phone_number": "+15145551234",
      "price_cents": 25, "status": "received", "code": "482913", "created_at": "2026-08-06 12:00:00" }
  ],
  "page": 1,
  "limit": 20,
  "total": 1
}