Blacklists (matchlists) comprise one of the following categories:

  • of entities (users or business)
  • IPs (single or ranges)
  • strings

ENDPOINT

DESCRIPTION

POST /blacklists/list

Retrieves an existing blacklist (matchlist).

POST /blacklists/create

Creates a blacklist (matchlist).

POST /blacklists/<blacklist_id>/add-values

Adds entries to a blacklist (matchlist).

Add Values to Blacklist

Each request must specify at least 1 object to blacklist. You may add up to 100 values to an existing blacklist at once.

The /blacklists/<blacklist-id>/add-values API will ignore entries provided that already exist in the blacklist. No error will be thrown when this occurs.

curl -X POST \
  https://<API_ENDPOINT>/v1/blacklists/<blacklist_id>/add-values \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '[
        {
          "ip_address": "255.255.255.255",
          "source": "Internal list"
        },
        {
          "ip_address": "255.255.128.128"
        }
      ]'

Supported Blacklists

Unit21 currently supports 5 types of blacklists:

  • STRING: Plain strings to match against any text-type field.
  • IP_INET: IPv4 or IPv6 IP addresses to blacklist.
  • IP_CIDR: Classless Inter-Domain Routing (CIDR) notation IP address ranges to blacklist, according to the standard format described here.
  • USER: Series of fields that a Unit21 user entity will be matched against.
  • BUSINESS: Series of fields that a Unit21 business entity will be matched against.

STRING Blacklist fields

The blacklist_value field is required.

{
  "blacklist_value": "abcde"
}

IP_INET Blacklist fields

The ip_address field is required.

{
  "ip_address": "255.255.255.255",
  "source": "internal list"
}

IP_CIDR Blacklist fields

The cidr field is required.

{
  "cidr": "255.255.255.255/32",
  "source": "internal list"
}

USER Blacklist fields

None of the fields are required. However, at least one field needs to be specified per object.

{
  "first_name": "Arthur",
  "last_name": "Gonzalez",
  "middle_name": "John",
  "alias_first_name": "Art",
  "alias_middle_name": "Terror",
  "date_of_birth": "04/05/1989",
  "ssn": "1112223333",
  "street": "222333 Peachtree Place",
  "city": "Atlanta",
  "state": "CA",
  "country": "US",
  "zip_code": "94107",
  "client_fingerprint": "fdam53-l0923-nkjdo-8639a",
  "email": "[email protected]",
  "entity_status": "active",
  "entity_subtype": "payments",
  "ip_address": "43.192.250.0",
  "phone_number": "+12345678901",
  "registered_at": 1572673225
}

BUSINESS Blacklist fields

None of the fields are required. However, at least one field needs to be specified per object.

{
  "business_name": "Acme Corp",
  "dba_name": "Acme Inc",
  "corporate_tax_id": "111223333",
  "street": "123 Peactree Dr",
  "city": "Atlanta",
  "state": "GA",
  "country": "US",
  "zip_code": "94205"
}