Additional Persona productsLists

Lists Cookbook

This doc provides recipes for populating lists via API. Note that lists can also be created and edited in the Persona dashboard.

Learn more in the Lists API documentation

Import email address list

First, create the list:

curl
1curl -X POST https://api.withpersona.com/api/v1/list/email-addresses \
2    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
3    -H "Content-Type: application/json" \
4    -d '{
5  "data": {
6    "attributes": {
7      "name": "My New List"
8    }
9  }
10}'

To add one email address at a time, use the 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:

curl
1curl -X POST https://api.withpersona.com/api/v1/importer/list-item/email-addresses \
2    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
3    -H "Content-Type: multipart/form-data" \
4    -F "data[attributes][file]=@/PATH/TO/YOUR/LOCAL/FILE.csv"
5    -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:

1value,match_type
2alexander@sample.com,email_address
3some-domain.com,domain

Import geolocation list

First, create the list:

curl
1curl -X POST https://api.withpersona.com/api/v1/list/email-addresses \
2    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
3    -H "Content-Type: application/json" \
4    -d '{
5  "data": {
6    "attributes": {
7      "name": "My New List"
8    }
9  }
10}'

To add one geolocation at a time, use the Create an Geolocation List Item API.

To import many geolocations at once, upload a CSV of your geolocation data via the importer API:

curl
1curl -X POST https://api.withpersona.com/api/v1/importer/list-item/geolocations \
2    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
3    -H "Content-Type: multipart/form-data" \
4    -F "data[attributes][file]=@/PATH/TO/YOUR/LOCAL/FILE.csv"
5    -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:

1latitude,longitude,radius_meters
240.7128,74.0060,200

Import government ID number list

First, create the list:

curl
1curl -X POST https://api.withpersona.com/api/v1/list/government-id-numbers \
2    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
3    -H "Content-Type: application/json" \
4    -d '{
5  "data": {
6    "attributes": {
7      "name": "My New List"
8    }
9  }
10}'

To add one government ID number at a time, use the Create an 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:

curl
1curl -X POST https://api.withpersona.com/api/v1/importer/list-item/government-id-numbers \
2    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
3    -H "Content-Type: multipart/form-data" \
4    -F "data[attributes][file]=@/PATH/TO/YOUR/LOCAL/FILE.csv"
5    -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:

1  id_number,id_class
2  200112,dl

Common values for id_class include ‘pp’ for passport and ‘dl’ for driver license. Please contact us if you need help getting id_class values!

Import IP address list

First, create the list:

curl
1curl -X POST https://api.withpersona.com/api/v1/list/ip-addresses \
2    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
3    -H "Content-Type: application/json" \
4    -d '{
5  "data": {
6    "attributes": {
7      "name": "My New List"
8    }
9  }
10}'

To add one IP address at a time, use the 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:

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

CSV format

The CSV should contain the following fields:

  • value

Here’s an example CSV:

1  value
2  192.168.1.1

Both IPv4 and IPv6 are supported.

Import name list

First, create the list:

curl
1curl -X POST https://api.withpersona.com/api/v1/list/names \
2    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
3    -H "Content-Type: application/json" \
4    -d '{
5  "data": {
6    "attributes": {
7      "allow-fuzzy-name-first": true,
8      "name": "My New List"
9    }
10  }
11}'

To add one name at a time, use the Create a Name List Item API.

To import many names at once, upload a CSV of your name data via the importer API:

curl
1curl -X POST https://api.withpersona.com/api/v1/importer/list-item/names \
2    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
3    -H "Content-Type: multipart/form-data" \
4    -F "data[attributes][file]=@/PATH/TO/YOUR/LOCAL/FILE.csv"
5    -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:

1  name_first,name_last
2  John,Doe

Import phone number list

First, create the list:

curl
1curl -X POST https://api.withpersona.com/api/v1/list/phone-numbers \
2    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
3    -H "Content-Type: application/json" \
4    -d '{
5  "data": {
6    "attributes": {
7      "name": "My New List"
8    }
9  }
10}'

To add one phone number at a time, use the 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:

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

CSV format

The CSV should contain the following fields:

  • value

Here’s an example CSV:

1  value
2  +1234567890