IPQualityScore C# API SDK

This C# interface grants easy to access IPQualityScore's API in one simple-to-use package. This page documents how to implement the interface into any C# project and how to utilize it.

Download the dll file here: IPQualityScore.CSharp.Interface.dll

Full IPQualityScore documentation is found here: IPQualityScore Documentation

Contents

• Installation
• Adding Request Parameters
• Using the Interface
• The Request List API Interface
• API Return Types
• Accessing and Printing the JSON Response
• Full Use Example

Installation

1. Download IPQualityScore.CSharp.Interface.dll

2. Import the file into the project space. Some IDEs can do this automatically. To add it manually, add the following lines to the project's .csproj file. The HintPath must match the file's location. It is best to use the full file path when possible.

<ItemGroup>
    <Reference Include="IPQualityScore.Csharp.Interface">
        <HintPath>...path...to...ROOT.../IPQualityScore.Csharp.Interface.dll</HintPath>
    </Reference>
</ItemGroup>

3. Import the following 3 libraries into the class using the interface.

using IPQualityScore.Csharp.Interface;
using IPQualityScore.Csharp.Interface.Models.Responses;
using System.Globalization;

Adding Request Parameters

Adding request parameters to the query will always enhance the accuracy of the score received. Simply place them in a Dictionary<string, object> variable using the field names found on the IPQualityScore documentation. Adding a parameter the API does not recognize should not cause any errors, however this can not be guaranteed.

Parameters are not required. A null value can always be sent. However, this will decrease the accuracy of the score.

The parameter dictionary created below is for proxy detection. Not all of these are required, nor is it all possible parameters. The code below is simply included as an example. Also, each API accepts slightly different parameters. Check here for a full list of proxy detection parameters.

private static Dictionary<string, object> parameters = new Dictionary<string, object>();
	
private static void populateParameters(){
	
	// Access user device's language
	string lang_iso = CultureInfo.InstalledUICulture.TwoLetterISOLanguageName;
	
	// General parameters
	parameters.Add("lighter_penalties", false);
	parameters.Add("user_language", lang_iso);
	parameters.Add("strictness", 1);
	parameters.Add("allow_public_access_points", true);
	
	// Add billing information
	parameters.Add("billing_first_name", "John");
	parameters.Add("billing_last_name", "Doe");
	parameters.Add("billing_company", "Company Name");
	parameters.Add("billing_country", "US");
	parameters.Add("billing_address_1", "1600 Pennsylvania Avenue LATER");
	parameters.Add("billing_address_2", "");
	parameters.Add("billing_city", "Washington");
	parameters.Add("billing_region", "DC");
	parameters.Add("billing_postcode", 20500);
	parameters.Add("billing_email", "john.doe@johnnydoe.com");
	parameters.Add("billing_phone", 9991234545);
	
	// Add shipping information
	parameters.Add("shipping_first_name", "John");
	parameters.Add("shipping_last_name", "Doe");
	parameters.Add("shipping_company", "Ships-R-Us");
	parameters.Add("shipping_country", "US");
	parameters.Add("shipping_address_1", "1600 Pennsylvania Avenue LATER");
	parameters.Add("shipping_address_2", "");
	parameters.Add("shipping_city", "Washington");
	parameters.Add("shipping_region", "DC");
	parameters.Add("shipping_postcode", 20500);
	parameters.Add("shipping_email", "john.doe@johnnydoe.com");
	parameters.Add("shipping_phone", 7622069353);
	
	// Add user information
	parameters.Add("username", "john.doe123");
	parameters.Add("password_hash", "<hash value>");
	
	// Add credit card information
	parameters.Add("credit_card_bin", 9999999999999999);
	parameters.Add("credit_card_hash", "");
	parameters.Add("credit_card_expiration_month", 05);
	parameters.Add("credit_card_expiration_year", 25);
	parameters.Add("avs_code", "999");
	parameters.Add("cvv_code", "999");
	
	// Add order information
	parameters.Add("order_amount", 1);
	parameters.Add("order_quantity", 1);
	
	// Add recurring information
	par	ameters.Add("recurring", false);
	parameters.Add("recurring_times", 0);
}

Using the Interface

Here is step-by-step process for utilizing the interface. This example assumes the library is already properly set up and imported.

1. Create an IPQS_CSharp_Interface object
2. Set the API key
3. Create a dictionary of parameters (null is acceptable)
4. Set the query's target
5. Submit the query and store the response

Step #1: Create an IPQS_CSharp_Interface object.

IPQS_CSharp_Interface ipqsInterface = new IPQS_CSharp_Interface();

Step #2: Setting the api key

Use SetKey(<string>) to set the IPQualityScore API key for all HTTP requests. It returns the value currently stored as the API key in order to verify accuracy if desired. See example below:

string final API_KEY = " PLACE THE ACCOUNT'S API KEY HERE ";
ipqsInterface.SetKey(API_KEY);

Step #3: Create Dictionary of Parameters

See section Adding Request Parameters above.

Step #4: Set Query

Store the element in question (email, url, phone number, etc...). There are many ways to do this. This is merely an example.

