Blacklist

TIP

Instructions for working with the blacklist in the Brainysoft interface can be found in the section:

"User Instructions" → "Operational Activities" → "Admin" → "Blacklist".

API Methods for Working with Blacklist

Method	URL	Description
GET\|HEAD	`auth/blacklist/template`	Get template
POST	`blacklist/load-template` `auth/blacklist/load-template`	Upload file with data for bulk addition
GET\|HEAD\|POST\| PUT\|PATCH\| DELETE\|OPTIONS	`blacklist/list/limit/{limit}/page/{page}` `auth/blacklist/list/limit/{limit}/page/{page}`	Get blacklist with pagination
POST	`blacklist/add-entry` `auth/blacklist/add-entry`	Add entry to blacklist
GET\|HEAD	`blacklist/{type}/client/{client_id}` `auth/blacklist/{type}/client/{client_id}`	Check client by type
GET\|HEAD	`blacklist/{type}/lead/{lead_id}` `auth/blacklist/{type}/lead/{lead_id}`	Check lead by type
GET\|HEAD	`api/inside/complexblacklist/{type}/ taskId/{taskId}/leadId/{leadId}`	Check by step in DMS (taskId) for lead
GET\|HEAD	`blacklist/list/delete/{id}` `auth/blacklist/list/delete/{id}`	Delete entry by ID
GET\|HEAD	`blacklist/list/clear` `auth/blacklist/list/clear`	Clear blacklist

Get Blacklist Template

GET|HEAD /auth/blacklist/template

Description

This method allows you to get the current template for bulk addition of entries to the blacklist (.xlsx). Use this template to prepare data before bulk upload via API.

Download template:
blacklist_template.xlsx

Request Example

GET /auth/blacklist/template

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1751000006000, // Response time (UNIX timestamp, ms)
  "data": {
    "url": "https://example.com/blacklist-template.xlsx" // Link to template
  }
}

Upload File with Data for Bulk Addition

POST /blacklist/load-template

POST /auth/blacklist/load-template

Description

This method allows you to upload a file with data (.xlsx) for bulk addition of entries to the blacklist. Use the current template, previously downloaded via the template retrieval method, fill it with your data and upload it using this method.

Download filled template example:
blacklist_template(1).xlsx

Request Body (multipart/form-data)

Field	Type	Description
file	file	File with data to upload

Request Example

POST /blacklist/load-template

Content-Type: multipart/form-data

file: blacklist.xlsx

Successful Response Example

json

{
  "status": "ok",
  "timestamp": 1751465170000,
  "data": {
    "result": "File successfully uploaded, queued for processing"
  }
}

Get Blacklist with Pagination

GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS /blacklist/list/limit/{limit}/page/{page} GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS /auth/blacklist/list/limit/{limit}/page/{page}

Description

This method allows you to get a list of blacklist entries with pagination. The response returns an array of entries (with an extended set of fields) and page information.

Pagination is a mechanism for dividing a large list of data into separate pages (page-by-page output). Instead of returning all records at once, the API or web interface returns only a limited number of elements per request (for example, 10, 20, or 100), and the rest can be obtained by navigating to the next pages.

Request Parameters (path)

Parameter	Type	Description
limit	integer	Number of entries per page
page	integer	Page number

Request Example

GET /blacklist/list/limit/10/page/1

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1751465512000, // Response time (UNIX timestamp, ms)
  "data": {
    "per_page": 10, // Number of entries per page
    "total_entries": 149, // Total number of entries
    "page": 1, // Current page
    "data": [
      {
        "id": 149, // Unique entry identifier
        "last_name": "Sato", // Last name
        "first_name": "Aoi", // First name
        "patronymic": "Deep", // Patronymic
        "birthdate": "1994-08-10", // Date of birth
        "passport_seria": "1334", // Passport series
        "passport_no": "601234", // Passport number
        "inn": "809234567890", // Tax ID (INN)
        "snils": "601-234-567 28", // Social Security Number (SNILS)
        "mobile_phone": "+7 (999) 123-47-15", // Mobile phone
        "email": "", // Email
        "qiwi_wallet": null, // Qiwi wallet
        "ya_wallet": null, // Yandex wallet
        "web_money": null, // WebMoney
        "account_no": null, // Bank account
        "bank_name": null, // Bank
        "card_no": null, // Bank card
        "company_name": "", // Company name
        "comments": null, // Comments
        "deleted_at": null, // Deletion date (if entry is deleted)
        "ip4": "", // IP address
        "mac": "", // MAC address
        "fio": "Sato Aoi Deep", // Full name as one string
        "passport_number": "601234", // Passport number (duplicate)
        "mobile": "+7 (999) 123-47-15", // Mobile phone (duplicate)
        "birthDate": "1994-08-10", // Date of birth (duplicate)
        "cardnumber": null // Bank card (duplicate)
      }
      // ... other entries
    ]
  }
}

