API Documentation

Introduction to API v2

FraudRecord API v2 provides a robust, JSON-based interface for reporting and querying data. All API v2 requests use POST method and receive JSON responses.

To test the API, you need to:

API Basics

Endpoint

All API requests should be sent as a POST request to:

https://www.fraudrecord.com/api/

Authentication

All API requests require your API key for authentication:

{
    "apiKey": "your16charAPIkey",
    "action": "action_name",
    ...
}

API key can be obtained from the reporter profile page in the dashboard. It's a 16-character hexadecimal string.

Request Format

API v2 requires all requests to:

• Use POST method
• Include properly formatted JSON data
• Set Content-Type header to application/json

GET requests will be considered an API version 1 request and will not work as described in the rest of this document.

Response Format

All API responses are in JSON format with a standardized structure:

Success Response

{
    "status": "success",
    "message": "Operation successful message",
    // Additional data specific to the request
}

Error Response

{
    "status": "error",
    "error": {
        "code": "ERROR_CODE",
        "message": "Detailed error message"
    }
}

Data Fields and Data Conversion

Data fields are one-way encrypted hashes which are converted from the raw information to a 40-character hexadecimal string.

For example, the email address john@compuserve.net will become the hash: ddb48c18cf40686416e811256b47c6f96485d70a

Our API only accepts 40-character hexadecimal hashes as data values.

Data field conversion method has its own API document. Please review it.

Data Conversion Algorithm

Example

This is an example data field composed of key-value pairs:

"data": { "name": "7ad8fd634cb7bdf8a9f1509ba1689bb6964228ab", "email": "97da1e5ff89ed630f8f116e8e9d45f754ee77dd8", "email2": "ddb48c18cf40686416e811256b47c6f96485d70a", "ip": "3ad371f071ded00ea98adbc6576ec61971582e4c" }

Data Key Guidelines

When submitting key-data pairs in the data field, consider the following:

• Keys are automatically converted to lowercase and spaces are replaced with dashes.
• Non-alphanumeric characters in keys are removed.
• Keys are limited to 17 characters.
• Some acceptable keys include: "name", "fullname", "email", "email2", "ip", "ip-address", "address", "phone", etc.
• The keys are not standardized. You may submit any key you want, the system will match them by comparing the hashes only.
• Hashes are generated via our data conversion algorithm.

API Endpoints

1. Submit Report

Submit a new fraud report to the system.

Required Parameters:

• apiKey - Your API key
• action - Must be "submit_report"
• description - Detailed description of the fraud incident
• type - Type of fraud (e.g., "chargeback", "identity_theft")
• severity - Severity rating from 1 to 10
• data - An associative array of key-value pairs that identify the reported entity

Optional Parameters:

• anonymize - Set to "1" to anonymize the report if your account has a subscription plan that allows it.
• anonymize - Set to "0" to submit the report without anonymization if your account is set to anonymize all reports by default.
• This parameter is silently ignored if the reporter profile account does not have a subscription plan with anonymization allowed.
• If this parameter is not provided, anonymization will default to the setting in the reporter profile.

Example Request:

{
    "apiKey":      "a51ff508c331b7e9",
    "action":      "submit_report",
    "description": "This client made a chargeback after 3 months of service",
    "type":        "chargeback",
    "severity":    7,
    "data": {
        "name":    "7ad8fd634cb7bdf8a9f1509ba1689bb6964228ab",
        "email":   "97da1e5ff89ed630f8f116e8e9d45f754ee77dd8",
        "email2":  "ddb48c18cf40686416e811256b47c6f96485d70a",
        "ip":      "3ad371f071ded00ea98adbc6576ec61971582e4c"
    },
    "anonymize": "1"
}

Example Response:

{
    "status":   "success",
    "message":  "Report created successfully.",
    "reportId": "ea864c03abd2ce90"
}

2. Query

Search the database for fraud reports matching your criteria.

Required Parameters:

• apiKey - Your API key
• action - Must be "query"
• data - An associative array of key-value pairs to search for

Example Request:

{
    "apiKey": "a51ff508c331b7e9",
    "action": "query",
    "data": {
        "name": "7ad8fd634cb7bdf8a9f1509ba1689bb6964228ab",
        "email": "97da1e5ff89ed630f8f116e8e9d45f754ee77dd8",
    }
}

Example Response:

{
    "status": "success",
    "query": {
        "value": "17",
        "count": 3,
        "confidence": "2.8",
        "historyScore": 5,
        "queryId": "fa452c76e310db8c"
    }
}

