> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Monitoring Events in Batch

> Submit up to 500 monitoring events in one request with a per-item outcome, so one malformed event never blocks the rest of the batch.



Create Monitoring Events in Batch API Prompt
        Copy prompt to clipboard



      
      

\<pre>

\`Send up to 500 monitoring events to Didit in one request from my backend, and handle the per-item outcomes.

Endpoint:
POST https://verification.didit.me/v3/events/batch/

Authentication:
Use the x-api-key header with my Didit API key, from my backend only. A scoped key needs transactions: write.

Goal:
\- Flush a queue of events (logins, gameplay rounds, payment steps, chargebacks) in as few requests as possible, without one bad event blocking the others.

Request body (application/json):
\{
"events": [ { ...one event, same envelope as POST /v3/events/... }, ... ]   // 1 to 500 events
}
A bare JSON array of events is also accepted.

Behavior:
\- Each item is validated, stored and evaluated on its own, exactly like POST /v3/events/. A rejected item never rolls back the others.
\- HTTP 201 when no item was rejected, 207 when at least one was. Treat both as success and read results[].
\- results[] has one entry per item in request order, with index pointing into my events array and outcome accepted, replayed or rejected.
\- accepted and replayed items carry the same fields as the single-event response (event_uuid, status, score, rule_matches, correlation_pending, retention_class, expires_at, idempotent_replay).
\- rejected items carry errors keyed by field, in the same shape as the 400 of POST /v3/events/. A reused event_id with different content is reported as a string under errors.event_id. Send event_id in snake_case so a rejected item's results[].event_id is filled.
\- Retry only the rejected items after fixing them. Resending an accepted item is safe: it comes back as replayed.
\- occurred_at must still be within 7 days in the past and 5 minutes in the future for every item.

Example call:
curl -X POST "https://verification.didit.me/v3/events/batch/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"events":[{"event_id":"login-2026-10-17-000001","event_category":"auth","action_type":"login","occurred_at":"2026-10-17T09:15:02.481Z","subject":{"vendor_data":"user-42"}}]}'

What to read from the response:
\- accepted_count, replayed_count, rejected_count.
\- results[].index and results[].outcome.
\- results[].errors for rejected items.
\- results[].event_uuid and results[].status for stored items.

Failure modes:
\- 400 - events missing, not an array, empty, or longer than 500 items ({ "events": "<message>" }). Nothing is stored; split the batch.
\- 429 - more than 300 writes per minute for this API key; honor Retry-After.
\- 401 - the API key has expired.
\- 403 - missing or invalid API key, a scoped key without transactions: write, or code event_monitoring_disabled (event ingestion is not switched on; nothing is stored).

Side effects: stores every valid item, may create subjects, and applies the actions of matched active rules.

For the full integration shape, see /integration/integration-prompt.`

\</pre>



      
      

Paste into

