--- title: "Read Person Matches by Example" method: POST path: "/tree/matches" tags: ["Matches"] --- # Read Person Matches by Example `POST /tree/matches` ## Request - Base URL: `https://apibeta.familysearch.org/platform` - URL: `https://apibeta.familysearch.org/platform/tree/matches` - Auth: HTTP bearer The Person Matches by Example resource returns a list of possible FamilySearch tree persons that match a person described by a GEDCOM X document containing person details (POST). This resource is particularly useful for matching a person in an external tree to a person in the FamilySearch tree. The Match by Tree Person Id resource should be used to find matches (possible duplicates) for a specific person already in the FamilySearch tree. Each entry in the match results may contain content of the GEDCOM X media type that provides data about the results, e.g., persons and relationships. Person Matches are non-exact. The match algorithm will take into account all the information given about the person (and the person's parents, children and spouses, if included) and return matches, each having a likelihood of the match being the same person that was specified in the request. Because the match algorithm is non-exact, a returned match may have information that does not exactly match the information specified in the request. The likelihood is contained in the `ResultConfidence` field of each `Entry` (match result). Dates can be specific (20 July 1946), partial (May 1836 or just 1836), approximate (about 1793) or a range (1898-1903). * * * The POST body must contain a valid GEDCOM X JSON or XML block. The following elements of the GEDCOM X are required: Primary Person There must be a primary person and the primary person must have an id (such as "primaryPerson") Main Source Description There must be a main source description in the GEDCOM X document that points to the primary person (see Main sourceDescription.about below) Main sourceDescription.about The main source description's about attribute must point to the primary person via an anchor tag (i.e. about="#primaryPerson") **Note:** For more accurate results, the GEDCOM X POST body may (and should whenever possible) contain the main person's parents, spouses, and children. All the persons in the GEDCOM X must have IDs so that relationships can be defined between the persons. Persons not specified in a relationship (other than the primary person) will be ignored when matching. The person IDs can be of any format. IDs such as "primaryPerson", "mother1", "child1" etc. are acceptable and more intuitive for human understanding. ## Query parameters - `count` integer - `confidence` integer - `collection` 'tree' | 'user_trees' | 'cet' - `treeId` string ## Headers - `Accept` 'application/x-gedcomx-atom+json' | 'application/json' | 'application/atom+xml' | 'application/xml', required - `Content-Type` 'application/x-gedcomx-atom+json' | 'application/x-fs-v1+json' | 'application/x-gedcomx-v1+json' | 'application/json' | 'application/atom+xml' | 'application/x-fs-v1+xml' | 'application/x-gedcomx-v1+xml' | 'application/xml', required ## Request body - ReadPersonMatchesByExample - `description` string, required: Reference to the source description ID (e.g., '#sd1') - `persons` object[], required: Array of persons to match. Must include at least one primary person with an ID. See Person Schema (JSON) - `id` string, required: The person identifier. Use descriptive IDs like 'primaryPerson', 'father1', 'mother1', etc. - `gender` object: The gender of the person - `type` string: The gender type URI - `names` object[]: Array of names for the person - `type` string: The name type URI - `nameForms` object[]: Array of name forms - `fullText` string: The full text of the name - `facts` object[]: Array of facts (events) for the person - `type` string: The fact type URI (e.g., Birth, Death, Marriage) - `date` object: The date of the fact - `original` string: The date in original form. Can be specific (20 July 1946), partial (May 1836 or just 1836), approximate (about 1793) or a range (1898-1903). - `place` object: The place of the fact - `original` string: The place in original form - `relationships` object[]: Array of relationships between persons. Persons not specified in a relationship (other than the primary person) will be ignored when matching. See Relationship Schema (JSON) - `type` string, required: The relationship type URI - `person1` object, required: Reference to the first person in the relationship - `resource` string, required: URI reference to a person ID (e.g., '#father1') - `person2` object, required: Reference to the second person in the relationship - `resource` string, required: URI reference to a person ID (e.g., '#primaryPerson') - `sourceDescriptions` object[], required: Array of source descriptions. Must include a main source description that points to the primary person. See SourceDescription Schema (JSON) - `id` string, required: The source description identifier - `about` string, required: Reference to the primary person ID via an anchor tag - `identifiers` object: Optional map of identifiers for the source description ## Response `200` The read was successful. See Person Schema (JSON) ## Other responses - `204`: Upon a successful query with no results. - `400`: If the query to be processed was unable to be understood by the application. - `414`: If the application declines to process the query because it would have resulted in too many results. - `429`: The request was throttled. --- [API](https://skmtc.dev/familysearch/apis/family-tree-endpoints.md) - [All operations](https://skmtc.dev/familysearch/apis/family-tree-endpoints/llms.txt) - [OpenAPI document](https://skmtc.dev/familysearch/apis/family-tree-endpoints/revisions/e248abd029e6?raw)