Notice: SSI.php was unable to load a session! This may cause problems with logout and other functions - please make sure SSI.php is included before *anything* else in all your scripts! in /home/frecord/public_html/forums/SSI.php on line 170
Developer Resources - FraudRecord - Report and Query Unpleasant Clients, Frauds, Fraudsters, Scammers, Spammers, Abusers - Fraud Prevention - Fraud Detection - Fraud Record.
Developer Resources
This page displays technical information about the integration API of FraudRecord for any external billing/support system.


Understanding the API

FraudRecord API is an HTTP protocol API that can be accessed via any software with internet access. A simple example of access would be:

https://www.fraudrecord.com/api/?_action=query&_api=a51ff508c331b7e9&name=7b30981dd586b87ea42ea864c03abd2ce9086520
This example utilizes three URL variables, namely _action, _api, and name. This example query would be used to check if "name" is in our database, and it would return an appropriate response. Variables can be submitted as GET requests, as well as POST request using cURL or any other form of post data format.

You can download a test kit that utilizes our system in a simple manner. Samples.zip (3 KB)
You will need to create a reporter profile before using it.
You can safely make test reports, our website panel allows you to remove your reports later. You can also delete your test profile, which will delete all its reports at once.

Overall Idea

It's usually a good idea to cover the entire article with a preliminary example, so that you know what to expect from the API.


Sample cURL example (Submitting New Report):

cURL Address https://www.fraudrecord.com/api/
POST DATA: "_action" = "report"
"_api" = "a51ff508c331b7e9"
"_type" = "chargeback"
"_text" = "This client made a chargeback after 3 months of server use."
"_value" = 6
"name" = "7b30981dd586b87ea42ea864c03abd2ce9086520"
"email" = "ba65e95764ee08a38bff8d281ad0dcbbe86c9b64"
"ip" = "ee302279497c4c79a2e64c532d01ba4bb3b57a0c"
API Response: OK:ea864c03abd2ce90

Sample cURL example (Querying Our Database):

cURL Address https://www.fraudrecord.com/api/
POST DATA: "_action" = "query"
"_api" = "a51ff508c331b7e9"
"name" = "7b30981dd586b87ea42ea864c03abd2ce9086520"
"email" = "ba65e95764ee08a38bff8d281ad0dcbbe86c9b64"
"ip" = "ee302279497c4c79a2e64c532d01ba4bb3b57a0c"
API Response: <report>14-3-6.7-abd2ce90ea864c03</report>

The API response consists of the report value (14), report count (3), report reliability (6.7), and access code for a detailed report that can be seen at
https://www.fraudrecord.com/api/?showreport=abd2ce90ea864c03
Any integration must allow the user to have a direct anchor link to the page above, or contain the result in a frame display.
These response values are just examples.


What is Expected From Integration?

There are 4 functions of a possible billing or client management system integration.

Query New Client Allows the user to ask our system about the past of a new client, so that if the client is in our database, the user may decide to cancel the new order.
Query Existing Client Allows the user to query about an existing client, to learn about their misbehavior among other companies.
Report New Client Allows the user to report a newly registered client to our system, for fraud, scam, or anything else.
Report Existing Client Allows the user to report an existing client to our system for any misbehavior, like fraud, illegal activity, chargeback, massive amount of tickets, public threads, etc.
We expect the first and the last functions of this list to be the most used functions.

Definitions

This article will use some definitions and abbreviations.
  • FRC: FraudRecord API system.
  • USER: Any end-user who will be utilizing the FRC system to report clients or query for information. Typically hosting companies.
  • CLIENT: The client or customer whose information will be submitted to our system for misbehavior or querying, by the USER.
  • EXT: The external billing system that the USER utilizes. API integration will be done for the communication between EXT and FRC
  • YOU: You the developer, who is creating a module for a billing system for integration.

Chapter 1. API Variables

