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

Change History

The FamilySearch API provides a Change History resource for the Person, Couple Relationship, and Child-and-Parents Relationship Change History resources.

The change history for a resource allows a view of the changes that are made to a resource by users over time. Changes are logged when adding, editing, or deleting. A change entry includes:

  • A way to identify the type of change using the subject, predicate and modifier
  • A reference to the contributor of the change.
  • A reason for the change that was provided by the contributor.
  • A timestamp for when the change occurred.
  • An old (or "original") value. In the case of a creation of a new value, however, no original value exists.
  • A new (or "resulting") value. In case of a deletion of a value, however, there is no resulting value.
  • A deleted (or "removed") value. In case of a creation of a new value or an update of an existing value, however, there is no removed value.

The Atom Feed

An Atom Feed is used to provide the set of changes for a resource. Each change is provided as an entry in the feed, which natively provides a timestamp. The contributor is provided as the author of the entry. The type of change is provided as the title of the change. If the change is an edit, the expected content will be the original and resulting values. If the change is a delete, the expected content will be the removed value. If it's an add, merge or undelete, only the resulting value will be returned. Click here to see an example of a Change History feed.

You may determine that a previous value in a change is the correct value and you want to restore the original value. When a change is restored, its values are reapplied and a new entry is added. The original change will still be in the change history. If an entry does not contain a restore link, the change is not able to be restored.

Each entry provides a custom ChangeInfo element that provides the reason for the change that the contributor gives, as well as identifiers for the original, resulting, and removed values, if applicable. The values themselves are provided in the content of the entry.

A "parent" change, such as a merge of two persons, causes cascading changes to happen. If a change has a parent, then the change ID of the parent change is provided in the ChangeInfo element.

Change Types

The type of change can be identified using the objectType, operation and objectModifier attributes. The objectType identifies the type of object to which the operation applies, such as a birth. The operation is the action that was taken on the change, such as create, edit or delete. The objectModifier is optional and describes whether the change happened on a person or a relationship. The following is a list of change types available in the FamilySearch API:

Person
Create Person
Delete Person
Merge Person
Unmerge Person
Undelete Person
Add Person Not a Match
Delete Person Not a Match

Couple Relationship
Create Couple Relationship
Delete Couple Relationship
Add Man to Couple Relationship
Edit Man in Couple Relationship
Add Woman to Couple Relationship
Edit Woman in Couple Relationship
Merge Couple Relationship
Unmerge Couple Relationship
Undelete Couple Relationship

Child and Parent Relationship
Create Child and Parents Relationship
Delete Child and Parents Relationship
Add Parent1 to Child and Parents Relationship
Edit Parent1 in Child and Parents Relationship
Remove Parent1 from Child and Parents Relationship
Add Parent2 to Child and Parents Relationship
Edit Parent2 in Child and Parents Relationship
Remove Parent2 from Child and Parents Relationship
Add Child to Child and Parents Relationship
Edit Child in Child and Parents Relationship
Merge Child and Parents Relationship
Unmerge Child and Parents Relationship
Undelete Child and Parents Relationship

Discussion References
You can add, edit or delete the following discussion references:
Person Discussion Reference, Couple Discussion Reference, and Child and Parents Discussion Reference

Evidence References
You can add, edit or delete the following evidence references:
Person Evidence Reference, Couple Evidence Reference and Child and Parents Evidence Reference

Facts
You can add, edit or delete the following facts:
Affiliation, Annulment, Bar Mitzvah, Bas Mitzvah, Birth, Burial, Christening, Common Law Marriage, Cremation, Death, Living Status, Divorce, Marriage, Milliary Service, Naturalization, Nobility Type, Occupation, Religious Affiliation, Residence, Stillborn, Couple Event, Other Event, Caste Name, Clan Name, Died Before Eight, Life Sketch, National Id, National Origin, Physical Description, Race, Tribe Name and Other Fact

Gender
You can add, edit or delete a gender.

Name
You can add, edit, or delete the following names:
Birth Name, Aka Name, Alternate Name, Married Name, Nick Name and Other Name

Lineage
You can add, edit or delete lineage.

Ordinances
Complete Baptism
Complete Confirmation
Complete Initiatory
Complete Endowment
Complete Couple Sealing
Complete Sealing to Parents

