Check Verification Code

Verifies a code entered by the user against a verification code sent via the Send Verification Code node. This node completes the verification process for two-factor authentication, phone number verification, and secure authentication flows.

Common Properties

• Name - The custom name of the node.
• Color - The custom color of the node.
• Delay Before (sec) - Waits in seconds before executing the node.
• Delay After (sec) - Waits in seconds after executing node.
• Continue On Error - Automation will continue regardless of any error. The default value is false.

info

If ContinueOnError property is true, no error is caught when the project is executed even if Catch node is used.

Prerequisites

Before checking a verification code:

1. Send Verification Code - A verification code must have been sent to the phone number using the Send Verification Code node
2. Use Same Verify SID - The Verify Service SID must match the one used to send the code
3. Within Time Limit - The code must not have expired (default: 10 minutes)

warning

This node must be used after sending a verification code with the Send Verification Code node. The phone number and Verify Service SID must match.

Input

• Connection Id - The Twilio connection identifier from the Connect node. This is optional if you provide credentials directly in the Options.
• To Number - The phone number that received the verification code. Must match the number used in Send Verification Code and be in E.164 format (e.g., +14155552672).
• Verification Code - The code entered by the user. This is typically a 4-8 digit numeric code (depending on your Verify Service configuration).

Output

• Response - The Twilio Verify API response containing verification check results including:
  • sid - Unique verification check identifier
  • service_sid - Verify Service SID
  • to - Phone number that was verified
  • channel - Delivery channel that was used (sms or whatsapp)
  • status - Verification check status (approved or pending)
  • valid - Boolean indicating if the code was correct (true or false)
  • date_created - Timestamp when verification was created
  • date_updated - Timestamp when verification was checked

tip

Check the valid field in the Response to determine if the verification was successful. true means the code was correct, false means it was incorrect.

Options

• Verify SID - Your Twilio Verify Service SID. This must be the same Verify Service SID used when sending the verification code. Required for all verification operations.
• Account SID - Your Twilio Account SID. This is optional if you're using a Connection Id from the Connect node.
• Auth Token - Your Twilio Auth Token. This is optional if you're using a Connection Id from the Connect node.

Examples

Example 1: Complete Phone Verification Flow

Full flow for verifying a phone number during registration:

Flow Structure:

1. User enters phone number
2. Send Verification Code
   • To Number: {{registration_phone}}
   • Channel: sms
3. Display code entry form
4. User enters code
5. Check Verification Code
   • To Number: {{registration_phone}}
   • Verification Code: {{user_entered_code}}
6. If Response.valid == true
   • Database Insert - Save user with verified phone
   • Display success message
7. Else
   • Display error - "Invalid code. Please try again."
   • Allow retry (limited attempts)

Response Example (Success):

{
  "sid": "VE1234567890abcdef1234567890abcdef",
  "service_sid": "VA1234567890abcdef1234567890abcdef",
  "to": "+14155552672",
  "channel": "sms",
  "status": "approved",
  "valid": true,
  "date_created": "2024-01-15T10:30:00Z",
  "date_updated": "2024-01-15T10:32:00Z"
}

Response Example (Failed):

{
  "sid": "VE1234567890abcdef1234567890abcdef",
  "service_sid": "VA1234567890abcdef1234567890abcdef",
  "to": "+14155552672",
  "channel": "sms",
  "status": "pending",
  "valid": false,
  "date_created": "2024-01-15T10:30:00Z",
  "date_updated": "2024-01-15T10:32:15Z"
}

Example 2: Two-Factor Authentication (2FA)

Verify user identity during login:

Flow Structure:

1. User logs in with username/password
2. If credentials valid
   • Send Verification Code to user's phone
   • Display 2FA code entry screen
3. User enters 2FA code
4. Check Verification Code
5. JavaScript - Extract validation result

   msg.verified = item.response.valid;

6. If verified
   • Create session
   • Redirect to dashboard
7. Else
   • Increment failed attempts
   • If attempts < 3 - Allow retry
   • Else - Lock account, send alert

Example 3: Password Reset with Verification

Verify user identity before allowing password reset:

Flow Structure:

1. User requests password reset
2. Database Query - Find user by email
3. Send Verification Code to user's phone
4. User enters verification code
5. Check Verification Code
6. If Response.valid == true
   • Generate password reset token
   • Store token in database
   • Display password change form
7. Else
   • Display error message
   • Log failed attempt
   • Email user about reset attempt

Example 4: Transaction Verification

Verify high-value transactions:

Flow Structure:

1. User initiates wire transfer
2. If amount > $10,000
   • Send Verification Code
   • Display confirmation screen
     • "Enter code sent to {{masked_phone}} to confirm transfer of ${{amount}}"
3. User enters code
4. Check Verification Code
5. If Response.valid == true
   • Process transaction
   • Log successful verification
   • Send confirmation email
6. Else
   • Cancel transaction
   • Alert security team
   • Log suspicious activity

Example 5: Multi-Attempt Verification with Retry Limit

Implement retry logic with attempt tracking:

Flow Structure:

