GuidesAPI ReferenceChangelogHelp
Guides

Integrating Hints

Suggest Edits

One of the most powerful services FamilySearch offers developers is the ability to generate research hints. The FamilySearch API allows developers to leverage FamilySearch’s “matching technology” to generate hints for persons added to a tree. Hints reference historical records that match the person.

See Family Tree Matching and Hinting to learn about matching and hinting, the Search and Match resource, as well as an explanation of the match results returned in the feed. Pay specific attention to the section on Recommended Hinting Flow. Due to current restrictions, historical records data can only be displayed to users by FamilySearch products and services. It is essential that users be directed to FamilySearch to view details about each hint and accept or reject the hinted information.

Historical Record Matches

Historical record matches are retrieved using the Match by Tree Person Id endpoint. Matched record information includes the persona name, the collection title, the record ID, a match score, confidence value, and the status of the match. See Read Matches by Tree Person Id request example to see an example of a record match.

The match status indicates the specific state of a match: Rejected, Accepted or Pending. See Family Tree Matching and Hinting for more information about Match statuses.

Linking to FamilySearch Records

Users must view the matched records on the FamilySearch website. When a 3rd party application redirects the user's web browser to display the hinted record, it is imperative that the browser context be set to the CET tree where the person resides. The Tree-Page-Links service handles the redirection and setting the context of the tree in the browser.

Tree-Page-Links requires three path parameters:

  • tid: The tree ID where the record resides
  • rid: The record ID (Ark or ID)
  • pid: The person ID

Tree-Page-Links also accepts a view query parameter to provide the view FamilySearch should use to display the record. Possible values include:

  • sourceLinker: This view provides a page that compares the persona from the record with the person in the tree. It lets the user easily add information to the tree.
  • recordDetails: This view shows the details of the record, including the indexed data and a link to the digital record image if there is one.

Example URLs

  • /tree-page-links/trees/{tid}/persons/{pid}/records/{rid}?view=sourceLinker
  • /tree-page-links/trees/{tid}/persons/{pid}/records/{rid}?view=recordDetails

Once the user is redirected to FamilySearch.org, the user can attach the record as well as add new relationships and facts to the [CET] person. Resulting additions can be synced to the developer’s database.

Updated 4 months ago