Family Tree Matching and Hinting

June 29, 2023

Matching is the process whereby a person is "matched" with persons in a set of FamilySearch collections. The Match by Tree Person ID 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 Match by Tree Person ID resource is used to find 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 API Compatible Checklist.

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 by Example resource 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.