didit-face-search_skill

Overview

This skill integrates the Didit Face Search standalone API to perform 1:N facial searches across all previously approved verification sessions. It returns ranked matches with similarity percentages and flags blocklisted faces for automatic decline. Use it to detect duplicate accounts, prevent repeat registrations, and surface potential matches for manual review.

How this skill works

Submit a user image (JPEG, PNG, WebP, TIFF; max 5MB) in a multipart/form-data POST to the Didit face-search endpoint with your x-api-key header. The API compares the image against all approved sessions and returns a face_search object containing status, total_matches, ranked matches with similarity_percentage, and user_image detection metadata. Status values (Approved, In Review, Declined) and warning tags guide automated decisions and manual workflows.

When to use it

• During new user registration to detect duplicate accounts before creating a profile
• When you need to check if a face already exists in your system or blocklist
• To implement automated blocking based on blocklist matches
• As part of a deduplication pipeline for an existing user database
• To surface likely matches for manual review when similarity is ambiguous

Best practices

• Only store non-sensitive metadata (session_id, similarity_percentage, vendor_data); avoid storing match images beyond 60 minutes
• Use rotate_image when collecting selfies that may not be upright to improve detection
• Treat 90%+ as strong matches, 70–89% as possible matches for manual review, below 70% as unlikely
• Honor warning tags: auto-decline on blocklist warnings, route In Review statuses to a human workflow
• Validate API key and monitor credit/usage to prevent 403 errors

Example use cases

• Reject registrations automatically when a face_search returns an is_blocklisted match
• Flag users for manual review when similarity_percentage is 75–88%
• Run periodic deduplication across stored sessions to find and merge duplicate accounts
• Combine with liveness and document verification for robust identity onboarding
• Search using vendor_data to correlate matches with existing internal IDs