Family Tree Matching and Hinting
Matching is the process whereby a person is "matched" with persons in a set of FamilySearch collections. The Person Matches resource can be used to provide hinting functionality. Hints for the match candidate are returned according to the Atom feed standard. The timestamp of the published element is the date when the system determined that the two records are possible matches. Examples of matching include:
- Finding the possible duplicates of a person in the FamilySearch Family Tree.
- Searching the FamilySearch Historical Records Archive for records of a person in the FamilySearch Family Tree.
- Searching for matches of a specific person who is not in the FamilySearch Family Tree.
The Person Matches resource is used to find the matches for a person in Family Tree. This resource provides the matches of a person in Family Tree with persons in other collections, including the FamilySearch Historical Records Archive. The collection(s) in which to find matches can be specified using a query parameter. A hinting application must go through a certification process. For more information, see Record Hinting Certification. Each match will specify the collection in which it was found. See the resource documentation for more details.
Note Due to legal restrictions, Historical Records Data can only be displayed to users by FamilySearch products and services. Applications that display Historical Records Data to users may be in violation of FamilySearch API usage policy.
Applications may display the title and the confidence level of the match to users and are expected to direct the user to the FamilySearch Web site using the persistent identifier of the record. For more information, see Persistent Identifiers.
In addition to a score and a confidence level, a "status" may also be provided with each match. The match status indicates a specific state of a match, described as follows:
- A "Rejected" match means that the match has been rejected by a user, implying that the match is invalid.
- An "Accepted" match means that the match has been accepted by a user as a valid match.
- A "Pending" match means that the match has neither been accepted nor rejected by a user.
The Person Matches Query is used to search for matches of a person that may or may not be known to FamilySearch by providing a query that describes the person. Currently, a match query can only provide matches in the FamilySearch Family Tree and not in the FamilySearch Historical Records Archive.
Unauthenticated access is allowed with this API. A session with a developer key needs to be created, but the specific user does not need to log in with their credentials and authenticate that session.
Recommended Hinting Flow
You can use this hinting/matching endpoint to show the number of hints available on a person. In a user's personal tree, the number of hints can be shown for each person. For example, a user could click on the hints to open a browser displaying the FamilySearch Hinting Details page. When the blue Review button is clicked, the "Source Attach" page could be displayed. The user can then attach sources to a person.