> This page is for Applications Protection.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.humansecurity.com/llms.txt.

# Get custom lists

GET https://console.humansecurity.com/api/v1/botDefender/customLists

Retrieve all custom lists for the authenticated account with optional search functionality.

The search parameter filters lists by finding those that contain identifiers 
with values matching the search term (case-insensitive). It does not search by list names or descriptions.


Reference: https://docs.humansecurity.com/applications/reference/get-custom-lists

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Servers

- `https://console.humansecurity.com/api` (Version 1 of the API, default)
- `https://console.humansecurity.com/api` (Version 2 of the API)

## Request

### Query parameters

- `search` (string, optional) — Search term to filter custom lists by their identifier values. This searches within the actual values of identifiers stored in the lists, not the list names or descriptions. Example: Searching for "192.168" will return lists containing identifiers with values like "192.168.1.100", "192.168.0.1", etc.

## Response

### 200

Successfully retrieved custom lists

- `result` (boolean, required) — Indicates if the request was successful
- `message` (string, required) — Response message
- `content` (list of CustomList, optional)

## Errors

### 401 Unauthorized Error

Authentication token is missing or invalid

- `result` (boolean, required) — Indicates if the request was successful
- `message` (string, required) — Response message
- `content` (string, optional)

### 500 Internal Server Error

Internal server error

- `result` (boolean, required) — Indicates if the request was successful
- `message` (string, required) — Response message
- `content` (string, optional)

## Types

### CustomList

- `_id` (string, required) — Unique identifier for the custom list
- `account_id` (string, required) — Account ID that owns this custom list
- `name` (string, required) — Name of the custom list
- `status` (enum, required) — Status of the custom list
  - Allowed values: `active`, `archived`
- `created_by` (string, required) — Email of the user who created the list
- `created_at` (string, required) — When the custom list was created
- `updated_at` (string, required) — When the custom list was last updated
- `updated_by` (string, required) — Email of the user who last updated the list
- `size` (integer, required) — Number of identifiers in the list
- `description` (string, optional) — Optional description of the custom list
- `usedBy` (list of CustomListUsedByItems, optional) — List of rules that use the list
- `last_inserted_time` (string, optional) — When the last identifier was added

### CustomListUsedByItems

- `rule_id` (string, optional) — Unique identifier for the rule
- `name` (string, optional) — Name of the rule
- `status` (string, optional) — Status of the rule

## Examples

**Response**

```json
{
  "result": true,
  "message": "success",
  "content": [
    {
      "_id": "64f8b12345678901234567ab",
      "account_id": "642be969c2186cae012347b8",
      "name": "IP Blocklist",
      "status": "active",
      "created_by": "admin@humansecurity.com",
      "created_at": "2023-09-01T10:00:00Z",
      "updated_at": "2023-09-01T15:30:00Z",
      "updated_by": "admin@humansecurity.com",
      "size": 150
    }
  ]
}
```

**SDK Code**

```python Lists filtered by search term
import requests

url = "https://console.humansecurity.com/api/v1/botDefender/customLists"

querystring = {"search":"192.168"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript Lists filtered by search term
const url = 'https://console.humansecurity.com/api/v1/botDefender/customLists?search=192.168';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Lists filtered by search term
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://console.humansecurity.com/api/v1/botDefender/customLists?search=192.168"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Lists filtered by search term
require 'uri'
require 'net/http'

url = URI("https://console.humansecurity.com/api/v1/botDefender/customLists?search=192.168")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java Lists filtered by search term
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://console.humansecurity.com/api/v1/botDefender/customLists?search=192.168")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php Lists filtered by search term
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://console.humansecurity.com/api/v1/botDefender/customLists?search=192.168', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp Lists filtered by search term
using RestSharp;

var client = new RestClient("https://console.humansecurity.com/api/v1/botDefender/customLists?search=192.168");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Lists filtered by search term
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://console.humansecurity.com/api/v1/botDefender/customLists?search=192.168")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```