Skip to content
Bullet SMS
OTP API

Verification codes, sent the moment you ask

Your system makes the code. Bullet SMS sends it straight away under your business name, checks that it went through, and re-routes it once if it's stuck.

Get an API tokenSee the request
How it works

What happens to a code

A verification code is only useful in the next minute or two, so it gets its own path, separate from campaigns.

  1. 1

    Code requested

    Your system calls /otp/send with the number and the code it generated.

  2. 2

    Sent immediately

    Codes skip the campaign queue, so they never wait behind a bulk send.

  3. 3

    Checked, re-routed if stuck

    If the first route hasn't delivered it, the same code goes out once more through another.

  4. 4

    Delivered, and you're told

    The status shows in your OTP log, and an otp.delivered webhook reaches your server.

Your name, an approved format

Codes that look like they came from you

Pick a format once in your OTP settings. Every code then goes out in that wording, under your business name.

  • Your company name, or another name you request and an admin approves
  • Names up to 30 characters, so a code stays a single SMS
  • The request carries only the number, the code and the expiry
  • So a leaked token can't be used to send anything else
  • Format 1

    482913 is your Himal Store verification code.

  • Format 2 Selected

    Your Himal Store verification code is 482913. Valid for 5 minutes. Do not share this code with anyone.

  • Format 3

    Himal Store: use 482913 to sign in. It expires in 5 minutes.

Examples only. The formats you can choose from are listed in your OTP settings.

The request

One call per code

Send the number and the code your system generated. The response gives the code's ID, its status and what it cost.

POST /otp/send
POST /otp/send
curl -X POST https://api.bulletsms.com/api/v1/otp/send \
  -H "Authorization: Bearer $BULLETSMS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "9801234567", "code": "482913", "expiryMinutes": 5 }'

Response · 200

{
  "success": true,
  "data": {
    "id": "cm2otp9x0002…",
    "to": "9801234567",
    "status": "SENT",
    "credits": 1,
    "expiryMinutes": 5,
    "resent": false,
    "balanceRemaining": 4998
  }
}

Request fields

  • tostringRequired

    One Nepal mobile number.

  • codestringRequired

    4 to 8 digits, generated and checked by your own system.

  • expiryMinutesnumberOptional

    How long the code is valid, 1 to 30 minutes. Defaults to 5.

Check a code's status any time with GET /otp/:id, or add a webhook URL to your token to receive otp.delivered and otp.failed.

Features

Built for codes, not campaigns

  • Sent at once

    Codes skip the campaign queue, so they never wait behind a bulk send.

  • Re-routed if stuck

    If the first route hasn't delivered a code, it goes out once more through another.

  • Charged once

    A code costs its segments once, even if it's re-routed, and nothing if it couldn't be sent.

  • OTP log

    Every code's status in one place in your dashboard, with totals.

  • Webhooks

    otp.delivered and otp.failed reach your server as they happen.

  • Your codes, your expiry

    4 to 8 digits, valid for 1 to 30 minutes, generated and checked by your own system.

FAQ

OTP questions

Your system does. You send us the code you generated, we send it and record its status, and when the user types it in, your system checks it.

You choose from approved formats in your OTP settings. The wording can't be set per request, which stops a leaked token from being used to send anything else.

Your company name, or a different name of up to 30 characters that you request from your OTP settings and an admin approves. The limit keeps a code to a single SMS.

Each code is checked after it's sent. If the first route hasn't delivered it, the same code goes out once more through another route. If it still can't be delivered, its status says so and an otp.failed webhook is sent.

By segment, like any SMS, and a code is normally one segment. You're charged once even if it's re-routed, and not at all if it couldn't be sent.

See all questions

Send your first verification code

Create an account and verify your number. Once it's approved and topped up, choose your format and send.

Get an API tokenRead the OTP reference