Fraud Detection and Risk Management

The Fraud Detection and Risk Management API enables comprehensive fraud prevention and security monitoring for business partners using Signet's services. Partners can blacklist suspicious users, flag compromised devices and IP addresses, verify geolocation data, report fraud incidents, and assess user risk scores. The API provides real-time transaction monitoring, pattern recognition, and automated fraud prevention measures to protect users and transactions. These endpoints provide businesses with a secure and efficient way to manage fraud detection, risk assessment, and security enforcement at scale.

The fraud detection model

The fraud detection model handles the data fields used in the Fraud Detection API endpoints for managing security threats, risk assessment, and fraud prevention. It enables comprehensive monitoring of users, devices, IP addresses, and fraudulent activities.

Properties

Name
userId
Type
string
Description
Unique identifier for the user (UUID format). Required for user-related operations.
Name
deviceId
Type
string
Description
Unique identifier for the device (UUID format). Required for device management operations.
Name
reasons
Type
array
Description
Reasons for blacklisting, flagging, or reporting. Required for security actions.
Name
limit
Type
integer
Description
Maximum number of records to return in a single response. Used for pagination.
Name
offset
Type
integer
Description
Number of records to skip before starting to return results. Used with "limit" for pagination.
Name
ip
Type
string
Description
IP address (IPv4 or IPv6 format). Required for IP flagging and geolocation verification.
Name
ipAddress
Type
string
Description
IP address for geolocation verification. Required for geo-verify endpoint.
Name
expectedCountry
Type
string
Description
Expected country for geolocation verification. Required for geo-verify endpoint.
Name
expectedCity
Type
string
Description
Expected city for geolocation verification. Required for geo-verify endpoint.

Blacklist Management

Blacklist user

The blacklist endpoint bans a user by userId with specified reasons. It validates ownership, prevents duplicate entries, records the ban with fraud reasons, and returns confirmation with user and developer IDs.

Required attributes

Name
userId
Type
string
Description
Unique identifier for the user (UUID format).
Name
reasons
Type
array
Description
Array of fraud reasons for risk assessment.

Request

POST

/fraud/v1/blacklist

curl -X POST https://localhost:4301/fraud/v1/blacklist \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "43c62e7f-6151-4c6b-87a3-c3fc27a14d6c",
    "reasons": [
      "Suspicious activity detected",
      "Multiple failed login attempts",
      "Violation of terms of service"
    ]
  }'

Response True (1/2)

{
  "success": true,
  "message": "User blacklisted successfully.",
  "data": {
    "userId": "43c62e7f-6158-4c6b-87a3-c3fc27a14d6c",
    "developerId": "b3bfcc1d-5bab-404c-87d0-82570ab311a0",
  }
}

Check Blacklist Status

The check-blacklist endpoint verifies if a user is banned by userId. It validates ownership, queries the blacklist, and returns the user’s status, reasons, and timestamps of blacklist and check events.

Required attributes

Name
userId
Type
string
Description
Unique identifier for the user (UUID format).

Request

GET

/fraud/v1/blacklist/user?userId

curl -X GET https://localhost:4301/fraud/v1/blacklist/user?userId \
  -H "Authorization: Bearer YOUR_API_KEY"

Response True (1/2)

{
  "success": true,
  "message": "User is blacklisted by this partner.",
  "data": {
    "userId": "f95edc93-2b44-4d33-b26c-8095d073c773",
    "developerId": "6a1e6eeb-c2ae-48c5-a615-3d0cd396cee9",
    "isBlacklisted": true,
    "reasons": [
      "Suspicious activity detected",
      "Multiple failed login attempts",
      "Violation of terms of service"
    ],
    "flagHistory": [
      {
        "reason": "Suspicious activity detected",
        "flaggedAt": "2025-10-01T19:16:05.923Z"
      },
      {
        "reason": "Multiple failed login attempts",
        "flaggedAt": "2025-10-01T19:16:05.923Z"
      },
      {
        "reason": "Violation of terms of service",
        "flaggedAt": "2025-10-01T19:16:05.923Z"
      }
    ],
    "blacklistedAt": "2025-10-01T19:16:05.923Z",
    "checkedAt": "2025-10-01T19:16:10.221Z"
  }
}

