Skip to main content
POST
curl
Event ingestion is opt-in. Switch it on in Transactions > Settings > Event monitoring before you send events; until then this endpoint answers 403 with "code": "event_monitoring_disabled".
Event ingestion covers the envelope, the ten categories, the required payload keys and the retention classes. Rules on events explains which rules run in the request and which run asynchronously. To send events from a browser or app instead of your backend, use SDK event submission.

Authorizations

​
x-api-key
string
header
required

Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is missing, wrong, revoked or expired; 403 means the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys.

Body

application/json

The event envelope, the same for every category. camelCase aliases are accepted: eventId, eventCategory (or category), actionType, occurredAt, timeZone (or zoneId), deviceContext (or device), transactionContext, customValues (or props); inside subject: vendorData, entityType, fullName; inside session: sessionId, pageUrl; inside transaction_context: paymentReferenceId.

​
event_id
string
required

Your identifier for the event, unique per application. It is the idempotency key: resending the same event_category, action_type, occurred_at, subject.vendor_data and payload under it is a replay, anything different is a conflict.

Maximum string length: 128
Example:

"login-2026-10-17-000001"

​
event_category
enum<string>
required

Event category.

Available options:
auth,
session,
gameplay,
bonus,
affiliate,
payment,
dispute,
security,
responsible_gambling,
custom
Example:

"auth"

​
action_type
string
required

What happened within the category. Open vocabulary; the managed actions listed in Event ingestion (for example login, deposit_completed, chargeback_opened) unlock typed validation and managed rule fields. Leading and trailing whitespace is trimmed.

Required string length: 1 - 128
Example:

"login"

​
occurred_at
string<date-time>
required

When the event happened on your side, ISO 8601 (a value without an offset is read as UTC). Must be no more than 7 days in the past and no more than 5 minutes in the future.

Example:

"2026-10-17T09:15:02.481Z"

​
subject
object
required

The user or company the event belongs to. It resolves to the user (or company) with this vendor_data in your application; one is created when none exists.

​
time_zone
string | null

Time zone of the occurrence on your side, for example Europe/Madrid. Stored with the event; not returned by the read endpoints.

Maximum string length: 64
​
business
object

The business the event belongs to, when it differs from the subject. Only vendor_data is read.

​
session
object

Your session context for the event.

​
device_context
object

Device and network context, stored as sent and returned by GET /v3/events/{event_uuid}/. On this server lane Didit does not see the end user's connection, so the IP enriched and used by rules is network_context.ip_address as you send it.

​
transaction_context
object

Money context. Non-empty values here also satisfy the required payload keys of the action.

​
payload
object

The category's domain fields, at most 16384 bytes once JSON-encoded. Some actions require keys (in payload or transaction_context): gameplay.p2p_settlement needs game_id, counterparty_vendor_data, stake_amount, net_result_amount, role and one of hand_id, round_id, match_id; gameplay.bet_placed and gameplay.bet_settled need game_id; payment.deposit_initiated, payment.deposit_completed, payment.withdrawal_requested and payment.withdrawal_completed need payment_reference_id, amount, currency, payment_method, status; payment.withdrawal_address_changed needs withdrawal_address_hash; dispute.chargeback_opened, dispute.chargeback_won and dispute.chargeback_lost need payment_reference_id and one of dispute_id, chargeback_id; session.bot_signal_observed needs telemetry_schema_version and one of bot_score, actions_per_minute, timing_variance_ms, pointer_entropy, keystroke_entropy, reaction_time_ms_p50; responsible_gambling.self_exclusion_match needs registry_source, exclusion_status, identity_match_ref. Every security action ending in _changed needs changed_field, plus previous_reference_hash or new_reference_hash when the field is password, mfa_method, mfa, email, phone, withdrawal_address, payout_method or api_key. Send hashes and references, never a card number, a full withdrawal address, a password hash or an MFA secret.

​
custom_values
object

Up to 100 keys of your own, addressable from rules as custom_values.<key>. Values must be scalars (string, number, boolean or null); nested objects and arrays are rejected.

Response

Idempotent replay: an event with this event_id and the same content is already stored. Nothing was stored or evaluated again; the body describes the stored event.

Outcome of ingesting one event. The same shape is returned for a new event and for an idempotent replay.

​
event_uuid
string<uuid>
required

Didit identifier of the stored event.

​
event_id
string
required

Your event_id.

​
status
enum<string>
required

Status after the real-time rules ran. See MonitoringEvent.status.

Available options:
ACCEPTED,
APPROVED,
IN_REVIEW,
DECLINED
​
score
integer
required

Score after the real-time rules ran.

​
rules_evaluated_count
integer
required

Number of event rules evaluated in the request. 0 in a sandbox application, where no rules run.

Required range: x >= 0
​
rules_matched_count
integer
required

Number of rules that matched, including TEST mode rules.

Required range: x >= 0
​
correlation_pending
boolean
required

true when an asynchronous rule still has to run. Read GET /v3/events/{event_uuid}/ a few minutes later for the final status and score.

​
retention_class
enum<string>
required

Retention class, after any promotion by a matched rule.

Available options:
low_value,
standard,
risk_relevant,
monetary_or_compliance
​
expires_at
string<date-time> | null
required

When the event expires under its retention class and is deleted. Null for monetary_or_compliance (payment and dispute) events.

​
idempotent_replay
boolean
required

true when an event with this event_id and the same content was already stored; the values are those of the stored event and no rule ran again.

​
rule_matches
object[]
required

Rules that matched the event.