Your product.
Our SMS API.

Get started with the API.

Base URL: https://smslovers.com/api/v1. Send JSON for POST requests. Successful responses contain data and requestId; collections use items, page, limit and nextPage. All EUR amounts are integer cents. All timestamps are Unix milliseconds.

API keys and permissions.

Send Authorization: Bearer <API_KEY> on every request. Keys are shown once, stored as keyed hashes and managed in your dashboard. Each key has a name, permissions, expiry and daily SMS spending cap. You can revoke it at any time. Revocation blocks new requests; an already submitted operation may still complete.

Keep keys on your backend in environment variables or a secret manager. Browser CORS is disabled. Do not put keys in URLs, frontend bundles, logs or messages to an AI agent. Use separate keys for separate integrations. Ten active keys per account; expiry options are 30, 90 or 365 days. Password resets, password changes, account suspension and identity linking also invalidate access; linking revokes existing keys on the merged accounts.

Discounted rates, built for your product.

Save 25–50% on eligible API SMS orders, depending on availability. Discounted quotes have a cost and margin floor, so some stock may be unavailable at API rates. Each option returns priceCents, retailPriceCents and discountPercent; the returned price is the amount charged. Rounding uses whole EUR cents.

This is an illustrative quote. Rates are live. API quotes last 60 seconds, belong to the key that requested them and cannot be used through website or Discord checkout. Website and Discord orders keep their normal prices. Add balance through the website or Discord bot. Deposits, promo codes and support tickets are not available through this API. Resends carry no customer fee.

The key’s daily cap counts gross SMS reservations from 00:00 UTC, including orders later refunded. Refunds return balance but do not replenish this daily cap. Existing idempotent retries do not count twice.

From number to verification.

1. Discover. Search GET /services and use exact country keys from GET /countries. Coverage does not guarantee stock.
2. Quote. POST /quotes returns available options. Select an options[].id; display the price to your customer.
3. Purchase. POST /orders with that quoteId and a unique, persisted Idempotency-Key. Balance is reserved once. At most five active purchases per account.
4. Poll. Read GET /orders/{id} every 5–10 seconds. The background service updates the code automatically. Codes and message history are private to your account.
5. Resend or cancel. After the first code, check/request a free resend if eligible. Unused waiting numbers may be cancelled after one minute. Only confirmed cancellations and refunds restore the exact amount charged.

Resend availability can change. A Resend quote selects eligible stock but does not guarantee indefinite reuse. One resend can be pending at a time; at most 25 attempts per number. The original code stays in message history. You must request the next code from the service you are verifying.

Get balance and SMS updates.

Read your current balance anytime with GET /account using account:read. For automatic updates, configure up to five public HTTPS receivers in Dashboard → Webhooks or through /webhooks. Choose the events you need and set your low-balance threshold in EUR cents.

webhooks:write permits endpoint management. Creating/updating subscriptions, rotating secrets and retrying private deliveries also require the corresponding read permissions above. webhooks:read allows endpoint settings and delivery metadata. The test action sends webhook.test with a harmless message.

Low-balance notifications fire once per downward crossing, then rearm when your balance reaches the threshold again. If the balance is already low when you create/re-enable the subscription or change its threshold, we queue one initial alert. Further spending below the same threshold does not send repeated alerts. The payload contains the balance at the time of the event; use GET /account for the latest amount.

{
  "id": "evt_balance_123",
  "type": "balance.low",
  "accountId": "22222222-2222-4222-8222-222222222222",
  "createdAt": 1792526400000,
  "data": {
    "currency": "EUR",
    "balanceCents": 430,
    "previousBalanceCents": 550,
    "thresholdCents": 500
  }
}

Verify every delivery.

Each POST contains JSON and these headers:

Calculate HMAC-SHA256 over timestamp + "." + exact raw JSON body, using the entire signing-secret string as the key. Do not base64-decode the secret or parse/re-serialize JSON before verification. Compare signatures in constant time, reject timestamps outside five minutes, then atomically deduplicate on the body’s id before applying business effects.

The signing secret is shown once when creating or rotating an endpoint. Store it privately. It is separate from your API key. API-key revocation stops API access; webhook subscriptions remain independent. Password reset/change, suspension and account merging pause existing webhook endpoints for security. Re-enable only the receivers you trust.

