Skip to main content
POST
Generate and send an OTP
Workspace otp_delivery_mode is sms | whatsapp | both | either (default sms). Optional request channel is sms | whatsapp. There is no silent WhatsApp→SMS fallback. A failed WhatsApp leg is refunded and reported failed. Mode both sends both legs and refuses an explicit channel. Mode either omits to SMS.

Authorizations

Authorization
string
header
required

Your Robase API key. Starts with robe_. Include as Authorization: Bearer robe_...

Headers

Idempotency-Key
string

Opaque client-generated key. Replaying the same key within 24 hours returns the original response (with Idempotent-Replayed: true) instead of performing the action again. Recommended for every send so a network-level retry cannot double-charge. The same key with a different endpoint or body returns 422 idempotency_key_reused; a repeat while the first request is still running returns 409 request_in_progress. 5xx and 429 responses are not kept, so a retry with the same key runs again.

Maximum string length: 255

Body

application/json
phone_number
string
required

Phone number in E.164 format

Example:

"+2348012345678"

code_length
integer
default:6

Number of digits in the generated code. Omit to use the default — sending 0 is not the same as omitting the field. Anything outside 4–8 is refused with validation_error.

Required range: 4 <= x <= 8
ttl_seconds
integer
default:600

How long the code stays verifiable, in seconds. Omit to use the default.

Required range: 1 <= x <= 3600
language
enum<string>

Language for the OTP message body. Omit to use the workspace's default language (Settings → General → Language & region). Supply it per request when your own end users are not all in the same language.

Accept-Language deliberately does not affect the message body — it describes the integrator reading our error responses, not the person receiving the SMS.

Available options:
en,
fr
Example:

"fr"

channel
enum<string>

Delivery channel for this send. Honoured only when the workspace otp_delivery_mode allows it:

  • sms mode: only sms (or omit); whatsapp → channel_not_allowed
  • whatsapp mode: only whatsapp (or omit); sms → channel_not_allowed
  • both mode: omit only; any explicit value → channel_not_allowed
  • either mode: sms or whatsapp; omit means SMS

WhatsApp is OTP-only (Meta Authentication + copy-code). A failed WhatsApp leg is never silently re-sent as SMS.

Available options:
sms,
whatsapp
Example:

"whatsapp"

metadata
object

Arbitrary key-value data stored with the OTP and returned by GET /v1/otp/{id}

Response

OTP created, charged, and queued for delivery

id
string<uuid>
required

OTP ID to use with the verify and get endpoints

phone_number
string
required

Destination the code was sent to, in E.164 format

Example:

"+2348012345678"

country_code
string
required

ISO 3166-1 alpha-2 country code derived from the number

Example:

"NG"

credit_cost
integer
required

Credits consumed by this send

Example:

1

status
enum<string>
required

Always pending — delivery happens asynchronously

Available options:
pending
code_length
integer
required

Number of digits in the generated code

Example:

6

expires_at
string<date-time>
required

After this instant the code can no longer be verified

created_at
string<date-time>
required
channel
enum<string>

Channel(s) this OTP was queued on. both means SMS and WhatsApp legs were charged together.

Available options:
sms,
whatsapp,
both