API Reference: Customer Status Endpoints
Endpoints
/customer/add
Add to whitelist or blacklist
/customer/remove
Remove from whitelist or blacklist
/customer/get
Retrieve a list of all users for a subscriber who are on the specified list
Endpoint: /customer/add
Property
Value
Method
POST
Description
Creates a new customer record or updates an existing one, setting their list status (Whitelist or Blacklist).
Authentication
Required: X-API-Key HTTP Header
API Overview
Fingerprint
Transaction Scoring
Customer Management
Request Query Parameters: (application/json)
Parameter
Type
Required
Description
subscriber_id
integer
Yes
Your organization's ID.
first_name
string
Yes
Customer's first name.
last_name
string
Yes
Customer's last name.
string
Yes
Customer's email address.
customer_reference_id
string
Yes
Your internal unique customer identifier.
add_to_whitelist
boolean
Conditional*
Set to true to add to the Whitelist.
add_to_blacklist
boolean
Conditional*
Set to true to add to the Blacklist.
role
string
No
The role of the party (default: PAYEE).
*Note: Exactly one of add_to_whitelist or add_to_blacklist must be set to true for list management.
Response Codes and Payloads
Status Code
Description
Success / Error
Payload Structure
200 OK
User status successfully set.
Success
{"subscriber_id": 12, "fullname": "...", "status": "WHITELIST"}
400 Bad Request
Missing required fields or conflict (e.g., trying to set both Whitelist and Blacklist).
Error
{"error": "...", "missing_fields": ["..."]}
401 Unauthorized
Missing or invalid API Key.
Error
{"error": "Invalid API key"}
500 Internal Server Error
Failure to process the database update.
Error
{"error": "Failed to upsert user", "details": "..."}
503 Service Unavailable
The internal parties service is unavailable.
Error
{"error": "Parties service unavailable"}
Endpoint: /customer/remove
Property
Value
Method
POST
Description
Removes a user from an explicit list status (Whitelist or Blacklist).
Authentication
Required: X-API-Key HTTP Header
Request Query Parameters: (application/json)
Parameter
Type
Required
Description
subscriber_id
integer
Yes
Your organization's ID.
string
Yes
Customer's email address.
customer_reference_id
string
Yes
Your internal unique customer identifier.
remove_from_whitelist
boolean
Conditional*
Set to true to remove from the Whitelist.
remove_from_blacklist
boolean
Conditional*
Set to true to remove from the Blacklist.
*Note: Exactly one of remove_from_whitelist or remove_from_blacklist must be set to true to specify the action.
Response Codes and Payloads
Status Code
Description
Success / Error
Payload Structure
200 OK
User successfully removed from the specified list.
Success
{"subscriber_id": 12, "email": "...", "status": "BLACKLIST", "result": "Removed user..."}
400 Bad Request
Missing required fields or invalid combination of removal flags.
Error
{"error": "...", "missing_fields": ["..."]}
401 Unauthorized
Missing or invalid API Key.
Error
{"error": "Invalid API key"}
500 Internal Server Error
Failure to process the database deletion.
Error
{"error": "Failed to remove user", "details": "..."}
503 Service Unavailable
The internal parties service is unavailable.
Error
{"error": "Parties service unavailable"}
Endpoint: /customer/get
Property
Value
Method
GET
Description
Retrieves a list of all users for a subscriber who are on the specified list (Whitelist or Blacklist).
Authentication
Required: X-API-Key HTTP Header
Request Query Parameters: (application/json)
Parameter
Type
Required
Description
subscriber_id
integer
Yes
Your organization's ID.
whitelisted
boolean
Conditional*
Set to true to fetch the list of Whitelisted users.
blacklisted
boolean
Conditional*
Set to true to fetch the list of Blacklisted users.
*Note: Exactly one of whitelisted or blacklisted must be set to true to specify the list type.
Response Codes and Payloads
Description
Success / Error
Payload Structure
200 OK
List of users successfully fetched.
Success
{"subscriber_id": 12, "reason": "WHITELIST", "users": [...]}
400 Bad Request
Missing subscriber_id or conflicting list requests.
Error
{"error": "Missing 'subscriber_id' request argument"}
401 Unauthorized
Missing or invalid API Key.
Error
{"error": "Invalid API key"}
500 Internal Server Error
Failure to retrieve the user list from the database.
Error
{"error": "Failed to fetch user list", "details": "..."}
503 Service Unavailable
The internal parties service is unavailable.
Error
{"error": "Parties service unavailable"}