---
title: "Lists API"
description: "Allowlists, blocklists, and list membership management."
collection: "api-reference"
slug: "lists"
url: "https://naiza.ai/docs/api-reference/lists"
markdown: "https://naiza.ai/docs/api-reference/lists.md"
full_docs: "https://naiza.ai/docs.md"
product: "Naiza"
base_url: "https://api.naiza.ai/api/v1"
---

# Lists API

> Allowlists, blocklists, and list membership management.

## Table of contents

- [Auth](#auth)
- [Endpoints](#endpoints)
- [List Entries](#list-entries)
  - [Endpoint](#endpoint)
  - [Query Parameters](#query-parameters)
  - [Response](#response)
- [Create List Entry](#create-list-entry)
  - [Endpoint](#endpoint)
  - [Request](#request)
  - [Response](#response)
  - [Entry Types](#entry-types)
  - [List Types](#list-types)
- [Remove Entry by ID](#remove-entry-by-id)
  - [Endpoint](#endpoint)
  - [Response](#response)
- [Scoped Convenience Routes](#scoped-convenience-routes)
- [Examples](#examples)
  - [cURL](#curl)
  - [Node.js](#nodejs)
- [Notes](#notes)

The Lists API manages allow/block controls for IP addresses, device fingerprints, and customer emails.

## Auth

`x-api-key` is required.

## Endpoints

- `GET /api/v1/lists`
- `POST /api/v1/lists`
- `DELETE /api/v1/lists/:id`
- `POST /api/v1/lists/customer/:email`
- `DELETE /api/v1/lists/customer/:email`
- `POST /api/v1/lists/device`
- `DELETE /api/v1/lists/device/:fingerprint`
- `POST /api/v1/lists/ip`
- `DELETE /api/v1/lists/ip/:ip`

## List Entries

List all entries in your lists with filtering.

### Endpoint

```http
GET /api/v1/lists
```

### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `page` | number | Page number (default: 1) |
| `limit` | number | Items per page (default: 50, max: 100) |
| `type` | string | Filter by type (`IP`, `DEVICE`, `EMAIL`) |
| `listType` | string | Filter by list type (`allow`, `block`) |
| `from` | string | Start timestamp (Unix seconds) |
| `to` | string | End timestamp (Unix seconds) |

### Response

```json
{
  "data": [
    {
      "id": "list_abc123",
      "type": "IP",
      "value": "203.0.113.50",
      "listType": "block",
      "reason": "Known malicious IP from threat intelligence",
      "expiresAt": "2026-12-31T23:59:59Z",
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-15T10:00:00Z"
    }
  ],
  "total": 50,
  "page": 1,
  "limit": 50,
  "hasMore": false
}
```

## Create List Entry

Add a new entry to a list.

### Endpoint

```http
POST /api/v1/lists
```

### Request

```json
{
  "type": "IP",
  "value": "203.0.113.50",
  "listType": "block",
  "reason": "Known malicious IP from threat intelligence",
  "expiresAt": "2026-12-31T23:59:59Z"
}
```

### Response

```json
{
  "id": "list_abc123",
  "type": "IP",
  "value": "203.0.113.50",
  "listType": "block",
  "reason": "Known malicious IP from threat intelligence",
  "expiresAt": "2026-12-31T23:59:59Z",
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}
```

### Entry Types

- `IP`: IP address (IPv4 or IPv6)
- `DEVICE`: Device fingerprint
- `EMAIL`: Customer email address

### List Types

- `block`: Block entries matching this value
- `allow`: Explicitly allow matching values

## Remove Entry by ID

Remove a list entry by its ID.

### Endpoint

```http
DELETE /api/v1/lists/:id
```

### Response

```json
{
  "success": true,
  "message": "Entry removed successfully"
}
```

## Scoped Convenience Routes

You can use type-specific routes instead of generic `POST /lists` and `DELETE /lists/:id`:

- Customer: `POST /api/v1/lists/customer/:email`, `DELETE /api/v1/lists/customer/:email`
- Device: `POST /api/v1/lists/device`, `DELETE /api/v1/lists/device/:fingerprint`
- IP: `POST /api/v1/lists/ip`, `DELETE /api/v1/lists/ip/:ip`

## Examples

### cURL

```bash
# Create block list entry
curl -X POST https://api.naiza.ai/api/v1/lists \
  -H "x-api-key: naiza_api_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "IP",
    "value": "203.0.113.50",
    "listType": "block",
    "reason": "Known malicious IP"
  }'

# List all block entries
curl -X GET "https://api.naiza.ai/api/v1/lists?listType=block" \
  -H "x-api-key: naiza_api_sk_live_..."

# Remove entry
curl -X DELETE https://api.naiza.ai/api/v1/lists/list_abc123 \
  -H "x-api-key: naiza_api_sk_live_..."

# Remove by email
curl -X DELETE https://api.naiza.ai/api/v1/lists/customer/user@example.com \
  -H "x-api-key: naiza_api_sk_live_..."
```

### Node.js

```javascript
// Create block list entry
const response = await fetch('https://api.naiza.ai/api/v1/lists', {
  method: 'POST',
  headers: {
    'x-api-key': 'naiza_api_sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'IP',
    value: '203.0.113.50',
    listType: 'block',
    reason: 'Known malicious IP',
  }),
});

const entry = await response.json();
console.log(`Created entry: ${entry.id}`);

// List entries
const listResponse = await fetch(
  'https://api.naiza.ai/api/v1/lists?listType=block',
  {
    headers: { 'x-api-key': 'naiza_api_sk_live_...' },
  }
);

const list = await listResponse.json();
console.log(`Found ${list.total} block list entries`);
```

## Notes

- Route parameter names are `:ip` and `:fingerprint` in the current API implementation.
- For id-based deletions, prefer storing the `id` returned at creation time.

## Related documentation

- [API Overview](https://naiza.ai/docs/api-reference/overview.md) — Base URL, versioning, and high-level API surface.
- [Authentication](https://naiza.ai/docs/api-reference/authentication.md) — API keys, Web SDK tokens, and secure key handling.
- [Web SDK API](https://naiza.ai/docs/api-reference/websdk.md) — Browser SDK endpoints and device signal collection.
- [Events API](https://naiza.ai/docs/api-reference/events.md) — Submit and query product events for risk evaluation.
- [Sessions API](https://naiza.ai/docs/api-reference/sessions.md) — Session grouping and timeline endpoints.
- [Error Handling](https://naiza.ai/docs/api-reference/errors.md) — Error shapes, status codes, and retry guidance.
- [Rate Limiting](https://naiza.ai/docs/api-reference/rate-limiting.md) — Quota headers and rate-limit behavior.
- [Decisions API](https://naiza.ai/docs/api-reference/decisions.md) — approve / deny / review evaluation and decision payloads (Events API uses ALLOW/REVIEW/BLOCK).

---

*Source: [https://naiza.ai/docs/api-reference/lists](https://naiza.ai/docs/api-reference/lists) · Full docs: [https://naiza.ai/docs.md](https://naiza.ai/docs.md)*