Overview

The Known User Key (user_id or clear_user_id) enables fast reverification in CLEAR's identity platform. After completing their first verification, users receive a unique user_id that enables selfie-only verification on all future attempts.

Key Concept: Two separate CLEAR projects handle two distinct flows:

Project A (Establish Identity - Initial Verification): Captures ID + selfie - may optionally use User Profile Matching
Project B (Known user key - Re-verification): Configured for Known User Key - captures selfie only (3-5 seconds)

⚠️ Important Notes:

User Profile Matching is optional - Project A can establish identity with or without matching against employee data. This guide shows the UPM approach as one lifecycle pattern.
Employee ID entry is optional - Users don't need to manually type identifiers if they're already authenticated (logged in via SSO, username/password, etc.). Your system can query the data source automatically. This guide shows manual entry as a "worst-case scenario" example.

Key Definitions

Establish Identity Flow

Purpose: First-time identity binding for a user within your customer ecosystem.

What it means: When a user verifies their identity for the first time with your organization, CLEAR performs full verification (ID document scan + selfie) and issues a customer-specific CLEAR userID (also called PSUID - Person-Specific Unique Identifier). This userID represents the verified identity relationship between that user and your organization.

Key characteristics:

First-time verification within your organization's ecosystem
May use User Profile Matching to bind verified identity to employee records
Results in a customer-specific user_id that enables future reverifications
Full verification: document scan + biometric selfie

Ecosystem Identity

What it means: A verified identity relationship between a user and a specific organization. When a user completes their first verification for your organization, they receive a customer-specific CLEAR userID that works only within your ecosystem.

Key characteristics:

Customer-scoped: Each organization has its own isolated ecosystem with unique userIDs
Ecosystem-bound: A userID issued by Company A does NOT work for Company B (privacy-preserving)
Reusable across touchpoints: Once established, the same userID works for ALL verification scenarios within your organization:
- Employee onboarding
- Password reset
- Laptop/device provisioning
- Building access (physical)
- VPN/network access
- Conditional access (high-risk login)
- MFA reset
- Account recovery
Not CLEAR Network: This userID is different from CLEAR's public network (airports, stadiums, LinkedIn) - it's specific to your organization

Example:

Day 1: Employee verifies for onboarding → receives user_id: ABC123
Week 2: Same employee needs laptop → takes 3-second selfie using same user_id: ABC123
Month 3: Same employee resets password → takes 3-second selfie using same user_id: ABC123

All verifications use the same customer-specific userID established on Day 1.

Known User Key Flow

Purpose: Fast re-verification for users who have already established their identity.

What it means: Once a user has completed their first verification (Establish Identity) and has a stored user_id, all subsequent verifications become selfie-only (3-5 seconds) instead of full document scanning. The system sends the stored user_id to CLEAR, which matches the live selfie against the stored biometric.

Key characteristics:

User already has clear_user_id stored in your system
Selfie-only verification (no document scan)
Completes in 3-5 seconds
Works across all use cases within your ecosystem

Project A: Initial Verification (User Profile Matching)

When to Use

First-time verification - No user_id exists on employee record
Employee record has clear_user_id = null

How It Works

User identification (multiple options):
- ✅ User already logged in (SSO, OAuth, username/password) → system automatically knows identity
- ✅ System queries HR/identity provider automatically based on session
- ⚠️ User manually enters Employee ID (shown in examples below as worst-case scenario)
System checks employee.clear_user_id → NULL (no stored user_id)
System routes to Project A (initial_project_id)
[Optional - if using User Profile Matching] Sends PII in user_profile_information:
- first_name (required for UPM)
- last_name (required for UPM)
- dob (optional, format: YYYY-MM-DD)
User scans ID + takes selfie on CLEAR
[If using UPM] CLEAR matches verified data against PII you sent
CLEAR returns user_id (regardless of UPM usage)
Process the successful match:
- Match: CLEAR verified identity data matches data you have on file
- Map: Correlate CLEAR's response back to your existing employee records (using custom_fields like employeeID)
- Store: Save the returned user_id to your database (required) + optionally store verified PII from CLEAR if needed

📌 Note: Establish Identity workflows require matching user data to data you have on file, then mapping it to your existing records, and finally storing data from a successful match (user_id is required, PII is optional).

API Call

curl --request POST \
  --url https://verified.clearme.com/v1/verification_sessions \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "project_id": "proj_abc123_establish",
    "redirect_url": "https://yourapp.com/verify/confirmation",
    "user_profile_information": {
      "name": {
        "first_name": "Jane",
        "last_name": "Smith"
      },
      "dob": "1990-05-15"
    },
    "custom_fields": {
      "employeeID": "EMP12345"
    }
  }'

