Person Matches Query

Description

The Person Matches Query resource defines the interface for retrieving a list of possible matches for a person that is not already in the tree. This is particularly useful for matching a person in an external tree to a person in the FamilySearch tree. The Person Matches resource should be used for persons already existing in the FamilySearch tree.

Each entry in the search results MAY contain content of the GEDCOM X media type that provides data about the results of the search, e.g., persons and relationships.

Searches for person matches require the given name, surname, gender and at least two of the following:

  • Birth date.
  • Birth place.
  • Death date.
  • Death place.
  • Spouse given name.
  • Spouse surname.
  • Father given name.
  • Father surname.
  • Mother given name.
  • Mother surname.
variable description
start The index of the first search result desired by the search client.
count The number of search results per page desired by the search client.
q

The query parameter that describes the search criteria. A parameter name and value is separated by a colon ':' and each name-value pair is separated by a white space ' '.

q=givenName:John surname:Smith gender:male birthDate:"30 June 1900"

Notice the white space in the birthDate value. If white space is required in the value, then the value must be wrapped in double quotes.

By default, values are exact. For non-exact matches append a tilde '~' at the end of the value such as givenName:Bob~.

name description
name: The full name of the person being searched.
givenName: The given name of the person being searched.
surname: The family name of the person being searched.
gender: The gender of the person being searched. Valid values are "male" and "female".
birthDate: The birth date of the person being searched.
birthPlace: The birth place of the person being searched.
deathDate: The death date of the person being searched.
deathPlace: The death place of the person being searched.
marriageDate: The marriage date of the person being searched.
marriagePlace: The marriage place of the person being searched.

Relation Search Parameters

The following set of standard parameters is defined as the substitution of {relation} with any of the values father, mother, and spouse.

{relation}Name: The full name of the {relation} of the person being searched.
{relation}GivenName: The given name of the {relation} of the person being searched.
{relation}Surname: The family name of the {relation} of the person being searched.
{relation}BirthDate: The birth date of the {relation} of the person being searched.
{relation}BirthPlace: The birth place of the {relation} of the person being searched.
{relation}DeathDate: The death date of the {relation} of the person being searched.
{relation}DeathPlace: The death place of the {relation} of the person being searched.
{relation}MarriageDate: The marriage date of the {relation} of the person being searched.
{relation}MarriagePlace: The marriage place of the {relation} of the person being searched.
{relation}Id: The ID of the {relation} of the person being searched.

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.

Parameters

Name Type Description
Authorization header The authorization carrying the OAuth 2.0 access token. See OAuth 2.0 Bearer Tokens.
X-FS-Feature-Tag header The comma-separated list of features to enable for the request. This list is used to enable any specific Pending Modifications. For more information, see the API Evolution Guide
access_token query The id of the OAuth 2 access token used for identification and authorization of the user (and agent) making the request.
candidateId query An id to constrain the search to.
count query The number of search results per page.
q query The search query.

Operations

GET - Read the results of a search.

Status Codes
200 Upon a successful read.
204 Upon a successful query with no results.
400 If the application declines to process the query because it would have resulted in too many results.
400 If the query to be processed was unable to be understood by the application.
429 If the request was throttled.
Warnings
400 If the query to be processed was unable to be understood by the application.
413 If the application declines to process the query because it would have resulted in too many results.

Example Requests

Read Match Scores for Persons How to determine the match scores for a given set of persons.
Search For Person Matches How to search for matches of a person.