Get All Blacklisted Users

The blacklisted-users endpoint returns a paginated list of banned users. It supports limit and offset, enriches records with user details, and responds with blacklist reasons, timestamps, and pagination metadata.

Optional attributes

Name
limit
Type
integer
Description
Maximum number of records to return
Name
offset
Type
integer
Description
Number of records to skip

Request

GET

/fraud/v1/blacklist/users

curl -X GET https://localhost:4301/fraud/v1/blacklist/users \
  -H "Authorization: Bearer YOUR_API_KEY"

Response True (1/2)

{
  "success": true,
  "message": "Blacklisted users retrieved successfully.",
  "data": {
    "users": [
      {
        "id": "f95edc93-2b44-4d33-b26c-8095d073c773",
        "name": "John Doe",
        "email": "johasdn.doe@example.com",
        "status": "active",
        "createdAt": "2025-10-01T18:18:09.498Z",
        "updatedAt": "2025-10-01T18:18:09.498Z",
        "createdBy": "6a1e6eeb-c2ae-48c5-a615-3d0cd396cee9",
        "updatedBy": "6a1e6eeb-c2ae-48c5-a615-3d0cd396cee9"
      }
    ],
    "pagination": {
      "total": 1,
      "limit": 20,
      "offset": 0
    }
  }
}

Remove User from Blacklist

The remove-blacklist-user endpoint unbans a user by userId. It validates ownership, removes the user from the blacklist database, and returns confirmation with user and developer IDs.

Required attributes

Name
userId
Type
string
Description
Unique identifier for the user (UUID format).

Request

DELETE

/fraud/v1/blacklist/remove

curl -X DELETE https://localhost:4301/fraud/v1/blacklist/remove \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "43c62e7f-6158-4c6b-87a3-c3fc27a14d6c"
  }'

Response True (1/2)

{
  "success": true,
  "message": "User has been removed from blacklist.",
  "data": {
    "userId": "43c62e7f-6158-4c6b-87a3-c3fc27a14d6c",
    "developerId": "b3bfcc1d-5bab-404c-87d0-82570ab311a0"
  }
}

Device Management

Flag a Device

The flag-device endpoint marks a device as suspicious by deviceId and userId. It prevents duplicate flags, records reasons with a timestamp, and returns confirmation with the flagged device details.

Required attributes

Name
deviceId
Type
string
Description
Unique identifier for the device (UUID format).
Name
userId
Type
string
Description
Unique identifier for the user (UUID format).
Name
reasons
Type
array
Description

Request

POST

/fraud/v1/flag-device

curl -X POST https://localhost:4301/fraud/v1/flag \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "deviceId": "5f66e9ea-7150-4049-b6eb-34f43f3cbfde",
    "userId": "f95edc93-2b44-4d33-b26c-8095d073c773",
    "reasons": [
      "fraud"
    ]
  }'

Response True (1/2)

{
  "success": true,
  "message": "Device flagged successfully.",
  "data": {
    "deviceId": "5f66e9ea-7150-4049-b6eb-34f43f3cbfde",
    "reasons": [
      "fraud"
    ]
  }
}

Check Device Status

The device-check endpoint verifies if a device is flagged by deviceId and userId. If flagged, it returns reasons, history, and timestamps; if not, it confirms the device is safe.

Required attributes

Name
deviceId
Type
string
Description
Unique identifier for the device (UUID format).
Name
userId
Type
string
Description
Unique identifier for the user (UUID format).

Request

GET

/fraud/v1/device/check?deviceId&userId