After creating session: Redirect user to https://verified.clearme.com/verify?token={token}

To retrieve results: Poll the session endpoint or handle redirect callback:

curl --request GET \
  --url https://verified.clearme.com/v1/verification_sessions/verify_abc123def456 \
  --header 'Authorization: Bearer YOUR_API_KEY'

⚠️ CRITICAL: After successful verification, save the returned user_id to your database immediately!

Project B: Reverification (Known User Key)

When to Use

Returning user - user_id exists on employee record
Employee record has clear_user_id populated

How It Works

User identification (same options as Project A):
- ✅ User already logged in → system knows identity automatically
- ✅ System queries data source based on session
- ⚠️ User enters Employee ID manually (worst-case example)
System checks employee.clear_user_id → EXISTS (user_id found!)
System routes to Project B (reverification_project_id)
Sends stored user_id instead of PII
User takes selfie only (no document scan) - 3-5 seconds
CLEAR matches selfie to stored biometric using user_id
Validate returned user_id matches stored value

📌 Note: Known User Key flow doesn't require user input - if they're authenticated, you already know which user_id to use.

API Call

curl --request POST \
  --url https://verified.clearme.com/v1/verification_sessions \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "project_id": "proj_def456_kukf",
    "redirect_url": "https://yourapp.com/verify/confirmation",
    "user_id": "UxBm6T2KkJxHgXlM7gaZrboYpwLIAnAh4lausdqO68",
    "custom_fields": {
      "employeeID": "EMP12345"
    }
  }'

After creating session: Redirect user to https://verified.clearme.com/verify?token={token}

⚠️ CRITICAL: After verification completes, validate the returned user_id matches your stored value!

Integration Logic & Error Handling

Routing Decision Logic

Core routing pattern:

1. Check if user has clear_user_id stored
   ├─ YES: Route to Project B (Known User Key)
   │        - Send user_id in request
   │        - User completes selfie-only flow
   │
   └─ NO:  Route to Project A (Establish Identity)
            - Send user_profile_information (if using UPM)
            - User completes ID scan + selfie
            - Save returned user_id to database

Error Handling: user_id Not Found

Scenario: You route to Project B (Known User Key) but CLEAR returns an error that the user_id does not exist.

Why this happens:

user_id was deleted/revoked in CLEAR's system
user_id is invalid or corrupted
Wrong user_id stored in your database

Required handling:

1. Catch the error from CLEAR API
2. Fallback to Project A (Establish Identity) flow
3. Ensure biographic match (use User Profile Matching)
4. Overwrite old user_id with new user_id returned from CLEAR
5. Save new user_id to database

Error Handling: Biographic Mismatch

Scenario: Using Project A with User Profile Matching, but verified identity data doesn't match employee data you sent.

Why this happens:

Wrong employee selected from database
Outdated employee information (name change, typo)
User scanned someone else's ID

Required handling:

1. CLEAR completes verification successfully (status: complete)
2. But no user_id is returned (match failed)
3. Flag for manual review
4. DO NOT save user_id to database
5. Notify administrator to reconcile data

Error Handling: user_id Mismatch on Reverification

Scenario: Using Project B (Known User Key), but returned user_id doesn't match stored value.

Why this happens:

Security issue: wrong person verified
Database corruption
CLEAR system error (rare)

Required handling:

1. Verification completes successfully
2. Compare returned user_id to stored user_id
3. If mismatch:
   - Log security alert
   - Deny access
   - Trigger security review
   - DO NOT overwrite stored user_id

Key Takeaways

✅ Two Projects, Not One: Project A (initial) and Project B (reverification) are separate CLEAR projects
✅ Same API Key: Both projects use the same API key
✅ Routing Logic: Check if clear_user_id exists → if yes, use Project B; if no, use Project A
✅ Save the user_id: After first verification, save user_id to employee record immediately
✅ Validate on Reverification: Always verify returned user_id matches stored value
✅ No Webhooks Needed: Use polling or redirect callback to retrieve results
✅ User Profile Matching is Optional: Project A can establish identity with or without UPM - the key is getting the user_id
✅ User Input is Optional: If users are authenticated (SSO, logged in), you can query their identity automatically - no manual Employee ID entry needed

User Experience Comparison

Flow	User Action	Time	Data Sent
Project A (Initial)	Scan ID + Selfie	30-60 seconds	`user_profile_information` (name, DOB)
Project B (Reverification)	Selfie only	3-5 seconds	`user_id`

Reference Documentation

CLEAR API Docs: https://docs.clearme.com
Create Session: https://docs.clearme.com/reference/create_verification_session
Get Verification: https://docs.clearme.com/reference/get_verification