---
title: "Quick Start Guide"
description: "Common operations for events, decisions, lists, and feedback."
collection: "guides"
slug: "quick-start"
url: "https://naiza.ai/docs/guides/quick-start"
markdown: "https://naiza.ai/docs/guides/quick-start.md"
full_docs: "https://naiza.ai/docs.md"
product: "Naiza"
base_url: "https://api.naiza.ai/api/v1"
---

# Quick Start Guide

> Common operations for events, decisions, lists, and feedback.

## Table of contents

- [1. Evaluate a Transaction](#1-evaluate-a-transaction)
- [2. Query a Decision](#2-query-a-decision)
- [2b. Ingest an Event (Async)](#2b-ingest-an-event-async)
- [3. Create a Block List Entry](#3-create-a-block-list-entry)
- [4. Send Feedback](#4-send-feedback)
- [5. Create a Webhook Subscription](#5-create-a-webhook-subscription)
- [Complete Integration Example](#complete-integration-example)
- [Next Steps](#next-steps)

Common operations you'll perform with the Naiza API.

## 1. Evaluate a Transaction

Get an immediate decision for a transaction.

```javascript
const response = await fetch("https://api.naiza.ai/api/v1/decisions/evaluate", {
  method: "POST",
  headers: {
    "x-api-key": process.env.NAIZA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    eventName: "payment.attempt",
    customer: {
      externalId: "cust_123",
      email: "user@example.com",
    },
    device: {
      fingerprint: "fp_abc123",
    },
    ip: "203.0.113.42",
    metadata: {
      amount: 99.99,
      currency: "USD",
    },
  }),
});

const decision = await response.json();

if (decision.decision === "deny") {
  // Block the transaction
  console.log("Transaction blocked:", decision.reasonCodes);
} else if (decision.decision === "review") {
  // Flag for manual review
  console.log("Requires review:", decision.riskLevel);
} else {
  // Approve the transaction
  console.log("Transaction approved");
}
```

## 2. Query a Decision

Retrieve details about a specific decision.

```javascript
const decisionId = "evt_ckm9876543210"; // From correlationIds.eventId

const response = await fetch(
  `https://api.naiza.ai/api/v1/decisions/${decisionId}`,
  {
    headers: {
      "x-api-key": process.env.NAIZA_API_KEY,
    },
  },
);

const details = await response.json();
console.log("Decision details:", details);
console.log("Rules evaluated:", details.outputs.rulesEvaluated);
console.log("Reason codes:", details.reasonCodes);
```

## 2b. Ingest an Event (Async)

Use async ingestion when you want fast acceptance and downstream processing via webhooks:

```javascript
const response = await fetch("https://api.naiza.ai/api/v1/events/async", {
  method: "POST",
  headers: {
    "x-api-key": process.env.NAIZA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    eventName: "user.register",
    eventCategory: "AUTHENTICATION",
    customer: { externalId: "user_345678", email: "newuser@example.com" },
    ip: "10.0.0.25",
  }),
});

const accepted = await response.json();
console.log("Queued job:", accepted.jobId);
```

## 3. Create a Block List Entry

Add an IP address to your block list.

```javascript
const response = await fetch("https://api.naiza.ai/api/v1/lists/ip", {
  method: "POST",
  headers: {
    "x-api-key": process.env.NAIZA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ip: "203.0.113.50",
    reason: "Known malicious IP from threat intelligence",
  }),
});

const entry = await response.json();
console.log("Created block list entry:", entry.id);
```

## 4. Send Feedback

Provide feedback on a decision to improve accuracy.

```javascript
const decisionId = "evt_ckm9876543210";
const idempotencyKey = `feedback-${decisionId}-${Date.now()}`;

const response = await fetch(
  `https://api.naiza.ai/api/v1/feedback/decision/${decisionId}`,
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.NAIZA_API_KEY,
      "Idempotency-Key": idempotencyKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      label: "FRAUD",
      notes: "Customer confirmed this was fraudulent activity",
      externalCaseId: "case_12345",
    }),
  },
);

const feedback = await response.json();
console.log("Feedback submitted:", feedback.id);
```

## 5. Create a Webhook Subscription

Subscribe to real-time decision notifications.

```javascript
const response = await fetch(
  "https://api.naiza.ai/api/v1/webhooks/subscriptions",
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.NAIZA_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://api.example.com/webhooks",
      eventTypes: ["EVENT_RISK_EVALUATED", "EVENT_FEEDBACK_SUBMITTED"],
    }),
  },
);