Here you can find the variables that our API accepts.
Variable Format Usage Example Value
_api alphanumeric string, [a-z, 0-9] 16 chars. Defines the unique api code of EXT. For authentication. a51ff508c331b7e9
_action short string Defines the command the EXT is aiming to run. "report", "query" or "delete"
_type short string, max 32 chars Report type, submitted by USER. Short description of what the offense of the CLIENT is. "staff abuse", "support abuse", "too many support tickets", "chargeback", "stolen card", etc...
_text long string Information about a reported CLIENT. Can be anything submitted by the USER. Any block of text explaining the case. Any length up to 65 kilobytes. Example: "This client made a chargeback after 3 months of server use."
_value integer between 1 and 10 The level of the offensive behavior. 1 means very Low Importance, 10 means Highly Dangerous. 6
_code alphanumeric string, [a-z, 0-9] 16 chars. Code of the report that is to be deleted. b22db4fa88f223f8
data variables 40 characters, consisting of hash characters [a-f, 0-9] Pieces of reported information. More information below. Variable names must be a short string, 16 char max, optionally ending with a number. Variable values should be salted SHA-1 hashes with 32,000 iterations.

name=e971baaa757297c7330915c88d0718a7700a7b04
email=5d61f8f8436aacab22db4fa88f223f859a35348b
email2=beaf13c6dcbf1a279374152af638cab9077b8832
email3=f776602322f92fa59d68a5cf2a0e9ff1245466f6
ip=81602d4ab9227f48a09207166a1ffae17a7954ea
address=c39db2711947ab7e97ba595e263c34e1e7dd3940
paypal=05a6a0c37f37324759700a86e7cf97a4c6e9c9a
etc...

Note that the variable names except the data variables start with an underscore character.

_api

This variable is used for authentication of EXT to FRC. The API code can be generated by the USER on the FraudRecord Panel, under "Reporter Profiles" menu.

_action

Action can be "report" or "query". "report" is for submitting a new client to our system, and "query" is for asking information about a client.

_type

Type is the short definition of the offensive behavior. Billing system module developers can offer pre-defined options such as 'staff abuse','support abuse','too many support tickets','chargeback','stolen card','fraud','early cancellation','non-payment','illegal hosting','criminal intent','excessive server load','public threats','other'. Custom values are also accepted.
Lowercase characters are preferred. Any uppercase character will be converted to lowercase in our database.

_text

Text is the block of information submitted by the USER. Any information posted will be publicly visible by any other USER that queries the same client. This is the only field where lowercase, uppercase, or any other character can be mixed. Any end user must be discouraged to submit private client information through this field, since the contents of this field will be visible by other companies that query for the same client.

_value

An integer value between 1 and 10. This is the level of the offensive behavior. 1 means very low importance, 10 means highly dangerous. 5 can be considered as Moderate Level. Typically any value below 5 will not require the company to terminate the client account, while values above 6 should be a basis for termination of service of the CLIENT.

Data variables

Data variables are the core of the FraudRecord system. They are used to transmit CLIENT information from USER to FRC. They are salted hashes of lowercase values of the client information.

Data variable names can be anything between 1 to 16 lowercase characters, however a standardization is highly encouraged. Some samples are as follows:
Variable Name Description
nameClient name.
passwordClient password. Usually a good indicator of identity. Security implications are discussed below.
companyCompany name which the client inputs.
emailClient's email address.
addressClient's postal address.
phoneClient's phone number.
ipClient's registration IP address.
hostnameHostname for server clients.
accountuserHosting account username.
accountpassHosting account password.
domainDomain name of the hosting client.
paymentPayment processor identification, e.g. paypal email address.
ccnameName on credit card
ccnumberCredit card number.
Any other variable can also be submitted as long as the variable name consists of [a-z] characters, 16 characters max. Uppercase variables will be converted to lowercase by FRC internally. Dash (hyphen) character is also accepted. For example, "paypal-email" is a valid variable name.

