Skip to main content
Developer API Reference

REST API Specification & Endpoints Reference.

Complete HTTP endpoint documentation, dual authentication headers, JSON request/response schemas, error codes, and OpenAPI 3.0 specification for NepalOTP.

Explore Full Docs OpenAPI 3.0 Spec
v1.0
API Version
JSON
Payload Format
OpenAPI 3.0
Specification
ENDPOINT // POST /v1/otp/send
200 OK
// Request Header
Authorization: Bearer npot_live_1a2b3c4d...
Content-Type: application/json
// Request Body
{
  "phone": "+9779841234567",
  "reference": "user_signup_abc123"
}
Response Object Latency: <50ms
{
  "success": true,
  "message": "OTP sent successfully",
  "otp_id": "otp_8f9a7b6c5d4e3f2a",
  "data": {
    "expires_at": "2026-01-15T10:35:00+05:45",
    "expires_in_seconds": 300
  }
}
Core Endpoints

HTTP Endpoints & Routes

Base URL: https://nepalotp.com/api/v1

Authentication: X-API-Key: npot_live_... or Authorization: Bearer npot_live_...

POST /v1/otp/send

Send OTP Code

Generates a 6-digit OTP and delivers it via SMS to Nepali phone numbers. In Sandbox mode (`npot_test_`), OTP is fixed to `123456` with zero balance deduction.

Body (JSON):
phone (req, E.164), reference (opt)
POST /v1/otp/verify

Verify OTP Passcode

Verifies the code entered by the user against an `otp_id`. The OTP is automatically invalidated upon successful verification or when max attempts (3) are exceeded.

Body (JSON):
otp_id (req), otp (req, 4-8 digits)
POST /v1/sms/send

Transactional SMS

Dispatches operational notifications (order confirmations, payment receipts, appointment reminders) using pre-approved templates with dynamic `{{variable}}` substitution.

Body (JSON):
phone (req), template_id (req), variables (obj)
WEBHOOK HTTP POST Callback

Webhooks & Signatures

Receives real-time delivery and verification updates (`otp.sent`, `otp.verified`, `sms.sent`, `sms.failed`). Signed with HMAC-SHA256 in `X-Npot-Signature`.

Header: X-Npot-Signature: t={ts},v1={hash}
SANDBOX Test Keys (npot_test_)

Always-Free Sandbox

Test integration with zero balance cost. Test keys (`npot_test_`) log requests without sending real SMS, always returning `123456` code for predictable testing.

Key Prefix: npot_test_ (Sandbox) vs npot_live_ (Live)
THROTTLE Abuse Protection

Rate Limits & Quotas

Platform throttle allows 120 req/min per key and 300 req/min per IP. Per-destination limits defaults: 1 OTP/min, 5 OTPs/hr, 20 OTPs/24hr (all configurable per app).

Header response: 429 Too Many Requests (retry_after)
POST /v1/sms/bulk-send

Bulk / Promotional SMS

Sends one free-text message to up to 500 recipients at once. Content is screened by AI moderation before anything is charged — fair promotional copy sends instantly, anything ambiguous is queued for manual review.

Body (JSON):
message (req), mobiles (req, array)
GET /v1/sms/bulk/{batch_id}

Bulk SMS Batch Status

Looks up a batch's status and carrier delivery breakdown — mainly for batches queued for manual review, since a `202` response has no other synchronous way to learn the outcome.

Returns: status, ntc/ncell/smartcell, invalid_numbers
Response Codes

HTTP Status Codes & Error Reference

Standard HTTP status codes and structured top-level JSON error payload definitions returned by the NepalOTP API.

HTTP Code Error Code (`code`)
200 OK SUCCESS
400 Bad Request INVALID_OTP
400 Bad Request OTP_EXPIRED
400 Bad Request MAX_ATTEMPTS_EXCEEDED
400 Bad Request MISSING_VARIABLES
400 Bad Request CONTENT_REJECTED
202 Accepted SUCCESS (pending_review)
401 Unauthorized INVALID_API_KEY
402 Payment Required INSUFFICIENT_BALANCE
403 Forbidden API_KEY_ENVIRONMENT_MISMATCH
404 Not Found OTP_NOT_FOUND / TEMPLATE_NOT_FOUND
422 Validation Error VALIDATION_ERROR
422 Validation Error TOO_MANY_RECIPIENTS
429 Too Many Requests RATE_LIMIT_EXCEEDED
500 Internal Error INTERNAL_ERROR

Related resources

Start building with NepalOTP.

Create your account, generate your API keys, and test endpoints in sandbox mode for free.

Get API Key Read Documentation