---
title: "Decisions API"
description: "approve / deny / review evaluation and decision payloads (Events API uses ALLOW/REVIEW/BLOCK)."
collection: "api-reference"
slug: "decisions"
url: "https://naiza.ai/docs/api-reference/decisions"
markdown: "https://naiza.ai/docs/api-reference/decisions.md"
full_docs: "https://naiza.ai/docs.md"
product: "Naiza"
base_url: "https://api.naiza.ai/api/v1"
---

# Decisions API

> approve / deny / review evaluation and decision payloads (Events API uses ALLOW/REVIEW/BLOCK).

## Table of contents

- [Auth](#auth)
- [Endpoints](#endpoints)
- [Evaluate Decision](#evaluate-decision)
- [Get Decision by ID](#get-decision-by-id)
- [List Decisions](#list-decisions)
- [Decision Stats](#decision-stats)
- [Integration Notes](#integration-notes)
- [Related Guides](#related-guides)

The Decisions API evaluates risk in real time and supports search/reporting for historical outcomes.

## Auth

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

## Endpoints

- `POST /api/v1/decisions/evaluate`
- `GET /api/v1/decisions/:id`
- `GET /api/v1/decisions`
- `GET /api/v1/decisions/stats`

## Evaluate Decision

```http
POST /api/v1/decisions/evaluate
```

```json
{
  "eventName": "payment.attempt",
  "eventCategory": "TRANSACTION",
  "customer": {
    "externalId": "cust_123456",
    "email": "user@example.com"
  },
  "device": {
    "externalId": "device_abc123",
    "fingerprint": "fp_xyz789"
  },
  "ip": "203.0.113.42",
  "userAgent": "Mozilla/5.0 ...",
  "metadata": {
    "amount": 199.95,
    "currency": "USD"
  }
}
```

```json
{
  "decision": "review",
  "riskScore": 68,
  "riskLevel": "high",
  "reasonCodes": [
    {
      "code": "HIGH_RISK_IP",
      "explanation": "IP address has elevated fraud history"
    }
  ],
  "correlationIds": {
    "requestId": "req_abc123xyz",
    "eventId": "evt_ckm9876543210",
    "customerId": "cus_123456",
    "deviceFingerprint": "fp_xyz789"
  },
  "ruleVersion": {
    "version": "v1.2.3"
  },
  "recommendedActions": [
    {
      "action": "STEP_UP_VERIFICATION",
      "description": "Require OTP challenge"
    }
  ],
  "evaluatedAt": "2026-04-16T10:30:00.000Z"
}
```

Decision enum (lowercase — mapped from internal `ALLOW` / `BLOCK` / `REVIEW`):

- `approve`
- `deny`
- `review`

> Note: the Events API (`POST /api/v1/events`) still returns uppercase `ALLOW` / `REVIEW` / `BLOCK`. Only the Decisions API surface uses this mapped lowercase vocabulary.

## Get Decision by ID

```http
GET /api/v1/decisions/:id
```

Response includes:

- input summary (`inputs`)
- output/rule details (`outputs`)
- linked entities (`linkedEntities`)

## List Decisions

```http
GET /api/v1/decisions
```

Key query params:

- `page`, `limit`
- `decision`, `minScore`, `maxScore`, `riskLevel`
- `customer`, `device`, `country`
- `from`, `to` (Unix timestamp seconds)
- `search`
- `sortBy` (`evaluatedAt`, `riskScore`, `decision`), `sortOrder`

Example:

```http
GET /api/v1/decisions?decision=deny&minScore=60&from=1711833600&page=1&limit=50
```

## Decision Stats

```http
GET /api/v1/decisions/stats
```

Optional query:

- `from` (Unix timestamp seconds)
- `to` (Unix timestamp seconds)

Response contains aggregate totals, rates, top reason codes, and time buckets.

## Integration Notes

- Keep `correlationIds.eventId` for subsequent lookup and support investigation.
- Send stable `eventName` taxonomy (`payment.attempt`, `user.login`, `checkout.submit`) to keep analytics clean.
- Handle `429` and `5xx` with bounded retries and backoff.

## Related Guides

- [Event Monitoring Integration](https://naiza.ai/docs/guides/event-monitoring.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.
- [Events API](https://naiza.ai/docs/api-reference/events.md) — Submit and query product events for risk evaluation.
- [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.
- [Lists API](https://naiza.ai/docs/api-reference/lists.md) — Allowlists, blocklists, and list membership management.

---

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