POST /v3/send — Deliver a Client-Supplied OTP Code

Use POST /v3/send when your system generates the OTP code and you want OTP.ID to handle only delivery. This is identical to POST /v3/request in every other respect — same channels, same response shape, same error codes — except you must supply the code in the otp field and the whatsapp_inbound channel is not supported. The code you supply is delivered to the user and is never echoed back in any API response.

Endpoint

POST https://api.otp.id/v3/send

Request Headers

Header	Value	Required
`Authorization`	`Bearer <api_key>`	✅ Yes
`Content-Type`	`application/json`	✅ Yes

Request Body

string

required

The OTP code to deliver. Must contain digits only and be between 4 and 8 characters long. Example: "482913".

string

required

The delivery channel for the OTP. Accepted values: whatsapp, sms, email, misscall.

The whatsapp_inbound channel is not supported by this endpoint. Passing whatsapp_inbound returns 400 INVALID_CHANNEL. Use POST /v3/request for inbound flows.

string

required

The destination phone number or email address.

Phone numbers: digits only, minimum 10 characters (e.g. "6281234567890")
Email: a valid email address (e.g. "user@example.com")

string

The brand name included in the OTP message. Defaults to the brand_name configured on your merchant account.

integer

Ignored when otp is provided — the length is inferred from the otp value you supply. Included for API compatibility; has no effect.

integer

Time-to-live in seconds before the OTP expires. Accepted range: 60–900. Defaults to 300 (5 minutes). Values outside this range are clamped to the nearest bound — not rejected.

string

Your own idempotency key for this transaction. If you resubmit the same external_id, OTP.ID returns the original otp_id without resending the message and without changing your balance.

Response Fields

string

The unique transaction ID assigned by OTP.ID. Use this in POST /v3/verify and GET /v3/otp/{otp_id}.

string

Current delivery status: sent / success when delivered, failed if vendor delivery failed.

string

The channel used to deliver the OTP, echoed from your request.

string

The destination address used, echoed from your request.

integer

Transaction cost in IDR. Present even when delivery fails; no balance deduction occurs on failure.

integer

Your account balance in IDR after this transaction. Unchanged if delivery failed or if this was an idempotency replay.

string

The datetime at which this OTP expires, in YYYY-MM-DD HH:MM:SS format (WIB, UTC+7).

Examples

SMS

curl -X POST https://api.otp.id/v3/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "sms", "number": "6281234567890", "otp": "482913", "brand": "MyApp", "ttl": 180, "external_id": "order-8822"}'

Success response:

{
  "success": true,
  "data": {
    "otp_id": "OTP20260807ABCD000003",
    "status": "sent",
    "channel": "sms",
    "number": "6281234567890",
    "price": 175,
    "last_balance": 99125,
    "expires_at": "2026-08-07 10:02:00"
  },
  "error": null
}

curl -X POST https://api.otp.id/v3/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "whatsapp", "number": "6281234567890", "otp": "739012", "brand": "MyApp", "ttl": 300}'

Success response:

{
  "success": true,
  "data": {
    "otp_id": "OTP20260807ABCD000004",
    "status": "sent",
    "channel": "whatsapp",
    "number": "6281234567890",
    "price": 350,
    "last_balance": 98775,
    "expires_at": "2026-08-07 10:05:00"
  },
  "error": null
}

The OTP code you sent is never returned in the response — you already know it on your side. Store it securely if you need to reference it later (e.g. for audit logs), but never log it in plaintext.

Error Responses

All errors follow the shape {"success": false, "data": null, "error": {"code": "...", "message": "..."}}.

HTTP Status	Error Code	Description
400	`INVALID_CHANNEL`	The `channel` value is invalid or is `whatsapp_inbound` (not supported by this endpoint).
400	`INVALID_NUMBER`	The `number` format is invalid or missing.
400	`VALIDATION_ERROR`	The `otp` field is missing, contains non-digit characters, or its length is outside 4–8; or another field failed validation.
401	`UNAUTHORIZED`	The `Authorization` header is missing or the API key is invalid.
402	`INSUFFICIENT_BALANCE`	Your account balance is too low to cover this transaction.
409	`DUPLICATE_EXTERNAL_ID`	An `external_id` collision with a different request payload was detected. `error.details.existing_otp_id` contains the conflicting transaction ID.
429	`RATE_LIMITED`	You have exceeded the API-level request rate limit.
429	`DESTINATION_RATE_LIMITED`	Too many OTPs have been sent to this destination in a short window.
503	`CHANNEL_UNAVAILABLE`	The requested channel is temporarily unavailable.
500	`INTERNAL_ERROR`	An unexpected server-side error occurred.

Example — otp validation error:

{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The otp field must contain digits only and be between 4 and 8 characters"
  }
}

OTP

Webhooks

POST /v3/send — Deliver a Client-Supplied OTP Code

Endpoint

Request Headers

Request Body

Response Fields

Examples

SMS

WhatsApp

Error Responses

​Endpoint

​Request Headers

​Request Body

​Response Fields

​Examples

​SMS

​WhatsApp

​Error Responses

Endpoint

Request Headers

Request Body

Response Fields

Examples

SMS

WhatsApp

Error Responses