Match by Tree Person Id
Path
/platform/tree/persons/{pid}/matches |
|
| Production: | https://api.familysearch.org/platform/tree/persons/{pid}/matches |
| Beta: | https://apibeta.familysearch.org/platform/tree/persons/{pid}/matches |
| Integration (Integration): | https://api-integ.familysearch.org/platform/tree/persons/{pid}/matches |
Description
The Match by Tree Person Id 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 using the collection query parameter.
Use of the collection query parameter in a production environment is restricted to applications that
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 Tree | https://familysearch.org/platform/collections/tree (or just "tree") |
The set of matches (possible duplicates) in the FamilySearch tree. | FamilySearch Records | https://familysearch.org/platform/collections/records (or just "records") |
The set of matches in the FamilySearch records. | FamilySearch CETs | https://familysearch.org/platform/collections/cet (or just "cet") |
The set of matches in the FamilySearch Cet. |
If no collection is specified, the request will be interpreted as matches in the FamilySearch tree (possible duplicates) Family Tree.
Each match has 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.
This resource also provides the interface to update the match status for possible matches.
Operations
|
GET - Read a set of matches for the given tree person id. FamilySearch tree matches are known as the possible duplicates for the given tree person id. For possible duplicates the tree matches that are no longer found or deleted are filtered from the list. Produces - Specify a returned data format using the
Accept
header.
Parameters
Status Codes
|
|||||||||||||||||||||
|
HEAD - Determine if there are matches for the given person id. Produces - Specify a returned data format using the
Accept
header.
Parameters
Status Codes
|
|||||||||||||||||||||
|
POST - Certification Required Add or modify a match resolution for the given tree person id. The status parameter should indicate if the match is Pending, Accepted, or Rejected. The body of the POST should contain a gedcomx document with a single record persona id for the match resolution. If an Accepted or Rejected match resolution declaration already exists for the given tree person id, 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. Produces - Specify a returned data format using the
Accept
header.
Consumes - Specify the incoming data format using the
Content-Type header.
Parameters
Status Codes
|
Example Requests
| Read Matches by Tree Person Id | How to get the record matches for a tree person id. |
| Read Matches by Tree Person Id for All Match Status Types | How to get the record matches for a tree person id for all types of match statuses. |
| Read Matches by Tree Person Id with Higher Confidence | How to get the record matches for a tree person id with higher confidence that are accepted. |
| Read Person Possible Duplicates | How to get the possible duplicates for a person. |
| Update Match Status by Tree Person Id for Record Matches | How to designate a match status for record matches of a tree person id. |