curl -X GET "https://localhost:4301/fraud/v1/device/check?deviceId&userId" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response True (1/2)

{
  "success": true,
  "message": "Device is flagged.",
  "data": {
    "deviceId": "5f66e9ea-7150-4049-b6eb-34f43f3cbfde",
    "isFlagged": true,
    "reasons": [
      "fraud"
    ],
    "flagHistory": [
      {
        "reason": "fraud",
        "flaggedAt": "2025-10-01T19:18:53.112Z"
      }
    ],
    "totalFlags": 1
  }
}

Unflag a Device

The unflag-device endpoint clears a device’s suspicious status by deviceId and userId. It validates the request, removes the flag if present, and returns confirmation with device and developer IDs.

Required attributes

Name
deviceId
Type
string
Description
Unique identifier for the device (UUID format).
Name
userId
Type
string
Description
Unique identifier for the user (UUID format).

Request

POST

/fraud/v1/device/unflag

curl -X POST https://localhost:4301/fraud/v1/device/unflag \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "deviceId": "5f66e9ea-7150-4049-b6eb-34f43f3cbfde",
    "userId": "5f66e9ea-7150-4049-b6eb-34f43f3cbfde"
  }'

Response True (1/2)

{
  "success": true,
  "message": "Device has been unflagged.",
  "data": {
    "deviceId": "5f66e9ea-7150-4049-b6eb-34f43f3cbfde",
    "developerId": "b3bfcc1d-5bab-404c-87d0-82570ab311a0"
  }
}

IP Address Management

Flag an IP Address

The flag-ip endpoint marks an IP as suspicious for a given userId. It prevents duplicate flags, records reasons with a timestamp, and returns confirmation with the flagged IP and user details.

Required attributes

Name
userId
Type
string
Description
Unique identifier for the user (UUID format).
Name
ip
Type
string
Description
The IP address to be flagged.
Name
reasons
Type
array
Description
Reason for flagging.

Request

POST

/fraud/v1/ip/flag

curl -X POST https://localhost:4301/fraud/v1/ip/flag \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "43c62e7f-6158-4c6b-87a3-c3fc27a14d6c",
    "ip": "192.168.1.100",
    "reasons": [
      "Too many requests."
    ]
  }'

Response True (1/2)

{
  "success": true,
  "message": "IP address flagged successfully.",
  "data": {
    "userId": "f95edc93-2b44-4d33-b26c-8095d073c773",
    "ip": "192.168.1.101",
    "reasons": [
      "Too many requests."
    ]
  }
}

Check IP Status

The ip-check endpoint verifies if an IP is flagged. It validates the IP, checks across the developer’s users, and returns whether it’s flagged along with reasons, history, and timestamps.

Required attributes

Name
ip
Type
string
Description
The IP address to be flagged.

Optional attributes

Name
userId
Type
string
Description
Unique identifier for the user (UUID format).
Name
limit
Type
integer
Description
Maximum number of records to return
Name
offset
Type
integer
Description
Number of records to skip

Request

GET

/fraud/v1/ip/check?ip

curl -X GET https://localhost:4301/fraud/v1/ip/check?ip \
  -H "Authorization: Bearer YOUR_API_KEY"

Response True (1/3)

{
  "success": true,
  "message": "IP address is flagged for this user.",
  "data": {
    "userId": "f95edc93-2b44-4d33-b26c-8095d073c773",
    "ip": "192.168.1.101",
    "flagged": true,
    "reasons": [
      "Too many requests."
    ],
    "flagHistory": [
      {
        "reason": "Too many requests.",
        "flaggedAt": "2025-10-01T20:21:51.959Z"
      }
    ],
    "totalFlags": 1
  }
}

Unflag an IP Address

The unflag-ip endpoint clears an IP’s suspicious status. It validates the IP, removes it from the flagged list for associated users, and returns confirmation with user and IP details.

Path attributes

