Attention: This site does not support the current version of your web browser. To get the best possible experience using our website we recommend that you upgrade to a newer version or install another browser

Skip main navigation

Generic Relationships Update

Changes to the FamilySearch API have been announced to support a more generic relationship model. This guide is intended to help you navigate the changes so that your integration will be ready for the updated API.

Schedule of Changes

Beginning October 1, 2019, all applications should be ready to handle the new API behavior. We recommend your application take the following steps prior to October 1, 2019 to be ready for the change. Your application should:

  • Begin requesting the new generic relationships model on all requests. See Activating the Generic Relationships Model for details on how to do this.
  • Be ready to consume and create data using the generic relationships model data model. The ability to use the generic relationships model is available on all environments, including the Production environment.
  • Be ready to handle cases of reading same-sex parent and spouse relationships. You can begin creating same-sex relationships in the Beta and Integration environments today by using the web client and the API with the generic relationships model activated.
  • Wait to enable creating same-sex relationships in the Production environment. The ability for any client to create same-sex relationships will be controlled by a global configuration that will be activated after October 1, 2019. API requests that attempt to create same-sex relationships prior to that date will receive an error response. You may consider implementing a configuration to enable this functionality in your application after this functionality has been enabled on FamilySearch.

Activating the Generic Relationships Model

To activate the generic relationships model, use the "X-FS-Feature-Tag" header with a value of "generic.relationship.terms" This should be used for all calls to the FamilySearch API. For more information on how to use these pending modification headers, see the Pending Modifications guide.

Relationship Objects in GEDCOM X

A GEDCOM X document either supports new generic naming or supports old naming. Only one type of naming may be used at a time. Although the model does not prevent both new and old names from being present at the same time, if both are present at the same time, behavior is undefined. Old and new naming may not be mixed within sections of a GEDCOM X document.

With new generic naming available, we will start allowing couple and child-and-parents relationships to be created with persons in non-traditional slots. For example, spouse1=female or parent1=female. This will also allow same-sex relationships to be created. Although either gender is allowed in both slots, it is preferred that for heterosexual relationships, traditional ordering should be used where ever possible. For example, spouse1=male spouse2=female and parent1=male parent2=female. This avoids confusion on formal pedigree and other views.

With new generic naming, a relationship is deemed equal if the same set of spouses or same set of parents exist in the relationship regardless of position. The platform/tree/child-and-parent-relationship/{caprid} and platform/tree/couple-relationship/{crid} are considered the canonical endpoints for person reference position. Other calls that return GEDCOM X may also return a ChildAndParentsRelationship or Relationship object as part of the response. These relationships are created based on underlying calls and data available from system. It may be possible that the person reference position of these calls may not always match the canonical source.

Model Change Details

Object Model Deprecated Name New Generic Name
JSON, XML, gedcomx-java
father parent1
mother parent2
fatherFacts parent1Facts
motherFacts parent2Facts
JSON, XML, gedcomx-java
Man: Spouse1:
Woman: Spouse2:
Father: Parent1:
Mother: Parent2:
Father Parent1
Mother Parent2
Man Spouse1
Woman Spouse2
ADD_MAN: "Man Added" ADD_SPOUSE1: "Spouse1 Added"
EDIT_MAN: "Man Changed" EDIT_SPOUSE1: "Spouse1 Changed"
ADD_WOMAN: "Woman Added" ADD_SPOUSE2: "Spouse2 Added"
EDIT_WOMAN: "Woman Changed" EDIT_SPOUSE2: "Spouse2 Changed"
ADD_FATHER: "Father Added" ADD_PARENT1: "Parent1 Added"
EDIT_FATHER: "Father Changed" EDIT_PARENT1: "Parent1 Changed"
REMOVE_FATHER: "Father Removed" REMOVE_PARENT1: "Parent1 Removed"
ADD_MOTHER: "Mother Added" ADD_PARENT2: "Parent2 Added"
EDIT_MOTHER: "Mother Changed" EDIT_PARENT2: "Parent2 Changed"
REMOVE_MOTHER: "Mother Removed" REMOVE_PARENT2: "Parent2 Removed"

Hypermedia rel removals

The "man" and "woman" hypermedia links have been totally removed. The "person1" and "person2" links that previously existed and will continue to exist. This affects:

Hypermedia rel changes

Old rel names (without experiment) New rel names (with experiment)
"father" "parent1"
"father-role" "parent1-role"
"mother" "parent2"
"mother-role" "parent2-role"

This affects:

Resources to be removed

Three resources will be removed and will return a 404.

Resources that Create, Modify, or Delete ChildAndParentsRelationship Entities

The following resources are used to create, modify, or delete ChildAndParentsRelationship entities in FamilySearch. Because of the possibility of data corruption, these resources will temporarily validate that the provided ChildAndParentsRelationship model object contains the correct naming based on the experiment and does NOT contain both old and new naming at the same time. This check will be removed when the experiment becomes permanent - so it should not be relied on in any way.

Method Resource Path Description
POST RelationshipsResource /tree/relationships Create a child-and-parents relationship
POST ChildAndParentsRelationshipsResource
/tree/child-and-parents-relationships Deprecated way to create a child-and-parents relationship. This will always fail (404) with experiment enabled.
POST ChildAndParentsRelationshipResource /tree/child-and-parents-relationships/{caprid} Updates a child-and-parents relationship
DELETE ChildAndParentsRelationshipParentResource /tree/child-and-parents-relationships/{caprid}/{role} Remove a parent from the person's role in a child-and-parents relationship
DELETE ChildAndParentsRelationshipConclusionResource /tree/child-and-parents-relationships/{caprid}/{role}/conclusions/{cid} Delete a specific fact attached to a child-and-parents relationship
Change Language


Feedback was sent.

Can't send feedback. Retry in 5 seconds.