Import your FamilySearch family tree, memories, and sources into your self-hosted ɳFamily instance. FamilySearch is free and has one of the largest genealogical databases in the world — this plugin brings that data home.
Requires nself-family. FamilySearch uses the GEDCOMX data model. The importer maps GEDCOMX persons and relationships to the local nSelf family schema.
nself license set nself_pro_...
nself plugin install family family-familysearch
nself build
nself startnself-family-familysearch authenticates against the FamilySearch Identity platform using OAuth 2.0. It fetches the authenticated user's tree using the FamilySearch API, translating GEDCOMX persons, relationships, and facts to the local family schema in np_family_members and np_family_relationships.
FamilySearch Memories (photos and documents attached to persons) can be downloaded and stored in MinIO when nself-photos is installed. Source citations and record hints are stored locally so family members can see the evidence behind each fact without needing a FamilySearch account.
Because FamilySearch is a collaborative tree, changes by other contributors are visible on the next sync cycle. The plugin stores a last_modified timestamp from the FamilySearch API and only fetches records that changed since the previous sync, keeping bandwidth low.
| Variable | Required | Default | Description |
|---|---|---|---|
PLUGIN_FAMILYSEARCH_CLIENT_ID | Yes | — | OAuth client ID from the FamilySearch Developer Portal |
PLUGIN_FAMILYSEARCH_SYNC_INTERVAL_HOURS | No | 12 | How often to poll for tree changes. Set to 0 to disable automatic sync. |
PLUGIN_FAMILYSEARCH_IMPORT_MEMORIES | No | true | Download FamilySearch Memories into MinIO. Requires nself-photos. |
PLUGIN_FAMILYSEARCH_IMPORT_SOURCES | No | true | Store source citations from FamilySearch records |
PLUGIN_FAMILYSEARCH_USE_SANDBOX | No | false | Point at the FamilySearch integration sandbox for testing |
| Endpoint | Method | Description |
|---|---|---|
/familysearch/auth | GET | Begin OAuth flow. Redirects to FamilySearch Identity. |
/familysearch/callback | GET | OAuth callback. Stores tokens and triggers first import. |
/familysearch/import | POST | Trigger a manual full or delta import |
/familysearch/status | GET | Last sync time, persons imported, delta stats |
/familysearch/sources/:person_id | GET | List source citations for a local family member |
/health | GET | Plugin health check |
| Table | Purpose |
|---|---|
np_familysearch_tokens | OAuth tokens per authenticated user (access token expires in 1 hour; refresh handled automatically) |
np_familysearch_person_map | Maps FamilySearch PIDs (e.g. LZNY-BX3) to local np_family_members IDs |
np_familysearch_sources | Source descriptions and citations: person_id, fact_type, title, url, repository |
np_familysearch_sync_log | Import history: started_at, persons_fetched, delta_since, errors |
| Event | Payload |
|---|---|
familysearch.import.completed | Persons added, updated, sync type (full/delta), duration |
familysearch.auth.revoked | User ID — sync paused until re-auth |
FamilySearch does not require registering a client secret — only a client ID. After completing the OAuth flow, syncs run automatically on the configured interval.
# 1. Register your redirect URI at https://www.familysearch.org/developers/
# Redirect URI: https://your-nself-host/familysearch/callback
# 2. Open the OAuth flow
open https://your-nself-host/familysearch/auth
# 3. After redirect, check import status
curl https://your-nself-host/familysearch/status \
-H 'Authorization: Bearer <token>'| Feature | nself-family-familysearch | FamilySearch.org only | GEDCOM download |
|---|---|---|---|
| Self-hosted data | Yes | No | Yes (one-time) |
| Delta sync | Yes | N/A | No |
| Source citations | Yes | Yes (on FS only) | Partial |
| Memories / photos | Yes (into MinIO) | Yes (on FS only) | No |
| Symptom | Fix |
|---|---|
| 401 on first import after auth | FamilySearch access tokens expire in 1 hour. If the callback took too long (e.g. browser was left open), re-authenticate via GET /familysearch/auth. |
| Import completes but person count is low | FamilySearch paginates at 100 persons per request. Large trees take multiple pages — check GET /familysearch/status for in_progress: true before assuming the import finished. |
| Sandbox mode returning production data | Set PLUGIN_FAMILYSEARCH_USE_SANDBOX=true and use a FamilySearch sandbox account — sandbox accounts are separate from production accounts. |
Port: 3831 | Bundle: ɳFamily ($0.99/mo) or ɳSelf+ ($3.99/mo) | Last Updated: May 2026 | Plugin Version 1.0.13