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

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

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

Get Decision by ID

Response includes:

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

List 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

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.