SMS OTP integration

Use this guide when you want OTP.ID to deliver an OTP through SMS. Send channel: "sms" to POST /v3/request or POST /v3/send, then verify the user-entered code with POST /v3/verify. SMS is useful when you need broad phone-number reach. It works on basic phones and does not require a messaging app or mobile data.

Flow overview

Create the OTP transaction

Use POST /v3/request for an OTP.ID-generated code, or POST /v3/send for a code generated by your backend.

OTP.ID sends the SMS

OTP.ID delivers the OTP text message to the phone number in destination.

Collect the code

Ask the user to type or paste the code from their SMS inbox.

Verify the code

Call POST /v3/verify with the otp_id and submitted code.

Option A: OTP.ID generates the code

Request

curl -X POST https://api.otp.id/v3/request \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "destination": "6281234567890",
    "brand": "TokoKita",
    "otp_length": 6
  }'

Success response

{
  "success": true,
  "data": {
    "otp_id": "OTP20260811SMSA000001",
    "status": "sent",
    "channel": "sms",
    "number": "6281234567890",
    "price": 175,
    "last_balance": 99825,
    "expires_at": "2026-08-11 10:05:00"
  },
  "error": null
}

The generated OTP code is not returned by the API. OTP.ID sends it only through SMS.

Option B: You provide the code

Request

curl -X POST https://api.otp.id/v3/send \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "destination": "6281234567890",
    "otp": "482913",
    "brand": "TokoKita"
  }'

Success response

{
  "success": true,
  "data": {
    "otp_id": "OTP20260811SMSA000002",
    "status": "sent",
    "channel": "sms",
    "number": "6281234567890",
    "price": 175,
    "last_balance": 99650,
    "expires_at": "2026-08-11 10:05:00"
  },
  "error": null
}

Verify the SMS OTP

Request

curl -X POST https://api.otp.id/v3/verify \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "otp_id": "OTP20260811SMSA000001",
    "otp": "482913"
  }'

Correct code response

{
  "success": true,
  "data": {
    "otp_id": "OTP20260811SMSA000001",
    "verified": true,
    "reason": ""
  },
  "error": null
}

Wrong code response

Wrong codes return HTTP 200. Always check data.verified.

{
  "success": true,
  "data": {
    "otp_id": "OTP20260811SMSA000001",
    "verified": false,
    "reason": "mismatch"
  },
  "error": null
}

Terminal error example

{
  "success": false,
  "data": null,
  "error": {
    "code": "TOO_MANY_ATTEMPTS",
    "message": "Percobaan verifikasi melebihi batas"
  }
}

UI recommendations

Show copy such as “Enter the code we sent by SMS.”
Keep the destination number visible in masked form, for example +62 812••••7890.
Use an OTP input that supports paste and numeric keyboard on mobile.
Show expires_at or a countdown based on your own server time.
Add a Resend SMS action after cooldown.
If SMS delivery fails, let the user retry or switch to WhatsApp when your product supports fallback.

Get Started

Core Concepts

Channel Guides

Guides

Reference

SMS OTP integration

Flow overview

Option A: OTP.ID generates the code

Request

Success response

Option B: You provide the code

Request

Success response

Verify the SMS OTP

Request

Correct code response

Wrong code response

Terminal error example

UI recommendations

​Flow overview

​Option A: OTP.ID generates the code

​Request

​Success response

​Option B: You provide the code

​Request

​Success response

​Verify the SMS OTP

​Request

​Correct code response

​Wrong code response

​Terminal error example

​UI recommendations

​Related pages

Flow overview

Option A: OTP.ID generates the code

Request

Success response

Option B: You provide the code

Request

Success response

Verify the SMS OTP

Request

Correct code response

Wrong code response

Terminal error example

UI recommendations

Related pages