Send and verify a requested OTP

Create a code

Use POST /otp with the recipient, an approved authentication template and its exact language. Codes contain six digits. expires_in accepts 60–600 seconds and defaults to 300. Save the returned OTP id and expires_at; a successful API response queues delivery rather than guaranteeing receipt.

Send an OTP only after the person requests it. STOP does not block their requested authentication code, but it still blocks marketing and utility messages. In test mode, use the built-in buddy_test_otp template with language en. Test responses include test_code; live responses never expose the code.

Verify and recover

Use POST /otp/verify with the OTP id and six-digit code. otp_invalid means the code is incorrect or the challenge is unavailable; otp_expired means the person must request a new code. After five incorrect attempts, otp_attempts_exceeded also requires a new code. Successful verification consumes the challenge.

Limit resends

Wait 60 seconds between requests to the same number. The limit is five codes per hour to the same number, within each workspace and mode. Respect otp_rate_limited and Retry-After. Reuse the original idempotency key only to retry an uncertain request; use a new key for a deliberate new code. Keep your own request limits and abuse checks in front of this flow.