The Person Matches resource defines the set of matches in the system for a person in the Family Tree.
The scope of the match results can be limited to a specific collection or set of collections using the
collection query parameter.
Use of the
collection query parameter in a production environment is restricted to people who have been certified. Applications requesting record matches must be certified.
See Record Hinting Certification.
Currently, only the following collections support match results:
||The set of FamilySearch records.|
If no collections are specified, the request will be interpreted as a request for possible duplicates and only contain results from the FamilySearch Family Tree.
Record matches will have a "status" that indicates it to be in one of the following states:
||The match has neither been accepted nor rejected.|
||The match has been accepted as valid.|
||The match has been rejected as invalid.|
Match results can be filtered using the
status query parameter. By default, only
Pending results are returned.
The Person Matches resource also provides the interface to update match statuses for possible matches.
If you make a
GET request, specify the desired data format using the
POST something, specify the data format using the
|Authorization||header||The authorization carrying the OAuth 2.0 access token. See OAuth 2.0 Bearer Tokens.|
|pid||path||The ID of the person.|
|access_token||query||The ID of the OAuth 2 access token used for identification and authorization of the user (and agent) making the request.|
|collection||query||The identifiers of the collection(s) in which to find matches.|
|confidence||query||The minimum confidence level of the results. If not provided, an unspecified default minimum confidence level will be provided.|
|context||query||The possible duplicates context token, allowing requests for subsequent pages. The context is supplied in the query response with the "X-FS-Page-Context" header.|
|count||query||The number of results to provide, an integer from 1 to 100. The default value is
|includeNotAMatchDeclarations||query||Whether to include persons in the results that have been declared by a user to be "not a match".|
|start||query||The index of the first search result for this page of results.|
|status||query||The match status(es) by which to filter the results, applicable only to record matches. By default, only
GET - Read a set of matches for a person.
POST - Certification Required Add or modify a match resolution, indicating that the referenced person match is Pending, Accepted, or Rejected. If an Accepted or Rejected match resolution declaration already exists for the referenced person, an error will be returned. The current resolution should first be reset to Pending, then a new match resolution may be set. A reason string should be provided indicating why the user believes this is or is not a match.
|Read Person Possible Duplicates||How to get the possible duplicates for a person.|
|Read Person Record Matches||How to get the record matches for a person.|
|Read All Match Status Types Person Record Matches||How to get all types of match statuses for record matches of a person.|
|Read Higher Confidence Person Accepted Record Matches||How to get higher confidence accepted record matches for a person.|
|Update Match Status for Person Record Matches||How to designate a match status for record matches of a person.|