OTP codes
Send one-time codes by SMS and check them, without storing codes yourself.
Send a code#
POST /v1/otp/send
| Name | Type | Required | Description |
|---|---|---|---|
to | string | yes | Recipient, same rules as messages. |
purpose | string | no | What the code is for, e.g. signup, login, reset. 1–40 characters of a–z, 0–9, _, -. Default default. A code only verifies for the purpose it was sent for. |
length | integer | no | Digits, 4–8. Default 6. |
ttlSec | integer | no | Seconds the code is valid, 60–3600. Default 300. |
text | string | no | Your own SMS text. Must contain {code} exactly once; {app} is replaced by your workspace name. Default: Your {app} code is {code}. |
curl -X POST "https://sms.liscosolutions.com/v1/otp/send" \
-H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"to":"+905321234567","purpose":"signup"}'const res = await fetch("https://sms.liscosolutions.com/v1/otp/send", {
method: "POST",
headers: {
Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "+905321234567",
purpose: "signup"
}),
});
console.log(res.status, await res.json());<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/otp/send");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"to" => "+905321234567",
"purpose" => "signup",
]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);import requests
res = requests.post(
"https://sms.liscosolutions.com/v1/otp/send",
headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
json={
"to": "+905321234567",
"purpose": "signup",
},
)
print(res.status_code, res.json())Response · 201
{
"otpId": "6650f2d1e4b0a1b2c3d4e600",
"messageId": "6650f2d1e4b0a1b2c3d4e5ff",
"to": "+905321234567",
"purpose": "signup",
"expiresAt": "2026-11-20T09:20:02.481Z"
}With your own text, length and lifetime:
curl -X POST "https://sms.liscosolutions.com/v1/otp/send" \
-H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"to":"+905321234599","purpose":"login","length":4,"ttlSec":600,"text":"{app}: your login code is {code}. It expires in 10 minutes."}'const res = await fetch("https://sms.liscosolutions.com/v1/otp/send", {
method: "POST",
headers: {
Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "+905321234599",
purpose: "login",
length: 4,
ttlSec: 600,
text: "{app}: your login code is {code}. It expires in 10 minutes."
}),
});
console.log(res.status, await res.json());<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/otp/send");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"to" => "+905321234599",
"purpose" => "login",
"length" => 4,
"ttlSec" => 600,
"text" => "{app}: your login code is {code}. It expires in 10 minutes.",
]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);import requests
res = requests.post(
"https://sms.liscosolutions.com/v1/otp/send",
headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
json={
"to": "+905321234599",
"purpose": "login",
"length": 4,
"ttlSec": 600,
"text": "{app}: your login code is {code}. It expires in 10 minutes.",
},
)
print(res.status_code, res.json())Response · 201
{
"otpId": "6650f2e7e4b0a1b2c3d4e602",
"messageId": "6650f2e7e4b0a1b2c3d4e601",
"to": "+905321234599",
"purpose": "login",
"expiresAt": "2026-11-20T09:25:02.481Z"
}Sending a new code for the same number and purpose replaces the previous one: only the newest code verifies.
The response has otpId (use it in your logs), the messageId of the SMS and expiresAt.
Verify a code#
POST /v1/otp/verify
| Name | Type | Required | Description |
|---|---|---|---|
to | string | yes | The number the code was sent to. |
code | string | yes | What the user typed. Spaces, dashes, and Arabic-Indic or Persian digits are accepted. |
purpose | string | no | The same purpose as when sending. Default default. |
A wrong code:
curl -X POST "https://sms.liscosolutions.com/v1/otp/verify" \
-H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"to":"+905321234567","purpose":"signup","code":"000000"}'const res = await fetch("https://sms.liscosolutions.com/v1/otp/verify", {
method: "POST",
headers: {
Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "+905321234567",
purpose: "signup",
code: "000000"
}),
});
console.log(res.status, await res.json());<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/otp/verify");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"to" => "+905321234567",
"purpose" => "signup",
"code" => "000000",
]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);import requests
res = requests.post(
"https://sms.liscosolutions.com/v1/otp/verify",
headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
json={
"to": "+905321234567",
"purpose": "signup",
"code": "000000",
},
)
print(res.status_code, res.json())Response · 422
{
"error": {
"code": "invalid_code",
"message": "The code is not correct.",
"attemptsLeft": 4
}
}The right code:
curl -X POST "https://sms.liscosolutions.com/v1/otp/verify" \
-H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"to":"+905321234567","purpose":"signup","code":"482913"}'const res = await fetch("https://sms.liscosolutions.com/v1/otp/verify", {
method: "POST",
headers: {
Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "+905321234567",
purpose: "signup",
code: "482913"
}),
});
console.log(res.status, await res.json());<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/otp/verify");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"to" => "+905321234567",
"purpose" => "signup",
"code" => "482913",
]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);import requests
res = requests.post(
"https://sms.liscosolutions.com/v1/otp/verify",
headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
json={
"to": "+905321234567",
"purpose": "signup",
"code": "482913",
},
)
print(res.status_code, res.json())Response · 200
{
"valid": true,
"otpId": "6650f2d1e4b0a1b2c3d4e600"
}A code works once. The same code again:
curl -X POST "https://sms.liscosolutions.com/v1/otp/verify" \
-H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"to":"+905321234567","purpose":"signup","code":"482913"}'const res = await fetch("https://sms.liscosolutions.com/v1/otp/verify", {
method: "POST",
headers: {
Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "+905321234567",
purpose: "signup",
code: "482913"
}),
});
console.log(res.status, await res.json());<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/otp/verify");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"to" => "+905321234567",
"purpose" => "signup",
"code" => "482913",
]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);import requests
res = requests.post(
"https://sms.liscosolutions.com/v1/otp/verify",
headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
json={
"to": "+905321234567",
"purpose": "signup",
"code": "482913",
},
)
print(res.status_code, res.json())Response · 422
{
"error": {
"code": "otp_not_found",
"message": "No active code for this number and purpose."
}
}Every outcome#
| Result | HTTP | When |
|---|---|---|
{"valid": true, "otpId": …} | 200 | The code is right. It can't be used again. |
invalid_code | 422 | Wrong code; attemptsLeft tells how many tries remain. |
too_many_attempts | 429 | 5 tries were used (every try counts, the right one too). Send a new code. |
otp_expired | 422 | The code's ttlSec has passed. |
otp_not_found | 422 | No open code: never sent, already verified, or replaced by a newer code. |
otp_rate_limited | 429 | (send) Too many codes to this number; see Limits. |
plan_feature_unavailable | 403 | Your plan doesn't include OTP. |
Response · 429
{
"error": {
"code": "too_many_attempts",
"message": "Too many wrong attempts. Send a new code."
}
}Security and privacy#
- Codes are random (
cryptoquality) and stored only as a keyed hash. Not even LiSco SMS can read them back. - Wherever a code message is shown (API, dashboard, webhooks, CSV export) the code appears as
•. Once the SMS is sent, failed or expired, the digits are removed from storage too. - OTP messages are handed to phones before other waiting messages, so a long queue never delays a login.
- Codes count toward your monthly message limit.