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

# Contact Lists

> Manage reusable target lists for monitors — list, create, and delete.

## Authentication

Requires an API key in the `Authorization` header.

```bash theme={"dark"}
Authorization: Bearer YOUR_API_KEY
```

***

## List all lists

**`GET /api/agent/lists`**

<ParamField query="type" type="string">
  Filter lists by type. Valid values: `email`, `phone`, `domain`, `ip`, `company`, `darkweb`.

  If omitted, returns all lists regardless of type.
</ParamField>

### Example request

```bash theme={"dark"}
curl "https://encrata.com/api/agent/lists?type=domain" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

Returns an array of list objects.

```json theme={"dark"}
[
  {
    "id": "d4e5f6a7-...",
    "name": "Priority Domains",
    "list_type": "domain",
    "email_count": 15,
    "created_at": "2026-05-01T10:00:00Z",
    "updated_at": "2026-05-10T14:30:00Z"
  }
]
```

<ResponseField name="id" type="string">
  Unique list identifier (UUID).
</ResponseField>

<ResponseField name="name" type="string">
  The list's display name.
</ResponseField>

<ResponseField name="list_type" type="string">
  The type of targets in this list: `email`, `phone`, `domain`, `ip`, `company`, or `darkweb`.
</ResponseField>

<ResponseField name="email_count" type="number">
  Number of targets in the list.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of last modification.
</ResponseField>

***

## Create a list

**`POST /api/agent/lists`**

<ParamField body="name" type="string" required>
  A display name for the list.
</ParamField>

<ParamField body="type" type="string">
  The type of targets. Default: `email`. Valid values: `email`, `phone`, `domain`, `ip`, `company`, `darkweb`.
</ParamField>

<ParamField body="emails" type="string[]">
  Initial targets to add (legacy field, works for all types).
</ParamField>

<ParamField body="targets" type="string[]">
  Initial targets to add.
</ParamField>

### Example request

```bash theme={"dark"}
curl -X POST https://encrata.com/api/agent/lists \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Competitor Domains",
    "type": "domain",
    "targets": ["competitor1.com", "competitor2.io", "rival.co"]
  }'
```

### Response

Returns the created list object with status `201`.

```json theme={"dark"}
{
  "id": "d4e5f6a7-...",
  "name": "Competitor Domains",
  "list_type": "domain",
  "email_count": 3,
  "created_at": "2026-05-15T10:00:00Z",
  "updated_at": "2026-05-15T10:00:00Z"
}
```

***

## Get a list

**`GET /api/agent/lists/{id}`**

Returns a single list by ID.

```bash theme={"dark"}
curl https://encrata.com/api/agent/lists/d4e5f6a7-... \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

## Delete a list

**`DELETE /api/agent/lists/{id}`**

Deletes a list and all its targets. Returns `204 No Content`.

```bash theme={"dark"}
curl -X DELETE https://encrata.com/api/agent/lists/d4e5f6a7-... \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

## Manage list targets

### List targets

**`GET /api/agent/lists/{id}/emails`**

Returns an array of target strings in the list.

```bash theme={"dark"}
curl https://encrata.com/api/agent/lists/d4e5f6a7-.../emails \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={"dark"}
["competitor1.com", "competitor2.io", "rival.co"]
```

### Add targets

**`POST /api/agent/lists/{id}/emails`**

<ParamField body="emails" type="string[]" required>
  Targets to add. Duplicates are ignored.
</ParamField>

```bash theme={"dark"}
curl -X POST https://encrata.com/api/agent/lists/d4e5f6a7-.../emails \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"emails": ["newdomain.com"]}'
```

### Remove targets

**`DELETE /api/agent/lists/{id}/emails`**

<ParamField body="emails" type="string[]" required>
  Targets to remove from the list.
</ParamField>

```bash theme={"dark"}
curl -X DELETE https://encrata.com/api/agent/lists/d4e5f6a7-.../emails \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"emails": ["competitor2.io"]}'
```