See [Batches](/transaction-monitoring/events.md#batches) in the event ingestion guide. The device lane has the same per-item outcomes for SDK flushes: see [SDK event submission](/transaction-monitoring/sdk-event-submission.md#batching).


## OpenAPI

````yaml POST /v3/events/batch/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: Identity verification API. Authenticate with x-api-key header.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/events/batch/:
    post:
      tags:
        - Monitoring Events
      summary: Create monitoring events in batch
      description: >-
        Submit 1 to 500 events in one request, each in the same envelope as
        `POST /v3/events/`. Every item is validated, stored and evaluated on its
        own and gets its own outcome (`accepted`, `replayed` or `rejected`), so
        one malformed event never rolls back the others: the response is `201`
        when no item was rejected and `207` when at least one was, and both mean
        the request was processed. Send `{"events": [...]}`; a bare JSON array
        of events is also accepted. Event ingestion must be switched on for the
        application, otherwise the whole request returns `403` with `code:
        event_monitoring_disabled` and nothing is stored. A scoped API key needs
        `transactions: write`. See
        [Batches](https://docs.didit.me/transaction-monitoring/events#batches).
      operationId: create_monitoring_events_batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - events
              properties:
                events:
                  type: array
                  minItems: 1
                  maxItems: 500
                  description: >-
                    1 to 500 events. Each item follows
                    `MonitoringEventCreateRequest`, including the 7-day past and
                    5-minute future window on `occurred_at`.
                  items:
                    $ref: '#/components/schemas/MonitoringEventCreateRequest'
            example:
              events:
                - event_id: login-2026-10-17-000001
                  event_category: auth
                  action_type: login
                  occurred_at: '2026-10-17T09:15:02.481Z'
                  subject:
                    vendor_data: user-42
                - event_id: deposit-2026-10-17-000002
                  event_category: payment
                  action_type: deposit_completed
                  occurred_at: '2026-10-17T09:16:40Z'
                  subject:
                    vendor_data: user-42
                  transaction_context:
                    amount: '100.00'
                    currency: EUR
                    payment_reference_id: dep_736
                  payload:
                    payment_method: card
                    status: completed
      responses:
        '201':
          description: 'No item was rejected: every item is `accepted` or `replayed`.'
          content:
            application/json:
              schema:
                type: object
                required:
                  - accepted_count
                  - replayed_count
                  - rejected_count
                  - results
                properties:
                  accepted_count:
                    type: integer
                    minimum: 0
                    description: Items stored and evaluated.
                  replayed_count:
                    type: integer
                    minimum: 0
                    description: Items already stored with the same content.
                  rejected_count:
                    type: integer
                    minimum: 0
                    description: Items not stored.
                  results:
                    type: array
                    description: One entry per item, in request order.
                    items:
                      type: object
                      description: >-
                        Outcome of one item. Accepted and replayed items also
                        carry every field of `MonitoringEventIngestResult`;
                        rejected items carry `event_id` and `errors` instead.
                      required:
                        - index
                        - outcome
                      properties:
                        index:
                          type: integer
                          minimum: 0
                          description: Position of the item in your `events` array.
                        outcome:
                          type: string
                          enum:
                            - accepted
                            - replayed
                            - rejected
                          description: >-
                            `accepted`: stored and evaluated. `replayed`:
                            already stored with the same content. `rejected`:
                            not stored; see `errors`.
                        event_id:
                          type: string
                          nullable: true
                          description: >-
                            Your `event_id`. On items rejected by validation it
                            is read from the item's snake_case `event_id` key,
                            so it is null when the item omitted it or sent the
                            `eventId` alias.
                        errors:
                          type: object
                          additionalProperties: true
                          description: >-
                            Rejected items only. Validation errors keyed by
                            field, in the same shape as the `400` of `POST
                            /v3/events/`; a reused `event_id` with different
                            content is reported as a string under
                            `errors.event_id`.
                        event_uuid:
                          type: string
                          format: uuid
                          description: Accepted and replayed items only.
                        status:
                          type: string
                          enum:
                            - ACCEPTED
                            - APPROVED
                            - IN_REVIEW
                            - DECLINED
                          description: Accepted and replayed items only.
                        score:
                          type: integer
                          description: Accepted and replayed items only.
                        rules_evaluated_count:
                          type: integer
                          description: Accepted and replayed items only.
                        rules_matched_count:
                          type: integer
                          description: Accepted and replayed items only.
                        correlation_pending:
                          type: boolean
                          description: Accepted and replayed items only.
                        retention_class:
                          type: string
                          enum:
                            - low_value
                            - standard
                            - risk_relevant
                            - monetary_or_compliance
                          description: Accepted and replayed items only.
                        expires_at:
                          type: string
                          format: date-time
                          nullable: true
                          description: Accepted and replayed items only.
                        idempotent_replay:
                          type: boolean
                          description: Accepted and replayed items only.
                        rule_matches:
                          type: array
                          description: Accepted and replayed items only.
                          items:
                            type: object
                            required:
                              - rule_id
                              - library_key
                              - mode
                              - is_async
                            properties:
                              rule_id:
                                type: string
                                format: uuid
                                description: UUID of the rule.
                              library_key:
                                type: string
                                nullable: true
                                description: >-
                                  Library key when the rule was installed from
                                  the rules library, otherwise null.
                              mode:
                                type: string
                                enum:
                                  - ACTIVE
                                  - TEST
                                description: >-
                                  `TEST` rules record the match but apply no
                                  actions.
                              is_async:
                                type: boolean
                                description: >-
                                  `true` when the match came from the
                                  asynchronous pass.
              examples:
                All landed:
                  value:
                    accepted_count: 1
                    replayed_count: 1
                    rejected_count: 0
                    results:
                      - index: 0
                        outcome: accepted
                        event_uuid: 33333333-4444-5555-6666-777777777777
                        event_id: login-2026-10-17-000001
                        status: ACCEPTED
                        score: 0
                        rules_evaluated_count: 6
                        rules_matched_count: 0
                        correlation_pending: false
                        retention_class: standard
                        expires_at: '2026-11-16T09:15:02.481000Z'
                        idempotent_replay: false
                        rule_matches: []
                      - index: 1
                        outcome: replayed
                        event_uuid: 11111111-2222-3333-4444-555555555555
                        event_id: deposit-2026-10-17-000002
                        status: ACCEPTED
                        score: 0
                        rules_evaluated_count: 6
                        rules_matched_count: 0
                        correlation_pending: false
                        retention_class: monetary_or_compliance
                        expires_at: null
                        idempotent_replay: true
                        rule_matches: []
        '207':
          description: >-
            At least one item was rejected. The other items were stored; fix and
            resend only the rejected ones (resending an accepted item is safe,
            it comes back `replayed`).
          content:
            application/json:
              schema:
                type: object
                required:
                  - accepted_count
                  - replayed_count
                  - rejected_count
                  - results
                properties:
                  accepted_count:
                    type: integer
                    minimum: 0
                    description: Items stored and evaluated.
                  replayed_count:
                    type: integer
                    minimum: 0
                    description: Items already stored with the same content.
                  rejected_count:
                    type: integer
                    minimum: 0
                    description: Items not stored.
                  results:
                    type: array
                    description: One entry per item, in request order.
                    items:
                      type: object
                      description: >-
                        Outcome of one item. Accepted and replayed items also
                        carry every field of `MonitoringEventIngestResult`;
                        rejected items carry `event_id` and `errors` instead.
                      required:
                        - index
                        - outcome
                      properties:
                        index:
                          type: integer
                          minimum: 0
                          description: Position of the item in your `events` array.
                        outcome:
                          type: string
                          enum:
                            - accepted
                            - replayed
                            - rejected
                          description: >-
                            `accepted`: stored and evaluated. `replayed`:
                            already stored with the same content. `rejected`:
                            not stored; see `errors`.
                        event_id:
                          type: string
                          nullable: true
                          description: >-
                            Your `event_id`. On items rejected by validation it
                            is read from the item's snake_case `event_id` key,
                            so it is null when the item omitted it or sent the
                            `eventId` alias.
                        errors:
                          type: object
                          additionalProperties: true
                          description: >-
                            Rejected items only. Validation errors keyed by
                            field, in the same shape as the `400` of `POST
                            /v3/events/`; a reused `event_id` with different
                            content is reported as a string under
                            `errors.event_id`.
                        event_uuid:
                          type: string
                          format: uuid
                          description: Accepted and replayed items only.
                        status:
                          type: string
                          enum:
                            - ACCEPTED
                            - APPROVED
                            - IN_REVIEW
                            - DECLINED
                          description: Accepted and replayed items only.
                        score:
                          type: integer
                          description: Accepted and replayed items only.
                        rules_evaluated_count:
                          type: integer
                          description: Accepted and replayed items only.
                        rules_matched_count:
                          type: integer
                          description: Accepted and replayed items only.
                        correlation_pending:
                          type: boolean
                          description: Accepted and replayed items only.
                        retention_class:
                          type: string
                          enum:
                            - low_value
                            - standard
                            - risk_relevant
                            - monetary_or_compliance
                          description: Accepted and replayed items only.
                        expires_at:
                          type: string
                          format: date-time
                          nullable: true
                          description: Accepted and replayed items only.
                        idempotent_replay:
                          type: boolean
                          description: Accepted and replayed items only.
                        rule_matches:
                          type: array
                          description: Accepted and replayed items only.
                          items:
                            type: object
                            required:
                              - rule_id
                              - library_key
                              - mode
                              - is_async
                            properties:
                              rule_id:
                                type: string
                                format: uuid
                                description: UUID of the rule.
                              library_key:
                                type: string
                                nullable: true
                                description: >-
                                  Library key when the rule was installed from
                                  the rules library, otherwise null.
                              mode:
                                type: string
                                enum:
                                  - ACTIVE
                                  - TEST
                                description: >-
                                  `TEST` rules record the match but apply no
                                  actions.
                              is_async:
                                type: boolean
                                description: >-
                                  `true` when the match came from the
                                  asynchronous pass.
              examples:
                Partial success:
                  value:
                    accepted_count: 1
                    replayed_count: 0
                    rejected_count: 2
                    results:
                      - index: 0
                        outcome: accepted
                        event_uuid: 33333333-4444-5555-6666-777777777777
                        event_id: login-2026-10-17-000001
                        status: ACCEPTED
                        score: 0
                        rules_evaluated_count: 6
                        rules_matched_count: 0
                        correlation_pending: false
                        retention_class: standard
                        expires_at: '2026-11-16T09:15:02.481000Z'
                        idempotent_replay: false
                        rule_matches: []
                      - index: 1
                        event_id: deposit-2026-10-17-000002
                        outcome: rejected
                        errors:
                          payload:
                            - >-
                              payment.deposit_completed requires:
                              payment_method, status.
                      - index: 2
                        event_id: login-2026-10-16-000777
                        outcome: rejected
                        errors:
                          event_id: >-
                            event_id 'login-2026-10-16-000777' already exists
                            with a different payload.
        '400':
          description: >-
            The batch itself is malformed: `events` is missing or not an array,
            is empty, or has more than 500 items. Nothing is stored; split large
            batches.
          content:
            application/json:
              examples:
                Not a list:
                  value:
                    events: Expected a list of events.
                Empty:
                  value:
                    events: At least one event is required.
                Too many:
                  value:
                    events: A batch accepts at most 500 events; received 612.
        '401':
          description: >-
            The scoped API key has expired. Only an expired key gets `401`; a
            missing or invalid key gets `403`.
          content:
            application/json:
              examples:
                Expired key:
                  value:
                    detail: This API key has expired.
        '403':
          description: >-
            Missing or invalid `x-api-key` (this endpoint answers `403`, never
            `401`, for a missing or invalid key), a scoped key without
            `transactions: write`, a key limited to some workflows or to
            approved sessions (such a key never reaches transaction monitoring
            data), or a request from outside the key's IP allowlist. Also
            returned with `code: event_monitoring_disabled` while event
            ingestion is switched off for the application; nothing is stored in
            that case, and the check runs before the body is validated.
          content:
            application/json:
              examples:
                Event monitoring disabled:
                  value:
                    detail: >-
                      Event monitoring is not enabled for this application. Turn
                      on event ingestion in the transaction monitoring settings
                      before submitting events.
                    code: event_monitoring_disabled
                Missing or invalid API key:
                  value:
                    detail: You do not have permission to perform this action.
                Scoped key without access:
                  value:
                    detail: This API key has no write access to transactions.
                Key limited to workflows or approved sessions:
                  value:
                    detail: >-
                      This API key only reaches sessions inside its workflow or
                      status limits, so it can't use this endpoint.
                IP not allowed:
                  value:
                    detail: This API key can't be used from this IP address.
        '429':
          description: >-
            Rate limit exceeded: write requests (`POST`, `PATCH`, `DELETE`)
            share a budget of 300 requests per minute per API key. Wait
            `Retry-After` seconds, then retry.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                minimum: 1
                example: 30
          content:
            application/json:
              examples:
                Throttled:
                  value:
                    detail: >-
                      Write request rate limit exceeded. You can make up to 300
                      requests per minute.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST 'https://verification.didit.me/v3/events/batch/' \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "events": [
                  {"event_id": "login-2026-10-17-000001", "event_category": "auth", "action_type": "login",
                   "occurred_at": "2026-10-17T09:15:02.481Z", "subject": {"vendor_data": "user-42"}},
                  {"event_id": "deposit-2026-10-17-000002", "event_category": "payment", "action_type": "deposit_completed",
                   "occurred_at": "2026-10-17T09:16:40.000Z", "subject": {"vendor_data": "user-42"},
                   "transaction_context": {"amount": "100.00", "currency": "EUR", "payment_reference_id": "dep_736"},
                   "payload": {"payment_method": "card", "status": "completed"}}
                ]
              }'
        - lang: python
          label: Python
          source: |-
            import os

            import requests

            events = [
                {
                    'event_id': 'login-2026-10-17-000001',
                    'event_category': 'auth',
                    'action_type': 'login',
                    'occurred_at': '2026-10-17T09:15:02.481Z',
                    'subject': {'vendor_data': 'user-42'},
                },
                {
                    'event_id': 'deposit-2026-10-17-000002',
                    'event_category': 'payment',
                    'action_type': 'deposit_completed',
                    'occurred_at': '2026-10-17T09:16:40.000Z',
                    'subject': {'vendor_data': 'user-42'},
                    'transaction_context': {'amount': '100.00', 'currency': 'EUR', 'payment_reference_id': 'dep_736'},
                    'payload': {'payment_method': 'card', 'status': 'completed'},
                },
            ]
            resp = requests.post(
                'https://verification.didit.me/v3/events/batch/',
                headers={'x-api-key': os.environ['DIDIT_API_KEY']},
                json={'events': events},
                timeout=10,
            )
            resp.raise_for_status()  # 201 and 207 are both success
            batch = resp.json()
            for item in batch['results']:
                if item['outcome'] == 'rejected':
                    print('fix and resend', events[item['index']]['event_id'], item['errors'])
        - lang: javascript
          label: JavaScript
          source: >-
            const events = [
              {
                event_id: 'login-2026-10-17-000001',
                event_category: 'auth',
                action_type: 'login',
                occurred_at: '2026-10-17T09:15:02.481Z',
                subject: { vendor_data: 'user-42' },
              },
              {
                event_id: 'deposit-2026-10-17-000002',
                event_category: 'payment',
                action_type: 'deposit_completed',
                occurred_at: '2026-10-17T09:16:40.000Z',
                subject: { vendor_data: 'user-42' },
                transaction_context: { amount: '100.00', currency: 'EUR', payment_reference_id: 'dep_736' },
                payload: { payment_method: 'card', status: 'completed' },
              },
            ];

            const resp = await
            fetch('https://verification.didit.me/v3/events/batch/', {
              method: 'POST',
              headers: {
                'x-api-key': process.env.DIDIT_API_KEY,
                'Content-Type': 'application/json',
              },
              body: JSON.stringify({ events }),
            });

            if (!resp.ok) throw new Error(await resp.text()); // 201 and 207 are
            both ok

            const batch = await resp.json();

            for (const item of batch.results) {
              if (item.outcome === 'rejected') console.log('fix and resend', events[item.index].event_id, item.errors);
            }
components:
  schemas:
    MonitoringEventCreateRequest:
      type: object
      description: >-
        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`.
      required:
        - event_id
        - event_category
        - action_type
        - occurred_at
        - subject
      properties:
        event_id:
          type: string
          maxLength: 128
          description: >-
            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.
          example: login-2026-10-17-000001
        event_category:
          type: string
          enum:
            - auth
            - session
            - gameplay
            - bonus
            - affiliate
            - payment
            - dispute
            - security
            - responsible_gambling
            - custom
          description: Event category.
          example: auth
        action_type:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            What happened within the category. Open vocabulary; the managed
            actions listed in [Event
            ingestion](https://docs.didit.me/transaction-monitoring/events) (for
            example `login`, `deposit_completed`, `chargeback_opened`) unlock
            typed validation and managed rule fields. Leading and trailing
            whitespace is trimmed.
          example: login
        occurred_at:
          type: string
          format: date-time
          description: >-
            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'
        time_zone:
          type: string
          nullable: true
          maxLength: 64
          description: >-
            Time zone of the occurrence on your side, for example
            `Europe/Madrid`. Stored with the event; not returned by the read
            endpoints.
        subject:
          type: object
          description: >-
            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.
          required:
            - vendor_data
          properties:
            vendor_data:
              type: string
              minLength: 1
              maxLength: 255
              description: Your id for the subject.
              example: user-42
            entity_type:
              type: string
              maxLength: 32
              default: individual
              description: >-
                `company` resolves the subject to a company; any other value
                (default `individual`) resolves it to an individual. The same
                `vendor_data` can name one of each.
              example: individual
            full_name:
              type: string
              nullable: true
              maxLength: 512
              description: >-
                Display name, used only when this event creates the user or
                company.
            email:
              type: string
              format: email
              nullable: true
              description: Validated as an email address; not stored on the event.
            phone:
              type: string
              nullable: true
              maxLength: 32
              description: Validated; not stored on the event.
            country:
              type: string
              nullable: true
              maxLength: 3
              description: Validated; not stored on the event.
        business:
          type: object
          description: >-
            The business the event belongs to, when it differs from the subject.
            Only `vendor_data` is read.
          additionalProperties: true
          properties:
            vendor_data:
              type: string
              maxLength: 255
              description: Your id for the business. Filterable as `business_vendor_data`.
              example: merchant-7
        session:
          type: object
          description: Your session context for the event.
          properties:
            session_id:
              type: string
              nullable: true
              maxLength: 255
              description: >-
                Your session identifier. Filterable and returned as
                `session_id`.
            sequence:
              type: integer
              nullable: true
              description: >-
                Position of the event within the session. Returned as
                `session_sequence`.
            page_url:
              type: string
              nullable: true
              maxLength: 2048
              description: Validated; not stored on the event.
            referrer:
              type: string
              nullable: true
              maxLength: 2048
              description: Validated; not stored on the event.
        device_context:
          type: object
          additionalProperties: true
          description: >-
            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.
          properties:
            fingerprint:
              type: string
              maxLength: 255
              description: Device fingerprint. Filterable as `device_fingerprint`.
            persistent_device_id:
              type: string
              maxLength: 255
              description: Your persistent device identifier.
            bot_score:
              type: integer
              description: Bot score from your own detection, as an integer.
            network_context:
              type: object
              additionalProperties: true
              properties:
                ip_address:
                  type: string
                  maxLength: 64
                  description: >-
                    End user's IP address. Public addresses are enriched once
                    per unique address.
                  example: 203.0.113.42
        transaction_context:
          type: object
          description: >-
            Money context. Non-empty values here also satisfy the required
            payload keys of the action.
          properties:
            amount:
              type: string
              nullable: true
              description: Amount as a decimal string (a number is also accepted).
              example: '1000.00'
            currency:
              type: string
              nullable: true
              maxLength: 10
              description: Currency code.
            direction:
              type: string
              nullable: true
              maxLength: 16
              description: >-
                Direction of the money movement, for example `inbound` or
                `outbound`.
            payment_reference_id:
              type: string
              nullable: true
              maxLength: 255
              description: Your payment reference. Filterable as `payment_reference_id`.
        payload:
          type: object
          additionalProperties: true
          description: >-
            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:
          type: object
          description: >-
            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.
          additionalProperties:
            nullable: true
            oneOf:
              - type: string
              - type: number
              - type: boolean
      example:
        event_id: login-2026-10-17-000001
        event_category: auth
        action_type: login
        occurred_at: '2026-10-17T09:15:02.481Z'
        time_zone: Europe/Madrid
        subject:
          vendor_data: user-42
          entity_type: individual
        session:
          session_id: web-session-abc
          sequence: 142
        device_context:
          fingerprint: fp-a8c1
          network_context:
            ip_address: 203.0.113.42
        payload:
          method: password
        custom_values:
          vip_tier: gold
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.