Add Entry to Blacklist via Request Body (Option 1: application/json)

POST /blacklist/add-entry

POST /auth/blacklist/add-entry

Description

The first way to add an entry to the blacklist is through a direct API request with a request body in JSON format (application/json).

Request Body (application/json)

Field	Type	Description
value	string	Value (e.g., phone, tax ID, email)
type	string	Value type (mobile_phone, inn, email, etc.)

Use values from the type column of the "Blacklist 'type' Allowed Values Reference" in the type field when adding an entry.
In the value field, specify the corresponding value.

Blacklist "type" Allowed Values Reference

type	Description	Example value
last_name	Last name	Sato
first_name	First name	Aoi
patronymic	Patronymic	Deep
birthdate	Date of birth (y-m-d)	1994-08-1
passport_seria	Passport series	1334
passport_no	Passport number	601234
inn	Tax ID (INN)	809234567890
snils	Social Security Number (SNILS)	601-234-567 28
mobile_phone	Mobile phone	79991234715
email	Email	test@example.com
qiwi_wallet	Qiwi wallet	QIWI123456
ya_wallet	Yandex wallet	YANDEX123456
web_money	WebMoney	WMID123456
account_no	Bank account	40817810099910004312
bank_name	Bank	Sberbank
card_no	Bank card	4276380012345678
company_name	Company name	LLC "Romashka"
comments	Comments	Fraud
deleted_at	Deletion date	2025-07-01T10:00:00+00:00
ip4	IP address	192.168.1.1
mac	MAC address	00:1A:2B:3C:4D:5E
fio	Full name as one string	Sato Aoi Deep
passport_number	Passport number (duplicate)	601234
mobile	Mobile (duplicate)	79991234715
birthDate	Date of birth (y-m-d) (duplicate)	1994-08-1
cardnumber	Bank card (duplicate)	4276380012345678

Request Example

json

{
  "last_name": "Joe", // Last name
  "first_name": "Joe", // First name
  "patronymic": "Joe", // Patronymic
  "birthdate": "1994-08-10", // Date of birth (YYYY-MM-DD)
  "comment": "Fraud" // Comment
}

Successful Response Example

json

{
  "status": "ok",
  "timestamp": 1751000001000,
  "data": {
    "result": "ok"
  }
}

Add Entry to Blacklist via File (Option 2: multipart/form-data)

POST /blacklist/add-entry

POST /auth/blacklist/add-entry

Description

The second way to add an entry to the blacklist is by uploading a file (.xlsx) containing the data to add.

Request Body (multipart/form-data)

Field	Type	Description
file	file	File with data to upload

Download template:
blacklist_template.xlsx

Request Example

POST /blacklist/add-entry

Content-Type: multipart/form-data

file: single_blacklist_entry.xlsx

Successful Response Example

json

{
  "status": "ok",
  "timestamp": 1751479717000,
  "data": {
    "result": "ok"
  }
}

Check Client by Type

GET|HEAD /blacklist/{type}/client/{client_id}

GET|HEAD /auth/blacklist/{type}/client/{client_id}

Description

This method allows you to check if a client has entries in the blacklist by a specific type (e.g., phone, inn, email). The response returns a recommendation (allow or deny the operation) and information about matches.

Request Parameters

{type} (string, required) — value type (phone, inn, email, etc.). See above "Blacklist 'type' Allowed Values Reference".
{client_id} (integer, required) — client identifier

Request Example

GET /blacklist/mobile_phone/client/3173

Response Example: Entry Not Found in Blacklist

json

{
  "status": "ok",
  "timestamp": 1751482337000,
  "data": {
    "recommendation": "APPROVE", // Recommendation: allow (not in blacklist)
    "options": {
      "mobile_record_id": null, // No entry in blacklist
      "mobile_match": 0, // Match not found
      "mobile_match_partly": 0 // Partial match not found
    }
  }
}

If recommendation = "APPROVE" and mobile_match = 0 — entry not found in blacklist, operation can be allowed.

Request Example

GET /blacklist/mobile_phone/client/3174

Response Example: Entry Found in Blacklist

json

