> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noresponse.org/llms.txt
> Use this file to discover all available pages before exploring further.

# People and investigations

> Retain workspace people, run investigations, share evidence across groups and keep decisions in their own context.

A person exists within one workspace environment. Groups reference that person. An investigation is a job against the person, with its own result and review history.

The API key selects the workspace and environment. Customer requests do not name either in the path. A test key cannot read live data. A key from another workspace receives 404 for your resource ids.

## Resources

| Route | Result |
| - | - |
| `POST /v1/people` | Create a person or reuse an explicit id or reference. |
| `GET /v1/people` | Page through retained people. |
| `GET /v1/people/{person_id}` | Read submitted details, expiry and the latest retained investigation evidence. |
| `DELETE /v1/people/{person_id}` | Delete the person, memberships, evidence and investigation history. |
| `POST /v1/investigations` | Start a job against a person. |
| `GET /v1/investigations` | Page through investigation history. |
| `GET /v1/investigations/{investigation_id}` | Read one job, its result and review history. |
| `POST /v1/investigations/{investigation_id}/reviews` | Append a decision in this investigation's context. |
| `POST /v1/investigations/{investigation_id}/cancel` | Cancel unfinished work. Send an empty JSON object. |

People pages use `after` and `limit`. Investigation pages use `before`, `limit` and an optional `person_id`. Both return `has_more` and `next_cursor`. Pass the cursor as the next request's `after` or `before` value.

## Create and reuse people

Submit at least a name, email, phone or known handle for a new person. You can also send `company`, `city` and your `external_id`.

To reuse a person, send its `person_id` or your existing `external_id`. A reference without new details keeps the stored identity. When you provide identity details, they replace the submitted identity. Send the complete details you want to keep.

The reference belongs to the workspace environment. It is not a ticket number scoped to one group. Conflicting or ambiguous references return 409 and do not merge records.

Email and phone matches return `suggested_matches` with candidate person ids and matching fields. They never reuse or merge a person automatically. Choose an explicit id after reviewing a suggestion.

An identity update does not extend retention. Earlier investigations remain as historical results. A group membership returns to `unscreened` when its submitted identity changes.

## Permissions and evidence

| Scope | Allows |
| - | - |
| `people` | Read people, groups and investigations, including evidence by default. |
| `people_write` | Create or update submitted people, groups and memberships. |
| `investigations` | Start or cancel investigation jobs and group screenings. |
| `decisions` | Record review decisions. |
| `exports` with `people` | Export group roster pages. |
| `delete` | Delete people, groups or memberships. |

Existing `groups` keys keep read, write, investigation and decision permissions. They do not gain export or deletion permission.

Verified workspaces receive full evidence by default. An authorized manager can set `denied_actions: ["evidence.read"]` for a member or key. Restricted responses retain submitted details, job status, coverage and decision summaries. They hide collected records, profiles, posts, media, discovered identifiers and free-text review notes.

`evidence_restricted: true` makes that restriction explicit. Restrictions apply to subsequent requests and survive key rotation. A write-only integration receives no match suggestions or previously retained identity details through creation or retry responses.

## Jobs, retries and decisions

An investigation creation requires `Idempotency-Key`. The same key and input return the same retained job in its current state. Different input with that key returns 409. A new key starts deliberate new work.

Statuses are `queued`, `running`, `completed`, `partial`, `failed`, `cancelled` and `unknown`. `unknown` identifies migrated history whose old records cannot establish a complete job outcome. It does not invent a successful investigation.

`expires_at` is the person's retention deadline. `deadline_at` is the job's execution deadline. A job cannot renew the person or save results after the person expires.

A review sends `decision` as `cleared`, `watch` or `escalated`, with an optional note. Each review appends history in that investigation. A group review applies only in that group's context. Shared source evidence never copies another context's decision.

The person report names its `evidence_investigation`. It combines that result with retained follow-up search evidence for the person. Earlier jobs remain available as their own historical results in investigation history. Deleting a group leaves those jobs available with `group_id: null`.

## Retention and deletion

The workspace retention setting controls each person's expiry, including people outside all groups. The API shows the effective `expires_at` on each person. Shortening retention can shorten that expiry. Extending the setting later cannot revive an expired person.

After expiry, reads return 404. Lists omit the person. Workers stop using the person and refuse late results. Cleanup deletes submitted details, evidence, memberships and investigation history.

Deleting a group deletes its memberships and group review context. It keeps workspace people and completed investigations. Deleting one membership has the same boundary for that membership. Use `DELETE /v1/people/{person_id}` to delete the person everywhere in that environment.

## Audit and webhooks

Person detail reads and list results produce `person.viewed` events. Group exports produce `person.exported` for each person returned. Searches, decisions, changes, deletion and retention cleanup also produce audit events. Events identify the actor and resource, without raw evidence or submitted identifiers.

A protected read fails if its audit cannot be saved. The audit is not a copy of the person's evidence.

`investigation.completed` announces a terminal job result, including cancellation. Person deletion or retention expiry deletes the job and its evidence. Its payload contains ids, status and completion metadata. Read the investigation using current permissions. Check the signature, deduplicate event ids and handle out-of-order delivery as described in [Webhooks](https://docs.noresponse.org/guides/webhooks.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.