OTP SMS API

Three form-encoded POSTs cover the whole loop: send a one-time passcode by SMS, fall back to a voice call, verify what the user typed. The code itself is generated, encrypted and expired by Signalmash Verifier, so your application never creates or stores a passcode. Base URL https://api.signalmash.com.

Authentication

Every request carries a token in the Authorization header. Tokens are created in the portal under API → Tokens and can be scoped per function, so the service that sends codes does not need the permissions of the one that buys numbers. Give the OTP integration its own token and rotate it on its own schedule.

Authorization: YOUR_API_TOKEN

How the loop works

Verifier creates a unique, encrypted passcode tied to one user session, delivers it, and keeps it valid only for the window you configure on the account (anywhere from 30 seconds to several minutes). Your side of the exchange is three steps: call POST /sendotpbysms when the user needs a code, collect what they type, then call POST /verifyotp with the code and the session identifier from the send. A 200 on the verify call is the only thing that means the user passed.

1. Send a code by SMS

POST /sendotpbysms with an application/x-www-form-urlencoded body of three required fields. FROM is your Signalmash number (local, toll-free or short code), TO is the recipient, and TemplateKey selects the message template the code is inserted into, so the wording, brand name and expiry text live on the account rather than in your code. A 200 means the code was sent; keep the session identifier returned with it, because the verify call needs it.

curl

curl -X POST https://api.signalmash.com/sendotpbysms \
  -H "Authorization: YOUR_API_TOKEN" \
  -d "FROM=15035550100" \
  -d "TO=15035550199" \
  -d "TemplateKey=login_code"

Python

import requests

resp = requests.post(
    "https://api.signalmash.com/sendotpbysms",
    headers={"Authorization": "YOUR_API_TOKEN"},
    data={"FROM": "15035550100", "TO": "15035550199", "TemplateKey": "login_code"},
    timeout=10,
)
resp.raise_for_status()          # 200 = OTP sent
session_id = resp.json().get("SessionId")   # store against the login attempt

Node.js

const res = await fetch("https://api.signalmash.com/sendotpbysms", {
  method: "POST",
  headers: {
    Authorization: process.env.SIGNALMASH_TOKEN,
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({ FROM: "15035550100", TO: "15035550199", TemplateKey: "login_code" }),
});
if (!res.ok) throw new Error(`OTP send failed: ${res.status}`);
const { SessionId } = await res.json();   // keep for /verifyotp

2. Fall back to a voice call

Some users are on a landline, some carriers are slow, some people simply prefer a call. POST /sendotpbycall reads the code out over the phone. It takes the same FROM and TO plus a boolean Template field. Offer it as a "call me instead" link after the first SMS attempt rather than as the default, so the SMS path stays the cheap one.

curl -X POST https://api.signalmash.com/sendotpbycall \
  -H "Authorization: YOUR_API_TOKEN" \
  -d "FROM=15035550100" \
  -d "TO=15035550199" \
  -d "Template=true"

3. Verify the code

POST /verifyotp with OTP (what the user typed) and SessionId (from the send). 200 means verified. Anything else, including an expired code, is a failure: an expired passcode is automatically invalid, so the right response is to offer a fresh send, not to retry the same one.

curl -X POST https://api.signalmash.com/verifyotp \
  -H "Authorization: YOUR_API_TOKEN" \
  -d "OTP=482913" \
  -d "SessionId=SESSION_FROM_SEND"

resp = requests.post(
    "https://api.signalmash.com/verifyotp",
    headers={"Authorization": "YOUR_API_TOKEN"},
    data={"OTP": user_input, "SessionId": session_id},
    timeout=10,
)
verified = resp.status_code == 200

What Verifier handles so you do not have to

• Code generation and storage. Passcodes are generated and encrypted on the Signalmash side and tied to the session. There is no secret to keep in your database and nothing to leak in a log line.
• Expiry. The validity window is set on the account, typically 30 seconds to a few minutes. Expired codes fail verification automatically.
• Delivery. SMS or voice from local, toll-free or short-code numbers, with international delivery where carriers support it.
• Infrastructure. Cloud-hosted. You integrate through the API or the web portal and run nothing yourself.

Before you ship

• Register the sending number. In the US, OTP traffic from a local number is A2P 10DLC traffic with a two-factor-authentication use case, and a toll-free number needs toll-free verification. Signalmash completes the registration as part of onboarding; the 10DLC readiness checker shows what a reviewer will ask for.
• Rate-limit resends. Cap send attempts per phone number and per IP. Unlimited resends are the classic way OTP endpoints get abused for toll fraud and pumping.
• Never put the code in a link or a query string. It ends up in access logs and referrer headers.
• Keep the template short and branded. One line, brand name first, the code, the expiry. Do not add marketing copy to an authentication message.
• Honour STOP even on 2FA. Process opt-out keywords on the sending number and show the user a different way to authenticate.
• Treat verify as the only source of truth. A successful send means the message left; only a 200 from /verifyotp means the person holds the phone.

SMS codes, authenticator apps or RCS?

SMS one-time passcodes reach every phone with no app install, which is why they remain the default second factor for consumer logins and transaction confirmations. Time-based codes from an authenticator app are stronger against SIM-swap attacks but need enrolment; our explainer on time-based one-time passwords covers the trade-off. For fintech and banking flows where the sender's identity matters as much as the code, RCS verified messaging shows a verified brand mark next to the passcode. The wider view is in 2FA and OTP as a service.

What it costs

OTP messages are billed like any other SMS or voice minute on the account, per message or per call, with carrier pass-through fees that every US provider charges identically. Current rates are on the pricing page. If you also send notifications or marketing, the same account and token serve the SMS API.