> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk import list items

> Bulk ingest items into a data list with optional replaceExisting flag and validation modes, designed for large batches — POST /data-lists/{id}/items/bulk.

## Overview

Imports many items in one request (validated per row). Intended for **bulk** or migration scenarios.

## Endpoint

```
POST https://api.gu1.ai/data-lists/{id}/items/bulk
```

## Authentication

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Request Body

<ParamField body="items" type="array" required>
  Each item may include: `primaryValue`, `secondaryValue`, `searchKeys`, `category`, `riskScore`, `severity` (`low` | `medium` | `high` | `critical`), `reason`, `sourceReference`, `itemData`, `metadata`, `isActive`, plus passthrough fields as accepted by the API.
</ParamField>

<ParamField body="skipValidationErrors" type="boolean">
  When true, continues importing valid rows while collecting errors for invalid ones (behavior as implemented server-side).
</ParamField>

<ParamField body="replaceExisting" type="boolean">
  When true, replaces existing matches according to server merge rules.
</ParamField>

## Response

Usually `200` with `successful`, `errors`, and per-row `errorDetails` for partial failures.

## Permissions

Requires **bulk import** permission for data lists. **Global** lists accept writes only from **system administrators**.