Keeping in Sync with FamilySearch Data

Developers are often faced with the challenge of keeping the data they've downloaded in sync with FamilySearch. It's important to know if the data has changed and, if so, what data has changed.

How to know if there is a change

The version of a person is provided using the ETag header. To see if your data is in sync with FamilySearch, do a GET or a HEAD on the person to see the version in the response:

GET /tree/persons/12345
If-None-Match: "vjfje78v34"

You can then compare two ETag values to see if there are any changes. This is true for relationships as well as persons.

If you want the server to automatically compare the eTags instead of doing it manually yourself, pass in the ETag of the person to compare using the If-None-Match header:

GET /tree/persons/12345
If-None-Match: "vjfje78v34"

If the version has changed, the server will provide you with the new version of that person. If the version has not changed, the server will respond with a 304 Not Modified. Allowing the server to compare the ETags will be more efficient because you won't have to do a full person READ if the person has not changed.

How to know what has changed

You can see what has changed between two versions of a person by comparing the two versions. You can also make a request to the Person Change History resource for that person. When you read the change history, it will include a list of changes that have happened to the person, listed in reverse chronological order. It will also include changes to the relationships associated with that person.

The change history for persons and relationships will include facts added, updated or removed; names added, updated or removed; sources attached or detached; memory personas attached or detached and discussions or notes added or removed. On the change history for a person, the changes on any relationships will be included but the change history for a relationship will not include the change history for any person in those relationships.

Currently, there is no change history for a discussion, source or memory. If you want to know how a source has changed, whether a comment was added to a discussion or if a memory was updated, you will need to compare the resources manually. There is not a way to subscribe to changes but this may be possible in the future.

Person identifiers

When you do a GET on a person or relationships, the response will include a link to itself which is the link you should use to make a request in the future (see the Persistent Identifiers guide). Using this link rather than creating your own URL will ensure that the link you use will remain valid and persistent. For example, use the person link rel in the Read Person example response:

Request

GET /platform/tree/persons/PPPJ-MYZ
Accept: application/x-gedcomx-v1+xml
Authorization: Bearer YOUR_ACCESS_TOKEN_HERE

Response

HTTP/1.1 200 OK
...
ETag: "vjfje78v34"
...

<?xml version="1.0" encoding="UFT-8" standalone="yes"?>
<gedcomx xmlns="http://gedcomx.org/v1/" xmlns:fs="http://familysearch.org/v1/" xmlns:atom="http://www.w3.org/2005/Atom" description="#SD-PPPJ-MYZ">
  <person id="PPPJ-MYZ">
  ...
    <link rel="person" href="https://familysearch.org/platform/tree/persons/PPPJ-MYZ"/>
  ...
</gedcomx>