HonkIOHonkIO

SMS

Verify (one-time codes)

Confirm that someone owns a phone number: they receive a one-time code by SMS, and you check the code they enter.

Phone Number Verification (OTP)

Use the Verify API to confirm ownership of a phone number before sending commercial messages. Your end-user receives a one-time code via SMS; submit it to the check endpoint to confirm.

A verification costs the per part message rate plus a verification upcharge; one the carrier refuses is refunded. Codes are 6 digits by default (codeLength 4, 6 or 8; REST code_length) and valid for 10 minutes (ttlMinutes, 1 to 60; REST ttl_minutes). Five wrong codes end it with VERIFICATION_MAX_ATTEMPTS, and an expired one answers VERIFICATION_EXPIRED. With a test key nothing is sent and the code is all zeros.

// Start a verification (sends OTP SMS)
const { data: verification, error } = await honkio.verify.start({
  from: '+1416XXXXXXX',
  to: '+1613XXXXXXX',
  codeLength: 6,
  ttlMinutes: 10,
  appName: 'Acme',
})
if (error) throw new Error(error.message)
// { id: 'clxxx...', status: 'pending', code_length: 6, ... }
console.log(verification.id, verification.status)
// Check the code submitted by your user
const { data, error } = await honkio.verify.check('clxxx...', { code: '483721' })
if (error?.name === 'VERIFICATION_INVALID_CODE') {
  console.log(error.details) // { attempts_remaining: 4 }
} else if (error) {
  throw new Error(error.message)
} else {
  console.log(data.status) // 'verified'
}
// Fetch status at any time
const { data, error } = await honkio.verify.get('clxxx...')
if (error) throw new Error(error.message)
console.log(data.status, data.attempts_remaining)

In test mode the code is always all zeros for the chosen length (e.g. 000000 for 6-digit). No SMS is sent and nothing is billed. Every verification returns a "mode" field of "LIVE" or "TEST" so you can tell a simulated verification from a real one.