Simility API

Integrate Your Applications To Send Data And Detect Fraud

Integrating with Simility

Simility is a comprehensive and powerful fraud analytics software. The software analyzes transactional data (streaming or historical) and detects fraudulent transactions. This helps enterprises protect their businesses from fraudsters in real time and prevent risk occurrence.

Simility software is available as a software as a service (SaaS) and as an on-premises software. If you are opting for SaaS, our data analysts (DA) create instances for your business and you can start using the software. The on-premises software is an installer that can be used on your local cluster or on your virtual private cloud (VPC) environments.

Before getting started, you’ll need to build a tight integration between your application and the Simility software for data feeds. Successful integration of data feeds and other information sources is an important part of deploying the solution. Simility facilitates multiple ways to integrate with our software and transmit data into the Simility engine for processing. Apart from ingesting data from your application, our software is also capable of sending the results obtained after processing the data.

Simility has an inventory of API/JS components that are specific to various use cases ranging from account take-over to transactional fraud. We will deliver what is considered ideal for your business needs and then will augment it based on variations in the data feeds and information that is provided through your system feeds.
The API/JS components help you integrate your application with Simility software, collect the data produced by your application, and transmit data to the Simility engine. Simility supports collecting data from various sources of your application, such as:

  • Application’s front end
  • Back-end servers
  • User experience
  • Mobile applications (Android and iOS)
  • Devices
  • Historical data
You can integrate your applications with the Simility software using Backend API and Device Recon.

Backend API

The Backend API helps you integrate your application’s back-end server with Simility software and then, collect the required data and transmit it to the software. Before sending data from your back-end servers using this API, ensure you agree and sign off on the final schema with Simility. Based on the agreed schema, our data analysts create and configure an instance for your business.
Simility provides you a UUID, an api-bearer-token, and endpoints that enable your application to connect to Simility software. Simility software accepts data in the JSON format when you choose the Backend API to send the data. You need to construct a JSON payload of the data with respect to the fields agreed upon and then send it to Simility software. You can send the JSON files using the following endpoints:

Description
Use the ingress endpoint to send new data into the Simility software. Data feeds received through this endpoint will be considered for processing by Simility’s pipelines.
URL
<UUID>.simility.com/server/rest/ingress
Example
curl -i -H "Authorization: Bearer <api-bearer-token>" -X 'POST' -d @jsonfilepath 'https://<UUID>.simility.com/server/rest/ingress'

In the above example, replace:

  • <api-bearer-token> with the bearer token provided by Simility
  • @jsonfilepath with the path of the JSON file that you want to send to the Simility software
  • <UUID> with the UUID provided by Simility.

Description
Use the update endpoint to update the existing data including decisions taken by your automated systems or by your analysts using any internal systems.

Note: To send decision updates, you must create decision labels specific to your business within the Simility web console.

You can also use the update endpoint to update the data that is sent through the ingress endpoint. The update endpoint just performs the upsert operation over the rows that are previously sent, but does not triggers reinvestigation of the existing rows with updates. If you want the existing rows with updates to be reinvestigated, send the data as new data using the ingress endpoint.
URL
<UUID>.simility.com/server/rest/ingress
Example
curl -i -H "Authorization: Bearer <api-bearer-token>" -X 'PUT' -d @jsonfilepath 'https://<UUID>.simility.com/server/rest/ingress'

In the above example, replace:

  • <api-bearer-token> with the bearer token provided by Simility
  • @jsonfilepath with the path of the JSON file that you want to send to the Simility software
  • <UUID> with the UUID provided by Simility.

JSON Payload

