# Matches endpoints

Suggested duplicate people: review them, then accept (merge) or reject. A group of duplicates can be merged in one request.

Paths are relative to https://kleiobase.com/api/v1. Request and response schemas are in the OpenAPI document at https://kleiobase.com/api/v1/openapi.json.

## List pending match suggestions

`GET /workspaces/{workspace_id}/matches`

A page can be shorter than limit when matches with a trashed person are dropped. Keep following next_cursor.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `limit` (query, optional): Page size. Default 25, max 100.
- `cursor` (query, optional): The next_cursor of the previous page. Opaque.

Responses:

- `200`: A page of pending matches.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan.
- `404`: The workspace does not exist or is not visible to this key's owner.
- `422`: Invalid limit or cursor.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Reject a match

`POST /workspaces/{workspace_id}/matches/{match_id}/reject`

The pair is not suggested again. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `match_id` (path, required): The match id.
- `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Takes a request body; see the OpenAPI document for its schema.

Responses:

- `200`: Rejected.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan, or the key is read-only (a read_write key is required).
- `404`: The workspace does not exist or is not visible to this key's owner. Also: The match does not exist or is not visible.
- `409`: The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. Also: The match is already resolved.
- `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Accept a match (merge)

`POST /workspaces/{workspace_id}/matches/{match_id}/accept`

Merges the match's two people. The body is optional; survivor_id defaults to person_a_id. To undo it, send the returned match_id to POST .../people/{person_id}/unmerge with the survivor in the path. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `match_id` (path, required): The match id.
- `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Takes a request body; see the OpenAPI document for its schema.

Responses:

- `200`: Merged. Returns the surviving person.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan, or the key is read-only (a read_write key is required).
- `404`: The workspace does not exist or is not visible to this key's owner. Also: The match does not exist or is not visible.
- `409`: The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. Also: The match is already resolved, or one of its people is gone.
- `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: survivor_id is not one of the match's two people, or a man and a woman.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Merge a group of duplicates

`POST /workspaces/{workspace_id}/matches/merge-group`

Merge every other person in person_ids into survivor_id, as one undoable group: unmerging any of the returned match_ids restores the whole group. If a later person cannot be merged, the earlier merges stand and that person is listed in failed. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Takes a request body; see the OpenAPI document for its schema.

Responses:

- `200`: Merged.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan, or the key is read-only (a read_write key is required).
- `404`: The workspace does not exist or is not visible to this key's owner. Also: A person does not exist or is not visible.
- `409`: The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress.
- `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Fewer than 2 or more than 20 people, survivor_id not in person_ids, or a man and a woman.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

Canonical: https://kleiobase.com/developers/docs/reference/matches