Verify a code sent to a phone number
Changed onChecks 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.
Request
- Base URL: https://api.clerk.com/v1
- URL: https://api.clerk.com/v1/phone_numbers/{phone_number_id}/attempt_verification
- Auth: HTTP bearer
Path parameters
The ID of the phone number whose code is being verified
Request body
Response
The verification. After prepare_verification it is pending (unverified); after attempt_verification its status reflects the attempt outcome.
Changes
- info
added the non-success response with the status
- info
added the non-success response with the status
- info
- info
endpoint added
- info