Person Matches


The Person Matches resource defines the set of matches in the system for a person.

Certification Required

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. Hinting applications must be certified. See Record Hinting Certification.

Currently, only the following collections support match results:

title identifier (production) identifier (sandbox) description
FamilySearch Records 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.

If collection(s) are specified, matches will have a "status" that indicates it to be in one of the following states:

name identifier description
Pending The match has neither been accepted nor rejected.
Accepted The match has been accepted as valid.
Rejected 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.

Data Formats

If you make a GET request, specify the data format using the Accept header.

If you POST something, specify the media type using the Content-Type header.


Name Type Description
Authorization header The authorization carrying the OAuth 2.0 access token. See OAuth 2.0 Bearer Tokens.
pid path The ID of the person.
count query Certification Required The number of results to provide, an integer from 1 to 100. The default value is 5.
status query Certification Required The match status(es) by which to filter the results. By default, only pending matches are returned.
includeNotAMatchDeclarations query Whether to include persons in the results that have been declared by a user to be "not a match".
confidence query Certification Required The minimum confidence level of the results, an integer from 1 to 5. The default value is 3.
collection query Certification Required The identifiers of the collection(s) in which to find matches.
access_token query The ID of the OAuth 2 access token used for identification and authorization of the user (and agent) making the request.


GET - Read a set of matches for a person.

Status Codes
200 Upon a successful read.
204 Upon a successful query with no results.
301 If the person has been merged.
404 If the person was not found.
410 If the person has been deleted.
429 If the request was throttled.

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.

Status Codes
204 The update was successful.
301 If the referenced person has been merged into another person.
404 If the referenced person is not found.
410 If the referenced person has been deleted.
429 If the request was throttled.

Example Requests

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.