Calculate Risk

Learn and practice how to calculate risk scores using Clearbit's risk API.

We'll cover the following

It is essential to calculate risk to discover any potential issues with signups beforehand. The data lookup is insufficient to check whether the incoming signups are fake or valid. Additionally, in the case of payments, we need to check whether they have a high chargeback risk or not. Therefore, Clearbit launched its risk score calculator. It checks the following:

  • If a certain email address is forged, disposable, undeliverable, or looks fake.

  • If an IP address is blacklisted or using a proxy.

The risk calculation method takes the above measures into account and gives us an overall risk score. This helps to maintain low risk. It's also recommended to use additional steps during the signup, like captcha or confirmation via mobile phone or email.

The risk API

We can use Clearbit's risk API endpoint to calculate risk scores for our new signups and filter the legitimate ones for our company. This endpoint takes two required parameters, the email and IP address of the entity (company or person). It then returns the risk score and some additional attributes that explain why the risk is high or low. The output is returned in a single JSON response.

The base URL for this endpoint is as follows:

https://risk.clearbit.com/v1/calculate

The risk API endpoint works with the help of a JavaScript library. Without that script, we might get incorrect scores. We'll have to make sure to add this JavaScript before we make a request to our REST API. We can add this piece of script in the HTML file where we have our checkout or signup page. The required JavaScript code snippet is as follows:

<script>
  !function(){
    var script = document.createElement('script');
    script.async = true;
    script.src = 'https://risk.clearbit.com/v1/risk.js';
    var parent = document.getElementsByTagName('script')[0];
    parent.parentNode.insertBefore(script, parent);
  }();
</script>

Request parameters

This endpoint supports the following request parameters:

Name

Type

Category

Description

email

string

required

This is the email address for which we want to calculate the risk score.

ip

string

required

This is the IP address for which we want to calculate the risk score.

country_code

string

optional but strongly recommended

This is the two-letter country code for the person.

zip_code

string

optional but strongly recommended

This is the postal/zip code for the person.

given_name

string

optional but strongly recommended

This is the first name of the person.

family_name

string

optional but strongly recommended

This is the last name of the person.

name

string

optional

This is the alternative to passing in a separate given_name and family_name.

Calculate the risk score

Let's calculate the risk score for a company using the code widget below. We’ve created a simple React application page. The page displays a form that takes the email and IP address of the entity against which we want the risk score.

Click "Run" to start the application. Once the server starts, either use the output tab of the below widget or click the link next to “Your app can be found at:” to view the application page in a separate tab.

DANGEROUSLY_DISABLE_HOST_CHECK=true
Demo application

Response parameters

As we know, the output of the risk endpoint is a JSON response—the table below explains some attributes of this response. Note that the dot notation, such as email.valid, indicates that the property is a nested one. In other words, email.valid is one level deep inside a hash.

Name

Type

Description

id

string

This is the internal ID associated with the company on Clearbit.

live

boolean

This is the flag that indicates whether or not the results are in live mode, that is, not using a loopback IP.

fingerprint

boolean

This is the flag that indicates whether or not the results got a fingerprint match.

email.valid

boolean

If true, this flag indicates that the provided email is syntactically valid and MX servers are present.

email.socialMatch

boolean

If true, this flag indicates that the provided email has an associated social profile and presence.

email.companyMatch

boolean

If true, this flag indicates that the email’s domain has a company associated with it.


email.nameMatch

boolean

If true, this flag indicates that the email’s social profile name matches the supplied name.

email.disposable

boolean

This is the flag that indicates whether the email is from a disposable provider, such as Mailinator, or not.

email.freeProvider

boolean

This is the flag that indicates whether the email is from a free provider, such as Gmail or not.

email.blacklisted

boolean

This is the flag that shows whether the email has been blacklisted or not.

address.geoMatch

boolean

This is the flag that indicates whether the provided country_code matches the country associated with the email or not.

ip.proxy

boolean

This is the flag that indicates whether the IP address belongs to a proxy server or not.

ip.geoMatch

boolean

This is the flag that indicates whether the IP address’s location matches that of the email or not.

ip.blacklisted

boolean

This is the flag that shows whether the IP address has been blacklisted or not.

ip.rateLimited

boolean

This is the flag that indicates whether the IP address has been rate-limited, that is, used multiple times or not.

risk.level

string

This is the risk level associated with the provided email and IP address. It can be either

"low," "medium," or "high."

risk.score

integer

This is the risk score out of 100.

risk.reasons

array

This is a list of reasons that will indicate how Clearbit has calculated a given risk score.