# People endpoints Read, create, edit, merge, unmerge and delete the people in a workspace; read a person's timeline, close family, tree and expected records; add and remove relatives. 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 people `GET /workspaces/{workspace_id}/people` Each person carries folder_id and tag_ids. 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. - `q` (query, optional): Name search (accent-insensitive, max 200 characters). - `folder_id` (query, optional): Only people in this folder. - `tag_id` (query, optional): Only people with this tag. Responses: - `200`: A page of people. - `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. Also: folder_id or tag_id is not in this workspace. - `422`: Invalid limit, cursor, q, folder_id or tag_id, or folder_id is a folder of records. - `429`: Rate limit exceeded. Wait the number of seconds in Retry-After. - `500`: Unexpected error. Retry later and quote request_id if it persists. ## Create a person `POST /workspaces/{workspace_id}/people` Matching for the new person is queued, never run inline. 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: - `201`: The created 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). Also: the plan's person limit is reached. - `404`: The workspace does not exist or is not visible to this key's owner. - `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. - `429`: Rate limit exceeded. Wait the number of seconds in Retry-After. - `500`: Unexpected error. Retry later and quote request_id if it persists. ## Get a person `GET /workspaces/{workspace_id}/people/{person_id}` The person plus the ids of their families and linked records. Parameters: - `workspace_id` (path, required): The workspace (project) id. - `person_id` (path, required): The person id. Responses: - `200`: The person. - `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. Also: The person does not exist, is in Trash, or is in another workspace. - `429`: Rate limit exceeded. Wait the number of seconds in Retry-After. - `500`: Unexpected error. Retry later and quote request_id if it persists. ## Update a person `PATCH /workspaces/{workspace_id}/people/{person_id}` At least one field is required. Pending matches are re-scored; new match candidates are found by the scheduled run. 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. - `person_id` (path, required): The person 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`: The updated 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 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. - `429`: Rate limit exceeded. Wait the number of seconds in Retry-After. - `500`: Unexpected error. Retry later and quote request_id if it persists. ## Move a person to Trash `DELETE /workspaces/{workspace_id}/people/{person_id}` No body. The person can be restored with POST .../trash/restore. 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. - `person_id` (path, required): The person 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. Responses: - `200`: Moved to Trash. - `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 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. - `429`: Rate limit exceeded. Wait the number of seconds in Retry-After. - `500`: Unexpected error. Retry later and quote request_id if it persists. ## Move many people to Trash `POST /workspaces/{workspace_id}/people/delete` All or nothing: every id must be a live person in this workspace, or nothing is moved. 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`: Moved to Trash. - `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, is not visible, or is already in Trash. - `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: Invalid body: 1 to 100 UUIDs. - `429`: Rate limit exceeded. Wait the number of seconds in Retry-After. - `500`: Unexpected error. Retry later and quote request_id if it persists. ## Get a person's timeline `GET /workspaces/{workspace_id}/people/{person_id}/timeline` Dated entries first (ascending), then undated. Not paginated. Parameters: - `workspace_id` (path, required): The workspace (project) id. - `person_id` (path, required): The person id. Responses: - `200`: Timeline entries. - `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. Also: The person does not exist or is not visible. - `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 two people `POST /workspaces/{workspace_id}/people/{person_id}/merge` The path person is the survivor; other_person_id is absorbed into it. To undo it, send the returned match_id to POST .../people/{person_id}/unmerge. 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. - `person_id` (path, required): The person 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: 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: Same person twice, a man and a woman, or a field_choices side with no value. - `429`: Rate limit exceeded. Wait the number of seconds in Retry-After. - `500`: Unexpected error. Retry later and quote request_id if it persists. ## Get a person's parents, partners and children `GET /workspaces/{workspace_id}/people/{person_id}/family` Each relative comes with the family it is linked through. A partner entry with person_id null is a family the person heads alone. Parameters: - `workspace_id` (path, required): The workspace (project) id. - `person_id` (path, required): The person id. Responses: - `200`: The person's close family. - `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. Also: The person does not exist or is not visible. - `429`: Rate limit exceeded. Wait the number of seconds in Retry-After. - `500`: Unexpected error. Retry later and quote request_id if it persists. ## Get tree data from a person `GET /workspaces/{workspace_id}/people/{person_id}/tree` People, families (unions) and the edges between them, walked from the person. Data only, no layout. Parameters: - `workspace_id` (path, required): The workspace (project) id. - `person_id` (path, required): The person id. - `direction` (query, optional): ancestors, descendants or both (default both). - `depth` (query, optional): Generations to walk, 1 to 8 (default 4). - `parents` (query, optional): For a person with more than one set of parents, which family to climb: comma-separated person_id.family_id pairs. Malformed pairs are ignored. Responses: - `200`: The tree data. - `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. Also: The person does not exist or is not visible. - `422`: Invalid direction or depth. - `429`: Rate limit exceeded. Wait the number of seconds in Retry-After. - `500`: Unexpected error. Retry later and quote request_id if it persists. ## List records a person should have `GET /workspaces/{workspace_id}/people/{person_id}/expected-records` Open research targets (for example a census the person should appear in), highest priority first. Parameters: - `workspace_id` (path, required): The workspace (project) id. - `person_id` (path, required): The person 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 expected records. - `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. Also: The person does not exist or is not visible. - `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. ## Add a relative `POST /workspaces/{workspace_id}/people/{person_id}/relatives` Link the person to a partner, parent, child, sibling or associate: an existing person (person_id) or a new one created in the same request (new_person). Same rules as the app, including the plan's person limit. Matching is queued, never run inline. 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. - `person_id` (path, required): The person 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`: Linked to an existing person. - `201`: A new person was created and linked. - `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). Also: the plan's person limit is reached (details: limit, used, plan). - `404`: The workspace does not exist or is not visible to this key's owner. Also: A person or the family 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 family's partner or parent slot is already taken. - `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid body, a field sent for the wrong type, a person linked to themselves, or a link the family rules refuse. - `429`: Rate limit exceeded. Wait the number of seconds in Retry-After. - `500`: Unexpected error. Retry later and quote request_id if it persists. ## Remove a relationship `DELETE /workspaces/{workspace_id}/people/{person_id}/relatives` The people are not deleted. Removing a link that does not exist changes nothing. 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. - `person_id` (path, required): The person 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`: Removed. - `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: Invalid body, or the same person twice. - `429`: Rate limit exceeded. Wait the number of seconds in Retry-After. - `500`: Unexpected error. Retry later and quote request_id if it persists. ## Undo a merge `POST /workspaces/{workspace_id}/people/{person_id}/unmerge` The path person must be the merge's survivor. A group merge is undone as a whole. 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. - `person_id` (path, required): The person 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`: Unmerged. - `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, is not visible, or the person is not its survivor. - `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 not a merge (nothing to unmerge). - `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. ## Dismiss an expected record `PATCH /workspaces/{workspace_id}/expected-records/{expected_record_id}` { dismissed: true } is the only change allowed. 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. - `expected_record_id` (path, required): The expected record 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`: Dismissed. - `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 expected record 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. - `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/people