As Simility software accepts data feeds only in the form of JSON format, you can construct the JSON payload using the following parameters to send data feeds from your back-end servers.
Parameters
Name Type Description
entity String Name of the table in which the data to be stored.
id String A unique ID that identifies a record in the entity.
fields key-value The fields parameter is a map of key-value pairs. The key-value pairs are the actual data feeds (schema) that you are suppose to send to Simility’s software for fraud detection. Work with the data analyst assigned to your business to discuss and freeze schema before you start sending the data feeds to Simility software. The Simility software accepts all basic data types (such as String, Numeric, Date) and also accepts nested data, including maps and arrays, to support complex data structure. Individual key-value data within the fields parameter can change for every POST; that is, sending a subset of fields or any additional field per call and the schema is dynamically handled at Simility’s back end.
Note: For the update endpoint, the existing records will be updated or merged based on the unique key (id) of the payload.
Example
//Ad Table
[{
	"entity": "ad",
	"id": "CA360497",
	"fields": {
		"language": "en-US",
		"referral_channel": "www.google.com",
		"creation_time": "2015-05-23 13:35:00",  //please use UTC  timezone.
		"ip_address": "204.23.100.11",  //from DeviceRecon, but you can provide it too.
		"session_id": "ES45D54ER82GF5D2DF5DFG1DF5DFG51DF",
		"device_id": "87YU98YUHJK", //from DeviceRecon
		"device_user_agent": "CorpInc/2.1.8 (build: 140111135; samsung SM-N910V LMY47X; Android 5.1.1; en_US)",  //from DeviceRecon
		"status": "ACTIVE",
		"market_region": "US",
		"user_id": "MCBUGGY1978",  //user who created the ad
		"user_first_name": "John",
		"user_last_name": "Doe",
		"user_email": "john.doe@gmail.com",
		"user_phone": "6502398673",
		"title": "New motorcycle battery",
		"description": "Selling brand new motorcycle battery $70 obo",
		"image_phash": "723443A87934IURJE",
		"image_url": "www.buy-my-stuff.com/CA360497/image.html",
		"category_level1": "Electronics",
		"category_level2": "General",
		"category_level3": "Battery",
		"listing_type": "Premium",
		"item_condition": "new",
		"location": "Palo Alto",
		"currency" : "USD",
		"price": 70,
		"price_usd": 70
		"custom_field_1": "xyz", //any additional field you would like to send. Please let us know the final field name.
		"custom_field_2": "xyz", //any additional field you would like to send. Please let us know the final field name.
		"custom_field_3": "xyz", //any additional field you would like to send. Please let us know the final field name.
		"custom_field_4": "xyz", //any additional field you would like to send. Please let us know the final field name.
		"custom_field_5": "xyz" //any additional field you would like to send. Please let us know the final field name.
	}
}]								

Device Recon

Device Recon collects data from the web, Android, and iOS applications and then sends the data to Simility software. Using Device Recon, you can collect data such as user actions, user details, browser details, device details, and so on from your application. Device Recon is classified into:

Web Application

Simility provides JavaScript programs to capture data from web applications. The JavaScript programs are of two types: Standard Page Load and Event Trigger. Our Simility engineering team helps you choose the one that best suits your needs. You must copy and paste the corresponding JavaScript program within the body section of individual web pages from which you want to capture the data.

Standard Page Load JavaScript

When a web page including the Standard Page Load JavaScript loads, the JavaScript gets downloaded and triggered to start capturing all actions performed on the web page along with the user details and send the captured data to Simility software.
Script Syntax
<script>
	var similityContext = {
		"customer_id": "<uuid>", 
		"session_id": "<session id>",
		"user_id": "<user_id>",
		"zone": "<zone>",
		"event_types": "<type>"
	};
</script>
<script type="application/javascript" src="https://cdn.simility.com/b.js"></script>
Parameters
Name Type Description
customer_id String Specify the UUID provided by Simility.
session_id String Specify a unique session ID assigned to the user session when a user accessed your application.
user_id String Optional. Specify the currently logged on user ID or email ID in case of anonymous transaction/activities. This can be internal identification you use in your organization.
Zone String Specify the zone where your data centers are hosted.
event_types String Specify the event or action that you want to associate with the JavaScript. You can specify multiple values separated by a comma.
Example
<script>
    var similityContext = {
            "customer_id": "5e295f6c-5fd2-11e7-907b-a6006ad3dba0",
            "session_id": "lit3py55t21z5v55vlm25s55",
            "user_id": "1200583092",
            "event_types": "user_registration",
            "zone": "us"
    };
</script>
<script type="application/javascript" src="https://cdn.simility.com/b.js"></script>
                                                
In case JavaScript is turned off on browsers, the standard page load JS cannot capture the required information from web pages. To record such cases, Simility recommends adding a <noscript> section as well. The <noscript> section is executed when JavaScript is disabled to run on browsers. You can add the <noscript> section using the following method:

NoScript Tag with Query Parameters

Add the following script in the body section of the web page.
<noscript>
        <img width="1" height="1" alt="" src="https://b-<zone>.simility.com/b.png?c=<customer_id>&si=<customer_session_id>&u=<user_id>">
 </noscript>
In the above script, replace the customer_id, session_id, and user_id parameters as per the Parameters table above.

Android SDK

The Android SDK collects data from Android mobile applications and transmits the collected data to Simility software. Simility provides a pre-built JAR file, which you must include in your Android application project.

