Send and check one-time codes (OTP)

In Flow, open Settings → Developers → OTP / Verification, go to Configuration and switch on Enable OTP (1). While you build, also switch on Test mode (2): every answer then includes the code as testCode, and nothing is sent or charged. (Without the Developers tab, OTP / Verification sits under Settings → AI & Automation.)

On the same screen: Code length (4, 6 or 8; 6 recommended — phones auto-fill numeric codes), Code type, Expiry (seconds) from 60 to 1800 (5 minutes by default), Max attempts before the code is blocked (3 by default), Resend cooldown and Max resends / hour (per number), the Channel order to try, your Brand name in message, and Allowed countries — only +91 until you add more, which stops costly foreign sends. For WhatsApp, open Advanced — WhatsApp template & SMS DLT (India): WhatsApp AUTH template id holds the id of an approved authentication template on your number. Without one, a WhatsApp code goes as a plain message, which WhatsApp delivers only to people who have written to you in the last 24 hours — everyone else gets the next channel in your order. Message us to set the template up.

From your website’s server, send POST /api/v1/otp/send/ with the customer’s number (with its country code) or email in to, and a channel: auto tries your channel order; whatsapp, sms or email pins one. The key needs Send and check one-time codes, or full access. Keep the requestId that comes back (1). In Test mode the answer also carries the code itself as testCode (2), and nothing is sent.

curl -s -X POST "https://flowserver.skode.ai/api/v1/otp/send/" \
  -H "Authorization: Bearer $FLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+91XXXXXXXXXX", "channel": "auto"}'

{"requestId": "…", "channelUsed": "whatsapp", "expiresInSec": 300}

Until you switch it on, sending answers 403 with "error": "otp_disabled" (1) and a message naming the switch: Settings → Developers → OTP / Verification → Configuration.

Send POST /api/v1/otp/verify/ with the requestId and the code (letters are not case-sensitive). A code that doesn’t pass answers "verified": false with a reason (1) — wrong_code, expired, too_many_attempts, already_used or delivery_failed — and attemptsLeft. "verified": true (2) means let them in — keep the receiptId as proof.

curl -s -X POST "https://flowserver.skode.ai/api/v1/otp/verify/" \
  -H "Authorization: Bearer $FLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestId": "<from the send>", "code": "482913"}'

{"verified": false, "reason": "wrong_code", "attemptsLeft": 2}

GET /api/v1/otp/<requestId>/ returns where a code stands: the number, masked (1); its status (2) — pending, verified, expired, blocked after too many wrong tries, or failed; the channel used and whether it was delivered (deliveryStatus reads test in Test mode); how many wrong codes were tried (3); and when it was sent, expires or was verified.

By default one number can get a new code every 45 seconds and at most 5 an hour, and your workspace 1,000 an hour. Past a limit, sending answers 429 "rate_limited". Each code sent is charged at WhatsApp’s authentication rate for the customer’s country (or your agreed flat price) and refunded if it can’t be delivered; a low wallet answers 402.