Getting Started with Identity Verification
Learn how to think about integrating per-registration identity verification into your application workflow.Mental Model: Identity verification is an enhancement option for individual registrations. Users choose whether to add verified identity based on the specific content they’re registering. The
/register endpoint automatically includes identity data when the user has recently completed verification for that registration.Understanding the Flow
Identity verification happens in 3 simple steps:1
User Choice
When registering a file, users choose between:
- Standard: Fast registration with blockchain proof
- Enhanced: Standard + verified identity (adds ~2 minutes)
2
Identity Verification (if chosen)
If enhanced registration chosen:
- Use
/register/identityendpoint to start verification - User scans QR code with Self app on Trust Engine’s verification page
- Takes photos of government ID and selects what information to share
3
Automatic Integration
The
/register endpoint automatically detects recent verification:- If verification completed: Includes verified identity data in registration
- If no recent verification: Proceeds with standard registration only
What Users Need
Before offering identity verification, users need: 📱 Device Requirements- Smartphone with camera
- Self app (free download from iOS App Store or Google Play)
- Internet connection
- Government-issued photo ID
- Valid (not expired) documents
- Clear, well-lit environment for photos
- About 2-3 minutes for verification
- One-time setup (faster for repeat use)
Key User Messages
Help users understand what’s happening: ❌ Avoid saying: “Identity verification is required”✅ Say instead: “Add verified identity to enhance this registration” ❌ Avoid saying: “Upload your ID documents”
✅ Say instead: “Verify your identity securely - documents stay on your device” ❌ Avoid saying: “This will verify all your future registrations”
✅ Say instead: “Choose enhanced registration to include verified identity for this file”
Implementation Approach
Choose your integration method:REST API
Best for: Any backend languageDirect HTTP calls to Trust Engine API endpoints
/register/identity → /identity/session/{wallet}JavaScript SDK
Best for: Node.js, React, web appsSimple method calls with automatic polling
sdk.verifyIdentity() → sdk.checkIdentityStatus()CLI Commands
Best for: Scripts, testing, demosCommand-line interface with interactive prompts
verify-identity → check-identityImplementation Workflow
1. Prerequisites Setup- Ensure users can create/link wallets ↗ Wallet API
- Set up basic file registration ↗ Register API
- Offer optional identity verification to users (usually one-time)
- Guide users through Self app download if needed
- Redirect users to Trust Engine’s verification page (no QR code implementation needed)
- Poll verification status every 5-10 seconds
- Handle completion, failure, and timeout scenarios
- Provide clear user feedback throughout process
- Session expiration (24 hours) → restart verification
- Verification failure → help with better document photos
- Network issues → implement retry logic
Different Registration Scenarios
🏠 Personal Document
🏠 Personal Document
User choice: Standard registration (no identity)Reasoning: Personal photos, notes don’t need identity verificationResult: Fast, simple registration process
📋 Business Contract
📋 Business Contract
User choice: Enhanced registration (name + nationality)Reasoning: Business partners want to know who they’re contracting withResult: Verified identity adds legal weight to agreement
🏦 Financial Document
🏦 Financial Document
User choice: Enhanced registration (full KYC fields)Reasoning: Regulatory compliance requires comprehensive identityResult: Meets KYC/AML requirements with blockchain immutability
🎓 Academic Credential
🎓 Academic Credential
User choice: Enhanced registration (name + date of birth)Reasoning: Credential authenticity requires identity confirmationResult: Verifiable credentials that employers/institutions can trust
What Happens After Verification
Once a user completes identity verification for a registration: ✅ Automatic inclusion: The/register endpoint detects recent verification and includes identity data✅ Enhanced credibility: That specific registration gains verified authorship
✅ Search benefits: When others search for that file, they see verified authorship
✅ Compliance ready: That registration meets KYC/AML requirements
Common Questions
Q: Do users have to verify for every registration?A: Only if they want that specific registration to include verified identity. Each registration is a separate choice. Q: What if users don’t want to verify their identity?
A: That’s fine! They can always use standard registration. Verification is completely optional. Q: Can users choose which identity fields to verify for each registration?
A: Yes! Users can choose different identity fields to verify based on what that specific registration requires. Q: What if verification fails?
A: Usually due to photo quality. Users can retry immediately with better lighting/positioning.
Development & Testing
Testing Without Real Documents
Development Environment Setup:- Mock SDK completes verification in 3 seconds
- Returns realistic test data for demonstrations
- No real identity documents required for testing
- Mock URLs can redirect to demo pages for stakeholder presentations
Integration Timeline
Development Effort Estimates: Basic Integration (API): 0.5-1 developer days- REST endpoint integration
- Simple URL redirect
- Basic status polling
- Error handling
- React/Node.js components
- Smooth UX with proper loading states
- Comprehensive error handling
- User communication & onboarding
- Polish redirect flow and user messaging
- Retry logic and edge case handling
Performance Considerations
Status Polling Best Practices:- Polling requests: ~1KB each, every 5-30 seconds
- Minimal bandwidth impact
- Consider WebSocket alternatives for high-traffic apps
- QR code page: Simple redirect - no additional implementation needed
User Communication Templates
Pre-Verification Messaging:- ✅ “You’ll be redirected to complete verification with the Self app”
- ✅ “Your ID photos are processed securely on your device only”
- ✅ “This usually takes 1-2 minutes to complete”
- ❌ “Verification failed - try retaking photos with better lighting”
- ⏰ “Session expired - tap to start new verification”
- 🌐 “Connection issue - tap to retry”
Next Steps
Choose Your Method
Pick API, SDK, or CLI based on your tech stack and start implementing
FAQ & Troubleshooting
Common issues and solutions for smooth integration
