Clerk API (unofficial showcase)
POST/email_addresses/{email_address_id}/attempt_verification

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.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 2 body fields
email_address_idstringrequired
The ID of the email address whose code is being verified
verification_idstringrequired
The ID of the verification to check, such as one returned by prepare_verification
codestringrequired
The verification code that was sent to the email address

6 status codes
200The verification. After prepare_verification it is pending (unverified); after attempt_verification its status reflects the attempt outcome.
objectstringoptional
The type of the verification object.
idstringoptional
The ID of the verification. Pass this to attempt_verification.
statusstringoptional
The status of the verification (unverified, verified, expired, or failed).
strategystringoptional
The verification strategy (email_code or phone_code).
attemptsintegeroptional
The number of attempts made against this verification.
expire_atintegeroptional
Unix timestamp (milliseconds) at which the code expires.
channelstringoptional
The channel the code was sent over (phone numbers only).
400Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
401Authentication invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
403Authorization invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
404Resource not found
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
500Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned: Request was not successful. A 401 is returned: Authentication invalid. A 403 is returned: Authorization invalid. A 404 is returned: Resource not found. A 500 is returned: Request was not successful.