Acknowledge quickly; handle duplicates.

Return any 2xx response after securely persisting the event, then process it asynchronously. Delivery is at least once and ordering is not guaranteed. A timeout after your server accepted an event can cause a retry. IDs and raw payload stay the same; the signature timestamp is refreshed. Use createdAt and authoritative API reads when handling out-of-order updates.

We attempt delivery up to eight times with backoff starting at 15 seconds, then 1 minute, 5 minutes, 15 minutes, 1 hour, 3 hours and 6 hours. A numeric Retry-After may lengthen the delay, up to 24 hours. We do not follow redirects. HTTP 410 pauses the endpoint. Inspect status, attempt counts and HTTP codes in the dashboard/API, and manually retry a failed delivery after fixing your receiver. Logs are retained for 30 days.

Receivers must use a public DNS hostname with HTTPS on port 443. Private, loopback, link-local, reserved and mixed public/private DNS destinations are blocked. The destination is checked again and pinned for every connection. To change a URL, create a new endpoint and remove the old one. In-flight requests may complete after pause/removal.

Webhook configuration/actions allow 20 requests per hour per account; tests allow five per hour and have a shared service limit. Core payment and SMS checks run independently of webhook retries. SMS event payloads contain the relevant code only; fetch the order for full history. A resend outcome includes resendId and may end while the original order remains received. Events from card/crypto creation or unconfirmed payments are not sent as credits.

// Node.js 22+. Put behind your public HTTPS reverse proxy on port 443.
import http from 'node:http';
import { createHmac, timingSafeEqual } from 'node:crypto';
const secret = process.env.SMSLOVERS_WEBHOOK_SECRET; // Full whsec_... string.
if (!secret) throw new Error('Set the signing secret privately');
const server = http.createServer(async (req, res) => {
  if (req.method !== 'POST' || req.url !== '/webhooks/smslovers') {
    res.writeHead(404).end(); return;
  }
  const timestamp = String(req.headers['x-smslovers-timestamp'] || '');
  const signature = String(req.headers['x-smslovers-signature'] || '');
  if (!/^\d{10}$/.test(timestamp) ||
      Math.abs(Date.now() / 1000 - Number(timestamp)) > 300 ||
      !/^v1=[a-f0-9]{64}$/.test(signature)) {
    res.writeHead(401).end(); return;
  }
  try {
    let size = 0; const chunks = [];
    for await (const chunk of req) {
      size += chunk.length;
      if (size > 32768) { res.writeHead(413).end(); return; }
      chunks.push(chunk);
    }
    const raw = Buffer.concat(chunks);
    const expected = createHmac('sha256', secret)
      .update(timestamp + '.').update(raw).digest();
    const supplied = Buffer.from(signature.slice(3), 'hex');
    if (!timingSafeEqual(expected, supplied)) {
      res.writeHead(401).end(); return;
    }
    const event = JSON.parse(raw.toString('utf8'));
    // REQUIRED: atomically persist event.id with a unique constraint and
    // enqueue the work in your database. If already stored, return 204.
    // await persistAndEnqueueOnce(event.id, event);
    // Replace the line above with your own durable queue before production.
    console.log('Verified event type:', event.type); // Never log private codes.
    res.writeHead(204).end(); // Acknowledge after durable storage succeeds.
  } catch {
    res.writeHead(500).end(); // SMSLovers will retry with the same event ID.
  }
});
server.requestTimeout = 15000;
server.listen(3000, '127.0.0.1');

This example verifies requests behind your HTTPS proxy. Connect the indicated persistence/queue step before production so duplicate events cannot repeat a business action. Never trust an unsigned event or use a return-page visit as proof of payment.

The endpoint reference.

All paths below are relative to /api/v1. Full field schemas and error responses are in the OpenAPI 3.1 specification. Expand an endpoint for its request and behavior.

{
  "name": "My product",
  "url": "https://api.example.com/webhooks/smslovers",
  "events": [
    "balance.low",
    "sms.received"
  ],
  "lowBalanceCents": 500,
  "enabled": true
}

{
  "enabled": false
}

{}

{}

{
  "deliveryId": "whd_0123456789abcdef0123456789abcdef"
}

{}

{
  "serviceId": 1,
  "country": "US"
}

{
  "quoteId": "11111111-1111-4111-8111-111111111111"
}

