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

Body

application/json

POST /v1/workspaces/{workspace_id}/lists/{environment} body. Adds one entry to the environment's list and, in the same change, re-decides every account it matches: each sends account.risk_changed when a decision changes. Needs the admin or owner role, or a management key of the environment.

kind
enum<string>
required

email matches one address, whatever the case of its local part. email_domain matches every address of the registrable domain and of its subdomains.

Available options:
email,
email_domain
value
string
required

An email address for kind email, written as in an assessment request; an LDH domain (A-label for an internationalised one) such as example.com for kind email_domain, which must sit below a public suffix (co.uk alone is refused with 400). NoResponse stores it in canonical form and answers that form.

Required string length: 3 - 254
Pattern: ^[^\s\x00-\x1f\x7f]+$
action
enum<string>
required

block decides block for the accounts the entry matches; allow decides allow. Block wins when both match.

Available options:
block,
allow
note
string

Why the entry exists, for the people who manage the list. It is shown with the entry and decides nothing.

Maximum string length: 200
Pattern: ^[^\x00-\x1f\x7f]*$
expires_at
string<date-time>

Optional expiry. An expired entry stops matching immediately; bounded maintenance removes it and propagates account risk changes.

Response

The entry, added, with its value in canonical form. Every account it matches was re-decided in the same change.

One entry of an environment's list: an exact email or an email domain that decides an account whatever its score. An account matches when one of its admitted assessments sent the email, or an email of the domain. A block entry decides block for every flow and an allow entry decides allow; when both match, block wins. The account's risk carries the list_match reason with the entry's id, and its score stays the one the assessment's facts give. A held flow still waits for its investigation.

id
string
required

The entry's id: lst_ and a ULID.

Pattern: ^lst_[0-7][0-9A-HJKMNP-TV-Z]{25}$
workspace_id
string
required

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 the key belongs to. A live key assesses with live sources; a test key answers from the deterministic simulator.

Available options:
live,
test
kind
enum<string>
required

email matches one address, whatever the case of its local part. email_domain matches every address of the registrable domain and of its subdomains.

Available options:
email,
email_domain
value
string
required

The value the entry matches, in canonical form: an email lower-cased whole, or a domain lower-cased and taken to its registrable domain (mail.example.co.uk is stored as example.co.uk).

Required string length: 3 - 254
Pattern: ^[^\s\x00-\x1f\x7f]+$
action
enum<string>
required

block decides block for the accounts the entry matches; allow decides allow. Block wins when both match.

Available options:
block,
allow
created_at
string<date-time>
required
created_by
string
required

The external user id of the member who added the entry through the console, or the prefix (nrk__) of the management key that added it.

Required string length: 1 - 256
Pattern: ^[!-~]{1,256}$
note
string

Why the entry exists, for the people who manage the list. It is shown with the entry and decides nothing.

Maximum string length: 200
Pattern: ^[^\x00-\x1f\x7f]*$
expires_at
string<date-time>

Optional expiry. An expired entry stops matching immediately; bounded maintenance removes it and propagates account risk changes.