• The user MUST be presented with a link to the full query result for every query, even for those that return a zero value.
• The queryId should be used to generate the URL: https://www.fraudrecord.com/query-result/<16charQueryId>
• A query result value of zero may still have further information on the results page, so it's important to direct the user to the full result URL.

3. Delete Report

Delete a report you previously submitted.

Required Parameters:

• apiKey - Your API key
• action - Must be "delete_report"
• reportId - The ID of the report to delete (16 hex characters)

Example Request:

{
    "apiKey":   "a51ff508c331b7e9",
    "action":   "delete_report",
    "reportId": "ea864c03abd2ce90"
}

Example Response:

{
    "status":  "success",
    "message": "Report deleted successfully."
}

---

4. Get Fraud Watch Limits

Retrieve information about your fraud watch limits.

Required Parameters:

• apiKey - Your API key
• action - Must be "get_fraud_watch_limits"

Example Request:

{
    "apiKey": "a51ff508c331b7e9",
    "action": "get_fraud_watch_limits"
}

Example Response:

{
    "status": "success",
    "fraudWatchLimits": {
        "limit": 900,
        "maxDuration": 90,
        "activeCount": 48
    }
}

We recommend getting the limits before every attempt to add a new fraud watch.

A limit of 0 (zero) indicates the reporter profile does not have fraud watch feature enabled. In this case, adding a fraud watch will not be accepted.

When your account reaches the total number of fraud watches allowed, activeCount will reach the limit value, new fraud watches will continue to be accepted. The system will automatically expire the ones with the closest expiry dates to make room for new ones.

However, it is important to keep track of the active fraud watch counts using the get_fraud_watch_limits command to make sure the user is not inadvertently overwriting active fraud watches.

You may need to alert the user of reaching the limits.

5. Add Fraud Watch

Add a new fraud watch to monitor existing clients.

Required Parameters:

• apiKey - Your API key
• action - Must be "add_fraud_watch"
• identifier - Unique identifier for the watch
• data - An associative array of key-value pairs to monitor

Optional Parameters:

• description - Description of the fraud watch
• duration - Duration in days (defaults to your account's maximum if not specified)

Example Request:

{
    "apiKey":      "a51ff508c331b7e9",
    "action":      "add_fraud_watch",
    "identifier":  "customer id 123",
    "description": "Monitoring a suspicious customer",
    "duration":    45,
    "data": {
        "name":  "7ad8fd634cb7bdf8a9f1509ba1689bb6964228ab",
        "email": "97da1e5ff89ed630f8f116e8e9d45f754ee77dd8",
        "ip":    "3ad371f071ded00ea98adbc6576ec61971582e4c"
    }
}

Example Response:

{
    "status":  "success",
    "message": "Fraud watch added successfully.",
    "watchId": "fa452c76e310db8c",
    "duration": 45
}

6. Delete Fraud Watch

Delete a fraud watch you previously added.

Required Parameters:

• apiKey - Your API key
• action - Must be "delete_fraud_watch"
• watchId - The ID of the watch to delete (16 hex characters)

Example Request:

{
    "apiKey":  "a51ff508c331b7e9",
    "action":  "delete_fraud_watch",
    "watchId": "fa452c76e310db8c"
}

Example Response:

{
    "status":  "success",
    "message": "Fraud watch deleted successfully."
}

You don't need to delete fraud watches as they automatically expire after their duration ends.

New fraud watches will silently overwrite the old ones with the closest expiry date.

You can determine whether a new fraud watch will overwrite an old one by checking the limits and the active count before or after submitting a new watch.

Error Codes and Handling

The API returns specific error codes to help you diagnose issues. The response will be in this format:

{
    "status": "error",
    "error": {
        "code": "ERROR_CODE",
        "message": "Detailed error message"
    }
}

Here are the ERROR_CODE possibilities:

Error Code	Description (Message)
NODATA	Empty request. POST method is required for v2 API.
API_KEY_MISSING	The API key is missing from the request.
ACTION_MISSING	The action is missing from the request.
API_KEY_INVALID	The API key is invalid. It must be 16 alphanumeric characters.
API_KEY_NOT_FOUND	The API key was not found or has been deleted.
REPORTER_PROFILE_DISABLED	The reporter profile is disabled.
Errors common to submit_report, query, add_fraud_watch methods:
INVALID_DATA	The data parameter must be an associative array with key-value pairs.
EMPTY_DATA	Please provide key-value pairs as an associative array inside the data field.
RATELIMIT_EXCEEDED_HOURLY	You have exceeded the hourly rate limit for reports, queries, or fraud watches.
RATELIMIT_EXCEEDED_DAILY	You have exceeded the daily rate limit for reports, queries, or fraud watches.
	Note: The message field will clarify which limit was exceeded.
Errors for submit_report method:
EMPTY_DESCRIPTION	Please provide a description field for the report.
EMPTY_TYPE	Please provide a type field for the report.
EMPTY_SEVERITY	Please provide a severity field for the report between 1 and 10.
Errors for delete_report method:
EMPTY_REPORT_ID	Please provide a reportId to identify the report you want to delete.
INVALID_REPORT_ID	The reportId must be 16 hexadecimal characters.
NONEXISTENT_REPORT_ID	The report with this reportId does not exist.
ALREADY_DELETED	The report with this reportId has already been deleted.
Errors for add_fraud_watch method:
EMPTY_IDENTIFIER	Please provide an identifier field for the fraud watch.
FRAUD_WATCH_NOT_ENABLED	This reporter profile does not have fraud watch feature enabled.
	Note: You can check the limits using get_fraud_watch_limits method.
INVALID_DURATION	Duration must be an integer or null.
Errors for delete_fraud_watch method:
EMPTY_WATCH_ID	Please provide a watchId to identify the fraud watch you want to delete.
INVALID_WATCH_ID	The watchId must be 16 hexadecimal characters.
NONEXISTENT_WATCH_ID	The fraud watch with this watchId does not exist.
Errors for unknown or invalid methods:
INVALID_ACTION	The action provided is not valid.

Error Handling Best Practices

• You can show the error message to the user when there is an error response.
• You don't need implement handling for every error as long as you display the message.

Rate Limits

To prevent abuse, the API implements rate limiting:

• Hourly and daily limits apply to report submissions, queries, and fraud watches.
• The exact limits may depend on your account standing.
• These limits are technical limits to manage server load and functioning.
• All plans, including the free and paid ones are subjected to similar technical limits.
• When a rate limit is exceeded, the API will return a RATELIMIT_EXCEEDED error.

Implementation Example

Here's a PHP example of how to use the API:

// PHP Example
$apiUrl = 'https://www.fraudrecord.com/api/';
$apiKey = 'your16charAPIkey';

// Function to convert data for FraudRecord API
function fraudrecord_conversion($value) {

    // raw values are trimmed, spaces removed, and lowercased
    $value = trim($value);
    $value = str_replace(" ", "", $value);
    $value = strtolower($value);

    for($i = 0; $i < 32000; $i++)
        $value = sha1("fraudrecord-".$value);

    return $value; // 40-character hexadecimal string
}

$data = [
    'apiKey' => $apiKey,
    'action' => 'query',
    'data' => [
        'email' => fraudrecord_conversion('customer@example.com'),
        'name' => fraudrecord_conversion('John Doe'),
        'ip' => fraudrecord_conversion('192.168.1.1')
    ]
];

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

if ($result['status'] === 'success') {
    // Process successful response
    $reportValue = $result['report']['value'];
    $reportCount = $result['report']['count'];
    $confidence = $result['report']['confidence'];
    $queryHistoryScore = $result['report']['historyScore'];
    $queryId = $result['report']['queryId'];

    echo "Query Result: https://www.fraudrecord.com/query-result/{$queryId}";

    // Example URL for query result page:
    // https://www.fraudrecord.com/query-result/e5a0e1d6498d3612

} else {
    // Handle error
    $errorCode = $result['error']['code'];
    $errorMessage = $result['error']['message'];

    echo "Error: $errorCode - $errorMessage";
}

Implementation Best Practices

For Submitting Reports

• Display the returned reportId to the user.
• They can use it to track the report on our web interface to edit/delete/respond.

For Querying

• The user MUST be presented with a link to the full query result for every query, even for those that return a zero value.
• https://www.fraudrecord.com/query-result/<16charQueryId>
• A query result value of zero may still have further information on the results page.

For Fraud Watches

• Always check the fraud watch limits before adding a new watch.
• Alert to user if their watch limit is reached, so that they know the new watch will overwrite the one with the closest expiry date.
• Display the returned watchId to the user.
• They can use it to track the fraud watch on our web interface to edit/delete.