White Black Lists

Overview

White and Black Lists allow you to explicitly allow or block transactions based on customer attributes. A black list flags transactions matching its entries for rejection, while a white list allows matching transactions to bypass certain scoring checks.

You can manage lists:

In the Admin Panel: Settings → White/Black Lists
Via API: BW Lists endpoints

Concept	Description
List	A named collection of items with a type (`WHITE` or `BLACK`) and a target scope
Item	A single entry in a list (e.g., an email address, phone number, card token)
Target	The entity scope where the list applies (cascade, gate, merchant, or bank)
Target Type	`ALL` (applies company-wide) or `DIRECT` (applies only to linked entities)
Multi-Component Group	A group of items that must ALL match for the list to trigger

Each item in a list has a type that determines what transaction attribute it matches against:

Type	Description	Example Value
`EMAIL`	Customer email address	`[email protected]`
`PHONE`	Customer phone number	`+79998887766`
`FINGERPRINT`	Browser fingerprint identifier	`fp_abc123`
`CARD_TOKEN`	Tokenized card identifier	`card_token_hash`
`CARD_BIN`	Card BIN (first 6 digits)	`411111`
`CARD_COUNTRY`	Card issuing country code	`RU`
`CARD`	Full card reference	`4111111111111234`
`CARD_MASK`	Masked card number	`411111****1234`
`CARDHOLDER_NAME`	Cardholder name	`John Doe`
`IP_ADDRESS`	Customer IP address	`203.0.113.42`
`IP_ADDRESS_COUNTRY`	Country derived from IP	`DE`
`ADDRESS`	Customer address	`123 Main St`
`CUSTOMER_EXTERNAL_ID`	Your internal customer ID	`cust_001`
`CUSTOMER_ID`	Embermind internal customer ID	`69e45d20-...`
`DOMAIN`	Domain name	`example.com`

When a transaction is processed, the system runs a BW precheck before scoring:

Load active lists — Find all lists linked to the transaction's cascade, gate, merchant, or bank (plus ALL lists)
Check black lists first — If any black list item matches a transaction attribute, the transaction is rejected
Check white lists — If a white list is in scope but no items match, the transaction is blocked
No match — If no lists match, the transaction proceeds to normal scoring

Priority: Black list matches always override white list matches.

Multi-component groups require ALL items in the group to match simultaneously. A single-item group behaves like a regular list entry.

Lists can be scoped using targetType:

Target Type	Description
`ALL`	List applies to all transactions in the company
`DIRECT`	List applies only to transactions processed through linked cascades, gates, merchants, or banks

When targetType is DIRECT, you must link the list to at least one cascade, gate, merchant, or bank.

Base URL: https://api.embermind.ch/api/v1/client/bw-lists

Get all white/black lists in your company.

curl -X POST 'https://api.embermind.ch/api/v1/client/bw-lists/get-list' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "page": 1,
    "perPage": 20
  }'

Response:

{
  "count": 2,
  "dataList": [
    {
      "id": "69e45d20-98a9-4c75-ab60-1188d64d510a",
      "title": "Blocked Emails",
      "type": "BLACK",
      "targetType": "ALL",
      "createdAt": "2024-01-15T10:30:00.027Z",
      "cascadeCount": 0,
      "gateCount": 0,
      "merchantCount": 0,
      "bankCount": 0,
      "itemCount": 15
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Trusted Customers",
      "type": "WHITE",
      "targetType": "DIRECT",
      "createdAt": "2024-01-15T11:00:00.027Z",
      "cascadeCount": 1,
      "gateCount": 2,
      "merchantCount": 0,
      "bankCount": 0,
      "itemCount": 50
    }
  ]
}

Get detailed information about a specific list.

curl -X POST 'https://api.embermind.ch/api/v1/client/bw-lists/get-one' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "bwListId": "69e45d20-98a9-4c75-ab60-1188d64d510a"
  }'

Response:

{
  "id": "69e45d20-98a9-4c75-ab60-1188d64d510a",
  "title": "Blocked Emails",
  "type": "BLACK",
  "targetType": "ALL",
  "createdAt": "2024-01-15T10:30:00.027Z",
  "cascadeCount": 0,
  "gateCount": 0,
  "merchantCount": 0,
  "bankCount": 0,
  "itemCount": 15
}

Create a new white or black list with items and target links.

curl -X POST 'https://api.embermind.ch/api/v1/client/bw-lists/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "title": "Blocked Emails",
    "type": "BLACK",
    "targetType": "ALL",
    "bwItemList": [
      {
        "type": "EMAIL",
        "value": "[email protected]",
        "comment": "Known fraud email"
      },
      {
        "type": "EMAIL",
        "value": "[email protected]",
        "comment": "Reported by merchant"
      }
    ],
    "cascadeIdList": [],
    "gateIdList": [],
    "merchantIdList": [],
    "bankIdList": []
  }'

Required fields:

Field	Type	Description
`title`	string	List name
`type`	string	`WHITE` or `BLACK`
`targetType`	string	`ALL` or `DIRECT`
`bwItemList`	array	Items to add (each with `type`, `value`, and optional `comment`)
`cascadeIdList`	array	UUIDs of cascades to link (for `DIRECT` target type)
`gateIdList`	array	UUIDs of gates to link
`merchantIdList`	array	UUIDs of merchants to link
`bankIdList`	array	UUIDs of banks to link

Update title and type of an existing list.

curl -X POST 'https://api.embermind.ch/api/v1/client/bw-lists/update' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "bwListId": "69e45d20-98a9-4c75-ab60-1188d64d510a",
    "title": "Updated Title",
    "type": "BLACK"
  }'

Permanently delete a list and all its items.

curl -X POST 'https://api.embermind.ch/api/v1/client/bw-lists/remove' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "bwListId": "69e45d20-98a9-4c75-ab60-1188d64d510a"
  }'

Get paginated list of items in a specific list.

curl -X POST 'https://api.embermind.ch/api/v1/client/bw-lists/bw-items/get-list' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "bwListId": "69e45d20-98a9-4c75-ab60-1188d64d510a",
    "page": 1,
    "perPage": 20
  }'

Response:

{
  "count": 2,
  "dataList": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "EMAIL",
      "value": "[email protected]",
      "normalizedValue": "[email protected]",
      "comment": "Known fraud email",
      "createdAt": "2024-01-15T10:30:00.027Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "type": "EMAIL",
      "value": "[email protected]",
      "normalizedValue": "[email protected]",
      "comment": "Reported by merchant",
      "createdAt": "2024-01-15T10:30:00.027Z"
    }
  ]
}

Update the comment on an existing item.

curl -X POST 'https://api.embermind.ch/api/v1/client/bw-lists/update-item' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "bwListId": "69e45d20-98a9-4c75-ab60-1188d64d510a",
    "bwItemId": "550e8400-e29b-41d4-a716-446655440000",
    "comment": "Updated reason for blocking"
  }'

Get all linked targets (cascades, gates, merchants, banks) for a list.

curl -X POST 'https://api.embermind.ch/api/v1/client/bw-lists/targets/get-list' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "bwListId": "69e45d20-98a9-4c75-ab60-1188d64d510a"
  }'

Response:

{
  "data": {
    "targetType": "DIRECT",
    "cascadeList": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "Main Cascade",
        "isActive": true
      }
    ],
    "gateList": [
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
        "title": "Gate 1",
        "isActive": true
      }
    ],
    "merchantList": [],
    "bankList": []
  }
}

Update targets for a list. Replaces all existing target links.

curl -X POST 'https://api.embermind.ch/api/v1/client/bw-lists/targets' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "bwListId": "69e45d20-98a9-4c75-ab60-1188d64d510a",
    "targetType": "DIRECT",
    "cascadeIdList": [
      { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "isActive": true }
    ],
    "gateIdList": [
      { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "isActive": true }
    ],
    "merchantIdList": [],
    "bankIdList": []
  }'

Import items from a CSV or XLSX file. The file must contain columns matching the item type (e.g., Email, Phone).

curl -X POST 'https://api.embermind.ch/api/v1/client/bw-lists/import-file' \
  -H 'x-api-key: YOUR_API_KEY' \
  -F 'file=@blocked_emails.csv' \
  -F 'bwListId=69e45d20-98a9-4c75-ab60-1188d64d510a' \
  -F 'importMode=APPEND'

Request parameters:

Field	Type	Required	Description
`file`	file	Yes	CSV or XLSX file with items
`bwListId`	string (uuid)	No	Existing list ID. If omitted, a new list is created
`title`	string	No	Required when `bwListId` is not provided
`type`	string	No	`WHITE` or `BLACK`. Required when `bwListId` is not provided
`importMode`	string	No	Import mode (e.g., `APPEND`)

Response:

{
  "taskId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "bwListId": "69e45d20-98a9-4c75-ab60-1188d64d510a",
  "status": "PENDING",
  "message": "Import task created"
}

Check the status of an import task.

curl -X POST 'https://api.embermind.ch/api/v1/client/bw-lists/import-status' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "taskId": "c3d4e5f6-a7b8-9012-cdef-345678901234"
  }'

Response:

{
  "taskId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "status": "COMPLETED",
  "progress": 100,
  "resultJson": {
    "totalRowCount": 1000,
    "successRowCount": 995,
    "failedRowCount": 5,
    "errorList": [
      {
        "rowNumber": 17,
        "reason": "INVALID_EMAIL",
        "rawRow": {
          "Email": "bad_email",
          "Comment": null
        }
      }
    ]
  }
}

Multi-component groups allow you to define rules that match only when all components in a group match simultaneously. This is useful for precise targeting, e.g., blocking a specific email + card combination rather than either attribute individually.

Base URL: https://api.embermind.ch/api/v1/client/bw-multi-component-groups

Create a multi-component group attached to a list.