In the app runtime, when the SDK is invoked, the required data is collected and sent to Simility software asynchronously in the background thread without affecting the user interface operations.

The data from the application is collected based on the manifest permissions set in the host application. The SDK explicitly does not request permissions to access and collect any data.

You can follow any one of the procedures below to configure the Android SDK in the Android Studio IDE.

Configuring using the JCenter Repository

  1. In the dependencies block of your build.gradle file, add the following line:
    compile ‘com.simility.recon:simility-recon:1.616’
  2. Clean the build.
  3. Import and call the Simility APIs with applicable parameters.
  4. Build and run the application.

Configuring using the New Module

  1. Download the .aar file and extract it.
  2. Create a new project or open your existing project.
  3. Click File > New > Import Module.
  4. In the Source directory box, select the extracted .aar file
  5. In the dependencies block of your build.gradle file, add the following line:
    compile ‘com.simility.recon:simility-recon:1.616’
  6. Clean the build.
  7. Import and call the Simility APIs with applicable parameters.
  8. Build and run the application.

Sample Code:

package com.example.androidintegratiodemo;
 
import android.app.Activity;
import android.os.Bundle;
 
// Import SimilityScript and SimilityContext
import com.simility.recon.SimilityScript;
import com.simility.recon.SimilityContext;
 
public class MainActivity extends Activity {
 
  @Override
    protected void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.activity_main);
      // Construct a valid SimilityContext
      SimilityContext similityContext = new SimilityContext();
      similityContext.setApplicationContext(getApplicationContext());
      similityContext.setCustomerId("5e295f6c-5fd2-11e7-907b-a6006ad3dba0"); // replace  with unique identifier assigned by Simility. This will be provided to you during signup.
      similityContext.setSessionId("your.session.id.variable"); //replace with sessionID variable
      similityContext.setUserId("your.user.id.variable"); //replace with userID variable
      similityContext.setEventTypes("payment_initiate"); // Comma separated snake_case string of action/event which is associated with this activity/view.
      similityContext.setZone("us"); // Default: "us". If data regulatory compliance requires your data to be hosted in Europe datacenters, please specify zone as "eu" 
 
      // Execute SimilityScript
      SimilityScript.getInstance().execute(similityContext);
    }
}
                                    

SimilityContext Class

Use the SimilityContext class to create a Simility context with required methods and pass it to the SimilityScript class below as a parameter.
In the SimilityContext class, you can add the following methods.

Description
Sets the application context.
Syntax
public void setApplicationContext(Context applicationContext);
Parameters
Name Type Description
applicationContext Context TBD.
Example
similityContext.setApplicationContext(getApplicationContext());

Description
Sets the customer ID.
Syntax
public void setCustomerId(customerId);
Parameters
Name Type Description
customerId String Specify the UUID provided by Simility.
Example
similityContext.setCustomerId("5e295f6c-5fd2-11e7-907b-a6006ad3dba0");

Description
Sets the type of the event.
Syntax
public void setEventTypes(eventTypes);
Parameters
Name Type Description
eventTypes String Specify the event or action that you want to associate with the JavaScript. You can specify multiple values separated by a comma.
Example
similityContext.setEventTypes("payment_initiate");

Description
Sets the session ID.
Syntax
public void setSessionId(sessionId);
Parameters
Name Type Description
SessionId String Specify a unique session ID assigned to the user sessions when users accessed your application.
Example
similityContext.setSessionId("your.session.id.variable");

Description
Sets the zone where your data centers are hosted.
Syntax
public void setZone(zone);
Parameters
Name Type Description
zone String Specify the zone where your datacenters are hosted.
Example
similityContext.setZone("us");

SimilityScript Class

Use the SimilityScript class to execute the created Simility context.

Description
Executes the specified Simility context.
Syntax
public static void execute(SimilityContext similityContext);
Parameters
Name Type Description
similityContext Context Specify the name of the Simility context that you want to execute.
Example
SimilityScript.execute(similityContext);

iOS SDK

The iOS SDK collects data from iOS mobile applications and transmits the collected data to Simility software. Simility provides a zip file, which you must include in your iOS application project.

In the app runtime, when the SDK is invoked, the required data is collected and sent to Simility software asynchronously in the background thread without affecting the user interface operations.

Refer to the following sections to learn how to configure the iOS SDK in the Objective-C-based application and in the Swift-based application.

Configuring the SDK in the Objective-C-based Application

