Resources
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 sendcompany, 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
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 requiresIdempotency-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 effectiveexpires_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 produceperson.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.