Documentation
Overview
kiwiSMS REST API for SMS OTP numbers. Rent a temporary line, keep a long-term number, and receive codes in the dashboard or over HTTP.
Start here
https://kiwisms.com.What you can do
Temporary numbers
Short OTP sessions. Rent, poll for a code, cancel while waiting, or reuse the same number when the kind allows it.
Read the guide →
Long-term numbers
Keep the same number for days. Wake sleeping L.1 lines, list messages, auto-renew, or refund within 30 minutes if no code arrived.
Read the guide →
Service types
Every catalog row has a kind. Behavior differs — read this before you rent. Prefer the short code field when calling the API (for example s1-5 or l2-3).
Phone day
Premium temporary number. Free reuse within 20 minutes; paid renew while the phone day is active; after the phone day, submit a renew request.
5–20 minutes
Active 5–20 minutes. Receive codes continuously during the window. Paid renew after expiry if the number is still available.
15 minutes
15-minute window. Free Awake after each code while active. Paid renew until 30 minutes from start; after that, rent a new number. Supports reusing a phone you already hold.
Service TTL
US Non-VoIP. Active for the service TTL. Receive codes continuously. Paid renew after expiry if the number is still available.
15 minutes
15-minute window. Window ends on each code; Awake restarts the timer. Paid renew after expiry if the number is still available.
10–20 minutes
Active 10–20 minutes. Free Awake after each code while the window is still running. Cancel if no code arrives.
Plan period
Wake/sleep long-term line. POST .../wake before you expect a code. Optional US area code and bulk quantity.
Plan period
Service long-term rental. Number stays active for the full period; codes arrive continuously.
Multi-day plan
Multi-day long-term rental. Number stays active for the full period; codes arrive continuously.
How billing works
Wallet first
Successful rents debit your kiwiSMS balance. If the wallet cannot cover the price, the API returns
402 INSUFFICIENT_BALANCE.Safe retries
Send
Idempotency-Keyon rent and renew. The same key and body within 24 hours returns the original result instead of charging twice.Refunds when nothing arrived
Temporary: cancel while
WAITING. Long-term: cancel within 30 minutes if no code has arrived.