In the Objective-C-based Application, you can configure the SDK by adding header and library files, and also using the CocoaPods file.

Configuring by adding Header and Library Files

  1. Download the zip file and extract it.
  2. In Xcode, create a new project or open an existing project.
  3. Drag the extracted files to the Supporting Files folder on the left pane. The Choose options for adding these files dialog box opens.
  4. Select Copy items if need, and click Finish.
  5. Import the SimilityRecon header file and add the code for calling the Simility API (refer the sample code below).
  6. Build and run the application.

Configuring using the CocoaPods file

  1. Execute the following command to add the POD repo.
    pod repo add SimilityRecon-iOS https://github.com/Simility/SimilityRecon-iOS-Specs.git
  2. In the POD file, add the following line:
    pod ‘SimilityRecon-iOS’, ‘~> 1.616’
  3. Install POD.
  4. Import the SimilityRecon header file and add the code for calling the Simility API (refer the sample code below).
  5. Build and run the application.

Sample Code:

#import "ViewController.h"
// Include Simility Header file
#import "SimilityRecon.h"
 
@interface ViewController ()
 
@end
 
@implementation ViewController
 
  - (void)viewDidLoad {
    [super viewDidLoad];
    // Do any additional setup after loading the view, typically from a nib.
    // Construct a valid SimilityContext object
    SimilityContext *similityContext = [[SimilityContext alloc] init];
    [similityContext setCustomerId:@"5e295f6c-5fd2-11e7-907b-a6006ad3dba0"]; // replace  with unique identifier assigned by Simility. This will be provided to you during signup.
    [similityContext setSessionId:@"your.session.id.variable"]; //replace with sessionID variable
    [similityContext setUserId:@"your.user.id.variable"]; //replace with userID variable
    [similityContext setEventtypes:@"payment_view"]; // Comma separated snake_case string of action/event which is associated with this activity/view.
    [similityContext setZone:@"us"]; // Default: "us". If data regulatory compliance requires your data to be hosted in Europe datacenters, please specify zone as "eu" 
 
    // Execute SimilityScript
    [[SimilityScript sharedInstance] execute:similityContext];
  }
 
@end
                                    

Configuring the SDK in the Swift-based Application

  1. Download the zip file and extract it.
  2. If the Object-C bridging header file does not exist in your project, create a dummy Objective-C file and place the file along with the extracted files.
  3. On the left pane, in your project, create a new folder with name, Supporting Files.
  4. Drag the extracted files along with the dummy Objective-C file to the Supporting Files folder. The Choose options for adding these files dialog box opens.
  5. Select Copy items if need, and click Finish. A dialog box opens asking whether to create Objective-C bridging header or not.
  6. Click Create Bridging Header.
  7. Delete the dummy Objective-C file from the Supporting Files folder.
  8. Open the ViewController file of the view from which you want to capture the data and add the following import statement.
    #import "SimilityBeacon.h"
  9. In the ViewController file, create the SimilityContext Class with necessary methods and then create the SimilityScript Class.
  10. Build and run the application.

Sample Code:

// Include Simility Header File in your Objective C Bridging-Header.h
#import "SimilityBeacon.h"
 
import UIKit
 
class ViewController: UIViewController {
  override func viewDidLoad() {
    super.viewDidLoad()
    // Construct a valid SimilityContext
    let similityContext =  SimilityContext()
    similityContext.customerId = "5e295f6c-5fd2-11e7-907b-a6006ad3dba0" // replace  with unique identifier assigned by Simility. This will be provided to you during signup.
    similityContext.sessionId = "your.session.id.variable" //replace with sessionID variable
    similityContext.userId = "your.user.id.variable" //replace with userID variable
    similityContext.eventTypes = "payment_view" // Comma separated snake_case string of action/event which is associated with this activity/view.
    similityContext.setZone("us") // Default: "us". If data regulatory compliance requires your data to be hosted in Europe datacenters, please specify zone as "eu" 
 
    // Execute SimilityScript 
    SimilityScript.execute(similityContext)
  }
}
                                    

SimilityContext Class

Use the SimilityContext class to create a Simility context with required methods and pass it to the SimilityScript class as a parameter.

In the SimilityContext class, you can add the following methods. These methods are applicable for Object-C-based applications and Swift-based applications as well.

Description
Sets the customer ID.
Syntax
- (void) setCustomerId:<customerId>
Parameters
Name Type Description
customerId String Specify the UUID provided by Simility.
Example
//Objective-C-based application
[similityContext setCustomerId:@"5e295f6c-5fd2-11e7-907b-a6006ad3dba0"];
 
