All documentation

Quick Start

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

Download Markdown
GuidesAPI ReferenceCode ExamplesBest Practices

Quick Start Guide

Common operations you'll perform with the Naiza API.

1. Evaluate a Transaction

Get an immediate decision for a transaction.

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 {
  // Allow the transaction
  console.log("Transaction allowed");
}

2. Query a Decision

Retrieve details about a specific decision.

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:

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.

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.

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.

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:

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