Integrate business messaging with a focused SMS API.

Use the InstSMS API to send individual messages, deliver the same message to multiple recipients, and review account availability from your server application.

Create an account

JSON request bodies

Copy-ready cURL examples

Idempotent send requests

terminal

curl -X POST "https://api.inst.lk/sms/send-sms" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345" \
  -d '{
    "user_id": "YOUR_USER_ID",
    "api_key": "YOUR_API_KEY",
    "sender_id": "INSTSMSDEMO",
    "contact": "947XXXXXXXX",
    "message": "Your message text"
  }'

Request accepted for processing

REST endpoints

Simple JSON requests

Protected requests

Private credentials

Safe retries

Idempotency support

Practical guide

Copy-ready examples

Overview

Start with the API base URL

All documented endpoints use JSON requests and are sent to the current InstSMS API base URL.

API base URL

https://api.inst.lk/sms

Authentication

Authenticate each request

API requests require the account User ID and private API key in the JSON request body.

User ID

YOUR_USER_ID

The account identifier available inside your InstSMS account.

API key

YOUR_API_KEY

A private credential that must remain inside your backend environment.

Keep credentials private

Do not include API credentials in public JavaScript, mobile application source code, repositories, or shared screenshots.

Official Node.js SDK

Build with InstSMS using a modern Node.js client

Install the official InstSMS package for a typed, server-side integration with convenient methods for individual messages, bulk messaging, account status, and consistent error handling.

@insttechnologies/sms

Available from npm with ES modules, CommonJS, and TypeScript declarations. Use it only in trusted backend applications where credentials remain private.

View package on npm

Install the SDK

Terminal

npm install @insttechnologies/sms

Environment variables

.env

INSTSMS_USER_ID=usr_xxxxxx
INSTSMS_API_KEY=your_private_api_key

Send one SMS

Node.js

import { InstSMS } from "@insttechnologies/sms";

const instsms = new InstSMS({
  userId: process.env.INSTSMS_USER_ID,
  apiKey: process.env.INSTSMS_API_KEY,
});

const response = await instsms.messages.send({
  senderId: "INSTSMSDEMO",
  recipient: "0771234567",
  message: "Your order is ready.",
});

console.log(response.data);

Send bulk SMS

Node.js

const response = await instsms.messages.sendBulk({
  senderId: "INSTSMSDEMO",
  recipients: ["0771234567", "+94771234568"],
  message: "A service update from your business.",
});

console.log(response.data);

Review account status

Node.js

const response = await instsms.account.getStatus();

console.log(response.data.sms_credit_balance);
console.log(response.data.sender_id_balances);

Handle API errors

Node.js

import { InstSMSError } from "@insttechnologies/sms";

try {
  await instsms.messages.send({
    senderId: "INSTSMSDEMO",
    recipient: "0771234567",
    message: "Your order is ready.",
  });
} catch (error) {
  if (error instanceof InstSMSError) {
    console.error(error.code, error.status, error.message);
  }
}

Use the SDK on your server

Keep the API key in environment variables or a managed secrets service. Never import the SDK into browser code or expose credentials through a public application.

POST/send-sms

Send one SMS

Send one message to one recipient using an active sender ID.

Idempotency-Key header required

Use a unique value for every new message request. Reuse the same value only when safely retrying the exact same request.

Request body

Send these fields as JSON.

Field	Type	Required	Description
`user_id`	string	Required	Your InstSMS User ID.
`api_key`	string	Required	Your private API key.
`sender_id`	string	Required	An active sender ID available for your account. For testing, use INSTSMSDEMO exactly as shown. Sender IDs are case-sensitive.
`contact`	string	Required	Recipient number using +94XXXXXXXXX, 0XXXXXXXXX, or 94XXXXXXXXX.
`message`	string	Required	The message content.

cURL example

bash

curl -X POST "https://api.inst.lk/sms/send-sms" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345" \
  -d '{
    "user_id": "YOUR_USER_ID",
    "api_key": "YOUR_API_KEY",
    "sender_id": "INSTSMSDEMO",
    "contact": "947XXXXXXXX",
    "message": "Your message text"
  }'

POST/send-bulk-sms

Send one message to multiple recipients

Send the same message to multiple recipients in one request. Duplicate numbers are processed once.

Idempotency-Key header required

Use one unique value for the complete bulk request, not one per recipient. Reuse it only when retrying that exact request.

Request body

Send these fields as JSON.

Field	Type	Required	Description
`user_id`	string	Required	Your InstSMS User ID.
`api_key`	string	Required	Your private API key.
`sender_id`	string	Required	An active sender ID available for your account. For testing, use INSTSMSDEMO exactly as shown. Sender IDs are case-sensitive.
`contacts`	string[]	Required	An array containing recipient phone numbers.
`message`	string	Required	The message content.

cURL example

bash

curl -X POST "https://api.inst.lk/sms/send-bulk-sms" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: campaign-12345" \
  -d '{
    "user_id": "YOUR_USER_ID",
    "api_key": "YOUR_API_KEY",
    "sender_id": "INSTSMSDEMO",
    "contacts": [
      "947XXXXXXXX",
      "947YYYYYYYY"
    ],
    "message": "Your message text"
  }'

POST/account-status

Review account status

Review account availability, credit information, and active sender allocations before sending.

Request body

Send these fields as JSON.

Field	Type	Required	Description
`user_id`	string	Required	Your InstSMS User ID.
`api_key`	string	Required	Your private API key.

cURL example

bash

curl -X POST "https://api.inst.lk/sms/account-status" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "YOUR_USER_ID",
    "api_key": "YOUR_API_KEY"
  }'

Responses

Understand API responses

A successful send request is accepted for processing before final network delivery is completed.

Accepted request

202 Accepted

{
  "success": true,
  "message": "Request accepted for processing",
  "data": {
    "request_id": "REQUEST_REFERENCE"
  }
}

Error response

Error

{
  "success": false,
  "message": "Unable to process the request",
  "code": "ERROR_CODE"
}

Accepted does not mean delivered

HTTP 202 means the request was accepted for processing. Final delivery information becomes available after the mobile network processes the message.

202

Accepted

The request was accepted and queued for message processing.

400

Bad request

One or more required values are missing or incorrectly formatted.

401

Unauthorized

The supplied API credentials could not be authenticated.

403

Forbidden

The account or selected sender ID cannot perform this operation.

409

Duplicate request

The supplied idempotency key was already used for another request.

429

Too many requests

The request limit was reached. Wait before sending another request.

500

Server error

An unexpected problem occurred while processing the request.

Troubleshooting

Common integration problems

Review these checks before repeating a request or contacting support.

Invalid credentials

Confirm that the User ID and API key are correct and belong to the same active account.

Sender ID unavailable

Use an active sender ID that is available for the required message type.

Repeated request

Use a new idempotency key for every new send. Reuse one only when retrying the same request.

Insufficient balance

Review the account balance and the available allocation for the selected sender ID.

Security

Protect your integration

Treat messaging credentials as sensitive business secrets and keep requests inside trusted systems.

Send requests from your server

Keep messaging requests inside a trusted backend environment rather than browser code.

Keep credentials private

Never publish credentials in repositories, public logs, screenshots, or client-side applications.

Replace exposed credentials

Replace an API key immediately if you believe it has been copied, shared, or exposed.

Use idempotency protection

Attach one unique idempotency key to each request. For bulk sends, that single key protects the complete recipient list.

Start integrating

Build your first InstSMS integration

Create your account, prepare an approved sender ID, and begin sending messages from your server application.

Create an account