v13

latestOpenAPI 3.0.3MITraw.githubusercontent.com2026-08-04237161688.6 KB
Email Addresses

Verify a code sent to an email address

Checks a one-time code against the verification identified by verification_id, and returns the verification with its updated status (verified, unverified, expired, or failed) and attempt count, so a backend driving its own frontend can react on every attempt — an incorrect or expired code is reported through the status, not as an error. Resubmitting a verification whose code was already accepted is rejected with a verification_already_verified error. If the code is correct and the email address is not already verified, it is also marked as verified as a side effect (just as it would be in a frontend verification flow); an already verified email address is left unchanged. It never creates a session; to sign the user in afterwards, mint a sign-in token.

post/email_addresses/{email_address_id}/attempt_verification

Path parameters

email_address_idstring required

The ID of the email address whose code is being verified

Request body

verification_idstring required

The ID of the verification to check, such as one returned by prepare_verification

codestring required

The verification code that was sent to the email address

Response

The verification. After prepare_verification it is pending (unverified); after attempt_verification its status reflects the attempt outcome.

objectstring

The type of the verification object.

idstring

The ID of the verification. Pass this to attempt_verification.

statusstring

The status of the verification (unverified, verified, expired, or failed).

strategystring

The verification strategy (email_code or phone_code).

attemptsinteger nullable

The number of attempts made against this verification.

expire_atinteger nullable

Unix timestamp (milliseconds) at which the code expires.

channelstring nullable

The channel the code was sent over (phone numbers only).