How-To: Customer Management
Idenza supports managing specific user lists (Whitelist/Blacklist) to influence risk scoring decisions based on the user. This guide is structured around common client tasks, followed by detailed API specifications. It details how to add, remove, and retrieve users from the subscriber-specific Whitelist and Blacklist. These lists are used by the risk scoring engine to automatically approve or decline transactions associated with the listed users.
Prerequisites
To manage customer statuses successfully, you must have the following:
-
API Key: An active API key must be supplied via the X-API-Key HTTP header.
-
Required Identifiers: The subscriber_id and unique customer identifying fields (email and customer_reference_id) are mandatory for all management operations.
Base URL: https://coral-app-2-4y6qg.ondigitalocean.app
1. Add or Set a User's Status (Whitelist or Blacklist)
To register a new user or modify an existing user’s status to either Whitelist or Blacklist, use the /customer/add endpoint. You must provide all required identifying fields and set exactly one status flag (add_to_whitelist or add_to_blacklist) to true.
If you don’t set any of (add_to_whitelist or add_to_blacklist) the customer will be treated as a Normal User.
API Overview
Fingerprint
Transaction Scoring
Customer Management
Mandatory Data Fields
Type
Description
subscriber_id
integer
Your organization's ID.
first_name
string
Customer's first name.
last_name
string
Customer's last name.
string
Customer's primary email address.
customer_reference_id
string
Your internal unique identifier for the customer.
add_to_whitelist or add_to_blacklist
boolean
Set one of these to true.
Example: Whitelisting a Customer
Bash
curl -X POST \
https://coral-app-2-4y6qg.ondigitalocean.app/customer/add \
-H "X-API-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"subscriber_id": 12,
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"customer_reference_id": "CUST-9001",
"add_to_whitelist": true
}'
2. Remove or Reset a User's Status
To remove a user from an explicit status list (Blacklist or Whitelist), use the /customer/remove endpoint. This operation requires identification and exactly one removal flag.
Mandatory Data Fields
Type
Description
subscriber_id
integer
Your organization's ID.
string
Customer's primary email address.
customer_reference_id
string
Your internal unique identifier for the customer.
remove_from_whitelist or
remove_from_blacklist
boolean
Set one of these to true.
Example: Removing a Customer
Bash
curl -X POST \
https://coral-app-2-4y6qg.ondigitalocean.app/customer/remove \
-H "X-API-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"subscriber_id": 12,
"email": "jane.doe@example.com",
"customer_reference_id": "CUST-9001",
"remove_from_blacklist": true
}'
3. Retrieve a List of Customers by Status
To fetch all customers currently on a specific list, use the /customer/get endpoint with query parameters. This uses the GET method.
Query Parameters
Type
Required / Optional
Description
subscriber_id
integer
Required
Your organization's ID.
whitelisted or
blacklisted
boolean
Optional
Set one of these to true to filter the results.
Example: Getting the Blacklist
Bash
curl -X GET \
'https://coral-app-2-4y6qg.ondigitalocean.app/customer/get?subscriber_id=12&blacklisted=true' \
-H "X-API-Key: <YOUR_API_KEY>"
Example Success Response (200 OK)
JSON
{
"subscriber_id": 12,
"reason": "BLACKLIST",
"users": [
{
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"customer_reference_id": "CUST-9001",
"status": "BLACKLIST"
}
]
}
Best practice: Exactly one status flag per call (add/remove). Log subscriber_id, user_id, and list changes for auditability.