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.

Body

application/json

Count this environment's assessments created in [from,to) by bucket, from counts kept as each assessment is first answered, not by scanning assessments. Each assessment counts once, by its first answer (the answer served when it was first answered); later revisions and late results do not count it again, and late_flips counts its later account decision changes. from and to start a bucket (an hour, or a day or a week from Monday that starts at midnight in time_zone, UTC by default), cover at most 366 days (31 for hour buckets, 92 for day and week buckets in a time_zone other than UTC) and from is inside the retention period. The filters are POST /v1/assessments/search's and describe the first answer, so a cell drills down to search with the same filters, revision first and the cell's bucket as from and to. Counts hold no identifier and stay when an assessment or account is deleted or erased; they expire with retention and go with the workspace. Reasons are counted by code and impact band, not by weight. No Idempotency-Key. Select retained_first_answers for exact facet filters and pairs over retained detail. This mode supports count, score_histogram and score_outcomes, and refuses late_flips. It has a 31-day and 100000-record work budget.

from
string<date-time>
required

The first bucket's start.

to
string<date-time>
required

The end, excluded: the start of the bucket after the last.

bucket
enum<string>
required

The period each count covers: an hour, or a day or a week (from Monday) in time_zone. Hour buckets are whole UTC hours in any time zone.

Available options:
hour,
day,
week
time_zone
string
default:UTC

The IANA time zone whose local midnight starts each day and week bucket, such as Europe/London or Asia/Kolkata; daylight saving changes make those days 23 or 25 hours long. A name the zone database does not know is refused (400 invalid_request naming time_zone). Day and week buckets in a zone other than UTC cover at most 92 days (400 invalid_request naming to); a year of them reads too many hourly counts to answer in time. Hour buckets stay whole UTC hours. Bucket starts, from and to stay instants. With the default population, a zone whose local midnight falls inside a UTC hour (a half-hour offset such as Asia/Kolkata) is refused for day and week buckets, as those counts are kept by the hour; retained_first_answers counts it.

Maximum string length: 64
Pattern: ^(?:UTC|[A-Za-z_]+(?:/[A-Za-z0-9_+.-]+)+)$
group_by
enum<string>[]

At most two dimensions to count by, of which at most one is reason, lane, country or asn. An assessment counts once in each of its reasons and incomplete lanes, so those groups can add up to more than the bucket's count. With population retained_first_answers, both dimensions can be facets; counts cover retained first answers only.

Maximum array length: 2

decision, recommendation and band: the first answer's. flow: the assessment's. list_match: the action of the list entry that decided the account when it was first answered. reason: a reason the first answer fired, with its impact band. lane: an evidence lane the first answer listed in incomplete_sources. country and asn: the submitted IP's, from the IP data.

Available options:
decision,
flow,
recommendation,
band,
reason,
lane,
country,
asn,
list_match
metrics
enum<string>[]

count: each bucket's count and groups. score_histogram: first answers by flow and 5-point score bucket. score_outcomes: the histogram's first answers that have a reported outcome, by flow, 5-point score bucket and the latest outcome reported for the assessment (POST /v1/assessments/{assessment_id}/outcomes); the rest of a bin has none reported. late_flips: changes of an assessment's account decision for its flow after its first answer, by from, to and delay.

Required array length: 1 - 4 elements
Available options:
count,
score_histogram,
score_outcomes,
late_flips
limit
integer
default:20

The most groups answered: the largest over the whole range, then by value. groups_truncated says when there were more.

Required range: 1 <= x <= 100
flow
enum<string>

The event an assessment is made for: account_creation (a user creates an account), login (a user returns to an existing account) or purchase (a payment or a credit grant). The account's risk is reported with the decision for this flow.

Available options:
account_creation,
login,
purchase
status
enum<string>

The first answer's status.

Available options:
complete,
partial,
pending
recommendation
enum<string>

The first answer's recommendation.

Available options:
allow,
step_up,
review
decision
enum<string>

The first answer's decision: block when its risk.block was true, otherwise its recommendation. Combined with recommendation using AND.

Available options:
allow,
step_up,
review,
block
revision
enum<string>

Always first: the aggregate counts first answers. Accepted so a filter can be sent to search unchanged; latest is refused.

Available options:
latest,
first
population
enum<string>
default:first_answers

