Skip to main content
The new interface gives a person a workspace identity and investigation history. A group holds memberships and its own review context. Account assessment and auth integration calls keep their existing behavior. This guide describes the released API and SDK change. Use SDK 14.x for Node, Python, Go, Java, C# and Ruby, 15.x for PHP, and 0.14 for MCP. Each SDK page shows its current published version.

Change the group path

Replace /v1/workspaces/{workspace_id}/groups/{environment} with /v1/groups. Keep the suffix for the group, person or screening. The API key selects its workspace and environment. A test key still cannot read live data. The old paths retire at the coordinated cutover. No ongoing compatibility route is part of the new public contract. Keep the same key, resource ids and idempotency keys when moving an existing integration. The console’s authenticated backend sends NR-Workspace and NR-Environment to select a workspace. Customer API keys need neither header. A header cannot move a key into another workspace.

Update SDK calls

Delete workspace and environment arguments from every group method. Keep arguments for the group, person, screening, body, cursor and idempotency key. Each SDK adds people and investigations services. The quickstart shows the API flow. Each SDK page starts with a typed person and investigation example. Keep a stable idempotency key in your own request record. An SDK-generated key protects retries within that call. Repeating the SDK or MCP call without your saved key can create new work.

Reuse a workspace person

Create a standalone person with POST /v1/people. Add them to a group by sending person_id in the group’s people batch. You can use the same person in several groups. Your external_id now identifies a person throughout the workspace environment. It is no longer a ticket number local to one group. Use distinct references for distinct people. Email and phone matches return suggested_matches. They never merge records. Select an explicit person id after checking a suggestion. Conflicting customer references return 409 person_reference_conflict. A reference-only request keeps stored identity. If you send new identity details, send the complete details you want to retain. The new details replace the submitted identity and reset affected memberships for screening. Earlier investigations remain historical results. Migration preserves existing people and evidence. It does not infer that two old group rows are one person from matching identifiers. An ambiguous old customer reference needs an explicit person id.

Read investigation history

Start a job with POST /v1/investigations and save its inv_ id. A new idempotency key starts a new job. Repeating the same key and input returns that retained job without repeating billable work. Read a specific job with GET /v1/investigations/{investigation_id}. List history with GET /v1/investigations?person_id=.... The person’s report identifies its latest retained evidence result in evidence_investigation. The report also includes retained follow-up search evidence. A specific investigation report preserves that job’s own result. Completed results include all collected posts and media, even when no finding cites them. partial keeps incomplete coverage visible. A migrated job can have unknown status when old records cannot prove its outcome. Append a decision under the investigation’s /reviews route. A group decision stays under that group’s /review route. Shared evidence never copies a decision between contexts. Subscribe to investigation.completed for terminal job results. The event carries ids and status metadata. Read evidence with your current permissions and handle duplicate deliveries.

Apply permissions and retention

Separate API key scopes cover reading (people), changes (people_write), work (investigations), decisions (decisions), export (exports) and deletion (delete). Existing groups keys keep non-destructive people access. Full evidence remains the default. An explicit evidence.read denial hides collected records, posts, media, discovered identifiers and review notes. Submitted details, job status, coverage and decision summaries remain available. Each person exposes expires_at from workspace retention. Delete any use of the obsolete group purge_after field. Group dates do not decide when person evidence expires. Import retries do not renew retention. A retry returns 404 when an imported person expires or you delete them. It omits expired or deleted match suggestions. Deleting a group now deletes the group, memberships and group review context. It keeps workspace people and completed investigations. Use DELETE /v1/people/{person_id} when you intend to delete that person and their evidence everywhere in the environment. Person views and exports create per-person audit events. Searches, decisions, changes and deletion also appear in the audit. Logs contain no raw evidence or submitted identifiers.