> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpersona.com/2020-05-18/lists-cookbook/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpersona.com/_mcp/server.

# Lists Cookbook

> Follow API recipes for creating and populating Persona Lists.

This doc provides recipes for populating lists via API. Note that lists can also be created and edited [in the Persona dashboard](https://withpersona.com/dashboard/lists).

> **Info**
>
> Learn more in the [Lists API documentation](/api-reference/lists)

## Import email address list

First, [create the list](/api-reference/lists/create-an-email-address-list):

**`curl`**

```curl curl
curl -X POST https://api.withpersona.com/api/v1/list/email-addresses \
    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
  "data": {
    "attributes": {
      "name": "My New List"
    }
  }
}'
```

To add one email address at a time, use the [Create an Email Address List Item](/api-reference/list-items/create-an-email-address-list-item) API.

To import many email addresses at once, upload a CSV of your email address data via the [importer API](/api-reference/importers/import-email-address-lists):

**`curl`**

```curl curl
curl -X POST https://api.withpersona.com/api/v1/importer/list-item/email-addresses \
    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
    -H "Content-Type: multipart/form-data" \
    -F "data[attributes][file]=@/PATH/TO/YOUR/LOCAL/FILE.csv"
    -F "data[attributes][list-id]=YOUR_LIST_ID_HERE"
```

### CSV format

The CSV should contain the following fields:

* value
* match\_type (either `email_address` or `domain`)

A match\_type of `email_address` will only match the entire email address of an individual, while a match\_type of `domain` will match any email address with the specified domain (i.e. all email addresses with domain 'gmail.com').

Here's an example CSV:

```csv
value,match_type
alexander@sample.com,email_address
some-domain.com,domain
```

## Import geolocation list

First, [create the list](/api-reference/lists/create-a-geolocation-list):

**`curl`**

```curl curl
curl -X POST https://api.withpersona.com/api/v1/list/geolocations \
    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
  "data": {
    "attributes": {
      "name": "My New List"
    }
  }
}'
```

To add one geolocation at a time, use the [Create a Geolocation List Item](/api-reference/list-items/create-a-geolocation-list-item) API.

To import many geolocations at once, upload a CSV of your geolocation data via the [importer API](/api-reference/importers/import-geolocation-lists):

**`curl`**

```curl curl
curl -X POST https://api.withpersona.com/api/v1/importer/list-item/geolocations \
    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
    -H "Content-Type: multipart/form-data" \
    -F "data[attributes][file]=@/PATH/TO/YOUR/LOCAL/FILE.csv"
    -F "data[attributes][list-id]=YOUR_LIST_ID_HERE"
```

### CSV format

The CSV should contain the following fields:

* latitude
* longitude
* radius\_meters

Here's an example CSV:

```csv
latitude,longitude,radius_meters
40.7128,74.0060,200
```

## Import government ID number list

First, [create the list](/api-reference/lists/create-a-government-id-number-list):

**`curl`**

```curl curl
curl -X POST https://api.withpersona.com/api/v1/list/government-id-numbers \
    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
  "data": {
    "attributes": {
      "name": "My New List"
    }
  }
}'
```

To add one government ID number at a time, use the [Create a Government ID Number List Item](/api-reference/list-items/create-a-government-id-number-list-item) API.

To import many government ID numbers at once, upload a CSV of your government ID number data via the [importer API](/api-reference/importers/import-government-id-number-lists):

**`curl`**

```curl curl
curl -X POST https://api.withpersona.com/api/v1/importer/list-item/government-id-numbers \
    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
    -H "Content-Type: multipart/form-data" \
    -F "data[attributes][file]=@/PATH/TO/YOUR/LOCAL/FILE.csv"
    -F "data[attributes][list-id]=YOUR_LIST_ID_HERE"
```

### CSV format

The CSV should contain the following fields:

* id\_number
* id\_class

Here's an example CSV:

```csv
  id_number,id_class
  200112,dl
```

> **Info**
>
> Common values for id\_class include 'pp' for passport and 'dl' for driver license. Please [contact us](https://app.withpersona.com/dashboard/contact-us) if you need help getting id\_class values!

## Import IP address list

First, [create the list](/api-reference/lists/create-an-ip-address-list):

**`curl`**

```curl curl
curl -X POST https://api.withpersona.com/api/v1/list/ip-addresses \
    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
  "data": {
    "attributes": {
      "name": "My New List"
    }
  }
}'
```

To add one IP address at a time, use the [Create an IP Address List Item](/api-reference/list-items/create-an-ip-address-list-item) API.

To import many IP addresses at once, upload a CSV of your IP address data via the [importer API](/api-reference/importers/import-ip-address-lists):

**`curl`**

```curl curl
curl -X POST https://api.withpersona.com/api/v1/importer/list-item/ip-addresses \
    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
    -H "Content-Type: multipart/form-data" \
    -F "data[attributes][file]=@/PATH/TO/YOUR/LOCAL/FILE.csv"
    -F "data[attributes][list-id]=YOUR_LIST_ID_HERE"
```

### CSV format

The CSV should contain the following fields:

* value

Here's an example CSV:

```csv
  value
  192.168.1.1
```

> **Info**
>
> Both IPv4 and IPv6 are supported. Subnets in CIDR notation (e.g. `192.168.1.0/24`) are also supported; a list item for a subnet matches any IP address within that range.

## Import name list

First, [create the list](/api-reference/lists/create-a-name-list):

**`curl`**

```curl curl
curl -X POST https://api.withpersona.com/api/v1/list/names \
    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
  "data": {
    "attributes": {
      "allow-fuzzy-name-first": true,
      "name": "My New List"
    }
  }
}'
```

To add one name at a time, use the [Create a Name List Item](/api-reference/list-items/create-a-name-list-item) API.

To import many names at once, upload a CSV of your name data via the [importer API](/api-reference/importers/import-name-lists):

**`curl`**

```curl curl
curl -X POST https://api.withpersona.com/api/v1/importer/list-item/names \
    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
    -H "Content-Type: multipart/form-data" \
    -F "data[attributes][file]=@/PATH/TO/YOUR/LOCAL/FILE.csv"
    -F "data[attributes][list-id]=YOUR_LIST_ID_HERE"
```

### CSV format

The CSV should contain the following fields:

* name\_first
* name\_last

Here's an example CSV:

```csv
  name_first,name_last
  John,Doe
```

## Import phone number list

First, [create the list](/api-reference/lists/create-a-phone-number-list):

**`curl`**

```curl curl
curl -X POST https://api.withpersona.com/api/v1/list/phone-numbers \
    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
  "data": {
    "attributes": {
      "name": "My New List"
    }
  }
}'
```

To add one phone number at a time, use the [Create a Phone Number List Item](/api-reference/list-items/create-a-phone-number-list-item) API.

To import many phone numbers at once, upload a CSV of your phone number data via the [importer API](/api-reference/importers/import-phone-number-lists):

**`curl`**

```curl curl
curl -X POST https://api.withpersona.com/api/v1/importer/list-item/phone-numbers \
    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
    -H "Content-Type: multipart/form-data" \
    -F "data[attributes][file]=@/PATH/TO/YOUR/LOCAL/FILE.csv"
    -F "data[attributes][list-id]=YOUR_LIST_ID_HERE"
```

### CSV format

The CSV should contain the following fields:

* value

Here's an example CSV:

```csv
  value
  +1234567890
```

## Create a string list

String lists store arbitrary strings, such as coupon codes or order IDs. First, [create the list](/api-reference/lists/create-a-strings-list):

**`curl`**

```curl curl
curl -X POST https://api.withpersona.com/api/v1/list/strings \
    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
  "data": {
    "attributes": {
      "name": "My New List"
    }
  }
}'
```

To add one string at a time, use the [Create a String List Item](/api-reference/list-items/create-a-string-list-item) API.

> **Info**
>
> There is currently no CSV importer for string lists. Use the Create a String List Item API instead.

> Follow API recipes for creating and populating Persona Lists.