Initialize: attempts = 0, max_attempts = 3

Loop:
1. User enters code
2. Increment attempts
3. Check Verification Code
4. If Response.valid == true
   - Exit loop, proceed with registration
5. Else
   - If attempts < max_attempts
     - Display: "Invalid code. {{max_attempts - attempts}} attempts remaining."
     - Continue loop
   - Else
     - Display: "Maximum attempts exceeded. Please request a new code."
     - Offer option to resend code
     - Reset attempts counter

Implementation:

// Before check
msg.attempts = (msg.attempts || 0) + 1;

// After check
if (item.response.valid) {
    msg.verified = true;
} else if (msg.attempts >= 3) {
    msg.max_attempts_exceeded = true;
} else {
    msg.retry_message = `Invalid code. ${3 - msg.attempts} attempts remaining.`;
}

Example 6: Account Recovery Verification

Verify account ownership during recovery:

Flow Structure:

1. User claims account ownership
   • Enters email/username
2. Database Query - Get account info
3. Send Verification Code to registered phone
4. Display verification form
   • "Code sent to phone ending in {{last_4_digits}}"
   • Security question
5. User enters code + answers security question
6. Check Verification Code
7. If Response.valid == true AND security answer correct
   • Grant account access
   • Force password change
   • Send email notification
8. Else
   • Increment failed recovery attempts
   • If failed_attempts > 5 - Temporarily lock account
   • Notify user via email

Tips

• Phone Number Matching - The To Number must exactly match the number used in Send Verification Code (including country code and format).
• Check 'valid' Field - Use {{response.valid}} to determine if verification was successful. Don't rely on status alone.
• Code Format - Codes are typically numeric (e.g., 123456). Ensure user input is validated before checking.
• Timing - Check codes immediately after user submits. Don't batch verifications or delay unnecessarily.
• Max Attempts - Twilio Verify limits verification attempts (default: 5). After max attempts, user must request a new code.
• Code Expiration - Codes expire after 10 minutes by default (configurable in Verify Service settings).
• Error Handling - Always handle both successful and failed verifications gracefully.
• User Feedback - Provide clear feedback: "Code verified successfully" or "Invalid code. Please try again."
• Rate Limiting - Implement client-side rate limiting to prevent rapid-fire verification attempts.
• Security Logging - Log failed verification attempts for security monitoring.
• Retry Logic - Allow limited retries (e.g., 3 attempts) before requiring a new code.
• One-Time Use - Once a code is successfully verified, it cannot be used again. Each verification requires a new code.

Common Errors

Empty To Number

Error: "ErrInvalidArg: To Number cannot be empty"

Solution:

• Ensure the To Number field is populated
• Verify the variable contains the phone number
• Check that the number matches the one used in Send Verification Code

Empty Verification Code

Error: "ErrInvalidArg: Verification Code cannot be empty"

Solution:

• Ensure the Verification Code field is populated
• Check that user has entered a code
• Verify the variable name matches the form input
• Validate user input before checking

Invalid Verification Code

Error: Code verification returns valid: false

Solution:

• User entered the wrong code
• Allow user to retry (with limited attempts)
• Check for typos in user input
• Ensure code hasn't expired (default: 10 minutes)
• Verify the code is for the correct phone number
• Consider offering "Resend Code" option

Max Check Attempts Exceeded

Error: "Max check attempts reached"

Solution:

• User has entered incorrect codes too many times (default: 5 attempts)
• User must request a new verification code
• Send new code using Send Verification Code node
• Implement retry limit in your UI to prevent this

Verification Not Found

Error: "Verification not found" or "No pending verifications found for this number"

Solution:

• No verification code was sent to this number
• Verification has expired (default: 10 minutes)
• Phone number doesn't match the one used in Send Verification Code
• User must request a new code
• Ensure To Number format matches exactly (including country code)

Invalid Verify SID

Error: "ErrInvalidArg: No SID Value"

Solution:

• Ensure Verify SID is configured in Options
• Verify the Verify SID is stored correctly in Vault
• Check that the SID starts with "VA" (Verify Service SID)
• Ensure you're using the same Verify SID as in Send Verification Code

Phone Number Mismatch

Error: Verification fails even with correct code

Solution:

• Ensure To Number exactly matches the number used in Send Verification Code
• Check phone number format (must be E.164: +14155552672)
• Verify no extra spaces or characters in the number
• Ensure country code is included and correct

Verification Already Approved

Error: Verification already approved or consumed

Solution:

• This code has already been successfully verified
• Codes are one-time use only
• User must request a new code for another verification
• Don't attempt to verify the same code twice

Service Not Found

Error: "The requested resource was not found"

Solution:

• Verify the Verify SID is correct
• Ensure the Verify Service exists in your Twilio account
• Check you're using the Verify Service SID (starts with "VA")
• Verify your Account SID and Auth Token are correct

Related Nodes

• Send Verification Code - Send the verification code that will be checked by this node
• Connect - Create a Twilio connection for authentication
• Send SMS - Send regular SMS messages
• Send WhatsApp Message - Send WhatsApp messages