Family Tree Matching and Hinting

Matching is the process whereby a person is "matched" with persons in a set of FamilySearch collections. The Read Person Matches by ID endpoint 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.
• Search the public CET collection for possible matches.
• Searching a specific public CET for possible matches.
• 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 Read Person Matches by ID endpoint is used to find matches for a person in Family Tree and CETs. This resource provides the matches of a person in Family Tree or a CET with persons in other collections, including the FamilySearch Historical Records Archive. The collection(s) in which to find matches can be specified using a collection query parameter as follows.

• tree or https://familysearch.org/platform/collections/tree for FamilySearch Open Access Tree. This is the default chosen if no parameter is provided.
• cet or https://familysearch.org/platform/collections/cet for CETs.
• records or https://familysearch.org/platform/collections/records for FamilySearch Historical Records.

To find a match within a specific CET, a treeId query parameter can be added in conjunction with the collection=cet query parameter that contains the tree identifier of the CET you wish to match against.

A hinting application must go through a certification process. For more information, see API Compatibility 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 Read Person Matches by Example endpoint is used to search for matches of a person that may or may not be known to FamilySearch by providing a body that describes the person. Currently, this match resource can only provide matches in the FamilySearch Family Tree and public CET collections, but 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.