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:
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. (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.
! HINT FROM THE FUTURE ! While the current API (explained in this page) is active and valid, we are developing a new API, called version 2, with more features. You will be able to modify your code to use the NEW API. The modifications will be small, you will be able to upgrade your integration code with a few changes.

The OLD API will still be usable, so your code will still function after we introduce the new version. However it won't be able to use some new features. You can upgrade any time. You will receive an announcement email when the new API arrives.

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


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.


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


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


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.
! HINT FROM THE FUTURE ! The next version of our API will include _version=2 as an additional parameter. In the future, old integrations that do not use _version API variable will default to version 1, which is the current implementation.

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.
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.
paypalemailPayment 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
	Secondary Email:
	Registration IP:
	Cell Phone: +1 000 111 22 33
	Landline: +1 555 123 45 67
	Credit Card Number: 1234 5678 9012 3456

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:

  • 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 "" are valid, as well as subdomains.
  • Plain hosting account 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
  • Whitespaces before and after the variables must be trimmed.

Limitations on the Data Variables - BLACKLIST

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

  • Some common dummy values, such as "John Smith", "John Doe", and "".
  • 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"
  • *** Full blacklist available as hashvalue:data format here ***

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		
	FUNCTION fraudrecord_hash ( value )
			value = "fraudrecord-" + value
			value = SHA-1( value )
		RETURN value
	hash = fraudrecord_hash ( prepare_value ( value ) )

Sample PHP Code:

function fraudrecord_hash($value) {
$i 0$i 32000$i++)
$value sha1("fraudrecord-".$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 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 are very good ways to uniquely identify a client between different companies. It is advisable to include them in applicable reports.

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.
Required variables _action
name, email, ip, etc...

For reporting, extra variables:

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
data variables
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.
ACTION: delete

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.

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:



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.

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.
REPORTCODE may expire after some time. You should provide a means to make a new query to receive a new report code on request. Currently, old reports are stored for several months.
! HINT FROM THE FUTURE ! When you submit a new report for a fraud client, the API returns a report code. When you make a query, the API generates a report, and another, unrelated report code is returned. These are different codes, but both called "report code". We will fix this naming issue in the future version of our API, by giving them appropriately different names.

Unsuccessful queries will result in an error, similar to the errors of a report action:
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