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.

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
name	Client name.
company	Company name which the client inputs.
email	Client's email address.
address	Client's postal address.
phone	Client's phone number.
ip	Client's registration IP address.
hostname	Hostname for server clients.
accountuser	Hosting account username.
accountpass	Hosting account password.
domain	Domain name of the hosting client.
paypalemail	Payment processor identification, e.g. paypal email address.
ccname	Name on credit card
ccnumber	Credit 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
	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
	phone1 = 3f09086d8d4e4019eb534ce28e6b64c8ef563ec9
	phone2 = d542e4bad3dbb13bcf0e31f484394997cd969b18
	ccnumber = de4344cdbe3ff89efffc767ca92d112265550023
	domain = ff07748b4d4b8f08f21499e078ef792fded46641

Calculation of Data Variables

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

Limitations on the Data Variables - BLACKLIST

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

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.

If you are developing a billing system integration, make sure that you are NOT using these values as test items. They will be silently ignored as if they are not sent at all. You can use your own dummy values, and at the end of testing, delete your reports.

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

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 ID 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 IDs.

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 ID code of the accepted report. Double quotes are not included. The ID 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.

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 required to provide the "full report" link even if the VALUE is 0. The detailed report page includes further details other than the report value, even if the value appears 0 in the API result.

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