---
title: "Events API"
description: "Submit and query product events for risk evaluation."
collection: "api-reference"
slug: "events"
url: "https://naiza.ai/docs/api-reference/events"
markdown: "https://naiza.ai/docs/api-reference/events.md"
full_docs: "https://naiza.ai/docs.md"
product: "Naiza"
base_url: "https://api.naiza.ai/api/v1"
---

# Events API

> Submit and query product events for risk evaluation.

## Table of contents

- [Auth](#auth)
- [Endpoints](#endpoints)
- [Ingest Event (Synchronous)](#ingest-event-synchronous)
- [Ingest Event (Asynchronous)](#ingest-event-asynchronous)
- [Query Events](#query-events)
- [Event Stats](#event-stats)
- [Important Integration Notes](#important-integration-notes)
- [Related Guides](#related-guides)

The Events API supports both synchronous and asynchronous event ingestion plus historical query/stats.

## Auth

`x-api-key` is required for all endpoints on this page.

## Endpoints

- `POST /api/v1/events` (sync)
- `POST /api/v1/events/async` (async queue)
- `GET /api/v1/events`
- `GET /api/v1/events/:id`
- `GET /api/v1/events/stats`

## Ingest Event (Synchronous)

```http
POST /api/v1/events
```

```json
{
  "eventName": "user.login",
  "eventCategory": "AUTHENTICATION",
  "customer": {
    "externalId": "user_123456",
    "email": "user@example.com",
    "metadata": {
      "loyalty_tier": "gold"
    }
  },
  "device": {
    "externalId": "device_abc123",
    "fingerprint": "fp_abcdef12345"
  },
  "ip": "203.0.113.42",
  "country": "US",
  "sessionId": "session_xyz789",
  "metadata": {
    "auth_result": "success"
  },
  "custom_fields": {
    "previous_login_count": 150
  }
}
```

```json
{
  "eventId": "evt_ckm9876543210",
  "decision": "ALLOW",
  "score": 15,
  "eventCategory": "AUTHENTICATION",
  "rulesEvaluated": 5,
  "receivedAt": "2026-04-16T10:30:00.000Z",
  "processingTimeMs": 42.5
}
```

## Ingest Event (Asynchronous)

```http
POST /api/v1/events/async
```

Returns `202 Accepted` with a `jobId`:

```json
{
  "status": "accepted",
  "jobId": "job_ckm1234567890",
  "eventName": "user.register",
  "receivedAt": "2026-04-16T10:30:00.000Z",
  "message": "Event queued for processing. Use the jobId to check status or configure a webhook for results."
}
```

## Query Events

```http
GET /api/v1/events
```

Key query params:

- `page`, `limit`
- `eventName`, `eventCategory`, `decision`
- `customer`, `device`, `country`
- `from`, `to` (Unix timestamp seconds)
- `sortBy`, `sortOrder`

## Event Stats

```http
GET /api/v1/events/stats
```

Returns aggregate counters such as:

- `totalEvents`
- `blockedEvents`
- `eventsUnderReview`
- `uniqueCustomers`
- `uniqueDevices`

## Important Integration Notes

- Previous docs sometimes referenced `/api/v1/events/ingest`; current path is `POST /api/v1/events`.
- `metadata`, `custom_fields`, and legacy `payload` are JSON objects with bounded depth/size.
- Use async ingestion for burst traffic and webhook-based downstream handling.

## Related Guides

- [Event Monitoring Integration](https://naiza.ai/docs/guides/event-monitoring.md)
- [AML Integration Guide](https://naiza.ai/docs/guides/aml-integration.md)

## Related documentation

- [API Overview](https://naiza.ai/docs/api-reference/overview.md) — Base URL, versioning, and high-level API surface.
- [Authentication](https://naiza.ai/docs/api-reference/authentication.md) — API keys, Web SDK tokens, and secure key handling.
- [Web SDK API](https://naiza.ai/docs/api-reference/websdk.md) — Browser SDK endpoints and device signal collection.
- [Sessions API](https://naiza.ai/docs/api-reference/sessions.md) — Session grouping and timeline endpoints.
- [Error Handling](https://naiza.ai/docs/api-reference/errors.md) — Error shapes, status codes, and retry guidance.
- [Rate Limiting](https://naiza.ai/docs/api-reference/rate-limiting.md) — Quota headers and rate-limit behavior.
- [Decisions API](https://naiza.ai/docs/api-reference/decisions.md) — approve / deny / review evaluation and decision payloads (Events API uses ALLOW/REVIEW/BLOCK).
- [Lists API](https://naiza.ai/docs/api-reference/lists.md) — Allowlists, blocklists, and list membership management.

---

*Source: [https://naiza.ai/docs/api-reference/events](https://naiza.ai/docs/api-reference/events) · Full docs: [https://naiza.ai/docs.md](https://naiza.ai/docs.md)*