---
title: "Read Person Matches by ID"
method: GET
path: "/tree/persons/{pid}/matches"
tags: ["Matches"]
---

# Read Person Matches by ID

`GET /tree/persons/{pid}/matches`

## Certification Required

The Match by Tree Person Id endpoint 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](https://familysearch.org/developers/docs/certification/read#certreq-RR01-tree-person-recordhint).**

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 User Trees | `https://familysearch.org/platform/collections/cet` (or just "cet") | The set of matches in the FamilySearch user trees. |

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.

## Path parameters

- `pid` string, required

## Query parameters

- `collection` 'tree' | 'user_trees' | 'records' | 'cet'
- `confidence` integer
- `count` integer
- `status` string
- `treeId` string

## Headers

- `Accept` 'application/x-gedcomx-atom+json' | 'application/json' | 'application/atom+xml' | 'application/xml', required

## Response `200`

The read was successful. See <a href="https://developers.familysearch.org/main/docs/json-schema#person" target="_blank">Person Schema (JSON)</a>

## Other responses

- `204` — Upon a successful read with no matches.
- `301` — If the person has been merged.
- `404` — If the person was not found.
- `410` — If the person has been deleted.
- `429` — The request was throttled.

---

[API](https://skmtc.net/familysearch/apis/authentication-endpoints.md) · [All operations](https://skmtc.net/familysearch/apis/authentication-endpoints/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/familysearch/authentication-endpoints/revisions/2b5020574a62/schema)