Data Conversion Algorithm
All data in FraudRecord is stored in a hashed format to protect the privacy of our users. Our API only accepts data in a specific format, and it is important to understand how to convert your data into the required format before sending it to our API.
Improperly converted data will not match any existing records in the database, and will result in a "No matches found" response. To ensure your data is properly converted, please follow the guidelines below.
Example
This is an example data field composed of key-value pairs, required by the report, query, or fraud watch methods:
"data": {
"name": "7ad8fd634cb7bdf8a9f1509ba1689bb6964228ab",
"email": "97da1e5ff89ed630f8f116e8e9d45f754ee77dd8",
"email2": "ddb48c18cf40686416e811256b47c6f96485d70a",
"ip": "3ad371f071ded00ea98adbc6576ec61971582e4c"
}
Data Conversion Steps
Data Keys:
Data keys are converted to appropriate format when received by the API. This is the code we use to convert the data keys:
// trim outer spaces
$key = trim($key);
// replace spaces with dashes
$key = str_replace(' ', '-', $key);
// replace underscores with dashes
$key = str_replace('_', '-', $key);
// remove any non-hexadecimal characters from the key
$key = preg_replace('/[^a-zA-Z0-9\-]/', '', $key);
// convert to lowercase
$key = strtolower($key);
// limit the key to 17 characters
$key = substr($key, 0, 17);
When you submit key-value pairs to the API, the keys will be automatically converted to the format described above. You do not need to manually convert the keys before sending them, but make sure they survive this process.
Data values are converted to a hashed format using the following algorithm:
// PHP Example
// 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
}
Here is a pseudocode for any language:
FUNCTION fraudrecord_conversion ( value )
value = LOWERCASE( value )
value = REPLACE( value, ' ' => '' )
value = TRIM( value )
FOR 32,000 TIMES LOOP:
value = "fraudrecord-" + value
value = SHA-1( value )
END LOOP
RETURN value
END FUNCTION
Hash Examples
Here are some examples of client data before hashing:
Name: John Smith
Email: john.smith@example.com
Secondary Email: jsmith@example.net
Registration IP: 11.22.33.44
Cell Phone: +1 000 111 22 33
Landline: +1 555 123 45 67
Domain: http://www.example.com
Address: 123 Example Street, Example City, EX 12345
Credit Card: 4111 1111 1111 1234 06/29
Any API implementation request must convert the data values to a lowercase raw data with spaces removed before hashing, to standardize processing:
name = johnsmith
email = john.smith@example.com
email2 = jsmith@example.net
ip = 11.22.33.44
phone1 = +10001112233
phone2 = +15551234567
domain = example.com
address = 123examplestreet,examplecity,ex12345
ccnumber = 4111111111111234
ccnumber2 = 41111111111112340629
Notice that we have chosen to remove http:// and www. from the domain name. You are encouraged to strip any unnecessary parts of the data values to ensure consistency and to avoid unnecessary data variations.
- Names must be the full name of the person, lowercased and spaces removed.
- IP addresses must be in the dot format.
- Phone numbers must include country codes.
- Domains must be lowercased, and http:// or www. prefixes should be removed.
- Addresses must be lowercased, and spaces removed.
- Credit card numbers can be submitted in multiple formats within the same request. Any format has a chance to match a record.
- In fact, any value can have multiple variations. A single report can accept up to 30 key-data pairs.
- The keys can be anything of your choosing, but they must stay descriptive.
Before sending this information to our API, any API integration should run the one-way hash algorithm on the values, so we receive these, and only these values in a report:
name = ac2c739924bf5d4d9bf5875dc70274fef0fe54cf
email = 34efd0a968b48cbf9a43ac3e73053e4f343234e4
email2 = 2a1ab4a6ed14713d0e26127c1920417e4b193924
ip = f25c0306279af0bd9faf1caf0549daedb3472b7f
phone1 = 3f09086d8d4e4019eb534ce28e6b64c8ef563ec9
phone2 = d542e4bad3dbb13bcf0e31f484394997cd969b18
domain = ff07748b4d4b8f08f21499e078ef792fded46641
address = 4b7ae31360c7a1eaa7e9aec748a7f1876b598808
ccnumber = b7a3766fad68cab0b70169edef890b74fbf87f6c
ccnumber2 = 0f1c784499f2a08615528ab8408d73d879b7ffaa
You can use these values displayed above to test your data conversion function. If you hash the values using the algorithm described above, you should get the same results.
Data Value Blacklist
We have a comprehensive blacklist of data values that are not accepted (silently ignored) by our API. This is to prevent the accidental or intentional submission of dummy data, which would not be useful for our database and could lead to false positives in queries.
- Some common dummy values, such as "192.168.0.1" or "127.0.0.1".
- Single characters like "a", and most repeating characters, such as "1111111111", "aaa", "----".
- Some sequential numbers that start with 0, 1 or 9. Such as "012345678", "1234", "98765".
- Some dummy phone numbers, such as "555-555-5555"
Full blacklist is available here. We have pre-hashed the values in the blacklist, so we can check them against the data hashes in the API.
If you are developing an API integration, you do not need to worry about this list. If you try to submit any of these values, they will be silently ignored by the API, and will not be stored in the database. If they are the only data values you are submitting, the API will return an error indicating that no data was submitted.
The rest of the API implementation can be found here.