Current Tree Selection

December 17, 2024

The FamilySearch API enables your users to select which FamilySearch tree to work with during their session. The tree selection changes certain behaviors of the API. It sets the tree context for actions such as creating persons and requesting matches.

The Current Tree

In each authenticated FamilySearch session, there is a “current tree” selected. This applies to both the user experience on FamilySearch.org as well as authenticated API interactions. Changing the currently selected tree in one application does not affect the currently selected trees in other applications.

The FamilySearch API provides an endpoint that enables an application to read the ID of the currently selected tree, as well as to set the ID of the currently selected tree. By default, the currently selected tree of a session is the global tree. Any tree that the user has permission to access can be set as the selected tree. The list of [CET] trees a user has access to can be obtained by making a GET request to the Groups endpoint. The ID of the global tree is “GLOBAL.”

Endpoints Impacted by Current Tree

Endpoints that operate on a tree are all impacted by the currently selected tree. Some endpoints accept a Tree ID override. In those cases, if the Tree ID is provided in the call that will override the currently selected Tree ID.

Person Create

A Person is created by sending a POST request to the Persons endpoint and the person will be created in the currently selected tree. However, if a Tree ID is provided in the body of the post, that will override the currently selected tree.

Matches

When requesting matches, matches will only be returned if the currently selected tree matches the tree where the Person is contained.

Reading Multiple Persons

When making a request for multiple Persons from the Persons endpoint, the request must only include IDs of Persons in the currently selected tree.

Implementation Details

The ID of the currently selected tree can be read by sending a GET request to the Current Tree Endpoint. The response body will contain the ID of the currently selected tree.

   GET /platform/trees/current HTTP/1.1
  Host: apibeta.familysearch.org
  Authorization: Bearer YOUR_ACCESS_TOKEN
  Accept: application/json
  
  HTTP/1.1 200 OK
  Content-Type: application/json
  Date: Thu, 21 Nov 2024 09:21:21 GMT
  
  {
    "trees": [{
      "id": "9NMM-9SQB"
    }]
  }

The currently selected tree can be set by sending a POST request to the Current Tree endpoint.

  POST /platform/trees/current HTTP/1.1
  Host: apibeta.familysearch.org
  Content-Type: application/x-fs-v1+json
  Authorization: Bearer YOUR_ACCESS_TOKEN
  Accept: */*
  Content-Length: 46
  
  {
    "trees": [{
      "id": "GLOBAL"
    }]
  }
   
  HTTP/1.1 204 No Content
  Date: Thu, 21 Nov 2024 09:21:28 GMT

Best Practices

When switching the current tree selection on an active session, please be aware that this will affect any other processes making API calls with the same session.

Consider the following scenario. Process A queues up many calls using a session that has tree Z as its currently selected tree. Process B comes along and sets the same session to tree Y, unbeknownst to process A. Process A, continues to make calls with the wrong tree context. This could cause data to be written to the wrong tree.

Recommendations

If your application enables working with multiple trees, you can address the above scenario by following either of these practices.

Work with only one tree at a time. If you need to switch tree selection, ensure that any other processes using the current tree selection have completed or have been stopped.

Use multiple sessions. By using multiple sessions, you can set each session to a target tree for the duration of the session. This can enable safely interacting with multiple trees simultaneously.

Currently, obtaining multiple sessions requires that a user go through the Authorization flow for each session. Depending upon the logged-in state of the user on the FamilySearch website, the user may not have to reenter credentials.