Menu
Menu
Menu

FamGEN – FamilySearch API Interface

Global Tree and CET Project Updates

The API interface links your FamGEN entries directly with the FamilySearch Global Tree and CET projects. You can create, update, and link persons or retrieve ancestors/descendants – without leaving the page.

Typical Use Cases

  • Create a new person (including basic facts like birth/marriage/death/emigration)
  • Update an existing person by PID (add/correct facts)
  • Set relationships: child ↔ parents, spouses, child ↔ proband (with matching spouse)
  • Quickly fetch ancestors/descendants (x generations) and load proband data to prefill the form

Requirements

  • Free FamilySearch account
  • Client ID (App ID) of your registered FamilySearch app
  • Configured redirect URI in the app (must exactly match the loaded api.html)

Privacy & Cost

  • Authentication uses OAuth2 PKCE in the browser; access tokens are stored locally only.
  • Use of the FamilySearch API is free for registered apps; platform API limits must be observed.

Technical Notes

Auth / Token
  • OAuth2 PKCE: authorization & token endpoints (cis-web/oauth2/v3), challenge via SHA-256; code_verifier stored in browser
  • Token storage: localStorage (including expires_at), automatic refresh before expiration; logout clears token
API Base
  • Base: https://api.familysearch.org/platform
  • Standard headers: Accept: application/x-fs-v1+json, Content-Type: application/x-fs-v1+json, Authorization: Bearer <token>
  • Optional: X-Reason: <your change reason>
  • For updates: If-Match: <ETag> if required
Supported Operations
  • POST /tree/persons – createPerson (person + facts)
  • POST /tree/persons/{pid} – updatePerson (modify facts)
  • POST /tree/relationships – ChildAndParents & Couple (links)
  • GET /tree/ancestry?person={pid}&generations=n – fetchAncestors
  • GET /tree/descendancy?person={pid}&generations=n – fetchDescendants
  • Convenience: fetchAncDesc (both calls sequentially), fetchPerson (GET /tree/persons/{pid})

Benefits at a Glance

  • Runs directly in the browser: no own server required, no backend token forwarding
  • PKCE login with refresh flow, status indicator and automatic refresh before expiration
  • Clear UX gating: “Prechecks” enforce duplicate check before creating / manual review before updating
  • One-click links to details/sources/tree for the current PID
  • Clean normalization for names, dates and places (e.g. 20.08.1910 → 20 Aug 1910)
  • URL prefill compatible with MS Access exports (nachname, vorname, gebJahr, …)
  • Protocol log & clear banners for success/warning/error

How to Use the GEDCOM Generator

  1. Enter Client ID
    Enter your FamilySearch Client ID and click Apply. The page displays the redirect URI that must be registered in your app.
  2. Login
    Click Login. The FamilySearch dialog (OAuth2 PKCE) opens. After success, the status indicator shows the active token.
  3. Check / edit source data
    Fill in fields like first name, last name, birth, marriage, death, occupation, residence on the right – or prefill via URL parameters (see below).
  4. Prechecks
    Before creating a person, clicking Prechecks opens the Tree search (duplicate check). For updates, it opens the FamilySearch detail page for the PID.
  5. Select Operation
    • Create Person – creates a new person with your basic facts
    • Update Person – updates facts for the PID (with If-Match/ETag if needed)
    • Link: Proband ↔ Parents – link PID as child with father/mother
    • Link: Spouses – link proband ↔ spouse(s) (one or multiple)
    • Link: Child ↔ Proband – assigns child n ID to spouse n ID (n=1..4)
    • Fetch – ancestors, descendants or both (number of generations configurable)
    • Load Proband – loads PID and automatically fills the “Source Data” section
  6. Set Change Reason (optional, recommended)
    Enter an X-Reason (e.g. “Baptism KB Langenselbold 1842”). The header is sent automatically.
  7. Execute & Check
    Click Execute Operation. Result/errors appear in the JSON field; a banner at the top shows a clear status message.

FAQ

Do I need a PID for testing?
No, creating a new person does not require a PID; for update/links/fetches a valid PID is required.

What is the “Change Reason” (X-Reason) for?
It makes changes in FamilySearch more transparent for others (source, register, year, etc.).

Why must I run “Prechecks” before creating?
To avoid duplicates in the tree; the appropriate search opens in a new tab.

Can I prefill fields via URL?
Yes, see the example above; the form understands e.g. vorname, nachname, gebJahr, gebOrt, heiratJahr, personId_kv, gender_kv.