string query = "www.google.com";

Step #5: Submit Query and Store the Response

There are 7 available query methods. Each method returns an object representation of the json returned by the HTTP Get request. Except for the CreditUsageRequest, each one requires string and Dictionary<string, object>? parameters. The latter can be null in certain cases.

To get a fraud score for an IP address (Proxy and VPN Detection):

/*
 * query = the IP address in question
 * parameters? = Any additional parameters sent will improve score accuracy
 * return = IPReputationResponse?
 */
SubmitIPReputationRequest(string query, Dictionary<string, object>? parameters)

To get a fraud score for an email address:

/* 
 * query = the email in question
 * parameters? = Any additional parameters sent will improve score accuracy
 * return = EmailValidationResponse?
 */ 
SubmitEmailValidationRequest(string query, Dictionary<string, object>? parameters)

To get a fraud score for a phone number:

/* 
 * query = the phone number in question
 * parameters? = Any additional parameters sent will improve score accuracy
 * return = PhoneValidationResponse?
 */ 
SubmitPhoneValidationRequest(string query, Dictionary<string, object>? parameters)

To get a fraud score for a URL:

/*
 * query = the URL in question
 * parameters? = Any additional parameters sent will improve score accuracy
 * return = URLScannerResponse?
 */ 
SubmitURLScannerRequest(string query, Dictionary<string, object>? parameters)

To look up past fraud scores:

This query parameter is limited to the type of response being searched ("proxy", "email", "devicetracker", "mobiletracker", or "phone"). The start_date parameter must be formatted as "Y-m-d" or "Y-m-d H:i:s".

/* 
 * query = 1 of 5 possible values: "proxy", "email", "devicetracker", "mobiletracker", or "phone"
 * start_date = Date of the earliest fraud score to be included in the results.  The date must formatted as "Y-m-d" or "Y-m-d H:i:s".
 * parameters? = Any additional parameters sent will improve score accuracy
 * return = RequestListResponse?
 */ 
SubmitRequestListRequest(string query, string start_date, Dictionary<string, object> parameters)

To report a malicious IP, email, phone number, transaction or any other similar data:

In this case, query is whatever data is being reported. This API call does not reduce available credits.

/* 
 * query = the data being reported
 * parameters? = Any additional parameters sent will improve score accuracy
 * return = FraudulentReportResponse?
 */ 
SubmitFraudulentReportRequest(string query, Dictionary<string, object> parameters)

To query the number of API calls left on the account for the billing period:

This API call does not reduce available credits.

/* 
 * return = CreditUsageResponse?
 */ 
SubmitCreditUsageRequest()
   return = CreditUsageResponse?

Example:

This example uses the Proxy Detection API. It assumes initial setup and parameters have already been completed.

// Step #1: Create API object
IPQS_CSharp_Interface ipqsInterface = new IPQS_CSharp_Interface();

// Step #2: Setting the API key
String API_KEY = " PLACE THE ACCOUNT'S API KEY HERE ";
ipqsInterface.SetKey(API_KEY);


// Step #3:
// Create parameter dictionary object.  
// Parameter population is not included.
// null can be sent as a parameter if desired.
Dictionary<string, object> parameters = new Dictionary<string, object>();
// add parameters

// Step #4: Setting the query's target
string url = "http://www.google.com";

// Step #5 Submit query and store the response
URLScannerResponse? response = ipqsInterface.SubmitURLScannerRequest(url, parameters);

The Request List API Interface

Using this interface requires two extra steps.

1. The query parameter is limited to one of the following request types: "email", "phone", "proxy", "devicetracker", or "mobiletracker".

2. The additional parameter start_date must be included so the system knows how far back to look. The start_date must be properly formatted ("Y-m-d" or "Y-m-d H:i:s"). For example, to receive results as early as 4:15 PM on January 2nd, 2020, the string literal should read "2020-01-02 16:15:00".

Example:

This query retrieves a list of all email validation requests since January 2nd, 2020.

// Create API object
IPQS_CSharp_Interface ipqsInterface = new IPQS_CSharp_Interface();

// Include the account's API key
String API_KEY = " PLACE THE ACCOUNT'S API KEY HERE ";
ipqsInterface.SetKey(API_KEY);

// Create dictionary of whatever parameters you wish to send (Not required but highly suggested)
Dictionary<string, object> parameters = new Dictionary<string, object>();
parameters.Add("min_fraud_score", 45);

// Make request
RequestListResponse? response = ipqsInterface.SubmitRequestListRequest("email", "2020-01-02", parameters);

API Return Types

All responses are deserialized json in one of the following nullable object types below. Unsuccessful queries that reach the IPQualityScore server will still receive a response with a corresponding error message.

Return Types

• IPReputationResponse? - for Proxy Detection API Documentation
• EmailValidationResponse? - for Email Validation API Documentation
• PhoneValidationResponse? - for Phone Number Validation API Documentation
• URLScannerResponse? - for Malicious URL Scanner API Documentation
• FraudulentReportResponse? - for Fraud Reporting API Documentation
• CreditUsageResponse? - for Credit Usage API Documentation
• RequestListResponse? - for Request List API Documentation

