Platform Testing & Validationg

Pre-Flight Checklist

Before going live, verify each integration point:

Test Scenarios

Scenario 1: First-Time Verification (User Profile Matching)

Setup:

Employee record with clear_user_id = NULL
First name: "John"
Last name: "Doe"
Employee ID: "123456"

Steps:

Navigate to /{company}/verify
Enter employee ID: "123456"
Click "Verify with CLEAR"
Complete CLEAR verification with selfie + ID
Redirected to confirmation page

Expected Results:

✅ Session created with initial_project_id
✅ user_profile_information sent with first_name and last_name
✅ CLEAR matches biometric to provided name
✅ Status changes from pending → complete
✅ user_id returned from CLEAR (e.g., user_abc123)
✅ clear_user_id saved to employee record in database
✅ Confirmation page shows "Thank you, John!"

How to Verify:

-- Check employee record
SELECT employee_id, clear_user_id FROM employees WHERE employee_id = '123456';
-- Should show: clear_user_id = 'user_abc123' (not NULL)

-- Check session record
SELECT status, clear_user_id FROM sessions WHERE employee_id = (SELECT id FROM employees WHERE employee_id = '123456') ORDER BY created_at DESC LIMIT 1;
-- Should show: status = 'complete', clear_user_id = 'user_abc123'

Scenario 2: Return Verification (Known User Key)

Setup:

Same employee from Scenario 1 (now has clear_user_id = 'user_abc123')

Steps:

Navigate to /{company}/verify
Enter employee ID: "123456"
Click "Verify with CLEAR"
Complete CLEAR verification (selfie only, faster)
Redirected to confirmation page

Expected Results:

✅ Session created with reverification_project_id
✅ user_id sent (not user_profile_information)
✅ CLEAR skips ID capture, only takes selfie
✅ Verification completes faster (~10-15 seconds vs 30-45 seconds)
✅ Status changes from pending → complete
✅ Same user_id returned
✅ Confirmation page shows "Thank you, John!"

How to Verify:

-- Check routing logic worked
SELECT clear_session_id FROM sessions WHERE employee_id = (SELECT id FROM employees WHERE employee_id = '123456') ORDER BY created_at DESC LIMIT 1;
-- Then use CLEAR API to check which project_id was used

Scenario 3: Employee Not Found

Steps:

Navigate to /{company}/verify
Enter employee ID: "999999" (doesn't exist)
Click "Verify with CLEAR"

Expected Results:

✅ Error message: "Employee not found. Please contact your administrator."
✅ No CLEAR session created
✅ No redirect happens

Scenario 4: Invalid API Credentials

Setup:

Temporarily change API key to invalid value

Expected Results:

✅ Error message: "Failed to create verification session"
✅ Error logged with 401 response from CLEAR
✅ User sees helpful error message

Scenario 5: Biometric Mismatch

Setup:

Employee with first_name "Jane", last_name "Smith"
User completes CLEAR verification but name on ID is "John Doe"

Expected Results:

✅ CLEAR returns status: 'failed'
✅ No user_id returned
✅ clear_user_id remains NULL on employee record
✅ User sees error message explaining verification failed

Scenario 6: User Abandons Verification

Setup:

User starts verification but closes browser before completing

Expected Results:

✅ Session status remains pending
✅ When user returns and starts new session, old session stays pending
✅ New session can be created without issues

Common Integration Bugs

Bug	Symptom	Root Cause	Fix
user_id not saving	Second verification still requires ID	Results endpoint not saving user_id to employee record	Check that `clear_user_id` update happens after status='complete'
Wrong project used	Always shows ID capture, even on second verification	Routing logic not checking `clear_user_id`	Ensure `isReverification = !!employee.clear_user_id` check works
Biometric matching fails	Status returns 'failed' on valid verification	First/last name mismatch between employee record and ID	Ensure employee.first_name and employee.last_name match ID exactly
API returns 401	"Invalid authentication" error	Wrong API key or missing Bearer prefix	Check Authorization header: `Bearer ${apiKey}`
API returns 400	"Project does not exist"	Wrong project_id or project archived	Verify project_id in CLEAR dashboard, check for typos
Redirect fails	User stuck on verification page	Invalid redirect_url or CORS issue	Ensure redirect_url is publicly accessible, matches protocol (http/https)
Polling times out	Confirmation page never loads	Results endpoint not polling CLEAR API	Check that `getVerificationSession()` is called in polling loop
Duplicate employees	Same employee_id exists twice	No UNIQUE constraint on (tenant_id, employee_id)	Add constraint: `UNIQUE(tenant_id, employee_id)`
Session status stuck	Status never changes from pending	CLEAR session never completed	Check CLEAR dashboard for session status, verify user completed flow
No traits returned	Verified data missing from response	Project configuration doesn't request traits	Update project settings in CLEAR dashboard to request specific traits

Troubleshooting Decision Trees

Decision Tree 1: Verification Session Creation Fails

Session creation fails
├─ HTTP 401 "Invalid authentication"
│  ├─ Check: API key correct in .env?
│  ├─ Check: Authorization header includes "Bearer " prefix?
│  └─ Fix: Verify credentials in CLEAR dashboard
│
├─ HTTP 400 "Project does not exist or is archived"
│  ├─ Check: Project ID matches CLEAR dashboard?
│  ├─ Check: Project archived or deleted?
│  └─ Fix: Use correct project_id or create new project
│
├─ HTTP 400 "Traits for user profile matching do not match project configuration"
│  ├─ Check: Sending first_name and last_name?
│  ├─ Check: Project configured for User Profile Matching?
│  └─ Fix: Update project settings or send correct traits
│
└─ HTTP 500 or network error
   ├─ Check: Can reach https://verified.clearme.com?
   ├─ Check: Firewall/proxy blocking requests?
   └─ Fix: Check network connectivity, update firewall rules

Decision Tree 2: user_id Not Saving to Employee Record

Second verification still requires ID capture
├─ Check database: Does employee.clear_user_id have value?
│  ├─ YES → Routing logic broken
│  │  ├─ Check: isReverification = !!employee.clear_user_id?
│  │  ├─ Check: Sending user_id instead of user_profile_information?
│  │  └─ Fix: Update create-session routing logic
│  │
│  └─ NO → user_id never saved
│     ├─ Check: First verification completed successfully?
│     │  ├─ Query sessions table: status = 'complete'?
│     │  └─ If pending: User never finished CLEAR flow
│     │
│     ├─ Check: CLEAR returned user_id in response?
│     │  ├─ Call GET /verification_sessions/{id}
│     │  └─ If no user_id: CLEAR session failed
│     │
│     └─ Check: Results endpoint saving user_id?
│        ├─ Add logging to update query
│        ├─ Check for SQL errors
│        └─ Fix: Ensure update happens when status='complete' AND user_id exists

Decision Tree 3: Biometric Matching Fails

Verification returns status='failed'
├─ Check CLEAR response for failure reason
│  ├─ "Biometric match failed"
│  │  ├─ Name on ID doesn't match user_profile_information
│  │  ├─ Check: employee.first_name exactly matches ID?
│  │  ├─ Check: employee.last_name exactly matches ID?
│  │  └─ Fix: Update employee record or ask user to use correct ID
│  │
│  ├─ "ID verification failed"
│  │  ├─ ID expired or invalid
│  │  ├─ ID photo quality too low
│  │  └─ Fix: Ask user to use valid government-issued ID
│  │
│  └─ "Liveness detection failed"
│     ├─ Selfie appeared to be photo of photo
│     ├─ Multiple faces detected
│     └─ Fix: Ask user to complete selfie in good lighting, alone
│
└─ No failure reason in response
   ├─ Check project configuration
   ├─ Contact CLEAR support
   └─ Provide session_id for debugging