{}

{}

{}

Start with working examples.

The first example shows a complete purchase and polling flow. Add durable storage for the idempotency key, request body and order ID before using it in production.

// Node.js 22+. Run on your server; persist keys before each write.
import { randomUUID } from 'node:crypto';
const base = 'https://smslovers.com/api/v1';
const key = process.env.SMSLOVERS_API_KEY;
if (!key) throw new Error('Set SMSLOVERS_API_KEY privately');
async function api(path, method = 'GET', body, requestKey) {
  const response = await fetch(base + path, {
    method, signal: AbortSignal.timeout(25000),
    headers: { Authorization: 'Bearer ' + key,
      ...(body ? { 'Content-Type': 'application/json' } : {}),
      ...(requestKey ? { 'Idempotency-Key': requestKey } : {}) },
    ...(body ? { body: JSON.stringify(body) } : {})
  });
  const result = await response.json();
  if (!response.ok) throw Object.assign(new Error(result.error.message), {
    status: response.status, requestId: result.requestId,
    retryAfter: response.headers.get('retry-after')
  });
  return result.data;
}
// Discover IDs/countries; this example uses Google (1) in US.
const quote = await api('/quotes', 'POST', { serviceId: 1, country: 'US' });
if (!quote.available) throw new Error('No discounted stock available');
const option = quote.options.find(o => o.label === 'Standard') ?? quote.options[0];
// Show option.priceCents to your customer and get purchase approval first.
const orderKey = randomUUID(); // SAVE in your database before the next call.
const purchaseBody = { quoteId: option.id }; // SAVE unchanged for retries.
const order = await api('/orders', 'POST', purchaseBody, orderKey);
// A retry must use the same orderKey and purchaseBody, even after timeout.
let current = order;
while (['purchasing', 'waiting', 'resending', 'cancel_requested'].includes(current.status)) {
  await new Promise(r => setTimeout(r, 10000));
  current = await api('/orders/' + order.id);
}
if (current.status === 'received') console.log(current.code); // String: keep zeroes.
else if (['reconciling', 'resend_review'].includes(current.status)) {
  throw new Error('Needs review; do not create a replacement automatically');
} else console.log('Order ended:', current.status);
// Production: persist the order ID too; resume polling after a restart.
// On 429 wait Retry-After seconds. On timeout/5xx, back off and retry the
// SAME operation/key/body. Do not log keys or SMS codes in production.

# Python 3, standard library. Read-only connection test.
import json, os, urllib.request, urllib.error
key = os.environ['SMSLOVERS_API_KEY']
request = urllib.request.Request(
    'https://smslovers.com/api/v1/account',
    headers={'Authorization': 'Bearer ' + key})
try:
    with urllib.request.urlopen(request, timeout=25) as response:
        account = json.load(response)['data']
        print('EUR balance:', account['balanceCents'] / 100)
except urllib.error.HTTPError as error:
    # Honor error.headers.get('Retry-After') on HTTP 429.
    print('API request failed:', error.code)
    raise

Rate limits and retries.

Per key: 240 GET and 60 POST requests per minute. Per account: 600 API requests per minute. These budgets are separate from website browsing and automatic payment/SMS checks. Shared-network ingress protection allows 1,800 API requests per minute per IP.

There is also a shared quote-capacity ceiling. A temporary pricing outage returns 503. Honor Retry-After on 429 and back off on 503. Polling every 10 seconds uses six requests per minute per order; five active orders use 30.

Persist a new Idempotency-Key (16–80 letters, numbers or hyphens) before each order, resend. Retry the same operation with the same key and identical body after timeouts/5xx. A changed order quote or checkout amount with the same key returns 409. Cancellation, receiving-address retrieval and ticket status updates are naturally idempotent. Quotes do not spend balance.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many attempts. Please try again later.",
    "retryAfterSeconds": 60
  },
  "requestId": "example-request-id"
}

400 invalid request; 401 invalid/expired/revoked key; 403 missing scope, cap or cross-origin request; 404 missing resource; 409 expired quote, insufficient balance, idempotency conflict or invalid state; 413 body over 32 KiB; 415 wrong content type; 429 rate limit; 503 service temporarily unavailable. Use requestId or the matching X-Request-Id header when contacting support. Do not log authorization headers or private SMS content.

Need help with your setup?