LiSco SMSDocs
Dashboardالعربية
  • Introduction
  • Quick start
  • Authentication
  • Errors
  • Limits
  • Phone numbers
  • Messages
  • Message statuses
  • OTP codes
  • Devices
  • Webhooks
  • Changelog

© 2026 LiSco SMS

TermsPrivacyDelete accountContact

Messages

Send a message#

POST /v1/messages queues an SMS and answers at once; a phone sends it within seconds.

NameTypeRequiredDescription
tostringyesRecipient. E.164 recommended; see Phone numbers.
textstringyesThe message. At most 6 SMS parts and 2,000 characters; see Limits.
requestIdstringnoYour own id for this message, 1–100 characters. Sending the same requestId again never creates a second message.
ttlSecintegernoSeconds the message may wait to be sent, 60–86400. Default 86400 (24 hours). After that it becomes expired.
deviceIdstringnoSend only from this phone (an id from GET /v1/devices). Without it, any of your online phones may send.
curl -X POST "https://sms.liscosolutions.com/v1/messages" \
  -H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to":"+905321234567","text":"Your order #1042 has shipped.","requestId":"order-1042-shipped","ttlSec":3600}'
const res = await fetch("https://sms.liscosolutions.com/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+905321234567",
    text: "Your order #1042 has shipped.",
    requestId: "order-1042-shipped",
    ttlSec: 3600
  }),
});
console.log(res.status, await res.json());
<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/messages");
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",
    "text" => "Your order #1042 has shipped.",
    "requestId" => "order-1042-shipped",
    "ttlSec" => 3600,
  ]),
]);
$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/messages",
    headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "to": "+905321234567",
        "text": "Your order #1042 has shipped.",
        "requestId": "order-1042-shipped",
        "ttlSec": 3600,
    },
)
print(res.status_code, res.json())
Response · 201
{
  "id": "6650f1c2e4b0a1b2c3d4e5f6",
  "to": "+905321234567",
  "text": "Your order #1042 has shipped.",
  "status": "pending",
  "deviceId": null,
  "sim": null,
  "error": null,
  "requestId": "order-1042-shipped",
  "createdAt": "2026-11-20T09:15:02.481Z",
  "updatedAt": "2026-11-20T09:15:02.481Z",
  "expiresAt": "2026-11-20T10:15:02.481Z"
}

A new message returns 201.

Idempotency with requestId#

Networks fail; retries happen. Send a requestId (for example your order or event id) and retry freely: if a message with that requestId already exists in your workspace, you get 200 with that message instead of a new one. Nothing else in the body is compared.

curl -X POST "https://sms.liscosolutions.com/v1/messages" \
  -H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to":"+905321234567","text":"Your order #1042 has shipped.","requestId":"order-1042-shipped","ttlSec":3600}'
const res = await fetch("https://sms.liscosolutions.com/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+905321234567",
    text: "Your order #1042 has shipped.",
    requestId: "order-1042-shipped",
    ttlSec: 3600
  }),
});
console.log(res.status, await res.json());
<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/messages");
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",
    "text" => "Your order #1042 has shipped.",
    "requestId" => "order-1042-shipped",
    "ttlSec" => 3600,
  ]),
]);
$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/messages",
    headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "to": "+905321234567",
        "text": "Your order #1042 has shipped.",
        "requestId": "order-1042-shipped",
        "ttlSec": 3600,
    },
)
print(res.status_code, res.json())
Response · 200
{
  "id": "6650f1c2e4b0a1b2c3d4e5f6",
  "to": "+905321234567",
  "text": "Your order #1042 has shipped.",
  "status": "sent",
  "deviceId": "6650e0a1e4b0a1b2c3d4e500",
  "sim": 1,
  "error": null,
  "requestId": "order-1042-shipped",
  "createdAt": "2026-11-20T09:15:02.481Z",
  "updatedAt": "2026-11-20T09:15:02.481Z",
  "expiresAt": "2026-11-20T10:15:02.481Z"
}
A repeat answers 200 even when the month's message limit has been reached in the meantime, so a retry never turns into an error.

Choosing the phone#

With deviceId only that phone may take the message. It is not handed to another phone if that one fails, so the message fails or expires instead. A deviceId that isn't an active phone of your workspace gets 422 device_not_found.

curl -X POST "https://sms.liscosolutions.com/v1/messages" \
  -H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to":"+905321234567","text":"Sent from a chosen phone.","deviceId":"6650e0a1e4b0a1b2c3d4e500"}'
const res = await fetch("https://sms.liscosolutions.com/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+905321234567",
    text: "Sent from a chosen phone.",
    deviceId: "6650e0a1e4b0a1b2c3d4e500"
  }),
});
console.log(res.status, await res.json());
<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/messages");
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",
    "text" => "Sent from a chosen phone.",
    "deviceId" => "6650e0a1e4b0a1b2c3d4e500",
  ]),
]);
$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/messages",
    headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "to": "+905321234567",
        "text": "Sent from a chosen phone.",
        "deviceId": "6650e0a1e4b0a1b2c3d4e500",
    },
)
print(res.status_code, res.json())
Response · 201
{
  "id": "6650f1c2e4b0a1b2c3d4e5f6",
  "to": "+905321234567",
  "text": "Sent from a chosen phone.",
  "status": "pending",
  "deviceId": null,
  "sim": null,
  "error": null,
  "requestId": null,
  "createdAt": "2026-11-20T09:15:02.481Z",
  "updatedAt": "2026-11-20T09:15:02.481Z",
  "expiresAt": "2026-11-21T09:15:02.481Z"
}

Get a message#

