Person Matches

Description

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

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. Applications requesting record matches must be certified. See Record Hinting Certification.

Currently, only the following collections support match results:

title identifier description
FamilySearch Records https://familysearch.org/platform/collections/records (or just "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.

Record matches will have a "status" that indicates it to be in one of the following states:

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

Readable

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

Writable

If you POST something, specify the data format using the Content-Type header.

Parameters

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.
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 5.
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 pending matches are returned.

Operations

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.
x

Select a language