Name
userId
Type
string
Description
Unique identifier for the user (UUID format).
Name
ip
Type
string
Description
The IP address to be flagged.

Request

DELETE

/fraud/v1/ip/unflag

curl -X POST https://localhost:4301/fraud/v1/ip/flag \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "ip": "192.168.1.100"
  }'

Response True (1/2)

{
  "success": true,
  "message": "IP has been unflagged for this user.",
  "data": {
    "userId": "43c62e7f-6158-4c6b-87a3-c3fc27a14d6c",
    "ip": "192.168.1.100"
  }
}

Geolocation Verification

Verify Geolocation

The geo-verify endpoint checks if a user’s IP location matches an expected country and city. It compares detected geolocation data with expected values and returns whether they match, along with detailed location info.

Required attributes

Name
userId
Type
string
Description
Unique identifier for the user (UUID format).
Name
ipAddress
Type
string
Description
The IP address of the user.
Name
expectedCountry
Type
string
Description
The expected country of origin.
Name
expectedCity
Type
string
Description
The expected city of origin.

Request

POST

/fraud/v1/geo/verify

curl -X POST https://localhost:4301/fraud/v1/geo/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "5f66e9ea-7150-4049-b6eb-34f43f3cbfde",
    "ipAddress": "183.8.82.28",
    "expectedCountry": "CN",
    "expectedCity": "Shenzhen"
  }'

Response True (1/2)

{
  "success": true,
  "message": "User location verified successfully.",
  "data": {
    "ipAddress": "183.8.82.28",
    "expected": {
      "country": "CN",
      "city": "Shenzhen"
    },
    "detected": {
      "country": "CN",
      "city": "Shenzhen"
    },
    "locationMatch": true
  }
}

User Reporting & Moderation

Report a User

The report-user endpoint lets developers flag a user for suspicious activity by userId and reasons. It creates a fraud report, marks the user for monitoring, and returns confirmation with report details and timestamp.

Required attributes

Name
userId
Type
string
Description
Unique identifier for the user (UUID format).
Name
reasons
Type
array
Description
The reason for reporting.

Request

POST

/fraud/v1/reporting/report

curl -X POST https://localhost:4301/fraud/v1/reporting/report \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "43c62e7f-6158-4c6b-87a3-c3fc27a14d6c",
    "reasons": [
      "Suspicious login from multiple locations."
    ]
  }'

Response True (1/2)

{
  "success": true,
  "message": "User reported successfully.",
  "data": {
    "userId": "f95edc93-2b44-4d33-b26c-8095d073c773",
    "reasons": [
      "Suspicious login from multiple locations."
    ]
  }
}

Check User Status

The check-user endpoint verifies if a user is flagged for fraud by userId. It validates ownership, queries the database, and returns the flag status with enrollment info and a check timestamp.

Required attributes

Name
userId
Type
string
Description
Unique identifier for the user (UUID format).

Request

GET

/fraud/v1/reporting/check?userId

curl -X GET https://localhost:4301/fraud/v1/reporting/check?userId \
  -H "Authorization: Bearer YOUR_API_KEY"

Response True (1/3)

{
  "success": true,
  "message": "User has not been flagged for this partner.",
  "data": {
    "userId": "43c62e7f-6158-4c6b-87a3-c3fc27a14d6c",
    "isFlagged": false
  }
}

Get User Reports

The get-user-reports endpoint retrieves all fraud reports for a user by userId. It supports pagination, validates ownership, and returns report reasons, timestamps, and pagination metadata.

Required attributes

Name
userId
Type
string
Description
Unique identifier for the user (UUID format).

Optional attributes

Name
limit
Type
integer
Description
Maximum number of records to return
Name
offset
Type
integer
Description
Number of records to skip

Request

GET

/fraud/v1/reporting/reports?userId

curl -X GET https://localhost:4301/fraud/v1/reporting/reports?userId \
  -H "Authorization: Bearer YOUR_API_KEY"

