POST/phone_numbers/{phone_number_id}/attempt_verification

Verify a code sent to a phone number

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 for this verification could not be sent (the SMS provider refused or failed the send after prepare_verification had returned), the attempt is rejected with a verification_code_not_sent error and no attempt is counted; call prepare_verification again to send a new code. If too many codes have been checked for this phone number recently, the attempt is rejected with a verification_code_too_many_attempts error and no attempt is counted; the limit is per phone number, so wait for the Retry-After period rather than sending a new code. If the code is correct and the phone number 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 phone number 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
phone_number_idstringrequired
The ID of the phone number 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 phone number

8 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
422Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
429Request was not successful
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 422 is returned: Request was not successful. A 429 is returned: Request was not successful. A 500 is returned: Request was not successful.