Pre-release — content may change.

GuidesIntegrating with Wicket

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:

  1. Receives or fetches user data from the external platform
  2. Matches users to existing Wicket person records
  3. Creates or updates person records as needed
  4. 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:

  1. Service Identity Match: Check if service identity already exists
  2. Email Match: Find person by email address
  3. 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:

  1. Compare incoming data with existing Wicket record
  2. Determine which fields should be updated
  3. Apply updates using PATCH
PATCH /people/{id}
{
  "given_name": "Jane",
  "family_name": "Smith-Jones"
}

Field Mapping Considerations

Required Fields

Wicket requires at minimum:

  • given_name or family_name
  • primary_email (recommended)

Data Transformation

Common transformations needed:

External FormatWicket Format
Full nameSplit into given_name/family_name
Phone with country codeE.164 format
Address as stringStructured address object

Conflict Resolution

When data conflicts occur:

ScenarioStrategy
Different emailsKeep Wicket email as primary, store alternate
Name variationsUse most recent or most complete
Duplicate detectionMerge or flag for manual review

Error Handling

ErrorCauseSolution
422 Validation ErrorMissing required fieldsCheck field requirements
409 ConflictDuplicate emailUse existing person record
400 Bad RequestInvalid data formatValidate before sending

Best Practices

  1. Validate early: Check data quality before processing
  2. Log everything: Track incoming data and decisions made
  3. Handle duplicates: Have clear strategy for potential matches
  4. Preserve data: Don't overwrite Wicket data unnecessarily
  5. Track source: Record which platform data came from

On this page