Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

Your API key, sent as Authorization: Bearer <key>. A key is nrk_live_ or nrk_test_, a 26-character key id, _ and a 43-character secret. Account, audit and usage data stay within the key's environment. Dedicated team scopes apply across the workspace.

assess creates and reads assessments, records outcomes and reports key usage. investigate reads accounts, assessment history and request diagnostics without export or enforcement access. The legacy history scope also permits account exports, submitted identifiers and enforcement reports. delete permits account and assessment deletion.

evidence or detailed adds detailed merged evidence and submitted identifiers where the operation permits them. Neither grants access to the underlying resource alone. exports permits exports with the underlying account or audit scope. audit reads audit events and usage reads usage. audit_manage manages audit streams and retention, and includes audit-read and export authority.

webhooks manages webhook endpoints. integrations manages hosted auth-provider integrations. management manages keys, settings, lists, reviews and policy evaluations in the key's environment. New keys cannot exceed the issuer's effective permissions.

settings reads configuration, previews policy and list changes, runs evaluations and changes retention. Publishing decision policy or changing lists requires settings and policy_publish together, or the legacy management scope.

people reads people, groups and investigations with full evidence by default. people_write changes submitted people, groups and memberships. investigations starts or cancels jobs and screenings. decisions records reviews. exports with people-read access exports rosters. delete deletes people, groups and memberships. Existing groups keys retain non-destructive people access. Explicit evidence.read restrictions withhold collected records, posts, media, discovered identifiers and notes.

members reads the workspace directory. members_manage also administers non-owner members and invitations. These scopes require a live key issued by a current owner with access to both environments. They grant access across the workspace. management does not grant team access. API keys cannot change owners or accept invitations.

A missing, unknown, revoked or expired key answers 401. A valid key without a required scope answers 403.

Headers

Idempotency-Key
string

Opaque request key, 16 to 128 characters. Repeating the key and request returns the same resource in its current state while it is retained. A different request with the same key answers 409. Use a new key for a deliberate new operation. Keys are scoped to the environment and operation; person searches also scope them to the group and person.

Required string length: 16 - 128
Pattern: ^[A-Za-z0-9._:-]{16,128}$

Body

application/json
name
string
required

The person's full name.

Required string length: 1 - 200
external_id
string

Your reference for this person within the workspace environment. Only an explicit reference or person_id can reuse an existing person.

Required string length: 1 - 128
email
string

The person's email.

Required string length: 3 - 254
Pattern: ^[^@\s]+@[^@\s]+$
phone
string

The person's phone in E.164 form.

Pattern: ^\+[1-9][0-9]{6,14}$
company
string

Where the person works.

Required string length: 1 - 200
city
string

Where the person lives.

Required string length: 1 - 100
handles
object[]

Accounts the person is known to hold, at most 20.

Required array length: 1 - 20 elements
person_id
string
Pattern: ^per_[0-7][0-9A-HJKMNP-TV-Z]{25}$

Response

Create or reuse a workspace person.

person
object
required
suggested_matches
object[]
required
Maximum array length: 20
created
boolean
required