API documentation

One REST API, one key. JSON in, JSON out. Base URL: https://bavarianilluminatiam.org/api/v1

Authentication

Create an account, then copy your key from Dashboard → Profile & API. Send it in the X-API-Key header. Keep it secret; regenerate it any time.

curl https://bavarianilluminatiam.org/api/v1/balance \
  -H "X-API-Key: YOUR_KEY"

<?php
$ch = curl_init('https://bavarianilluminatiam.org/api/v1/balance');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_KEY']]);
echo curl_exec($ch);

const res = await fetch('https://bavarianilluminatiam.org/api/v1/balance', { headers: { 'X-API-Key': 'YOUR_KEY' } });
console.log(await res.json());

import requests
r = requests.get('https://bavarianilluminatiam.org/api/v1/balance', headers={'X-API-Key': 'YOUR_KEY'})
print(r.json())

POST/sms/send

Send one message or a batch (up to the per-send limit set by the site). Use international numbers. Your sender must be the default sender or an approved Sender ID. Recipients who replied STOP are skipped automatically. By using the API you confirm every recipient agreed to receive your messages (see the Acceptable Use Policy).

Fields: to (string or array), sender, message, optional scheduled_at (ISO 8601, e.g. 2026-12-01T09:00:00Z), optional respect_quiet (true holds messages until 08:00 account time if sent 21:00-08:00).

curl -X POST https://bavarianilluminatiam.org/api/v1/sms/send \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"to":["+15551234567","+442071234568"],"sender":"SwiftSMS","message":"Your order has shipped"}'

<?php
$payload = json_encode(['to' => ['+15551234567'], 'sender' => 'SwiftSMS', 'message' => 'Your order has shipped']);
$ch = curl_init('https://bavarianilluminatiam.org/api/v1/sms/send');
curl_setopt_array($ch, [
  CURLOPT_POST => true, CURLOPT_POSTFIELDS => $payload, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_KEY', 'Content-Type: application/json'],
]);
$res = json_decode(curl_exec($ch), true);
print_r($res);

const res = await fetch('https://bavarianilluminatiam.org/api/v1/sms/send', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ to: ['+15551234567'], sender: 'SwiftSMS', message: 'Your order has shipped' }),
});
console.log(await res.json());

import requests
r = requests.post('https://bavarianilluminatiam.org/api/v1/sms/send',
  headers={'X-API-Key': 'YOUR_KEY'},
  json={'to': ['+15551234567'], 'sender': 'SwiftSMS', 'message': 'Your order has shipped'})
print(r.json())

Response:

{"ok":true,"accepted":2,"skipped":[],"cost":0.0800,"segments":1,"message_ids":[101,102]}

GET/sms/status/{id}

Status is one of queued, sending, sent, delivered, failed. Failed messages are refunded automatically.

curl https://bavarianilluminatiam.org/api/v1/sms/status/101 -H "X-API-Key: YOUR_KEY"

requests.get('https://bavarianilluminatiam.org/api/v1/sms/status/101', headers={'X-API-Key': 'YOUR_KEY'}).json()

await (await fetch('https://bavarianilluminatiam.org/api/v1/sms/status/101', { headers: { 'X-API-Key': 'YOUR_KEY' } })).json();

<?php
$ch = curl_init('https://bavarianilluminatiam.org/api/v1/sms/status/101');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_KEY']]);
echo curl_exec($ch);

GET/sms/rates?country=US

Cheapest current price per SMS part for a country (omit country for all). A GSM-7 message is 160 characters per part (153 when split); Unicode is 70 (67 when split).

curl "https://bavarianilluminatiam.org/api/v1/sms/rates?country=US" -H "X-API-Key: YOUR_KEY"

Verification numbers

GET/prices?country=US · POST/buy (country, service) · GET/status/{id} · POST/cancel/{id}

Buy a number, then poll /status/{id} every 3-5 seconds until status is completed and code is filled. Orders with no SMS expire and are refunded automatically.

curl -X POST https://bavarianilluminatiam.org/api/v1/buy -H "X-API-Key: YOUR_KEY" -d "country=US&service=whatsapp"
curl https://bavarianilluminatiam.org/api/v1/status/55 -H "X-API-Key: YOUR_KEY"

<?php
function api($method, $path, $data = null) {
  $ch = curl_init('https://bavarianilluminatiam.org/api/v1' . $path);
  curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => $method,
    CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_KEY'], CURLOPT_POSTFIELDS => $data]);
  return json_decode(curl_exec($ch), true);
}
$o = api('POST', '/buy', ['country' => 'US', 'service' => 'whatsapp']);
for ($i = 0; $i < 40; $i++) {
  sleep(3);
  $s = api('GET', '/status/' . $o['order']['id']);
  if (!empty($s['order']['code'])) { echo $s['order']['code']; break; }
}

const h = { 'X-API-Key': 'YOUR_KEY' };
const buy = await (await fetch('https://bavarianilluminatiam.org/api/v1/buy', { method: 'POST', headers: h, body: new URLSearchParams({ country: 'US', service: 'whatsapp' }) })).json();
for (let i = 0; i < 40; i++) {
  await new Promise(r => setTimeout(r, 3000));
  const s = await (await fetch('https://bavarianilluminatiam.org/api/v1/status/' + buy.order.id, { headers: h })).json();
  if (s.order.code) { console.log(s.order.code); break; }
}

import requests, time
h = {'X-API-Key': 'YOUR_KEY'}
o = requests.post('https://bavarianilluminatiam.org/api/v1/buy', headers=h, data={'country': 'US', 'service': 'whatsapp'}).json()
for _ in range(40):
    time.sleep(3)
    s = requests.get('https://bavarianilluminatiam.org/api/v1/status/%s' % o['order']['id'], headers=h).json()
    if s['order'].get('code'):
        print(s['order']['code']); break

Webhooks

Set an https URL under Dashboard → Bulk SMS → API & webhooks. We POST JSON like {"event":"sms.delivered","created":"...","data":{"id":101,"to":"15551234567"}}. Events: sms.sent, sms.delivered, sms.failed, sms.inbound, sms.optout. Reply with any 2xx; failed deliveries are retried up to 5 times with growing delays.

Verify the X-Swift-Signature header: HMAC-SHA256 of the raw body using your signing secret.

<?php
$raw = file_get_contents('php://input');
$ok = hash_equals(hash_hmac('sha256', $raw, 'YOUR_SECRET'), $_SERVER['HTTP_X_SWIFT_SIGNATURE'] ?? '');
http_response_code($ok ? 200 : 401);

const crypto = require('crypto');
// express.raw({ type: 'application/json' })
const expected = crypto.createHmac('sha256', 'YOUR_SECRET').update(req.body).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.get('X-Swift-Signature') || ''));

import hmac, hashlib
expected = hmac.new(b'YOUR_SECRET', request.get_data(), hashlib.sha256).hexdigest()
ok = hmac.compare_digest(expected, request.headers.get('X-Swift-Signature', ''))

Delivery reports & inbound SMS (for suppliers)

If you connect your own SMS supplier, the admin panel shows two callback URLs per route: /webhook/sms/dlr/<token> (delivery reports: message_id, status, or Twilio's MessageSid/MessageStatus) and /webhook/sms/inbound/<token> (from, text, or Twilio's From/Body). A reply of STOP, UNSUBSCRIBE, CANCEL, END or QUIT opts the sender out automatically.

Errors & limits

Errors return {"ok":false,"error":"..."} with a status: 401 bad key, 404 unknown item, 422 request refused (balance, sender, content, limits), 429 too many requests. Default: 120 requests per minute per IP.