Uploading a Tree to [CET]

Follow these steps to upload a tree to [CET]:

1. Create a Group. This group will be used to manage access to the tree.
2. Create a Tree. This tree will become the repository for uploaded data.
3. Select the Current Tree. This sets the new tree to be the target for the remaining calls for uploading the tree.
4. Upload Tree Data. This step creates the persons, relationships, and other data in the tree.
5. Finalize Upload. This step selects the starting person, sets the privacy settings, and marks the tree as ready to be viewed.
6. Save a Timestamp. Do this if you plan to use the Tree Change History to stay in sync with changes.

Let’s review each of these steps in a little more detail.

1. Creating a Group

The group serves as the mechanism for managing user roles associated with the corresponding tree in [CET]. To create a group, send a POST request to the Groups endpoint.

The POST to create the group will include the following information:

• Name: This is the [CET] tree name that will be displayed on the FamilySearch website. For example, “Marshall and Amanda Felch Tree”
• Description: This description will be displayed on [CET] tree details page. For example, “This tree documents the descendants of Marshall Felch and Amanda Colburn.”
• Code of Conduct: This is displayed on the [CET] tree details page and is seen by other contributors when they are invited to the tree. It can describe any desired collaboration protocols for working with the tree.

Implementation Documentation

• Groups Endpoint
• Create Group Example Request
• Group Data Schema
• Postman Example

Managing Group Membership

Management of group membership and roles occurs on the FamilySearch.org website. You can link to the group management page with the following URL template.

https://{domain}/service/tree/page-links/groups/{group-id}/details

Please note that this URL may change prior to the full release of [CET].

2. Creating a Tree

Once the group has been created, you can create a tree and associate it with the group. To create the new tree, send a POST request to the Trees endpoint.

The POST to create the tree will require the following information:

• Group ID: The ID obtained when creating the group in the previous step.
• Name: This is not displayed on the FamilySearch website. It can be set to the same value as the Group name.
• Description: This is not displayed on the FamilySearch website. It can be set to the same value as the Group description.
• Owner Access: This is the setting that determines which third-party clients the owner of the tree can use to access the tree through the API. See [CET] Access Model for more details.
• Group Access: This is the setting that determines which third-party clients the group members can use to access the tree through the API. See [CET] Access Model for more details.

Implementation Documentation

• Trees Endpoint
• Create Tree Example Request
• Tree Data Schema
• Postman Example
• The X-Entity-Id header in the response will contain the ID for the newly created tree. You will need this for the next step of selecting the current tree.

3. Selecting the Current Tree

Selecting the tree sets the tree context for the session used for the remaining calls to upload the tree data. For more information, see the Current Tree Selection document.

Implementation Documentation

• Current Tree Endpoint
• Set Current Tree Example Request
• Tree Schema

4. Uploading the Tree Data

Creating a Person

A Person is created by sending a POST request with a GEDCOM X document that describes the person (including details such as living status, sex, names, events, facts, and more) to the Persons endpoint.

Implementation Documentation

• Persons Endpoint
• Create Person Example Request
• Person Data Schema
• Persons Guide
• Postman Example

The X-Entity-Id header in the response will contain the Person Id for the added person. Your application will need to store this Person Id, associated with your application’s person data. It is recommended to also store the Tree Id with the Person Id.
Note: If you are going to use the person change history, you may want to save the initial timestamp.

Creating Relationships

Relationships between persons are created through a POST to the Relationships endpoint. When creating relationships between persons, no tree Id is required. However, the system will return an error if an attempt is made to create a relationship between persons belonging to different tree spaces.

Trees support the creation of:

• ChildAndParents relationships which connect a child to one or two parents.
• Couple relationships which connect a person to a spouse.

Implementation Documentation

• Relationships Endpoint
• Create Child and Parents Relationship Example Request
• Create Couple Relationship Example Request
• ChildAndParentsRelationship Data Schema
• Relationship Data Schema: used for Couple relationships

These requests return an X-Entity-Id header containing the Id of the relationship. These relationship Ids can be used later to update the relationships. They can also be discovered by reading the relationships for a person.

Creating Sources

Sources are added to persons and relationships by creating source descriptions and then adding source references to a person or relationship.

Creating a source description is done through a POST to the Source Descriptions endpoint. The request to create a source description returns an “X-entity-id” header containing the ID of the source description. This ID is used later when attaching the source description to a person or a relationship. See this example request for details of how to create the source.

Creating a source reference is done through a POST to the Person endpoint, Couple Relationship endpoint, or Child and Parents Relationship endpoint.

Note: A Source Description can be associated with multiple tree persons, including persons belonging to different trees.

Implementation Documentation

• Source Descriptions Endpoint
• Create Source Description Example Request
• Source Description Data Schema
• Create Person Source Reference Example Request
• Create Child and Parents Source Reference Example Request
• Create Couple Source Reference Example Request
• Contributing Sources Guide

Creating Memories

Memories consist of photos, stories, documents, and audio. Memories are created through a POST to the Memories endpoint.

Memories can then be tagged to the persons who are represented in the memory. Tags are created through a POST to the Memory Personas resource.

Implementation Documentation

Here are example requests for creating and tagging memories:

• Memories Endpoint
• Source Description Data Schema: Used to describe the memory.
• Memory Personas Endpoint
• Person Data Schema: Used to describe the memory persona and media.
• Memories Developer Guide
• Example Requests:
  • Upload Photo
  • Upload Story
  • Upload PDF Document
  • Upload Multiple Photo Memories (multipart request)
  • Upload Image as a Document

5. Finalizing the Tree Upload

Finalizing the upload consists of updating the starting person, the private state, and the hidden state of the tree. This can be accomplished with a single POST request to the Tree endpoint. See the Update Tree example request.

Starting Person

You now must set the starting person for the tree. This person will serve as the focal point when a user accesses a link to view the tree online. As the default focus person, the starting person will be prominently displayed on the tree view while viewing the tree online.

Hidden State

By default, the tree is hidden when its created. Now that your application has loaded all its information into the [CET], the tree is ready to be viewed online. Your application should set hidden attribute of the tree to false. This will enable you and all group members to view and edit the tree on the FamilySearch.org.

Be aware that a hidden tree is not the same as a private tree. The hidden state of a tree is only intended to keep users from viewing the tree online during the initial upload.

Private State

When a tree is created it is private by default. You can change the tree to public by setting private to false. You should only set the tree to public after completing the data upload.

If the tree remains in the private state, it will not show up in any Searches or Matches on the FamilySearch website. For more information, see the [CET] Privacy Settings document.

6. Save a Timestamp

If you plan to stay in sync with changes happening in the [CET] tree, you should save a timestamp. This will be useful when using the Tree Change History endpoint to request the latest changes. For more information, see the Syncing Family Trees guide.