Null Returns

A null return is likely due to one of the following reasons.

• The API key has not be set yet
• One of the required parameters is in the wrong format or is missing
• Some type of network connection error

Accessing and Printing the JSON Response

To access the data, add the appropriate key to the response object. For a full list of keys, consult the corresponding API's full documentation here: IPQualityScore Documentation

// Appropriate setup is assumed
URLScannerResponse? response = ipqsInterface.SubmitURLScannerRequest("www.google.com", parameters);

Console.WriteLine(response.message);	// prints: Success
Console.WriteLine(response.unsafe);		// prints: false
Console.WriteLine(response.risk_score);	// prints: 0

To print the entire response, re-serialize the json with the `WriteIndented` option set to `true`.

URLScannerResponse? response = ipqsInterface.SubmitURLScannerRequest("www.google.com", parameters);
Console.WriteLine(JsonSerializer.Serialize(response, new JsonSerializerOptions { WriteIndented = true }));

// Written to the console
{
  "message": "Success.",
  "success": true,
  "unsafe": false,
  "domain": "google.com",
  "ip_address": "172.253.124.101",
  "server": "gws",
  "content_type": "text/html; charset=UTF-8",
  "status_code": 200,
  "page_size": 48023,
  "domain_rank": 1,
  "dns_valid": true,
  "parking": false,
  "spamming": false,
  
  ...etc...
  
}

Full Use Example

The example below uses most IPQS_CSharp_Interface methods and prints their responses to the console. The fraud reporting and request list methods are not shown.

To run:

1. Complete the installation process
2. Copy the class below into its own file
3. Add the account's API key at the designated spot
4. Run the following line from another method: IPQS_CSharp_Example.IPQS_Example_API_Calls();

using IPQualityScore.Csharp.Interface;
using IPQualityScore.Csharp.Interface.Models.Responses;
using System.Globalization;
using System.Text.Json;


public static class IPQS_CSharp_Example{

    private const String API_KEY = " PLACE THE ACCOUNT'S API KEY HERE ";
    private static IPQS_CSharp_Interface ipqsInterface = new IPQS_CSharp_Interface();
    private static Dictionary<string, object> parameters = new Dictionary<string, object>();
    
    public static void IPQS_Example_API_Calls()
    {
        ipqsInterface.SetKey(API_KEY);

        // Method to populate a few parameters
        populateParameters();  

        // Get score for IP Address 8.8.8.8 (the primary DNS server for Google)
        IPReputationResponse? ipResponse = ipqsInterface.SubmitIPReputationRequest("8.8.8.8", null);
        System.Console.WriteLine("IP Address / Proxy Fraud Score:");
        System.Console.WriteLine(JsonSerializer.Serialize(ipResponse, new JsonSerializerOptions { WriteIndented = true }));

        // Get score for noreply@ipqualityscore.com
        EmailValidationResponse? emailResponse = ipqsInterface.SubmitEmailValidationRequest("support-in@google.com", parameters);
        System.Console.WriteLine("\n\n\n Email Address Fraud Score:");
        System.Console.WriteLine(JsonSerializer.Serialize(emailResponse, new JsonSerializerOptions { WriteIndented = true }));
        
        /* 
         * Get score for 1-800-713-2618
         * 
         * While this is not advised, no parameters are being
         * sent to illustrate that everything still works.
         */        
        PhoneValidationResponse? phoneResponse = ipqsInterface.SubmitPhoneValidationRequest("18007132618", parameters);
        System.Console.WriteLine("\n\n\n Phone Number Fraud Score:");
        System.Console.WriteLine(JsonSerializer.Serialize(phoneResponse, new JsonSerializerOptions { WriteIndented = true }));
        
        // Get score for www.google.com
        URLScannerResponse? urlResponse = ipqsInterface.SubmitURLScannerRequest("www.google.com", parameters);
        System.Console.WriteLine("\n\n\n URL Fraud Score:");
        System.Console.WriteLine(JsonSerializer.Serialize(urlResponse, new JsonSerializerOptions { WriteIndented = true }));

        // Get remaining credits for the billing period
        CreditUsageResponse? creditUsageResponse = ipqsInterface.SubmitCreditUsageRequest();
        System.Console.WriteLine("\n\n\n Credit Usage Response:");
        System.Console.WriteLine(JsonSerializer.Serialize(creditUsageResponse, new JsonSerializerOptions { WriteIndented = true }));
        
    }


    private static void populateParameters(){
        
        // Reset the current parameters so there's no bleed
        parameters = new Dictionary<string, object>();
        
        // The regional language of whatever device is running this
        string lang_iso = CultureInfo.InstalledUICulture.TwoLetterISOLanguageName;

        // Add general parameters
        parameters.Add("lighter_penalties", false);
        parameters.Add("user_language", lang_iso);
        parameters.Add("strictness", 1);
        parameters.Add("fast", true);
        parameters.Add("allow_public_access_points", true);
        
        // To show that non-existent parameters won't break anything
        parameters.Add("numPinkFlamingos", "7");
      
    }
}