Tree to Tree Linking

In FamilySearch, the same individual may be represented in more than one tree. Tree to Tree Linking allows a person in one tree to reference their counterpart in another tree by creating a Tree Person Reference. A Tree Person Reference is a directional link from a person in one tree to a person in another tree who is believed to represent the same individual.

Use Cases

Tree to Tree Linking serves multiple purposes, including:

• Supporting Tree to Tree Hints – Helping researchers discover potential matches across trees.
• Preserving known links between trees – Maintaining connections when data is transferred between trees, such as when downloading from the shared public tree and uploading to a private tree (e.g., a CET tree).

These use cases are described in detail below.

Tree to Tree Hints

One of the key use cases for Tree to Tree Linking is to support Tree to Tree Hints. These hints alert researchers when a person in another tree appears to match someone in their own tree. The researcher can then compare the records, evaluate the match, and choose to copy relevant data.

If the user confirms that the two persons represent the same individual, a Tree Person Reference is created. This reference ensures the link is stored, so researchers can track which individuals across trees have already been identified as the same.

Preserving Known Links Between Trees

Another important use case is maintaining known links between trees. For example, a researcher may export part of the shared public tree and upload it to a new CET tree for further research. Tree Person References preserve the link to the original shared tree person, ensuring continuity in the research process and avoiding unnecessary duplicate identification.

Tree Person Reference Data Model

A Tree Person Reference is a directional link to a person in another tree who is believed to represent the same individual. These links maintain relationships between persons without merging their data.

If a person has one or more Tree Person References, they appear in the tree-person-references array.

Example: Person with a Tree Person Reference

{
  "persons": [
    {
      "id": "BSSY-L55",
      //...
      "tree-person-references": [
        {
          "id": "55a832be-5f0d-4a9c-a26a-f33d61a5bb1c",
          "treePerson": {
            "resource": "https://beta.familysearch.org/ark:/61903/4:1:KWCH-DGR",
            "resourceId": "KWCH-DGR"
          },
          "tree": {
            "resource": "/collections/tree",
            "resourceId": "SHARED PUBLIC TREE"
          },
          "attribution": {
            "contributor": {
              "resource": "https://apibeta.familysearch.org/platform/users/agents/MM94-938",
              "resourceId": "MM94-938"
            },
            "modified": 1753309883924
          }
        }
      ]
    }
  ]
}

Directionality

A Tree Person Reference is a directed link from one person record in a tree to another person record in a different tree, indicating they represent the same individual.

Key Characteristics

• Directed Link
  • The reference flows from the source person to the target person in another tree.
  • Links are not automatically reciprocal.
• Unidirectional
  • If Tree A has a person A1 referencing person B1 in Tree B, this link only goes from A1 → B1.
  • To create a reciprocal link, you must explicitly create a separate reference from B1 → A1.

Why Direction Matters

Direction communicates intent and ownership:

• The source person asserts that a person in another tree is the same individual.
• Different trees and systems can maintain separate provenance, attribution, and control over their own data.

API Integration

Reading an Existing Tree Person Reference

Retrieve existing Tree Person References using the Read Person operation. Look for the tree-person-references array on the person. See the example JSON.

Creating a Tree Person Reference

Add a Tree Person Reference using the Update Person operation. You only need to include the person ID (pid) as the resourceId of the treePerson. You do not need to include the tree object. See the Create Tree Person Reference example request.

Deleting a Tree Person Reference

Delete a Tree Person Reference using the Delete Tree Person Reference operation.