{
  "status": "ok",
  "timestamp": 1751482391000,
  "data": {
    "recommendation": "DENY", // Recommendation: deny (found in blacklist)
    "options": {
      "mobile_record_id": 121, // ID of found entry in blacklist
      "mobile_match": 1, // Match found
      "mobile_match_partly": 0, // Partial match not found
      "mobile_comments": null // Comments
    }
  }
}

If recommendation = "DENY" and mobile_match = 1 — entry found in blacklist, it is recommended to deny the operation.

Response Fields Description

Field	Type	Description
status	string	Request execution status
timestamp	integer	Response time (UNIX timestamp, ms)
data.recommendation	string	Recommendation based on check result (`DENY` — deny, `ALLOW` — allow)
data.options.mobile_record_id	integer	Internal mobile phone record identifier
data.options.mobile_match	integer	Full match indicator (1 — found in blacklist, 0 — not found)
data.options.mobile_match_partly	integer	Partial match indicator (1 — partial match, 0 — not found)
data.options.mobile_comments	string\|null	Comments on check result

Check Lead by Type

GET|HEAD /blacklist/{type}/lead/{lead_id}

GET|HEAD /auth/blacklist/{type}/lead/{lead_id}

Description

This method allows you to check if a lead has entries in the blacklist by a specific type (e.g., phone, inn, email).

Request Parameters

{type} (string, required) — value type (phone, inn, email, etc.). See above "Blacklist 'type' Allowed Values Reference".
{lead_id} (integer, required) — lead identifier.

Request Example

GET /blacklist/mobile_phone/lead/7336

Response Example: Entry Not Found in Blacklist

json

{
  "status": "ok",
  "timestamp": 1751481784000,
  "data": {
    "recommendation": "APPROVE", // Recommendation: allow (not in blacklist)
    "options": {
      "mobile_record_id": null, // No entry in blacklist
      "mobile_match": 0, // Match not found
      "mobile_match_partly": 0 // Partial match not found
    }
  }
}

If recommendation = "APPROVE" and mobile_match = 0 — entry not found in blacklist, operation can be allowed.

Request Example

GET /blacklist/mobile_phone/lead/7337

Response Example: Entry Found in Blacklist

json

{
  "status": "ok",
  "timestamp": 1751481902000,
  "data": {
    "recommendation": "DENY", // Recommendation: deny (found in blacklist)
    "options": {
      "mobile_record_id": 121, // ID of found entry in blacklist
      "mobile_match": 1, // Match found
      "mobile_match_partly": 0, // Partial match not found
      "mobile_comments": null // Comments
    }
  }
}

If recommendation = "DENY" and mobile_match = 1 — entry found in blacklist, it is recommended to deny the operation.

Response Fields Description

Field	Type	Description
status	string	Request execution status
timestamp	integer	Response time (UNIX timestamp, ms)
data.recommendation	string	Recommendation based on check result (`DENY` — deny, `ALLOW` — allow)
data.options.mobile_record_id	integer	Internal mobile phone record identifier
data.options.mobile_match	integer	Full match indicator (1 — found in blacklist, 0 — not found)
data.options.mobile_match_partly	integer	Partial match indicator (1 — partial match, 0 — not found)
data.options.mobile_comments	string\|null	Comments on check result

Check by Step in DMS (taskId) for Lead

GET|HEAD /blacklist/checks/{type}/taskId/{taskId}/leadId/{leadId}

!GET|HEAD /api/inside/complexblacklist/{type}/taskId/{taskId}/leadId/{leadId}

!GET|HEAD /api/inside/blacklist/{type}/taskId/{task_id}/leadId/{lead_id}

Description

This method allows you to check for entries in the blacklist by a specific type for a lead within a specific step in the Decision Making System (DMS), identified by taskId.

Note about taskId:
taskId is the step identifier in the DMS (Decision Making System). To find the current taskId for an application, open DevTools on the application page and execute the following command in the console:
js
engymod();
As a result, an object will be displayed in the console where you can find the required taskId (ruleTaskId=...).

Request Parameters

{type} (string, required) — value type (e.g., mobile_phone, inn, email, etc.)
{taskId} (integer, required) — step identifier in DMS (taskId)
{leadId} (integer, required) — lead identifier

Request Example

GET /api/inside/complexblacklist/mobile_phone/taskId/15531/leadId/7328

Response Example: Entry Found in Blacklist

json

{
  "status": "ok",
  "timestamp": 1751481902000,
  "data": {
    "recommendation": "DENY", // Recommendation: deny (found in blacklist)
    "options": {
      "mobile_record_id": 121, // ID of found entry in blacklist
      "mobile_match": 1, // Match found
      "mobile_match_partly": 0, // Partial match not found
      "mobile_comments": null // Comments
    }
  }
}

