All documentation

Getting Started

Make your first Naiza API call and verify your integration.

Download Markdown
GuidesAPI ReferenceCode ExamplesBest Practices

Getting Started

This guide will help you make your first API call and verify your integration.

Prerequisites

  • A Naiza account with an active subscription
  • An API key (see Authentication)
  • Basic knowledge of REST APIs and JSON

Step 1: Get Your API Key

  1. Log in to the Naiza Dashboard
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Copy and securely store your API key (format: naiza_api_sk_live_...)

⚠️ Important: API keys are only shown once. Store them securely.

Step 2: Make Your First Call

Let's evaluate a transaction to get a decision.

curl -X POST https://api.naiza.ai/api/v1/decisions/evaluate \
  -H "x-api-key: naiza_api_sk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "eventName": "payment.attempt",
    "customer": {
      "externalId": "cust_test_123",
      "email": "test@example.com"
    },
    "ip": "203.0.113.42"
  }'

Step 3: Understand the Response

A successful response looks like this:

{
  "decision": "approve",
  "riskScore": 25,
  "riskLevel": "low",
  "reasonCodes": [
    {
      "code": "NO_RISK_INDICATORS",
      "explanation": "No risk indicators detected"
    }
  ],
  "correlationIds": {
    "requestId": "req_abc123xyz",
    "eventId": "evt_ckm9876543210",
    "customerId": "cus_test_123"
  },
  "ruleVersion": {
    "version": "v1.0.0"
  },
  "evaluatedAt": "2025-01-15T14:30:00.000Z"
}

Key fields:

  • decision: approve, deny, or review (lowercase; Events API uses uppercase ALLOW/BLOCK/REVIEW)
  • riskScore: 0-100 (higher = more risky)
  • riskLevel: low, medium, high, or critical
  • correlationIds.eventId: Use this to query decision details later

Step 4: Verify Webhook Signature (Optional)

If you've set up webhooks, verify the signature:

const crypto = require("crypto");

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(payload))
    .digest("hex");

  const provided = signature.replace("sha256=", "");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
}

// In your webhook handler
const signature = req.headers["x-webhook-signature"];
const isValid = verifySignature(
  req.body,
  signature,
  process.env.WEBHOOK_SECRET,
);

Step 5: Query a Decision

Use the eventId from the correlation IDs to query decision details:

curl -X GET "https://api.naiza.ai/api/v1/decisions/evt_ckm9876543210" \
  -H "x-api-key: naiza_api_sk_live_YOUR_KEY_HERE"

Next Steps

Troubleshooting

"Invalid API key" error

  • Verify the key format: naiza_api_sk_live_<32-chars>
  • Check for extra spaces or newlines
  • Ensure the key hasn't been revoked

"Validation failed" error

  • Review required fields in the API documentation
  • Check field types and formats
  • Ensure JSON is properly formatted

Need Help?