//Swift-based application
similityContext.customerId = "5e295f6c-5fd2-11e7-907b-a6006ad3dba0"
                                                        

Description
Sets the type of the event.
Syntax
- (void) setEventTypes:<eventTypes>
Parameters
Name Type Description
eventTypes String Specify the event or action that you want to associate with the JavaScript. You can specify multiple values separated with a comma.
Example
//Objective-C-based application
[similityContext setEventtypes:@"payment_view"];
 
//Swift-based application
similityContext.eventTypes = "payment_view"                                                            
                                                        

Description
Sets the session ID.
Syntax
- (void) setSessionId:<sessionId>
Parameters
Name Type Description
SessionId String Specify a unique session ID assigned to the user sessions when users accessed your application.
Example
//Objective-C-based application
[similityContext setSessionId:@"your.session.id.variable"];
 
//Swift-based application
similityContext.sessionId = "your.session.id.variable"                                                            
                                                        

Description
Sets the zone where your data centers are hosted.
Syntax
- (void) setZone:<zone>
Parameters
Name Type Description
zone String Specify the zone where your datacenters are hosted.
Example
//Objective-C-based application
[similityContext setZone:@"us"];
 
//Swift-based application
similityContext.setZone("us")                                                            
                                                        

SimilityScript Class

Use the SimilityScript class to execute the created Simility context.

Description
Executes the specified Simility context.
Syntax
+ (void) execute:<similityContext>
Parameters
Name Type Description
similityContext Context Specify the name of the Simility context that you want to execute.
Example
//Objective-C-based application
[SimilityScript execute:similityContext];
 
//Swift-based application
SimilityScript.execute(similityContext)                                                                
                                                            

Building Business Logic

After you integrate your application with Simility software and start sending data, you are ready to use the Simility web console. The web console helps you manage the fraud detection process, define rules to detect fraud, view the fraud cases, make decisions, and much more. To learn more about the web console, refer its online help.

The data analyst assigned to your deployment will be responsible for deploying this instance and customizing it based on your business requirements.

Receiving Decisions

You can request and receive fraud decisions made by Simility in order to populate your database or enact appropriate actions on your business operations. For example, you can automatically freeze the accounts as soon as they are flagged as fraudulent by Simility. You can request to receive the data, such as decisions, scores, labels, features, and so on, from the Simility back end. The response from the Simility back end is sent as a JSON object.
You can receive the results from Simility software using the following methods:
  • Synchronous

    Use the synchronous method to receive the result as a RESPONSE object to your POST request when you send data. Assume that the data to Simility software is sent using the Backend API, which is a POST request, and the moment a record of the data is processed, the result of the processed record is sent as a RESPONSE object (200 OK) to your application.
  • Asynchronous

    Use the Asynchronous method to receive the results on your Webhook listener service. You must implement a Webhook/ REST JSON listener that can consume the JSON object sent from Simility software.

    Also, share the URL endpoint with the Simility team when the listener is available along with authentication mechanisms; for example, Bearer Token.
In both Synchronous and Asynchronous methods, to set the response time and timeouts, contact the Simility team.
The standard JSON object sent from the Simility back end for both Synchronous and Asynchronous contains the following parameters:
Parameters
Name Type Description
id String ID of the savings account.
decisionLabels List Decision set in the Simility web console mapped correctly to your back end.
decisionReasons List Reason statement attached with the Label. This is a leaf-level categorization for the decision selected and it can be configured in the Simility web console
timestamp String Timestamp at which the decision was taken.
decisionBy String Person who took the decision.
note String Note entered while passing decision.
score Numeric Aggregated score.
leadLabels String Individual scores.
queue String Queue from which decision was taken. The value could be null sometimes.
queueState String TBD.
additionalData String You can pass additional parameters as part of the decision payload using this field if required.
Example
{
	"entries": [
		{
			"id": "123",
			"entity": "be_$event_name$_event",
			"decisionLabels": ["REJECT"],
			"decisionReasons": ["bad_loginr"],
			"timestamp": "2017-05-18 07:24:50",
			"decisionBy": "analyst@simility.com",
			"note": "this is a bad session",
			"score": -30,
			"leadLabels": {
				"LinkedAccounts": -10,
				"Wallet": -10,
				"LinkedCardsAccounts": -10
			},
			"queue": "Bad_User",
			"queueState": null,
			"additionalData": null
		}
	],
	"type": "decision"
}