Verify API
Send a code and check it from your server, behind your own UI.
Use this when you want your own code-entry form. Two calls, both from your server with the API key.
Send
const { token, exp } = await verifyme.send({
target: "+85512345678",
provider: "sms", // email | whatsapp | telegram | sms:<slug> | auto
length: 6, // 4–8, default 4
timeout: 300, // seconds, 10–300, default 60
})| Field | Notes |
|---|---|
target | E.164 phone (+855…) or email address |
provider | Channel or pinned profile — see Concepts |
template_id | A saved template; otherwise the channel default, then a built-in message |
template | Inline text with {{code}} — overrides saved templates |
The token is a credential. Keep it on the server (session, cache, DB row) —
never in the browser, a URL or a log.
Check
const { success } = await verifyme.check({ token, code })success: false for a wrong, spent or expired code. Anything else — bad key,
firewall, rate limit, outage — throws a VerifymeError.
Five wrong attempts burn the token; the user needs a new code. Every failure returns the same message, so nothing leaks about why.
Status
GET /api/v1/verify/:token (verifyme.status(token)) returns
{ status, target, created_at } without spending an attempt.
A complete flow
app.post("/phone/start", async (req, res) => {
const { token } = await verifyme.send({ target: req.body.phone, provider: "sms" })
req.session.verify = { token, phone: req.body.phone }
res.sendStatus(204)
})
app.post("/phone/confirm", async (req, res) => {
const pending = req.session.verify
if (!pending) return res.sendStatus(400)
const { success } = await verifyme.check({ token: pending.token, code: req.body.code })
if (!success) return res.status(400).json({ error: "Wrong or expired code" })
delete req.session.verify
await users.markPhoneVerified(req.user.id, pending.phone)
res.sendStatus(204)
})Message templates
Create wording per channel in Console → Templates (SMS, email with subject
and HTML, Telegram) and mark one default. Variables: {{code}} (required),
{{app_name}}, {{minutes}}.