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

2018 - July Newsletter

Important Announcements

Please be aware that several deprecated API resources will be turned off beginning in September. See the Upcoming September Changes below.

June Changes in Review

Transition from familysearch.org to api.familysearch.org

API requests to familysearch.org began redirecting to api.familysearch.org. Please be advised that this redirect is temporary and will be turned off in September.

GEDCOM X POST for Person Matches Resource

A new feature was released on the Person Matches Resource providing more accurate match results. This feature provides the ability to describe the person, parents, spouses, and children with a GEDCOM X document. The GEDCOM X document is to be sent through the POST method to the Person Matches Resource.

Deprecation of GET for Person Matches Resource

Please note that with the release of this improved match capability comes the deprecation of the GET method on the Person Matches Resource. It is strongly advised to migrate to the new POST method as quickly as possible. The GET method will continue to be supported for the near term, but watch for a future announcement regarding the retirement of the GET method.

Upcoming September Changes

Warning The following are changes that if ignored, could potentially break your integration.

Turning off deprecated API resources

Beginning September 18 the following API resources may be turned off, resulting in a 404 status code response.

API calls to familysearch.org will no longer redirect to api.familysearch.org. Please make sure your integrations are updated to point directly to api.familysearch.org or your code will no longer function.

API Resource Documentation Resource Path Link Rel Migrate To
Discovery /platform/app-meta
/.well-known/app-meta
Collections Resource
or
Family Tree Collection Resource
Person with Relationships /platform/tree/persons-with-relationships{?access_token,person,persons} person-with-relationships-query Person Resource
Relationships to Parents /platform/tree/persons/{pid}/parent-relationships parent-relationships-template Person Resource
Relationships to Spouses /platform/tree/persons/{pid}/spouse-relationships{?access_token,persons} spouse-relationships-template Person Resource
Relationships to Children /platform/tree/persons/{pid}/child-relationships{?access_token,persons} child-relationships-template Person Resource
Person Source References /platform/tree/persons/{pid}/source-references{?access_token} person-source-references-template Person Resource
Person Discussion References /platform/tree/persons/{pid}/discussion-references{?access_token} person-discussion-references-template Person Resource
Person Memory References /platform/tree/persons/{pid}/memory-references{?access_token} person-memory-persona-references-template Person Resource

API Integration Tips

Handling of API Responses

As your integration with the FamilySearch API processes responses, please make sure that it is prepared to handle the various HTTP status codes that may be returned by the API. In particular, a few status codes to focus on are the 429 and 401 status codes.

The 429 status code represents a rate-limited response. This means that your application has used up its allocated processing time and needs to wait a given interval of time before trying again. The throttled response should contain special headers indicating how many seconds to wait before you try again. Please make sure your integration does not immediately attempt a retry without waiting the appropriate time. Please see the Throttling guide for more information.

The 401 status code represents a request containing a missing or invalid access token. Please be aware that an access token will expire after it has been inactive for a certain period, or when it has reached its max lifespan. When you receive a 401 status code, your integration will need to reestablish a new valid access token. For more information see the Access Token Resource documentation.

Warning Headers

The API returns Warning headers intended to report on integration best practices, provide additional error troubleshooting information, and inform of deprecations. It may be useful to you as a developer to develop a way to log or display these warning messages in a way that doesn't interfere with your end customer experience but in a place that you as a developer will see them.

Change Language
Feedback

Sending...

Feedback was sent.

Can't send feedback. Retry in 5 seconds.