first_answers uses anonymous counters that can include erased detail. retained_first_answers computes exact intersections over retained first answers within 31 days. Requests exceeding the 100000-record work budget are refused.

Available options:
first_answers,
retained_first_answers
band
enum<string>
Available options:
low,
medium,
high,
critical
reason
enum<string>
required if impact is set

A reason fired by the selected stored revision.

Available options:
no_digital_footprint,
voip_number,
disposable_email,
new_email,
no_email_matches,
spam_reports,
fraud_flag,
identity_mismatch,
country_mismatch,
proxy_ip,
seen_before,
shared_ip,
many_recent_accounts,
established_accounts,
aged_identity,
breach_name_match,
breach_cooccurrence,
breach_name_mismatch,
breach_phone_mismatch,
recent_password_exposure,
credential_list_exposure,
abuse_ecosystem_member,
no_breach_history,
automation_fast_submit,
client_clock_skew,
bot_or_automation,
auth_email_verified,
auth_phone_verified,
auth_mfa_recent,
auth_new_session,
auth_new_account,
auth_impersonated,
context_timezone_mismatch,
context_locale_mismatch,
context_line_country_mismatch,
prior_abuse_link,
test_scenario,
shared_api_key,
list_match,
young_email_domain,
email_domain_no_mx,
email_domain_nonexistent,
google_account_missing,
google_empty_account,
google_active_profile,
google_aged_account,
google_name_match,
google_name_mismatch,
google_country_match,
google_country_mismatch,
forum_sanctioned,
prior_payment_abuse,
ip_history_match,
identity_attribute_conflict,
impossible_identity_age,
breach_shared_ip,
nationality_mismatch,
minor_identity,
reported_account_abuse,
breach_city_match,
breach_city_mismatch
impact
enum<string>

The selected reason's served impact band. Requires reason.

Available options:
none,
low,
medium,
high
lane
enum<string>

An incomplete lane in the selected stored revision.

Available options:
accounts,
phone,
breach,
domain,
ip
country
string
Pattern: ^[A-Z]{2}$
asn
integer
Required range: 1 <= x <= 4294967295
score_min
integer

Inclusive lower score bound. Pending answers without a score do not match.

Required range: 0 <= x <= 100
score_max
integer

Inclusive upper score bound, at least score_min when both are supplied.

Required range: 0 <= x <= 100
list_match
enum<string>

The list action captured at the first answer. Requires revision first. Older answers without captured list state do not match, including none.

Available options:
allow,
block,
none

Response

Counts of first answers per bucket.

Body of the 200 answer to POST /v1/assessments/aggregate: one entry per bucket of [from,to), empty buckets included. Counts are of first answers and stay when an assessment or account is deleted or erased; search returns only assessments still retained.

schema_version
any
required

Version of the body shape.

from
string<date-time>
required
to
string<date-time>
required
bucket
enum<string>
required
Available options:
hour,
day,
week
group_by
enum<string>[]
required
Maximum array length: 2

decision, recommendation and band: the first answer's. flow: the assessment's. list_match: the action of the list entry that decided the account when it was first answered. reason: a reason the first answer fired, with its impact band. lane: an evidence lane the first answer listed in incomplete_sources. country and asn: the submitted IP's, from the IP data.

Available options:
decision,
flow,
recommendation,
band,
reason,
lane,
country,
asn,
list_match
metrics
enum<string>[]
required
Required array length: 1 - 4 elements
Available options:
count,
score_histogram,
score_outcomes,
late_flips
time_zone
string
required

The time zone whose local midnight started each day and week bucket, as requested; UTC when the request named none.

Maximum string length: 64
retention_days
integer
default:365
required

The calling workspace's configured retention period in days. Default 365 (12 months), which is also the maximum: a workspace may only shorten it, to at least 1 day. Each record expires from its own created_at; see assessment expires_at.

Required range: 1 <= x <= 365
groups_truncated
boolean
required

true when more groups had counts than limit allowed.

buckets
object[]
required
Maximum array length: 744
coverage
object

Captured in the same database snapshot as the counts. Capture start times describe when counting began, not the earliest creation time counted: an older assessment may first answer later. Older outcomes are not inferred to be absent. Erased detail cannot be returned by drill-down even while its anonymous count remains.