GET /v1/messages/{id} returns the message with its timeline in events. An id from another workspace is 404 not_found, exactly like an id that doesn't exist.

curl "https://sms.liscosolutions.com/v1/messages/6650f1c2e4b0a1b2c3d4e5f6" \
  -H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
const res = await fetch("https://sms.liscosolutions.com/v1/messages/6650f1c2e4b0a1b2c3d4e5f6", {
  headers: {
    Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  },
});
console.log(res.status, await res.json());
<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/messages/6650f1c2e4b0a1b2c3d4e5f6");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  ],
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);
import requests

res = requests.get(
    "https://sms.liscosolutions.com/v1/messages/6650f1c2e4b0a1b2c3d4e5f6",
    headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
)
print(res.status_code, res.json())
Response · 200
{
  "id": "6650f1c2e4b0a1b2c3d4e5f6",
  "to": "+905321234567",
  "text": "Order #1042 is ready for pickup.",
  "status": "delivered",
  "deviceId": "6650e0a1e4b0a1b2c3d4e500",
  "sim": 2,
  "error": null,
  "requestId": null,
  "createdAt": "2026-11-20T09:15:02.481Z",
  "updatedAt": "2026-11-20T09:15:14.020Z",
  "expiresAt": "2026-11-21T09:15:02.481Z",
  "events": [
    {
      "at": "2026-11-20T09:15:02.481Z",
      "type": "queued",
      "deviceId": null,
      "sim": null,
      "detail": null
    },
    {
      "at": "2026-11-20T09:15:03.902Z",
      "type": "claimed",
      "deviceId": "6650e0a1e4b0a1b2c3d4e500",
      "sim": null,
      "detail": null
    },
    {
      "at": "2026-11-20T09:15:08.377Z",
      "type": "attempt_failed",
      "deviceId": "6650e0a1e4b0a1b2c3d4e500",
      "sim": 1,
      "detail": "no_service"
    },
    {
      "at": "2026-11-20T09:15:10.651Z",
      "type": "sent",
      "deviceId": "6650e0a1e4b0a1b2c3d4e500",
      "sim": 2,
      "detail": null
    },
    {
      "at": "2026-11-20T09:15:14.020Z",
      "type": "delivered",
      "deviceId": "6650e0a1e4b0a1b2c3d4e500",
      "sim": 2,
      "detail": null
    }
  ]
}

Each event has at (time), type, the deviceId and sim involved (if any) and a detail such as an error code:

typeMeaning
queuedAccepted by the API.
claimedA phone took it.
attempt_failedSending failed on one phone; it goes back to the queue for another phone.
requeuedReturned to the queue because the phone holding it went offline, or was unlinked.
sentThe phone sent it.
deliveredThe network confirmed delivery.
failedEvery allowed attempt failed; detail holds the error.
expiredttlSec passed before it was sent.

List messages#

GET /v1/messages returns your workspace's messages, newest first.

Query parameterTypeDescription
statusstringOnly this status: pending, claimed, sent, delivered, failed or expired.
limitinteger1–100, default 20.
cursorstringThe nextCursor of the previous page.
curl "https://sms.liscosolutions.com/v1/messages?status=delivered&limit=2" \
  -H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
const res = await fetch("https://sms.liscosolutions.com/v1/messages?status=delivered&limit=2", {
  headers: {
    Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  },
});
console.log(res.status, await res.json());
<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/messages?status=delivered&limit=2");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  ],
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);
import requests

res = requests.get(
    "https://sms.liscosolutions.com/v1/messages?status=delivered&limit=2",
    headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
)
print(res.status_code, res.json())
Response · 200
{
  "data": [
    {
      "id": "6650f1c2e4b0a1b2c3d4e5f6",
      "to": "+905321234567",
      "text": "Order #1042 is ready for pickup.",
      "status": "delivered",
      "deviceId": "6650e0a1e4b0a1b2c3d4e500",
      "sim": 1,
      "error": null,
      "requestId": null,
      "createdAt": "2026-11-20T09:15:02.481Z",
      "updatedAt": "2026-11-20T09:15:02.481Z",
      "expiresAt": "2026-11-21T09:15:02.481Z"
    },
    {
      "id": "6650f0a8e4b0a1b2c3d4e5e1",
      "to": "+905321234567",
      "text": "Your appointment is confirmed.",
      "status": "delivered",
      "deviceId": "6650e0a1e4b0a1b2c3d4e500",
      "sim": 2,
      "error": null,
      "requestId": null,
      "createdAt": "2026-11-20T09:15:02.481Z",
      "updatedAt": "2026-11-20T09:15:02.481Z",
      "expiresAt": "2026-11-21T09:15:02.481Z"
    }
  ],
  "nextCursor": "6650f0a8e4b0a1b2c3d4e5e1"
}

nextCursor is null on the last page. The list includes every message of the workspace: those you sent through the API, codes from /v1/otp/send, and test messages sent from the dashboard.

The message object#

FieldTypeDescription
idstringThe message id.
tostringRecipient in E.164.
textstringThe text. For OTP messages the code is always shown as •.
statusstringpending, claimed, sent, delivered, failed or expired; see Message statuses.
deviceIdstring or nullThe phone that holds or sent it.
siminteger or nullThe SIM slot it was sent from (1 or 2).
errorstring or nullWhy it failed or expired (e.g. no_service, generic_failure, expired).
requestIdstring or nullYour requestId, if you sent one.
createdAtstringWhen it was queued (ISO 8601, UTC).
updatedAtstringLast change.
expiresAtstringWhen it expires if not sent by then.
PreviousPhone numbersNextMessage statuses