Skip to main content
POST
Check a code

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.

Path Parameters

sid
string
required

The verification sid returned by Start a verification.

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

"VE6650c3a1b2c3d4e5f6a7b8c9"

Body

application/json
code
string
required

The code your user entered, 4–8 digits.

Pattern: ^\d{4,8}$
Example:

"482913"

Response

The code was checked. Read valid to see whether it matched.

valid
boolean
required

true when the code matched and the verification is now approved.

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."