One SMS API.
Multiple use cases.

Send a notification

Use a key with sms:send for alerts, customer updates, application-triggered reminders, and other messages. Ask the operator to enable this permission when issuing your key.

export TO1SMS_URL="https://your-gateway-domain"
# Set TO1SMS_API_KEY in your server's secret manager.
curl "$TO1SMS_URL/v1/sms" \
  -H "Authorization: Bearer $TO1SMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+919876543210","text":"Your order is ready for pickup."}'

The response returns message_id and status: queued. Poll GET /v1/messages/{message_id} with messages:read to inspect status. Your application controls event triggers and scheduling; this release has no built-in reminder scheduler.

OTP: send the code

export TO1SMS_URL="https://your-gateway-domain"
# Set TO1SMS_API_KEY in your server's secret manager.
curl "$TO1SMS_URL/v1/otp/send" \
  -H "Authorization: Bearer $TO1SMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+919876543210","purpose":"login"}'

A successful request returns request_id, expires_at, resend_after, and a masked phone number. It confirms queuing, not carrier delivery. Default codes have six digits and expire in five minutes. Phone numbers use international format.

OTP: verify the code

curl "$TO1SMS_URL/v1/otp/verify" \
  -H "Authorization: Bearer $TO1SMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"otp_REPLACE_ME","code":"USER_CODE"}'

A successful response contains valid: true, the verified phone, and purpose. Create a login session in your own backend only after a successful verification. Codes are single-use, with up to five incorrect attempts.

Inspect daily usage

curl "$TO1SMS_URL/v1/usage" \
  -H "Authorization: Bearer $TO1SMS_API_KEY"

Counts cover messages created today in UTC, grouped by current status. These are message records, not carrier segments or billable units.

API permissions

Default new keys include otp:send, otp:verify, messages:read, and usage:read. Raw SMS requires an explicitly issued sms:send scope.

POST /v1/otp/send       otp:send
POST /v1/otp/verify     otp:verify
POST /v1/sms            sms:send
GET  /v1/messages/{id}  messages:read
GET  /v1/usage          usage:read

Raw SMS accepts {"phone":"+91…","text":"…"} and returns a message_id for status polling. Status responses exclude message text to protect verification codes.

Handle failures

400: invalid input, expired code, incorrect code, or exhausted verification attempts. 401: invalid or revoked key. 403: missing scope. 429: rate limit exceeded. 5xx: service problem. Error bodies are plain text; inspect the HTTP status before parsing JSON.

Sending currently limits each project and recipient to ten OTP requests per hour. Apply abuse controls and resend timers in your application as well. Automatic send retries can queue duplicates: idempotency is not guaranteed by this release.

Queue a recipient list

Keys with sms:send can submit up to 1,000 recipients per batch. Numbers are validated together and duplicate recipients are removed. Reuse the same idempotency key when retrying the same batch submission.

POST /v1/sms/batches
Authorization: Bearer YOUR_PROJECT_KEY
Content-Type: application/json

{
  "name": "Customer update",
  "phones": ["+919876543210", "+919876543211"],
  "text": "Your message",
  "idempotency_key": "a-unique-request-id"
}

The response returns batch_id. Read progress with GET /v1/sms/batches/{batch_id} using messages:read. Use PATCH on the same URL with {"action":"pause"}, resume, or cancel using sms:send. A cancelled batch cannot be resumed. Already dispatched messages cannot be recalled.

OTPs have priority over list messages and expire out of the queue. A project can have at most 10,000 queued or dispatched messages by default. Phones must be connected and have an operator-configured segment budget. Missing acknowledgments become unknown; they are not automatically retried. These protections reduce duplicate risks but do not provide exactly-once carrier delivery.

Deployment status

This is an operator-managed pilot. Customer signup, billing, provider delivery, customer billing quotas, and a finished Android enrollment UI are not included. The operator provisions projects and keys through the console or admin API. Complete phone delivery tests and an operations review before launching paid traffic.