Syncing People from Your Platform to Wicket
How to import and update member data in Wicket from external platforms
This guide covers how to synchronize person records from external platforms into Wicket, keeping your member database current with activities across integrated systems.
Overview
Inbound sync imports user data from external platforms into Wicket. This process:
- Receives or fetches user data from the external platform
- Matches users to existing Wicket person records
- Creates or updates person records as needed
- Establishes service identity links
Sync Triggers
Webhook Receivers
Accept webhooks from external platforms:
- User registration events
- Profile update notifications
- Account status changes
Polling
Periodically fetch users from the external platform:
- Query for recently modified users
- Process changes since last sync timestamp
- Handle pagination for large datasets
Person Matching
Before creating a new person, attempt to match with existing records. See Record Matching Strategies for detailed approaches.
Quick reference:
- Service Identity Match: Check if service identity already exists
- Email Match: Find person by email address
- External ID Match: Match on previously stored identifiers
Creating People
When no match is found, create a new person:
POST /people
{
"given_name": "Jane",
"family_name": "Smith",
"primary_email": "jane.smith@example.com",
"additional_info": {
"source_platform": "your-platform-name"
}
}Then create the service identity link:
POST /service_identities
{
"person_id": "new-wicket-person-uuid",
"service_id": "your-service-uuid",
"external_id": "platform-user-id"
}Updating People
When a match is found:
- Compare incoming data with existing Wicket record
- Determine which fields should be updated
- Apply updates using PATCH
PATCH /people/{id}
{
"given_name": "Jane",
"family_name": "Smith-Jones"
}Field Mapping Considerations
Required Fields
Wicket requires at minimum:
given_nameorfamily_nameprimary_email(recommended)
Data Transformation
Common transformations needed:
| External Format | Wicket Format |
|---|---|
| Full name | Split into given_name/family_name |
| Phone with country code | E.164 format |
| Address as string | Structured address object |
Conflict Resolution
When data conflicts occur:
| Scenario | Strategy |
|---|---|
| Different emails | Keep Wicket email as primary, store alternate |
| Name variations | Use most recent or most complete |
| Duplicate detection | Merge or flag for manual review |
Error Handling
| Error | Cause | Solution |
|---|---|---|
| 422 Validation Error | Missing required fields | Check field requirements |
| 409 Conflict | Duplicate email | Use existing person record |
| 400 Bad Request | Invalid data format | Validate before sending |
Best Practices
- Validate early: Check data quality before processing
- Log everything: Track incoming data and decisions made
- Handle duplicates: Have clear strategy for potential matches
- Preserve data: Don't overwrite Wicket data unnecessarily
- Track source: Record which platform data came from