DocumentationAPI Reference
DocumentationAPI Reference

A listlist - A set of characteristics that can match on inquiries. can be used to identify individuals who go through the Persona flow by predefined characteristics. For example, these characteristics could be the government ID numbers of known fraudulent individuals or the IP addresses of whitelisted developers.

Persona currently supports a variety of list types:

  • Browser fingerprint
  • Email address
  • Geolocation
  • Government ID number
  • IP address
  • Name
  • Phone number

Importing Email Address Lists

If you would like to import many list items at once into an email address list in Persona, first create the list in the Persona dashboard by selecting "Email address" for the list type. Next, you can upload a CSV of your email address data.

API_KEY=YOUR_API_KEY_HERE
LIST_ID=YOUR_LIST_ID_HERE
FILE_PATH=CSV_FILE_PATH

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $API_KEY" -d'{
  "data": {
    "type": "importer",
    "attributes": {
      "list-id": "$LIST_ID",
      "file": { "data": "'"$(base64 $FILE_PATH)"'", "filename": "$FILE_PATH" }
    }
  }
}' https://withpersona.com/api/v1/importer/list-item/email-addresses

The information we support during bulk import for email address lists are:

  • value
  • match_type (either 'email_address' or 'domain')

📘

A match_type of 'email_address' will need to match the entire email address of an individual, while a match_type of 'domain' will match on the email address domain of an individual (i.e. all email addresses with domain 'gmail.com').

👍

Example CSV

value,match_type
[email protected],email_address
some-domain.com,domain

Importing Geolocation Lists

If you would like to import many list items at once into a geolocation list in Persona, first create the list in the Persona dashboard by selecting "Geolocation" for the list type. Next, you can upload a CSV of your geolocation data.

API_KEY=YOUR_API_KEY_HERE
LIST_ID=YOUR_LIST_ID_HERE
FILE_PATH=CSV_FILE_PATH

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $API_KEY" -d'{
  "data": {
    "type": "importer",
    "attributes": {
      "list-id": "$LIST_ID",
      "file": { "data": "'"$(base64 $FILE_PATH)"'", "filename": "$FILE_PATH" }
    }
  }
}' https://withpersona.com/api/v1/importer/list-item/geolocations

The information we support during bulk import for geolocation lists are:

  • latitude
  • longitude
  • radius_meters

Importing Government ID Number Lists

If you would like to import many list items at once into a government ID number list in Persona, first create the list in the Persona dashboard by selecting "Government ID number" for the list type. Next, you can upload a CSV of your government ID number data.

API_KEY=YOUR_API_KEY_HERE
LIST_ID=YOUR_LIST_ID_HERE
FILE_PATH=CSV_FILE_PATH

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $API_KEY" -d'{
  "data": {
    "type": "importer",
    "attributes": {
      "list-id": "$LIST_ID",
      "file": { "data": "'"$(base64 $FILE_PATH)"'", "filename": "$FILE_PATH" }
    }
  }
}' https://withpersona.com/api/v1/importer/list-item/government-id-numbers

The information we support during bulk import for government ID number lists are:

  • id_number
  • id_class

📘

Common values for id_class include 'pp' for passport and 'dl' for driver license. Please contact us or reach out to [email protected] if you need help getting id_class values!

Importing IP Address Lists

If you would like to import many list items at once into an IP address list in Persona, first create the list in the Persona dashboard by selecting "IP address" for the list type. Next, you can upload a CSV of your IP address data.

API_KEY=YOUR_API_KEY_HERE
LIST_ID=YOUR_LIST_ID_HERE
FILE_PATH=CSV_FILE_PATH

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $API_KEY" -d'{
  "data": {
    "type": "importer",
    "attributes": {
      "list-id": "$LIST_ID",
      "file": { "data": "'"$(base64 $FILE_PATH)"'", "filename": "$FILE_PATH" }
    }
  }
}' https://withpersona.com/api/v1/importer/list-item/ip-addresses

The information we support during bulk import for IP address lists are:

  • value

📘

Both IPv4 and IPv6 are supported.

Importing Name Lists

If you would like to import many list items at once into a name list in Persona, first create the list in the Persona dashboard by selecting "Name" for the list type. Next, you can upload a CSV of your name data.

API_KEY=YOUR_API_KEY_HERE
LIST_ID=YOUR_LIST_ID_HERE
FILE_PATH=CSV_FILE_PATH

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $API_KEY" -d'{
  "data": {
    "type": "importer",
    "attributes": {
      "list-id": "$LIST_ID",
      "file": { "data": "'"$(base64 $FILE_PATH)"'", "filename": "$FILE_PATH" }
    }
  }
}' https://withpersona.com/api/v1/importer/list-item/names

The information we support during bulk import for name lists are:

  • name_first
  • name_last

Importing Phone Number Lists

If you would like to import many list items at once into a phone number list in Persona, first create the list in the Persona dashboard by selecting "Phone number" for the list type. Next, you can upload a CSV of your phone number data.

API_KEY=YOUR_API_KEY_HERE
LIST_ID=YOUR_LIST_ID_HERE
FILE_PATH=CSV_FILE_PATH

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $API_KEY" -d'{
  "data": {
    "type": "importer",
    "attributes": {
      "list-id": "$LIST_ID",
      "file": { "data": "'"$(base64 $FILE_PATH)"'", "filename": "$FILE_PATH" }
    }
  }
}' https://withpersona.com/api/v1/importer/list-item/phone-numbers

The information we support during bulk import for phone number lists are:

  • value