API Basics

To start working with the FamilySearch API, you need to become familiar with the following concepts:

  1. Authentication and Discovery
  2. Reading the Summary of the Person for the Authenticated User
  3. Searching for Persons

NoteIf you are new to FamilySearch development and have not registered as a developer, the Getting Started Guide tells you how to register.

NoteYou will not be able to participate in the following hands-on tutorial without a developer username and password.

Authentication and Discovery

The FamilySearch API is designed to conform to RESTful architectural principles, including the principle of hypermedia. In practical terms, because everything is "linked," you don't have to manage a big list of URIs that map to the resources in the system. In other words, the state of the application is being driven by hypermedia. You make a request to the collection and the collection points you to where the sources are.

To get started, the only thing you should need is the FamilySearch Family Tree resource, which contains links to available resources and serves as the entry point to the system.

You will need to be able to find the URI for the collection you're interested in.

Get the Unauthenticated FamilySearch Family Tree Resource

The collection has links that you can use to authenticate. Note especially the <link rel="http://oauth.net/core/2.0/endpoint/authorize" href="..."/> and the <link rel="http://oauth.net/core/2.0/endpoint/token" href="..."/> links. Those are the links you need to get an access token. For more information, see Authentication.

Get an Access Token

After signing in to FamilySearch developers’ sandbox system with your developer username and password and receiving your access token, you can make an authenticated request to the FamilySearch Family Tree resource. For the purposes of this tutorial, you will authenticate by using the access_token query parameter, but note that using the Authorization header is preferred. This is because it's more secure and is more amenable to caching.

When you have your access token, click the button below and replace YOUR_ACCESS_TOKEN_HERE with the access token.

Get the Authenticated Collection Resource

As emphasized before, for your application, you're probably going to want to use the Authorization header as specified by the OAuth 2 bearer token protocol.

Notice that an authenticated request for the collection resource returns links that have the access_token query parameter appended. You may follow these links to make authenticated requests to the API. Each link describes its relationship to the resource with an attribute called rel. This rel attribute is like a label or an identifier that describes the meaning of the link. For example, you can follow the link that appears similar to <link rel="current-user-person" href="..."/> to get the person resource for the currently authenticated user.

Find Your Person

Look at the authenticated collection resource and scroll to the rel="current-user-person" resource, and then locate the href="..." attribute. This is the link to the person for the currently authenticated user. This button is a shortcut to the Current User Person resource; if you use it, you must replace YOUR_ACCESS_TOKEN_HERE with your access token.

Get My Person

Search for Persons

Now you can do a search for "Rex Edward Hayes" with parents "John Edward Hayes" and "Harriet Elizabeth Jeffs." To accomplish this, return to the authenticated collection resource to find the link to the Person Search resource, which is identified by the rel="person-search" link.

The interesting thing about this link is that it doesn't have an href attribute. Instead, it links to the Person Search resource via a URI template. A URI template isn't a URI. It's a way of describing how to build a URI by plugging in values for specific variables. According to the spec, this is done by passing search variables through the template processor. To do this for this tutorial, click the Search for Rex Edward Hayes button below, replacing YOUR_ACCESS_TOKEN_HERE with your access token:

Search for Rex Edward Hayes

This query is built by passing the following search variables through the template processor. The variables are described in the documentation for the Person Search resource. For now, the only variables to be concerned with are access_token (to provide your access token) and q. The values for q are provided below and the syntax is given in the description for q in the Person Search documentation.

variable value
givenName Rex Edward
surname Hayes
fatherGivenName John Edward
fatherSurname Hayes
motherGivenName Harriet Elizabeth
motherSurname Jeffs

Sample App

Now try the sample app. It will walk you through even more complex examples.