Notes
You can add, edit or delete the following notes:
Person Note, Child and Parents Note and Couple Note

View an example of a person change history request.

Example Change History Feed

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<gedcomx xmlns="http://gedcomx.org/v1/" xmlns:fs="http://familysearch.org/v1/" xmlns="http://www.w3.org/2005/Atom">
    <link rel="next" href="https://familysearch.org/platform/tree/persons/KWCR-JW3/changes.xml?from=6VMN-4KZ"/>
    <link rel="person" href="https://familysearch.org/platform/tree/persons/KWCR-JW3.xml"/>
    <link rel="self" href="https://familysearch.org/platform/tree/persons/KWCR-JW3/changes.xml"/>
    <title>Change History for Person KWCR-JW3</title>
    <updated>2014-09-11T20:30:06.983Z</updated>
    <entry>
      <title>Person Created</title>
        <fs:changeInfo objectType="http://gedcomx.org/Person" operation="http://familysearch.org/v1/Create">
            <fs:resulting resource="#NPJG-LZ2" resourceId="NPJG-LZ2"/>
        </fs:changeInfo>
        <content type="application/x-gedcomx-v1+xml">
            <gx:gedcomx>
                <gx:person id="NPJG-LZ2">
                    <gx:identifier type="http://gedcomx.org/Primary">KWCR-JW3</gx:identifier>
                </gx:person>
            </gx:gedcomx>
        </content>
        <contributor>
            <name>Mike</name>
            <uri>https://familysearch.org/platform/users/agents/MMMM-MMK</uri>
        </contributor>
        <id>MMTN-F6V</id>
        <link rel="agent" href="https://familysearch.org/platform/users/agents/MMMM-MMK.xml"/>
        <updated>2014-09-11T20:30:06.983Z</updated>
    </entry>
    <entry>
      <title>Birth Added</title>
        <fs:changeInfo objectModifier="http://gedcomx.org/Person" objectType="http://gedcomx.org/Birth" operation="http://familysearch.org/v1/Create">
            <fs:resulting resource="#MMTN-F6211306419.resulting" resourceId="MMTN-F6211306419.resulting"/>
        </fs:changeInfo>
        <content type="application/x-gedcomx-v1+xml">
            <gx:gedcomx>
                <gx:person id="MMTN-F6211306419.resulting">
                    <gx:identifier type="http://gedcomx.org/Primary">KWW5-W21</gx:identifier>
                    <gx:fact type="http://gedcomx.org/Birth" id="V.777-7774">
                        <gx:date>
                            <gx:original>14 Jan 1808</gx:original>
                        </gx:date>
                        <gx:place>
                            <gx:original>Newtown, Pennsylvania</gx:original>
                        </gx:place>
                    </gx:fact>
                </gx:person>
            </gx:gedcomx>
        </content>
        <contributor>
            <name>Mike</name>
            <uri>https://familysearch.org/platform/users/agents/MMDZ-DN2</uri>
        </contributor>
        <id>MMTN-F62</id>
        <link rel="agent" href="https://familysearch.org/platform/users/agents/MMDZ-DN2"/>
        <updated>2014-11-12T13:30:41.562-07:00</updated>
    </entry>
    <entry>
      <title>Child and Parents Source Reference Added</title>
        <fs:changeInfo objectModifier="http://familysearch.org/v1/ChildAndParentsRelationship" objectType="http://gedcomx.org/SourceReference" operation="http://familysearch.org/v1/Create">
            <fs:resulting resource="#MMTN-FVP-1342652786.resulting" resourceId="MMTN-FVP-1342652786.resulting"/>
        </fs:changeInfo>
        <content type="application/x-gedcomx-v1+xml">
            <gx:gedcomx>
                <fs:childAndParentsRelationship id="MMTN-FVP-1342652786.resulting">
                    <gx:source description="https://familysearch.org/platform/sources/descriptions/MMCM-181" id="MMM9-264"/>
                    <gx:identifier type="http://gedcomx.org/Primary">MMMR-V1Q
                </fs:childAndParentsRelationship>
            </gx:gedcomx>
        </content>
        <contributor>
            <name>Mike
            <uri>https://familysearch.org/platform/users/agents/MMDZ-DN2</uri>
        </contributor>
        <id>MMTN-FVP</id>
        <link rel="agent" href="https://familysearch.org/platform/users/agents/MMDZ-DN2"/>
        <updated>2014-11-12T13:31:41.272-07:00</updated>
    </entry>
    <entry>
      <title>Child and Parents Note Changed</title>
        <fs:changeInfo objectModifier="http://familysearch.org/v1/ChildAndParentsRelationship" objectType="http://gedcomx.org/Note" operation="http://familysearch.org/v1/Update">
            <fs:original resource="#MMTN-FVL-1342652786.original" resourceId="MMTN-FVL-1342652786.original"/>
            <fs:resulting resource="#MMTN-FVL-1342652786.resulting" resourceId="MMTN-FVL-1342652786.resulting"/>
        </fs:changeInfo>
        <content type="application/x-gedcomx-v1+xml">
            <gx:gedcomx>
                <fs:childAndParentsRelationship id="MMTN-FVL-1342652786.resulting">
                    <gx:note id="MMM9-G51">
                        <gx:subject>cool note</gx:subject>
                        <gx:text>This is different text of a note</gx:text>
                    </gx:note>
                    <gx:identifier type="http://gedcomx.org/Primary">MMMR-V1Q</gx:identifier>
                </fs:childAndParentsRelationship>
                <fs:childAndParentsRelationship id="MMTN-FVL-1342652786.original">
                    <gx:note id="MMM9-G51">
                        <gx:subject>cool note</gx:subject>
                        <gx:text>This is the text of a note</gx:text>
                    </gx:note>
                    <gx:identifier type="http://gedcomx.org/Primary">MMMR-V1Q</gx:identifier>
                </fs:childAndParentsRelationship>
            </gx:gedcomx>
        </content>
        <contributor>
            <name>Mike</name>
            <uri>https://familysearch.org/platform/users/agents/MMDZ-DN2</uri>
        </contributor>
        <id>MMTN-FVL</id>
        <link rel="agent" href="https://familysearch.org/platform/users/agents/MMDZ-DN2"/>
        <link rel="restore" href="https://familysearch.org/platform/tree/changes/MMTN-FVL/restore"/>
        <updated>2014-11-12T13:31:37.657-07:00</updated>
    </entry>
    <entry>
      <title>Child and Parents Relationship Removed</title>
        <fs:changeInfo objectType="http://familysearch.org/v1/ChildAndParentsRelationship" operation="http://familysearch.org/v1/Delete">
            <fs:removed resource="#MMTN-V1Y-1342652786.removed" resourceId="MMTN-V1Y-1342652786.removed"/>
        </fs:changeInfo>
        <content type="application/x-gedcomx-v1+xml">
            <gx:gedcomx>
                <fs:childAndParentsRelationship id="MMTN-V1Y-1342652786.removed">
                    <gx:identifier type="http://gedcomx.org/Primary">MMMR-V1Q</gx:identifier>
                    <fs:parent1 resource="https://familysearch.org/platform/tree/persons/KWW5-W21" resourceId="KWW5-W21"/>
                    <fs:parent2 resource="https://familysearch.org/platform/tree/persons/KWW5-WLM" resourceId="KWW5-WLM"/>
                    <fs:child resource="https://familysearch.org/platform/tree/persons/KWW5-WL6" resourceId="KWW5-WL6"/>
                </fs:childAndParentsRelationship>
                <gx:person id="KWW5-WL6">
                    <gx:identifier type="http://gedcomx.org/Primary">KWW5-WL6</gx:identifier>
                </gx:person>
                <gx:person id="KWW5-W21">
                    <gx:identifier type="http://gedcomx.org/Primary">KWW5-W21</gx:identifier>
                </gx:person>
                <gx:person id="KWW5-WLM">
                    <gx:identifier type="http://gedcomx.org/Primary">KWW5-WLM
                </gx:person>
            </gx:gedcomx>
        </content>
        <contributor>
            <name>Mike</name>
            <uri>https://familysearch.org/platform/users/agents/MMDZ-DN2</uri>
        </contributor>
        <id>MMTN-V1Y</id>
        <link rel="agent" href="https://familysearch.org/platform/users/agents/MMDZ-DN2"/>
        <updated>2014-11-12T13:46:45.578-07:00</updated>
    </entry>
  </feed>
</gedcomx>
Change Language
Feedback

Sending...

Feedback was sent.

Can't send feedback. Retry in 5 seconds.