You can submit multiple variables with the same name, by adding a number to the end. For example, email, email2, email3, ..., email9 will all be accepted as "email" into our system. The added number doesn't count against the 16 character limit, but it must be a single digit. The digits don't need to be in order. You can simply submit "email5" and our system will read it as "email", even if there aren't any other email fields.

Values of Data Variables

All those data variables have a single format for their values. Trimmed, lowercased, salted, and hashed, in this order. Best way to explain is to give examples.
Sample client:
	Name: John Smith
	Email: john.smith@example.com
	Secondary Email: jsmith@example.net
	Registration IP: 11.22.33.44
	Password: iLoveLinux!
	Cell Phone: +1 000 111 22 33
	Landline: +1 555 123 45 67
	Credit Card Number: 1234 5678 9012 3456
	Domain: www.example.com

Any of this information can uniquely identify this client across many companies. If John Smith committed misbehavior, for example making a chargeback after several months of service use, the hosting company will want to report this incident to FraudRecord. The billing system of the company will need to submit his information in this format:
	name = ac2c739924bf5d4d9bf5875dc70274fef0fe54cf
	email = 34efd0a968b48cbf9a43ac3e73053e4f343234e4
	email2 = 2a1ab4a6ed14713d0e26127c1920417e4b193924
	ip = f25c0306279af0bd9faf1caf0549daedb3472b7f
	password = 93491c2dff7b35528c319f304b0222fc55ebcfcb
	phone1 = 3f09086d8d4e4019eb534ce28e6b64c8ef563ec9
	phone2 = d542e4bad3dbb13bcf0e31f484394997cd969b18
	ccnumber = de4344cdbe3ff89efffc767ca92d112265550023
	domain = ff07748b4d4b8f08f21499e078ef792fded46641

Calculation of Data Variables

There must be a standardization for certain variables. Here are the rules:

  • All values must be stripped off the spaces between the characters, and at the beginning/end. "George Michael" must be sent as "georgemichael"
  • Strings like names, emails, postal addresses, domain names, must be passed through an english alphabet "lowercase" function.
  • Domain names must be stripped off the initial "www." part, or "http://" part. Plain names like "example.com" are valid, as well as subdomains.
  • Plain passwords must NOT be made lowercase, since their uppercase characters are their defining values. Already hashed passwords should be made lowercase.
  • IP Addresses must be in regular format, like 123.45.67.89
  • Whitespaces before and after the variables must be trimmed.

Limitations on the Data Variables

There are several pre-defined pre-hashed values that are rejected by our system.

  • Some common dummy values, such as "John Smith", "John Doe", and "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 phone numbers, such as "555-555-5555"

These pre-defined values have been hashed for blacklisting in our system. Any dummy value that we may have forgotten to blacklist will be allowed. Since we can't see the original data source of the hashed value, we cannot define rules for limitations that cover every possibility. We did our best to manually add those blacklists. If you encounter a dummy value that should have been rejected by our system, please inform us and we will add them to the blacklist.

The Hashing Function

The hashing function used to create the hashes is a salted SHA-1 function with 32,000 iterations. The salt is a prefix, namely "fraudrecord-", appended to the beginning of the standardized variable before each hashing.

Hash function must produce hexadecimal values like "ac2c739924bf5d4d9bf5875dc70274fef0fe54cf" represented as strings. Binary representations are discouraged.
	Pseudo Code:
	
	FUNCTION prepare_value ( value )
		TRIM the WHITESPACE characters from VALUE,
			including NEWLINE and TAB characters		
		REMOVE SPACE characters from value 				
		LOWERCASE value using english alphabet characters		
		RETURN value		
	END FUNCTION
	
	FUNCTION fraudrecord_hash ( value )
		FOR 32,000 TIMES LOOP
			value = "fraudrecord-" + value
			value = SHA-1( value )
		END LOOP
		RETURN value
	END FUNCTION
	
	hash = fraudrecord_hash ( prepare_value ( value ) )
	

