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.

groups creates and reads groups, adds people, starts and cancels screenings and records decisions on people, in the key's environment.

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.

Path Parameters

workspace_id
string
required

The workspace id. A workspace the acting user is not an active member of answers 404, as do another workspace than an API key's own, a malformed id and a test environment's id. The workspace id, which is also its live environment's workspace id; the test environment's is the same id with:test appended. A workspace created through the API is tnt_ and a 26-character ULID.

Pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]{0,122}$
environment
enum<string>
required

The environment: live or test. Each has its own settings. Any other value answers 400. An API key reads and changes only its own environment's; the other answers 404. The environment the key belongs to. A live key assesses with live sources; a test key answers from the deterministic simulator.

Available options:
live,
test
group_id
string
required
Pattern: ^grp_[0-7][0-9A-HJKMNP-TV-Z]{25}$
person_id
string
required
Pattern: ^per_[0-7][0-9A-HJKMNP-TV-Z]{25}$
search_id
string
required
Pattern: ^srh_[0-7][0-9A-HJKMNP-TV-Z]{25}$

Body

application/json

An empty object.

Response

The search: counting, or queued to run. Read the person after Retry-After to see its status, its count and what it found.

One search a person started on a value of one of a person's records. Nothing searches again by itself.

search_id
string
required
Pattern: ^srh_[0-7][0-9A-HJKMNP-TV-Z]{25}$
record_id
string
required

The record whose value led to the search.

Pattern: ^rec_[0-9a-f]{32}$
field
string
required

The field of that record that holds the value.

Required string length: 1 - 500
kind
enum<string>
required

The kind of the value searched.

Available options:
email,
phone,
username,
person_name,
password,
hash,
ip
value
string
required

The value searched: the field's cleaned value, else as the source wrote it.

status
enum<string>
required

A password or hash search is counting, then counted: rows says how many breach rows hold the value, and nothing runs until a person runs it (POST.../searches/{search_id}/run). Any other search is queued, then running. completed: every source it asked answered. partial: some did not. failed: none answered or none could be asked, which says nothing about whether the value is held anywhere.

Available options:
counting,
counted,
queued,
running,
completed,
partial,
failed
sources
integer
required

How many sources the search asked: the breach search and the account and phone lookups that take the value's kind.

Required range: x >= 0
answered
integer
required

How many of them gave a definite answer, found or not found.

Required range: x >= 0
found
integer
required

How many records the search found. They are among the person report's lookup records, each match naming this search.

Required range: x >= 0
estimated_spend
integer
required

What the search may spend, in US cents, held against the environment's daily screening cap while it runs.

Required range: x >= 0
spent
integer
required

What the search spent, in US cents, metered as screening work.

Required range: x >= 0
requested_by
string
required

Who started the search.

Required string length: 1 - 256
created_at
string<date-time>
required
table
string

The one breach table searched, when the search was of one table.

Required string length: 1 - 500
rows
integer

How many breach rows hold the password or hash, counted before the search runs.

Required range: x >= 0
error_code
enum<string>

Why a failed search found nothing: its sources did not answer, none could be asked, or it could not run before its attempts were spent.

Available options:
not_answered,
no_source,
worker_attempts_exhausted
finished_at
string<date-time>