Skip to main content
POST
Start a verification

Authorizations

Authorization
string
header
required

Your project API key, sent as Authorization: Bearer otp_live_.... Create keys on the API Keys page of the dashboard.

Body

application/json
to
string
required

Destination phone number in international format. OTPBay normalizes it to E.164, so +1 (415) 555-2671 becomes +14155552671.

Example:

"+14155552671"

metadata
object

Your own key-value data, returned in responses and webhooks. At most 32 keys of 1–64 characters. Values are strings (up to 512 characters), numbers or booleans.

Example:
callback
string<uri>

Public http or https URL that receives status webhooks. Localhost, private and link-local addresses are rejected. Defaults to the channel's default callback from project settings.

Maximum string length: 2048
Example:

"https://example.com/webhooks/otpbay"

Response

The verification was created and the first code was sent.

sid
string
required

Unique verification ID.

Pattern: ^VE[a-f0-9]{24}$
Example:

"VE6650c3a1b2c3d4e5f6a7b8c9"

status
enum<string>
required

pending until the user enters the right code (approved), the code expires (expired), or the code can't be sent or too many wrong codes are entered (failed).

Available options:
pending,
approved,
expired,
failed
to
string
required

Destination phone number in international format. OTPBay normalizes it to E.164, so +1 (415) 555-2671 becomes +14155552671.

Example:

"+14155552671"

channel
enum<string>
required

Channel the code was last sent on.

Available options:
telegram,
sms
fallback_reason
enum<string> | null
required

Why the code was re-sent by SMS, or null if it wasn't.

Available options:
telegram_failed,
timeout,
null
attempts
object[]
required

Every send of the code, oldest first.

checks_left
integer
required

Wrong codes the user can still enter before the verification fails.

Example:

5

fee
string
required

Amount in US dollars as a decimal string.

Pattern: ^\d+\.\d{2}$
Example:

"0.02"

cost
string
required

Verify fee plus what the channel sends currently cost. Refunded sends count as 0.00.

Pattern: ^\d+\.\d{2}$
Example:

"0.04"

date_created
string<date-time>
required
expires_at
string<date-time>
required

When the code stops being accepted.

approved_at
string<date-time> | null
required

When the right code was entered.

metadata
object
required

Your own key-value data, returned in responses and webhooks. At most 32 keys of 1–64 characters. Values are strings (up to 512 characters), numbers or booleans.

Example:
last_error
string

Why the verification failed. Only present when status is failed.

Example:

"Too many wrong codes."