Response Fields Description

Field	Type	Description
status	string	Request execution status
timestamp	integer	Response time (UNIX timestamp, ms)
data.recommendation	string	Recommendation based on check result (`DENY` — deny, `ALLOW` — allow)
data.options.mobile_record_id	integer	Internal mobile phone record identifier
data.options.mobile_match	integer	Full match indicator (1 — found in blacklist, 0 — not found)
data.options.mobile_match_partly	integer	Partial match indicator (1 — partial match, 0 — not found)
data.options.mobile_comments	string\|null	Comments on check result

Delete Entry by ID

GET|HEAD /blacklist/list/delete/{id}

GET|HEAD /auth/blacklist/list/delete/{id}

Description

This method allows you to delete an entry from the blacklist by its unique identifier. Use this method when you need to delete a specific entry from the blacklist (e.g., by mistake or by user request).

Request Parameters (path)

Parameter	Type	Description
id	integer	Unique entry identifier

Request Example

GET /blacklist/list/delete/121

Successful Response Example

json

{
  "status": "ok",
  "timestamp": 1751483864000,
  "data": null
}

Clear Blacklist

GET|HEAD /blacklist/list/clear

GET|HEAD /auth/blacklist/list/clear

Description

This method allows you to completely clear the blacklist (delete all entries from the blacklist).

Request Example

GET /blacklist/list/clear

Successful Response Example

json

{
  "status": "ok",
  "timestamp": 1751483030000,
  "data": null
}

Field Descriptions

Field	Type	Description
status	string	Request execution status
timestamp	integer	Response time (UNIX timestamp, ms)
per_page	integer	Number of entries per page (for pagination)
total_entries	integer	Total number of entries (for pagination)
page	integer	Current page (for pagination)
data	array/object	Array or object with data (e.g., blacklist entries, upload result, etc.)
id	integer	Unique entry identifier
last_name	string	Last name
first_name	string	First name
patronymic	string	Patronymic
birthdate / birthDate	string	Date of birth (YYYY-MM-DD). May appear as birthdate or birthDate
passport_seria	string	Passport series
passport_no / passport_number	string	Passport number
inn	string	Tax ID (INN)
snils	string	Social Security Number (SNILS)
mobile_phone / mobile	string	Mobile phone. May appear as mobile_phone or mobile
email	string	Email
qiwi_wallet	string	Qiwi wallet
ya_wallet	string	Yandex wallet
web_money	string	WebMoney
account_no	string	Bank account
bank_name	string	Bank
card_no / cardnumber	string	Bank card. May appear as card_no or cardnumber
company_name	string	Company name
comments	string	Comment
deleted_at	string	Entry deletion date
ip4	string	IPv4 address
mac	string	MAC address
fio	string	Full name as one string
value	string	Value to add to blacklist (e.g., phone, tax ID, email, etc.)
type	string	Value type (mobile_phone, inn, email, etc.; see type reference)
file	file	File for bulk upload
recommendation	string	Recommendation based on check result (APPROVE — allow, DENY — deny, ALLOW — allow)
options	object	Object with check result details
mobile_record_id	integer/null	Internal mobile phone record identifier (or null if not found)
mobile_match	integer	Full match indicator (1 — found in blacklist, 0 — not found)
mobile_match_partly	integer	Partial match indicator (1 — partial match, 0 — not found)
mobile_comments	string/null	Comments on check result (if any)
url	string	Link to download template or file
result	string	Operation execution result (e.g., "ok" or text message)

Blacklist ​

API Methods for Working with Blacklist ​

Get Blacklist Template ​

Upload File with Data for Bulk Addition ​

Get Blacklist with Pagination ​

Add Entry to Blacklist via Request Body (Option 1: application/json) ​

Blacklist "type" Allowed Values Reference ​

Add Entry to Blacklist via File (Option 2: multipart/form-data) ​

Check Client by Type ​

Check Lead by Type ​

Check by Step in DMS (taskId) for Lead ​

Delete Entry by ID ​

Clear Blacklist ​

Field Descriptions ​

Blacklist

API Methods for Working with Blacklist

Get Blacklist Template

Upload File with Data for Bulk Addition

Get Blacklist with Pagination

Add Entry to Blacklist via Request Body (Option 1: application/json)

Blacklist "type" Allowed Values Reference

Add Entry to Blacklist via File (Option 2: multipart/form-data)

Check Client by Type

Check Lead by Type

Check by Step in DMS (taskId) for Lead

Delete Entry by ID

Clear Blacklist

Field Descriptions