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 endpoint supports message-based outbound channels only: whatsapp, sms, and email. 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.

The misscall and whatsapp_inbound channels are not supported by this endpoint. Passing either value returns 400 INVALID_CHANNEL. Use POST /v3/request for Missed Call and WhatsApp 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

Legacy alias for destination. It is still accepted for backward compatibility, but new integrations and all examples should use destination. If both destination and number are provided, destination takes precedence.

string

Legacy fallback for Email OTP. It is used only when both destination and number are empty.

string

The brand name included in channels that deliver a 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 within 24 hours with identical parameters (same channel, resolved destination, and otp), OTP.ID returns the original otp_id without resending the message and without deducting additional credits. A resubmission with different parameters returns 409 DUPLICATE_EXTERNAL_ID.

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. This response field is still named number for backward compatibility, even when your request uses destination.

integer

The number of credits charged for this transaction. Present even when delivery fails; no credits are deducted on failure.

integer

Your remaining credits 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", "destination": "6281234567890", "otp": "482913", "brand": "MyApp"}'

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", "destination": "6281234567890", "otp": "739012", "brand": "MyApp"}'

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 `misscall` / `whatsapp_inbound` (not supported by this endpoint).
400	`INVALID_NUMBER`	The `destination` 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.
403	`IP_NOT_ALLOWED`	The request IP is not in the merchant’s API V3 IP whitelist.
402	`INSUFFICIENT_BALANCE`	You do not have enough credits 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": "Payload tidak valid"
  }
}

Account & Billing

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