OTP API

Verify that a user controls a phone number: send a one-time code by SMS, then check the code the user typed. One-time codes are part of the SMS API — same base URL, same token, same wallet.


Base URL	`https://api.omaxtelecom.com/sms`
Authentication	Bearer access token — how to get one
Postman	Collection · Environment
AI assistants	Open in ChatGPT · Open in Claude · Markdown · MCP server

[!TIP] Try it here: enter your Client ID and Client Secret in the Authentication box, click Authorize, then use Test Request on any endpoint.

[!NOTE] OTP uses the SMS API's token, errors, rate limits and delivery tracking. Get a token as described in Getting started; everything else is in the SMS API guide.

How it works

Step	Endpoint	What happens
1. Send	`POST /otp/send`	The API generates a 6-digit code, sends it by SMS and returns a `verification_id`
2. Verify	`POST /otp/verify`	You pass the `verification_id` and the code the user typed; the API answers `verified: true` or `false`

The code is never returned by the API and is not stored in readable form. Your system only ever handles the verification_id.

Send a code

curl -s -X POST https://api.omaxtelecom.com/sms/otp/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "MYSHOP",
    "to": "+38765123456",
    "template": "Your MyShop code is {code}",
    "ttl_seconds": 300
  }'

{
  "success": true,
  "data": {
    "verification_id": "0198c5f6-3b9c-70d1-a2e4-5d8f6c1b7a90",
    "message_id": "0198c5f2-7a10-7c3e-9d4b-2f6a1e8b0c11",
    "to": "38765123456",
    "expires_at": "2026-10-12T12:05:00+00:00"
  }
}

Field	Required	Rules
`from`	yes	An approved sender ID
`to`	yes	International number, with or without `+`
`template`	no	Message text; must contain `{code}`. Default: `Your verification code is {code}`
`ttl_seconds`	no	How long the code is valid: 30 to 3600, default 300

Store verification_id with the user's session. message_id is the SMS that carries the code — track its delivery with GET /messages/{id} or webhooks, like any other message. The sms.otp.verified and sms.otp.expired webhooks tell you when a code was verified or expired.

Verify a code

curl -s -X POST https://api.omaxtelecom.com/sms/otp/verify \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"verification_id": "0198c5f6-3b9c-70d1-a2e4-5d8f6c1b7a90", "code": "482913"}'

{ "success": true, "data": { "verified": true, "reason": null, "attempts_remaining": 0 } }

The answer is always 200 — read verified. When it is false:

`reason`	Meaning	What to show the user
`invalid_code`	Wrong code; `attempts_remaining` tries are left	Ask them to type it again
`expired`	The code ran out of time	Offer to send a new code
`too_many_attempts`	5 wrong codes; the verification is locked	Offer to send a new code
`already_used`	The code was already verified once	Start a new verification

An unknown verification_id answers 404 NOT_FOUND.

With the Node.js SDK

import { Omax } from "@omaxtelecom/sdk";

const omax = new Omax(); // reads OMAX_CLIENT_ID and OMAX_CLIENT_SECRET

const { verification_id } = await omax.otp.send({ from: "ACME", to: "+38765123456" });
// later, with the code the user typed:
const result = await omax.otp.verify({ verification_id, code: "123456" });

The SDK sends the Idempotency-Key for otp.send and keeps it when it retries, so a retry never sends a second code. See Getting started for installation.

Rules

Rule	Value
Code length	6 digits
Validity	5 minutes by default, 30 seconds to 1 hour with `ttl_seconds`
Attempts	5 per code
Use	Once
Resend to the same number	After 30 seconds; earlier returns `429 OTP_RESEND_TOO_SOON` with `Retry-After`
Price	The SMS is charged like any other message

Security checklist

Call POST /otp/verify from your server, never from the browser or app: its answer decides whether the user is who they claim to be.
Keep verification_id on the server side of the session; the user only needs to type the code.
Limit how many codes one user or IP address can request — the API limits resends per number, not per user.
Do not put the code in a URL, a log or an analytics event.
Treat expired and too_many_attempts as "start again", not as "try another code".

Common uses

Sign-up — confirm the phone number before creating the account.
Login — a second factor after the password.
Password reset — confirm identity before changing credentials.
Sensitive actions — confirm a payment, a transfer or a change of contact details.

Need help?

Email support@omaxtelecom.com. Tell us which endpoint you called, when, and what the response was — including its request_id if it has one. Never send your Client Secret or access token.