const subscription = await response.json();
console.log("Webhook subscription created:", subscription.id);
console.log("Store signing secret once:", subscription.signingSecret);
```

## Complete Integration Example

Here's a complete example integrating all operations:

```javascript
class NaizaClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = "https://api.naiza.ai/api/v1";
  }

  async evaluateTransaction(transaction) {
    const response = await fetch(`${this.baseUrl}/decisions/evaluate`, {
      method: "POST",
      headers: {
        "x-api-key": this.apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(transaction),
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error.message);
    }

    return response.json();
  }

  async getDecision(decisionId) {
    const response = await fetch(`${this.baseUrl}/decisions/${decisionId}`, {
      headers: { "x-api-key": this.apiKey },
    });

    return response.json();
  }

  async blockIP(ip, reason) {
    const response = await fetch(`${this.baseUrl}/lists/ip`, {
      method: "POST",
      headers: {
        "x-api-key": this.apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        ip,
        reason,
      }),
    });

    return response.json();
  }

  async submitFeedback(decisionId, label, notes) {
    const idempotencyKey = `feedback-${decisionId}-${Date.now()}`;

    const response = await fetch(
      `${this.baseUrl}/feedback/decision/${decisionId}`,
      {
        method: "POST",
        headers: {
          "x-api-key": this.apiKey,
          "Idempotency-Key": idempotencyKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ label, notes }),
      },
    );

    return response.json();
  }
}

// Usage
const client = new NaizaClient(process.env.NAIZA_API_KEY);

// Evaluate transaction
const decision = await client.evaluateTransaction({
  eventName: "payment.attempt",
  customer: { externalId: "cust_123" },
  ip: "203.0.113.42",
});

console.log(`Decision: ${decision.decision}, Risk: ${decision.riskScore}`);

// If blocked, add to block list
if (decision.decision === "deny") {
  await client.blockIP("203.0.113.42", "High risk transaction");
}

// Later, provide feedback
if (customerConfirmedFraud) {
  await client.submitFeedback(
    decision.correlationIds.eventId,
    "FRAUD",
    "Customer confirmed fraud",
  );
}
```

## Next Steps

- Review [Integration Examples](https://naiza.ai/docs/guides/integration-examples.md) for more patterns
- Explore the [API Reference](https://naiza.ai/docs/api-reference/overview.md) for complete documentation
- Set up [Webhooks](https://naiza.ai/docs/api-reference/webhooks.md) for real-time notifications
- **Browser SDK:** On the docs site open **Guides → Web SDK — Install & CDN** for npm, jsDelivr/unpkg script tags, and cross-site checks; API shapes are under [Web SDK API](https://naiza.ai/docs/api-reference/websdk.md)
- Read [Best Practices](https://naiza.ai/docs/guides/best-practices.md) before enforcing decisions in production

## Related documentation

- [Overview](https://naiza.ai/docs/guides/overview.md) — Base URL, authentication, decision types, risk scores, and rate limits.
- [Getting Started](https://naiza.ai/docs/guides/getting-started.md) — Make your first Naiza API call and verify your integration.
- [Tenant Onboarding](https://naiza.ai/docs/guides/tenant-onboarding.md) — Create tenants, invite operators, and configure webhooks.
- [Web SDK — Install & CDN](https://naiza.ai/docs/guides/web-sdk-install.md) — Install the browser SDK via CDN, self-host, and verify ingest.
- [Event Monitoring](https://naiza.ai/docs/guides/event-monitoring.md) — Model product events and turn rule outcomes into decisions.
- [AML Integration](https://naiza.ai/docs/guides/aml-integration.md) — Screen customers and counterparties against AML watchlists.
- [Integration Examples](https://naiza.ai/docs/guides/integration-examples.md) — Node.js, Python, cURL, and webhook handler examples.
- [Best Practices](https://naiza.ai/docs/guides/best-practices.md) — Production guidance for keys, idempotency, and enforcement.

---

*Source: [https://naiza.ai/docs/guides/quick-start](https://naiza.ai/docs/guides/quick-start) · Full docs: [https://naiza.ai/docs.md](https://naiza.ai/docs.md)*