Sample PHP Code:


<?php
function fraudrecord_hash($value) {
    for(
$i 0$i 32000$i++)
        
$value sha1("fraudrecord-".$value);
    return 
$value;
}

    
$name "John Smith \n";
    
$hash['name'] = fraudrecord_hash(strtolower(str_replace(" ","",trim($name))));
    
// processed as "johnsmith"
    // result is ac2c739924bf5d4d9bf5875dc70274fef0fe54cf
    
    
$password "iLoveLinux!";
    
$hash['password'] = fraudrecord_hash($password);
    
// processed unchanged, as "iLoveLinux!"
    // result is 93491c2dff7b35528c319f304b0222fc55ebcfcb
    
    
$phone "+1 000 111 22 33 ";
    
$hash['phone'] = fraudrecord_hash(str_replace(" ","",trim($phone)));
    
// processed as "+10001112233"
    // result is 3f09086d8d4e4019eb534ce28e6b64c8ef563ec9
?>

Once the EXT billing system generates these values, they can be submitted through GET or POST requests, along with the other variables like _api.


Security Considerations

Submitting a hashed version of the user password or credit card number is quite safe for the following reasons:

A. Salted Sha-1 hashes are the industry standard for one-way encryption of sensitive values. Salting prevents pre-made rainbow table attacks.
B. 32,000 iterations ensure that a brute-force attack is very expensive compared to a single iteration sha-1 function.
C. All values are transmitted through an SSL protected gateway to our database.
D. There is no API or web panel access to the stored values in our database, unless the USER submits the same value for cross-checking.

Credit card numbers or unique account passwords are very good ways to uniquely identify a client between different companies. It is advisable to include these values in applicable reports.

In most cases, password values will be encrypted on the USER side as well, so there may not be a way to use their plain values for querying purposes. In this case, we advise you that you feed the stored values of passwords (whether it is already encrypted or not) into the fraudrecord_hash() function for reporting and querying purposes. Every bit of information helps when it is about dealing with scammers, even if it is not quite possible to standardize it across different billing software.

Chapter 2. Submitting a Report or Query, or Deleting a Report

Once you have all the data variables hashed properly, you are ready to submit your report/query to the system. You can use cURL on PHP to submit the information, or any other method of sending information on the internet.
API URL https://www.fraudrecord.com/api/?
Required variables _action
_api
name, email, ip, etc...

For reporting, extra variables:
_text
_type
_value


Reporting vs. Querying

When reporting, descriptive fields like text, type and value are required. These are not required when querying a client.
Reporting Querying
ACTION: report query
REQUIRED VARIABLES: _api
_action
data variables
_text
_type
_value
_api
_action
data variables

While querying, the data variable names you send don't need to match the names in our database. If you query a variable called "email" which matches "emailaddress", our system will still call it a match, and return the appropriate response. In fact, you can make query with any name as long as it satisfies the character restrictions, including the words "any" or "other". However, providing correct/consistent matches are recommended since our detailed report page displays matched data variables in detail.

Sample Report and Query actions have been provided at the "Overall Idea" section of this document.

Deleting a Report

If you want to delete a report, you will need to submit the report code that was returned from a previous "report" action.
Deleting
ACTION: delete
REQUIRED VARIABLES: _api
_action
_code

The _code variable is an alphanumeric string, consisting of [a-z] and [0-9], 16 characters. Its value is retrieved from a previous report response. The following section explains retrieving report response codes.

Chapter 3. API Response

When you submit a report or query, the API will provide a response.

Response to "report" action

On a successful submission of a report, the API will simply respond with the text "OK:ea864c03abd2ce90", where the character sequence after "OK:" is the response code of the accepted report. Double quotes are not included. The code can be used to manually track previous reports on the FraudRecord panel. It can also be used to delete a report.