curl -X POST 'https://api.embermind.ch/api/v1/client/bw-multi-component-groups/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "bwListId": "69e45d20-98a9-4c75-ab60-1188d64d510a",
    "componentList": [
      {
        "type": "EMAIL",
        "value": "[email protected]",
        "comment": "Suspicious email"
      },
      {
        "type": "CARD_BIN",
        "value": "411111",
        "comment": "Combined with suspect email"
      }
    ]
  }'

This group will only match when a transaction has both the email [email protected] and card BIN 411111.

Get multi-component groups for a list.

curl -X POST 'https://api.embermind.ch/api/v1/client/bw-multi-component-groups/get-list' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "bwListId": "69e45d20-98a9-4c75-ab60-1188d64d510a",
    "page": 1,
    "perPage": 20
  }'

Response:

{
  "count": 1,
  "dataList": [
    {
      "id": "d4e5f6a7-b8c9-0123-defg-456789012345",
      "blackWhiteListId": "69e45d20-98a9-4c75-ab60-1188d64d510a",
      "createdAt": "2024-01-15T10:30:00.027Z",
      "componentList": [
        {
          "id": "e5f6a7b8-c9d0-1234-efgh-567890123456",
          "type": "EMAIL",
          "value": "[email protected]",
          "normalizedValue": "[email protected]",
          "comment": "Suspicious email"
        },
        {
          "id": "f6a7b8c9-d0e1-2345-fghi-678901234567",
          "type": "CARD_BIN",
          "value": "411111",
          "normalizedValue": "411111",
          "comment": "Combined with suspect email"
        }
      ]
    }
  ]
}

Remove a multi-component group.

curl -X POST 'https://api.embermind.ch/api/v1/client/bw-multi-component-groups/remove' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "multiComponentGroupId": "d4e5f6a7-b8c9-0123-defg-456789012345"
  }'

Scenario: Block all transactions from a known fraud email company-wide.

Step 1: Create a black list with target type ALL:

curl -X POST 'https://api.embermind.ch/api/v1/client/bw-lists/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "title": "Blocked Fraud Emails",
    "type": "BLACK",
    "targetType": "ALL",
    "bwItemList": [
      {
        "type": "EMAIL",
        "value": "[email protected]",
        "comment": "Confirmed fraud case #1234"
      }
    ],
    "cascadeIdList": [],
    "gateIdList": [],
    "merchantIdList": [],
    "bankIdList": []
  }'

Now any transaction with the email [email protected] will be automatically rejected across all cascades, gates, and merchants.

Scenario: Allow specific trusted customers to bypass scoring for a particular gate.

Step 1: Get your gate ID:

curl -X POST 'https://api.embermind.ch/api/v1/client/gates/get-list' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{}'

Response (excerpt):

{
  "dataList": [
    { "id": "gate-uuid-1", "title": "Premium Gate" }
  ]
}

Step 2: Create a white list linked to that gate:

curl -X POST 'https://api.embermind.ch/api/v1/client/bw-lists/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "title": "Trusted VIP Customers",
    "type": "WHITE",
    "targetType": "DIRECT",
    "bwItemList": [
      {
        "type": "EMAIL",
        "value": "[email protected]",
        "comment": "VIP customer"
      },
      {
        "type": "CARD_TOKEN",
        "value": "trusted_card_token_abc",
        "comment": "Verified card"
      }
    ],
    "cascadeIdList": [],
    "gateIdList": ["gate-uuid-1"],
    "merchantIdList": [],
    "bankIdList": []
  }'

Now transactions through Premium Gate matching these items will be allowed to bypass scoring.

Scenario: Block transactions only when a specific email AND card BIN appear together.

Step 1: Create a black list:

curl -X POST 'https://api.embermind.ch/api/v1/client/bw-lists/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "title": "Fraud Pattern - Email + BIN",
    "type": "BLACK",
    "targetType": "ALL",
    "bwItemList": [],
    "cascadeIdList": [],
    "gateIdList": [],
    "merchantIdList": [],
    "bankIdList": []
  }'

Step 2: Get the list ID from get-list, then create a multi-component group:

curl -X POST 'https://api.embermind.ch/api/v1/client/bw-multi-component-groups/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "bwListId": "new-list-uuid",
    "componentList": [
      {
        "type": "EMAIL",
        "value": "[email protected]",
        "comment": "Part of fraud pattern"
      },
      {
        "type": "CARD_BIN",
        "value": "411111",
        "comment": "Specific BIN linked to fraud"
      }
    ]
  }'

Now transactions are rejected only when both [email protected] and BIN 411111 appear in the same transaction. Either attribute alone will not trigger a block.

Adding an item to a black list that already exists in a white list (or vice versa) with the same value will result in a conflict error. Remove the conflicting entry first.
Items are uniquely identified by the combination of type and value. The same value can appear in different lists if the types differ.
Values are automatically normalized (e.g., emails are lowercased) for consistent matching.

Scoring Rules — Configure risk scoring
Alerts — Configure fraud alert notifications
Data Migration — Import historical transactions