Skip to navigation
Identity verification APIEvents and Signals

Submit an event for scoring

Scores one transaction or customer action and returns the decision. This is the compatibility endpoint for the older free-form event shape; new integrations should use the transactions and activities endpoints of the Risk Intelligence API.

Idempotency. externalEventId is the idempotency key within your organisation and environment. Sending the same event again returns the stored decision with status 200 and does not score, alert or bill a second time. Reusing the identifier with different content is refused with 409.

Status. A recognised activity type returns 201 when first assessed and 200 on a replay. Every other event type returns 200. With async: true where queued scoring is available the response is 202 and the decision is delivered by the event.flagged webhook.

Side effects. A decision other than ALLOW can raise or update an alert, returned as alertId. Events scored outside the recognised activity types also fire the event.flagged webhook for a REVIEW or BLOCK decision. When monitoring is switched off for your organisation the event is accepted and answered ALLOW with an empty id, and nothing is stored.

Billing. Scoring is billed in production only, where event monitoring is billed for your organisation. Sandbox events are free, and a replay is never billed again.

Error codes

errorStatusMeaning
invalid_request400The body failed validation. details carries the field-level breakdown.
insufficient_wallet402The credit balance cannot cover the assessment. activityId names the held activity.
subject_not_found404The customer could not be resolved in this organisation and environment.
idempotency_conflict409The externalEventId was already used for different content.
transaction_id_conflict409The transaction identifier was already used for a different transaction.
secret_key_required403A publishable key was used. This API accepts secret keys only.
environment_mismatch403The key belongs to an environment this host does not serve.
rate_limited429The request rate limit for this key was reached. Retry after a short wait.
rate_limit_store_unavailable503Rate limiting is temporarily unavailable. Retry shortly.

A missing or unknown key returns 401 with a plain sentence in error rather than a code.

Any other assessment failure is also returned as 503 with its own code in error; retry with the same identifiers.

Requires a secret (sk_) key. A publishable key receives 403 secret_key_required.

Authentication

AuthorizationBearer
Send the API key as a Bearer token. Each operation states whether a publishable key is enough or a secret key is required.

Headers

X-Request-IdstringOptional
Your own request identifier, recorded with the assessment.

Request

This endpoint expects an object.
externalUserIdstringRequired>=1 character
Your own reference for the customer the event belongs to.
externalEventIdstringRequired>=1 character
Your own unique identifier for the event. It is the idempotency key.
typestringRequired>=1 character

A free-form event name, such as transaction.transfer or session.login. Names containing transaction, payment, transfer, login, sign-in, sign-up, register, password reset, beneficiary add, profile change, device change, payout or withdraw are assessed as that kind of activity.

datamap from strings to anyOptional

Free-form details used for scoring. Recognised keys include amount, currency, direction, counterparty, channel, method, country, transactionId, deviceHash and location (city, region, country, latitude, longitude, accuracyRadiusKm). A transaction-like event is assessed as a transaction only when both amount and currency are present.

asyncbooleanOptional

Set to true to queue the event and receive the decision by webhook instead of in the response. Honoured only where queued scoring is available; otherwise the event is scored in the request as usual.

Response

The event was scored, or a stored decision was replayed.
idstring
The identifier of the stored event or activity. Empty when monitoring is switched off for your organisation.
decisionstring

The verdict in upper case: ALLOW, REVIEW or BLOCK. An event that could not be scored yet returns PENDING, RESCORING or PENDING_CREDIT, which are not verdicts; send the same event again later.

riskScoredouble

The risk score. Events assessed as a recognised activity return a value from 0 to 1; all other events return a value from 0 to 100.

alertIdstring or null

The identifier of the alert raised or updated by this event, when the decision was not ALLOW.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error
503
Service Unavailable Error