On an unsuccessful report attempt, the API will respond with error. The responses are simple text responses, easily retrievable by cURL or similar means.

ERROR RESPONSE DESCRIPTION
NODATA The API was called without any POST or GET requests.
ERR:ACTION Incorrect or missing _action variable.
ERR:DATA No data variable was provided. Data variables like name, email, etc are required during reporting and querying.
ERR:API Incorrect or missing API code, or a deleted/disabled API code. API code must be generated on the FraudRecord Panel, "My Reporter Profiles" section.
ERR:NOT-APPROVED An API code for an unapproved reporter profile was used during a "report" action. Reporter profiles can only be used for "query" action until they are approved by FraudRecord.
ERR:EMPTY-VALUE _value variable was left empty, or sent incorrectly, during a "report" action.
ERR:EMPTY-TEXT _text variable was left empty during a "report" action.
ERR:EMPTY-TYPE _type variable was left empty during a "report" action.
Any POST variable that doesn't start with an underscore character is considered a data variable, if the variable name consist of a-z characters, optionally ending with a digit. These data variables are then tested for their values, which must be a 40 character hash string produced with the custom SHA-1 function discussed above. If the value does not satisfy the hash string conditions, that specific POST variable is quietly ignored. Errors on data variables are produced only if there is no matching data variable in the request. Even if only one data variable is submitted successfully, the API will not produce errors on incorrect variables.


Response to "query" action

Successful submission of a "query" action will result in a response that needs to be parsed and displayed to the USER properly. This is the structure of the response:


<report>VALUE-COUNT-RELIABILITY-REPORTCODE</report>

Examples:
<report>14-3-6.7-cf2b27b5556c2ddc</report>
<report>9-2-1.0-09a67a3854efb64a</report>
<report>24-11-9.9-b45db7b9dfbd6f54</report>
<report>6-1-10.0-465eb38516346009</report>
<report>0-0-0.0-9b7a2acd078751c9</report>

The response values will be encapsulated inside a <report></report> tag. It is important to make sure that the integration system reads only the data between these tags, to ensure future compatibility in case the response system is modified in the future.

VALUE is an integer between 0 and any positive value. 0 means no report, while any other number means there are reports resulting in the returned value. Higher values mean the queried client information was reported by many other companies, possibly with high complaint values. It is the total of the _value variables submitted by other companies in the past.

COUNT is the total number of reports on the queried clients. Higher counts mean many other companies complained about the same client.

RELIABILITY is a measure of how valuable the results are. All new companies that start using FRC will start with a reliability of 1, and will increase in time up to 10. Combined reliability values are calculated by FRC and provided in a decimal number starting from 1.0 to 10.0, including any value in between, and 0.0 if there are no reports. There is always one digit after the decimal point.

REPORTCODE is the key code to see further information on the report. When the returned key code is used in the following URL, the resulting page will list as many details as it can.

https://www.fraudrecord.com/api/?showreport=REPORTCODE

The REPORTCODE and resulting report link should be provided to the client as a simple anchor text, reading something like "View Full Report »", which will open in a new window so that the USER can read the details of the reports. Even if there are no reports for a certain query, a report code is returned. It is advisable to provide the "full report" link even if the VALUE is 0.
REPORTCODE expires after 7 days. When this time period is over, you should not link to the detailed report page, but provide a means to make a new query to receive a new report code.


Unsuccessful queries will result in an error, similar to the errors of a report action:
ERROR RESPONSE DESCRIPTION
NODATA The API was called without any POST or GET requests.
ERR:ACTION Incorrect or missing _action variable.
ERR:DATA No data variable was provided. Data variables like name, email, etc are required during reporting and querying.
ERR:API Incorrect or missing API code, or a deleted/disabled API code. API code must be generated on the FraudRecord Panel, "My Reporter Profiles" section.


Further Help and Details

Our developer forums are available for you to ask any question you may have.
Billing System Integration & Development Forums