All documentation

Decisions API

Decisions API reference: how Naiza evaluates an event and returns ALLOW, REVIEW, or BLOCK with the score and the rules that produced the decision.

Download Markdown
GuidesAPI ReferenceCode ExamplesBest Practices

Decisions API

The Decisions API evaluates risk in real time and supports search and 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

POST/api/v1/decisions/evaluate

Request

{
  "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"
  }
}

Response

{
  "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 vocabulary mapped from internal ALLOW/BLOCK/REVIEW. The Events API still returns uppercase values.

  • approve
  • deny
  • review

Get Decision by ID

GET/api/v1/decisions/:id

Response includes:

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

List Decisions

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

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

Decision Stats

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.