Response True (1/4)

{
  "success": true,
  "message": "Fraud reports retrieved successfully.",
  "data": {
    "reports": [
      {
        "reasons": [
          "Suspicious login from multiple locations."
        ],
        "flagHistory": [
          {
            "reason": "Suspicious login from multiple locations.",
            "flaggedAt": "2025-10-01T20:39:53.873Z"
          }
        ]
      },
      {
      "reasons": [
        "Suspicious login from multiple locations."
        ],
        "flagHistory": [
          {
            "reason": "Suspicious login from multiple locations.",
            "flaggedAt": "2025-10-01T20:39:23.466Z"
          }
        ]
      }
    ],
    "pagination": {
      "total": 2,
      "limit": 20,
      "offset": 0,
      "hasMore": false
    }
  }
}

Remove a Report

The remove-report endpoint deletes all fraud reports for a user by userId. It validates ownership, clears the reports from the database, and returns confirmation with the user ID and removal timestamp.

Required attributes

Name
userId
Type
string
Description
Unique identifier for the user (UUID format).

Request

DELETE

/fraud/v1/reporting/report/remove

curl -X DELETE https://localhost:4301/fraud/v1/reporting/report/remove \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "43c62e7f-6158-4c6b-87a3-c3fc27a14d6c"
  }'

Response True (1/3)

{
  "success": true,
  "message": "Reports removed successfully.",
  "data": {
    "userId": "43c62e7f-6158-4c6b-87a3-c3fc27a14d6c"
  }
}

Unflag a User

The unflag-user endpoint clears a user’s suspicious status by userId. It validates ownership, removes the flag if present, and returns confirmation with the user ID.

Required attributes

Name
userId
Type
string
Description
Unique identifier for the user (UUID format).

Request

DELETE

/fraud/v1/reporting/unflag

curl -X DELETE https://localhost:4301/fraud/v1/reporting/unflag \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "43c62e7f-6158-4c6b-87a3-c3fc27a14d6c"
  }'

Response True (1/3)

{
  "success": true,
  "message": "User has been unflagged.",
  "data": {
    "userId": "43c62e7f-6158-4c6b-87a3-c3fc27a14d6c"
  }
}

Risk Assessment & Fraud Reporting

Check Risk Score

The check-risk-score endpoint retrieves a user’s fraud risk score by userId. It queries the risk engine, returning the score, flagged status, and check timestamp, or a default score of 0 if no data exists.

Required attributes

Name
userId
Type
string
Description
Unique identifier for the user (UUID format).

Request

POST

/fraud/v1/risk/check?userId

curl -X GET https://localhost:4301/fraud/v1/risk/check?userId \
  -H "Authorization: Bearer YOUR_API_KEY"

Response True (1/3)

{
  "success": true,
  "message": "No risk data found, using default score.",
  "data": {
    "userId": "43c62e7f-6158-4c6b-87a3-c3fc27a14d6c",
    "riskScore": 0,
    "flagged": false
  }
}

Report Fraud

The report-fraud endpoint flags a user by userId with fraud reasons. It validates ownership, updates the risk engine with the reasons, recalculates the risk score, and returns confirmation with submitted details.

Required attributes

Name
userId
Type
string
Description
Unique identifier for the user (UUID format).
Name
reasons
Type
array
Description
Reasons for the reports.

Request

POST

/fraud/v1/risk/report-fraud

curl -X POST https://localhost:4301/fraud/v1/risk/report-fraud \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "reasons": [
      "suspicious_activity",
      "location_mismatch"
    ]
  }'

Response True (1/2)

{
  "success": true,
  "message": "Fraud report submitted successfully.",
  "data": {
    "userId": "43c62e7f-6158-4c6b-87a3-c3fc27a14d6c",
    "reasons": [
        "suspicious_activity",
        "location_mismatch"
    ]
  }
}