---
title: "Getting Started"
description: "Make your first Naiza API call and verify your integration."
collection: "guides"
slug: "getting-started"
url: "https://naiza.ai/docs/guides/getting-started"
markdown: "https://naiza.ai/docs/guides/getting-started.md"
full_docs: "https://naiza.ai/docs.md"
product: "Naiza"
base_url: "https://api.naiza.ai/api/v1"
---

# Getting Started

> Make your first Naiza API call and verify your integration.

## Table of contents

- [Prerequisites](#prerequisites)
- [Step 1: Get Your API Key](#step-1-get-your-api-key)
- [Step 2: Make Your First Call](#step-2-make-your-first-call)
  - [cURL](#curl)
  - [Node.js](#nodejs)
  - [Python](#python)
- [Step 3: Understand the Response](#step-3-understand-the-response)
- [Step 4: Verify Webhook Signature (Optional)](#step-4-verify-webhook-signature-optional)
  - [Node.js](#nodejs)
  - [Python](#python)
- [Step 5: Query a Decision](#step-5-query-a-decision)
- [Next Steps](#next-steps)
- [Troubleshooting](#troubleshooting)
  - ["Invalid API key" error](#invalid-api-key-error)
  - ["Validation failed" error](#validation-failed-error)
  - [Need Help?](#need-help)

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](https://naiza.ai/docs/api-reference/authentication.md))
- Basic knowledge of REST APIs and JSON

## Step 1: Get Your API Key

1. Log in to the [Naiza Dashboard](https://app.naiza.ai)
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

```bash
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"
  }'
```

### Node.js

```javascript
const response = await fetch("https://api.naiza.ai/api/v1/decisions/evaluate", {
  method: "POST",
  headers: {
    "x-api-key": "naiza_api_sk_live_YOUR_KEY_HERE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    eventName: "payment.attempt",
    customer: {
      externalId: "cust_test_123",
      email: "test@example.com",
    },
    ip: "203.0.113.42",
  }),
});

const decision = await response.json();
console.log("Decision:", decision.decision);
console.log("Risk Score:", decision.riskScore);
```

### Python

```python
import requests

response = requests.post(
    'https://api.naiza.ai/api/v1/decisions/evaluate',
    headers={
        'x-api-key': 'naiza_api_sk_live_YOUR_KEY_HERE',
        'Content-Type': 'application/json',
    },
    json={
        'eventName': 'payment.attempt',
        'customer': {
            'externalId': 'cust_test_123',
            'email': 'test@example.com',
        },
        'ip': '203.0.113.42',
    },
)

decision = response.json()
print(f"Decision: {decision['decision']}")
print(f"Risk Score: {decision['riskScore']}")
```

## Step 3: Understand the Response

A successful response looks like this:

```json
{
  "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:

### Node.js

```javascript
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,
);
```

### Python

```python
import hmac
import hashlib
import json

def verify_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        json.dumps(payload, sort_keys=True).encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    provided = signature.replace('sha256=', '')
    return hmac.compare_digest(expected, provided)
```

## Step 5: Query a Decision

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

```bash
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

- Read the [Quick Start Guide](https://naiza.ai/docs/guides/quick-start.md) for common operations
- Review [Integration Examples](https://naiza.ai/docs/guides/integration-examples.md) for code patterns
- Explore the [API Reference](https://naiza.ai/docs/api-reference/overview.md) for complete documentation

## 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?

- Check the [Error Handling](https://naiza.ai/docs/api-reference/errors.md) guide
- Review the [API Reference](https://naiza.ai/docs/api-reference/overview.md)
- Contact support with your API key (sanitized) and error details

## Related documentation

- [Overview](https://naiza.ai/docs/guides/overview.md) — Base URL, authentication, decision types, risk scores, and rate limits.
- [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.
- [Quick Start](https://naiza.ai/docs/guides/quick-start.md) — Common operations for events, decisions, lists, and feedback.
- [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/getting-started](https://naiza.ai/docs/guides/getting-started) · Full docs: [https://naiza.ai/docs.md](https://naiza.ai/docs.md)*