Record Matching Strategies
How to match and link records between Wicket and external platforms
Record matching is essential for maintaining data integrity across integrated systems. This guide covers strategies for linking Wicket person records with external platform users.
Overview
When syncing data between systems, you need to determine whether an incoming record matches an existing person in Wicket. Effective matching prevents:
- Duplicate person records
- Lost data connections
- Sync errors and conflicts
Matching Hierarchy
Use this recommended order for matching attempts:
1. Service Identity Match (Highest Priority)
Check if a service identity already exists for this external ID:
GET /service_identities?filter[service_id]={service_id}&filter[external_id]={external_id}If found, you have a confirmed match. This is the most reliable method.
2. Email Match
Search for person by email address:
GET /people?filter[primary_email]={email}Email is typically unique and reliable for matching.
Matching Strategies by Scenario
New User Registration
1. Check service identity for external_id
2. If not found, check email
3. If match found:
- Create service identity link
- Optionally update person fields
4. If no match:
- Create new person
- Create service identityWebhook Processing
1. Extract identifier from payload
2. Check service identity (should exist for updates)
3. If not found, fall back to email match
4. Process update or create as appropriateHandling Ambiguous Matches
Multiple Potential Matches
When multiple records could match:
- Rank by confidence: Choose highest scoring match
- Flag for review: Queue for manual verification
- Create new: When uncertain, create new record
No Match Found
Options when no match exists:
- Create person: Add new person record to Wicket
- Queue for review: Hold for manual data entry
- Reject: Return error if match is required
Namespace Considerations
Service identities can use namespaces to separate different user types:
# Different namespaces for different record types
{ "external_id": "123", "namespace": "customers" }
{ "external_id": "456", "namespace": "subscribers" }When matching, consider namespace:
- Same person might exist in multiple namespaces
- Match within namespace first, then across
Best Practices
- Service identity first: Always check existing links before other methods
- Email is reliable: Email addresses are the best secondary identifier
- Avoid name-only matching: Names are not unique; combine with other fields
- Log match decisions: Track why matches were made for debugging
- Handle duplicates gracefully: Have a strategy when duplicates are detected
- Case insensitive: Normalize email and names before comparing
- Trim whitespace: Clean data before matching