API

https://sms-orchestrator.6scphmjxvp.workers.dev

Set once as API_BASE and reuse it. Every path below is relative to it.

Quickstart

Four calls, start to finish.

# 1. what can we route, and at what price?
curl "$API_BASE/control/limits?token=$KEY&application_id=1003"

# 2. lease a number — the only call that spends money, so send a key you can retry on
curl "$API_BASE/control/get-number?token=$KEY\
&application_id=1003&country_id=idn&idempotency_key=order-8842"
# -> {"request_id":904412,"number":"6281234557712","application_id":"1003","country_id":"idn"}

# 3. wait for the code. one connection, no polling.
#    NOTE the stream is keyed on the ACTIVATION UUID, not the integer request_id.
curl -N "$API_BASE/sse/af6ae0b7-…"

# 4. acknowledge success (already settled — this is a no-op you can skip)
curl "$API_BASE/control/set-status?token=$KEY&request_id=904412&status=used"

# …or give up, which releases the number and refunds you, exactly once
curl "$API_BASE/control/set-status?token=$KEY&request_id=904412&status=close"

Authentication

Every endpoint takes token as a query parameter. There are no headers to set and no OAuth dance. A bad or revoked key returns wrong_token.

# every call carries the key as a query parameter
curl "$API_BASE/control/get-balance?token=sms_live_xxxxxxxxxxxxxxxx"

Retries and duplicate protection

Read this before you write retry logic. Buying a number spends money; every other endpoint does not, so retry those freely and give this one your attention.

Pass your own unique string to get-number. If the same key arrives again from the same API key, you get the original response back verbatim — no second number is leased and no second charge is placed. Safe to retry after a timeout, as many times as you like.

# safe to retry after a timeout, as many times as you like
curl "$API_BASE/control/get-number?token=$KEY\
&application_id=1003&country_id=idn\
&idempotency_key=order-8842-attempt"

sms-man clients drop in unmodified and never send an idempotency key, and rejecting them for that would defeat the point of the façade. So a short window protects them anyway.

Realtime

GET /sse/:activationId is a Server-Sent Events stream of the activation's state changes, ending with the code. Use it instead of calling /control/get-sms in a loop — you get the code the moment it lands, over one connection.

event: open
data: {"activationId":"af6ae0b7-…"}

event: state
data: {"activationId":"af6ae0b7-…","status":"WAITING_SMS","mobile":"8519…","updatedAt":1788…}

event: state
data: {"activationId":"af6ae0b7-…","status":"CODE_RECEIVED","mobile":"8519…","code":"483920","sms":"Your code is 483920","updatedAt":1788…}

event: code
data: {"activationId":"af6ae0b7-…","code":"483920","sms":"Your code is 483920"}

event: done
data: {"activationId":"af6ae0b7-…","status":"CODE_RECEIVED"}

const es = new EventSource(`${API_BASE}/sse/${activationId}`);

// The events are NAMED. A plain es.onmessage handler fires only for unnamed
// frames and will sit silent forever against this stream.
es.addEventListener('state', (ev) => {
  const s = JSON.parse(ev.data);   // INIT -> ACQUIRING -> WAITING_SMS -> …
  render(s.status, s.mobile);
});

es.addEventListener('code', (ev) => {
  const { code } = JSON.parse(ev.data);
  use(code);
});

es.addEventListener('done', () => es.close());   // the server closes too

Webhooks

Register a callback with POST /control/webhook and we push the code to you instead of you waiting for it.

{
  "activation_id": "af6ae0b7-…",
  "service": "1003",
  "country": "idn",
  "mobile": "8519…",
  "code": "483920",
  "sms": "Your code is 483920"
}

import { createHmac, timingSafeEqual } from 'node:crypto';

app.post('/hooks/sms', async (req, res) => {
  const body = req.rawBody;                       // the exact bytes, unparsed

  // 1. verify the signature BEFORE trusting anything in the payload
  const expected = createHmac('sha256', WEBHOOK_SECRET).update(body).digest('hex');
  const given = req.get('x-smstoyou-signature') ?? '';
  if (given.length !== expected.length ||
      !timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(body);

  // 2. DEDUPE. Delivery is at-least-once: you WILL sometimes see the same
  //    activation twice. An INSERT that a unique constraint rejects is the
  //    whole implementation.
  const fresh = await db.insertIfAbsent('seen_activations', event.activation_id);

  // 3. reply 2xx promptly, then do the slow part
  res.sendStatus(200);
  if (fresh) await handleCode(event);
});

Reply 2xx promptly and do the slow work after replying — that is what keeps a successful delivery from being retried as a failure.

Errors

Every error carries sms-man's own error_code envelope, so an existing sms-man client parses it unchanged. Unlike sms-man we also set a real HTTP status — 401 for a bad token, 429 for a rate limit, 409 for a reused idempotency key — so a generic client can react without parsing the body. The one exception is wait_sms, which is HTTP 200 because it is not a failure.

{ "error_code": "no_numbers", "error_msg": "no numbers available" }