Questions? Feedback? powered by Olark live chat software

Simility API Documentation

Fraud Detection That Adapts and Scales


Full API Diagram - All Data Flows

Overview

Introduction

This API documentation is broken into three sections:

The Simility application is a software platform for detecting spam, fraud and member abuse. You can send us data about your users and their activity and we will tell you the risk that user is committing fraud. The processing and decisioning is visible on your Simility dashboard at app.simility.com.

  1. Device Recon: With our Javascript snippet, iOS SDK or Android SDK, you can passively collect valuable information about your users as they access your website or mobile app with their devices: phones, tablets and computers. Simility will tell you how risky a user is simply from their opening your website or mobile app.
  2. Send Data: You can upload any format of data from your users that may be useful for combatting fraud. With our REST API, this data is uploaded from your database to Simility’s servers. Alternatively, with our JavaScript snippet, you can pass us data actively generated by users from their sessions on your website, such as an email field they fill out.
  3. Get Decisions: You can request the fraud decisions made by Simility in order to populate your own database or enact appropriate actions on your business operations. For example you could auotmatically freeze any accounts as soon as they are flagged as fraudulent by Simility.

You need an account with Simility in order to use our service. Upon signup we will provide with your a customer_id (e.g microinc1) which will be unique to your company.
Please contact us and we’ll set you up.

Device Recon

Introduction

Device Recon is a script which runs on your website or mobile app and collects characteristics about your users’ devices (PC, tablets, and phones), such as browser, operating system, device hardware, and user behavior. Simility uses these characteristics to determine the fingerprint and riskiness of the device and its associated user.

JavaScript

Simility supports two types of JS integration. Our integration engineer will work with you to choose the one that best serves your needs and paste the corresponding JavaScript snippet in the <body> section of specific pages on your website. Typically you need to define object named similityContext which will have subset of below mentioned properties based on your definition.

JS1: Standard Page Load

This is the standard production setup. Script execution begins from the moment this script is downloaded as part of page load.

Copy

<script>
  var similityContext = {
      "customer_id": "5e295f6c-5fd2-11e7-907b-a6006ad3dba0",  // required; provided to you by simility during signup 
      "session_id": "your.page.session.id.variable",  // required; unique per user session, typically persistent by your backend 
      "user_id": "your.user.id.variable",  // recommended; user_id variable from your session, typically persistent on your backend 
      "event_types": "payment_form",  // required; Comma separated snake_case strings of action/event which is associated with this activity/view 
      "zone": "us" // If data regulatory compliance requires your data to be hosted in Europe datacenters, please specify zone as "eu" 
  };
</script>
<script type="application/javascript" src="https://cdn.simility.com/b.js"></script>

JS2: Event Trigger

Use this setup if you want to trigger script execution on an event trigger, like a button click, instead of on page load. Be careful not to set it up on events(login event) that cause a quick redirect to another page and might not allow simility script to finish execution. It’s recommended you follow JS1 for such pages.

In the example below, the customer is browsing e-commerce and performs checkout post adding few items to cart. This is a popular setup when using a single page application. Let’s say you have a button widget defined with id checkout-button.

Copy

<button id="checkout-button">Checkout</button>

Option 1: Download script synchronously beforehand and execute script on trigger of an event.

Copy

<script type="application/javascript" src="https://cdn.simility.com/b.js"></script>

<script>
  $('#checkout-button').click(function() {
    if (window.SimilityScript) {
      var sc = {
      "customer_id": "5e295f6c-5fd2-11e7-907b-a6006ad3dba0",
      "session_id": "your.page.session.id.variable",
      "user_id": "your.user.id.variable",
      "event_types": "checkout_page",
      "zone": "us" 
      };
      var ss = new SimilityScript(sc);
      ss.execute();
    } 
  });
</script>

Option 2: Download script asynchronously and execute in completion callback using jQuery on trigger of an event.

Copy

<script>
  $('#checkout-button).click(function() {
    $.getScript('https://cdn.simility.com/b.js', function() {  
      var sc = {
      "customer_id": "5e295f6c-5fd2-11e7-907b-a6006ad3dba0",
      "session_id": "your.page.session.id.variable",
      "user_id": "your.user.id.variable",
      "event_types": "checkout_page",
      "zone": "us" 
      };
      var ss = new SimilityScript(sc);
      ss.execute();
  }); 
});
</script>

Note: We strongly recommend you set the session_id variable that is persistent on your backend. This is the default way to join the frontend device data with your backend transactions user data that you might send to Simility (See the Upload section below).

 

Properties


customer_id (required, string): Unique identifier assigned by Simility. This will be provided to you during signup.

session_id (required, string): Unique per user session, typically persistent by your backend.

user_id (optional, string): Current logged in user Id or email Id in case of anonymous transaction/activities. This can be whatever internal identification you use in your organization.

event_types (required, string): Comma separated string of action/event which is associated with this activity.

zone (required, string): Default: "us". If data regulatory compliance requires your data to be hosted in Europe datacenters, please specify zone as "eu".
 
Advanced Configurations
transaction_info (optional, array): Use this to send transaction data. You will have to define array of JSON Objects, which follows the same format as described in the Upload Data > REST API section below.

request_endpoint (optional, string): If your prefer your request to be sent to your internal server first and forward it later to Simility servers, you can specify your endpoint URL here.

simility_lite (optional, bool): Default: true. If set to false, we request some additional information from your customers, like mouse movements, etc. Our integration engineer will work with you to decide this value if required.

simility_lite_level (optional, float): Default: 1. This value varies between 0 and 1 and defines the set of additional information that should be collected/skipped. Our integration engineer will work with you to decide this value if required.

iOS

Simility’s iOS SDK APIs allows you to collect data for fraud detection from your iOS application. Once a relevant API is invoked, it collects and sends data to our server asynchronously in a background thread without affecting any user interface operations. Simility will provide two artifacts: the header file SimilityBeacon.h and Cocoa touch static library libSimilityBeacon.a.

Declarations


Class
SimilityContext

Methods
- (void) setCustomerId:(NSString *) customerId;
Parameters
  - customerId: Unique identifier provided to you by Simility during signup.
 
- (void) setSessionId:(NSString *) sessionId;
Parameters
  - sessionId: Unique per user session, typically persistent by your backend.
 
- (void) setUserId:(NSString *) userId;
Parameters
  - userId: The User ID of the current user. This can be whatever internal identification you use in your organization.
 
- (void) setEventTypes:(NSString *) eventTypes;
Parameters
  - eventTypes: Comma separated string of action/event which is associated with this activity/view.
 
- (void) setZone:(NSString *) zone;
Parameters
  - zone: Default: "us". If data regulatory compliance requires your data to be hosted in Europe datacenters, please specify zone as “eu”.
 
Advanced Configurations
- (void) addTransactionEntry:(NSString * _Nonnull) entity id:(NSString * _Nonnull) id fields:(NSDictionary * _Nullable) fields;
Use below api to associate transaction data with recon request. It will generate transaction entry as detailed at Upload Data > REST API section and send it to Simility servers.

Parameters
  - entity (required, NSString): The entity you are sending data for, e.g. users or transactions. The Entity param in the json overrides the entity param in the URL.
  - id (required, NSString): This is the unique key that identifies that event/record i.e. Entity Id. Typically user_id or transaction_id. In this example, we use AA1001 and AA1002 for id values.
  - fields (required, NSDictionary): This is customer defined section in our json payload. You can send any custom key-value pair json data. Basic data types of string, numeric, date etc are supported and nested data including maps, arrays are also supported to send any complex data structure. Note that this is an upsert API and existing record will be updated/merged based on the unique key "id" of that payload. This should be convertible to JSON data.  This can be nil if you don’t have to pass any fields.
 
- (void) setRequestEndpoint:(NSString *) requestEndpoint;
Parameters
  - requestEndpoint (required, NSString): If your prefer your request to be sent to your internal server first and forward it later to Simility servers, you can specify your endpoint URL here.

Class
SimilityScript

Methods
+ (void) execute:(SimilityContext * _Nonnull) similityContext;
Parameters
  - similityContext (required, SimilityContext):  SimilityContext object with valid customerId, sessionId and other properties.

Objective C based Applications

  1. Download and extract the zip file
  2. Create a new Xcode project and open the existing project
  3. Drag the extracted files to the supporting files group or to a newly created new group
  4. From the options dialog for adding files, opt to copy items if needed and add to targets
  5. Import the SimilityBeacon header file and add the code for calling the Simility API (refer sample code in below section)
  6. Build and run

Sample code for calling the Simility API:

Copy

#import "ViewController.h"
#import "SimilityBeacon.h"
// Include Simility Header file
#import "SimilityBeacon.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 execute:similityContext];
  }

@end

Swift based Applications

  1. Download and extract the zip file
  2. If your project doesn’t have an existing Objective C bridging header file, create a dummy Objective C file and place it along with extracted files
  3. Create a new Xcode project or open the existing project
  4. Drag the extracted files to the supporting files group or to a newly created new group
  5. From the options dialog for adding files, opt to copy items if needed and add to targets
  6. When prompted to create bridging header file, choose create. You can delete the dummy Objective C file if you used it earlier
  7. Import the SimilityBeacon header file and add the code for calling the Simility API (refer sample code in below section)
  8. Build and run

Sample code for calling the Simility API:

Copy
  
// 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)
  }

}

Android

Simility’s Android APIs allows you to collect data for fraud detection from your Android application. Once a relevant API is invoked, it collects and sends data to our server asynchronously in a background thread without affecting any user interface operations. Simility will provide a pre-built jar file that need to be included in your project. Signals are collected on the basis of Manifest permissions in the host Application and it doesn’t explicitly requests for permissions.

Declarations

Copy

Class
SimilityContext

Methods
public void setApplicationContext(Context applicationContext);
Parameters
  - applicationContext: You need to pass application context here.
 
public void setCustomerId(String customerId);
Parameters
  - customerId: Provided to you by Simility during signup.
 
public void setSessionId(String sessionId);
Parameters
  - sessionId: Unique per user session, typically persistent by your backend.
 
public void setUserId(String userId);
Parameters
  - userId: The UserID of the currently active user. This can be whatever internal identification you use in your organization.
 
public void setEventTypes(String eventTypes);
Parameters
  - eventTypes: Comma separated string of action/event which is associated with this activity/view.
 
public void setZone(String zone);
Parameters
  - zone: Default: "us". If data regulatory compliance requires your data to be hosted in Europe datacenters, please specify zone as "eu"
 
Advanced Configurations
public void addTransactionEntry(String entity, String id, Map<String, Object> fields) throws JSONException;
Use below api to associate transaction data with recon request. It will generate transaction entry as detailed at Upload Data > REST API section and send it to Simility servers.

Parameters
  - entity: The entity you are sending data for, e.g. users or transactions. The Entity param in the json overrides the entity param in the URL.
  - id: This is the unique key that identifies that event/record i.e. Entity Id. Typically user_id or transaction_id. In this example, we use AA1001 and AA1002 for id values.
  - fields: This is customer defined section in our json payload. You can send any custom key-value pair json data. Basic data types of string, numeric, date etc are supported and nested data including maps, arrays are also supported to send any complex data structure. Note that this is an upsert API and existing record will be updated/merged based on the unique key "id" of that payload. This should be convertible to JSON data.  This can be null if you don’t have to pass any fields.
 
public void setRequestEndpoint(String requestEndpoint);
Parameters
  - requestEndpoint: If your prefer your request to be sent to your internal server first and forward it later to Simility servers, you can specify your endpoint URL here.

Class
SimilityScript

Methods
public static void execute(SimilityContext similityContext);
Parameters
  - similityContext:  SimilityContext object with valid applicationContext, customerId and other properties.

Eclipse IDE

  1. Download and extract the .jar file
  2. Create a new Android Application project and open the existing project
  3. Create a new folder called libs in your project’s root folder, if it does not exist already
  4. Copy the JAR files to this libs folder
  5. Import and call the Simility APIs with applicable parameters (refer sample code in below section)
  6. Build and run

Android Studio IDE

  1. Download and extract the .jar file
  2. Create a new Android Application project and open the existing project
  3. Go to Project Structure in the left pane and locate the libs folder under app
  4. Copy the JAR file inside the libs folder. Right click on the JAR file and opt for Add as Library. It will take care of adding the compile files in build.grade
  5. Import and call the Simility APIs with applicable parameters (refer sample code in below section)
  6. Build and run

Sample code for calling the Simility API:

Copy

package com.example.androidintegratiodemo;

import android.app.Activity;
import android.os.Bundle;

// Import SimilityScript and SimilityContext
import com.simility.beacon.SimilityScript;
import com.simility.beacon.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.execute(similityContext);
    }
}

PhoneGap/Cordava

    1. Follow steps for adding JAR file as shown above
    2. To call the Simility APIs, add import in the class extending DroidGap, call super.init() and add JavascriptInterface with WebView of super class

Sample code for the class extending DroidGap

Copy

package com.simility.phonegaptestapp;

import org.apache.cordova.DroidGap;
import android.app.Activity;
import android.os.Bundle;
import android.view.Menu;
import android.view.MenuItem;
import android.webkit.JavascriptInterface;
import android.webkit.WebView;

// Import SimilityScript and SimilityContext
import com.simility.beacon.SimilityScript;
import com.simility.beacon.SimilityContext;

public class MainActivity extends DroidGap/*Activity*/ {

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    super.init();
    super.appView.addJavascriptInterface(this, "MainActivity");
    super.loadUrl("file:///android_asset/www/index.html");
  }

  @JavascriptInterface
  public void callSimilityScript() {
    // Construct a valid SimilityContext
    SimilityContext similityContext = new SimilityContext();
    similityContext.setApplicationContext(getApplicationContext());
    similityContext.setCustomerId("5e295f6c-5fd2-11e7-907b-a6006ad3dba0");
    similityContext.setSessionId("your.session.id.variable");
    similityContext.setUserId("your.user.id.variable");
    similityContext.setEventTypes("payment_initiate");
    similityContext.setZone("us");
  }
}
    1. Add a method with annotation @JavascriptInterface, which allows exposing methods to JavaScript (this will call the Simility API with the context of super activity as a parameter)
    2. In your webpage source code, add the code for Javascript call

Sample code on HTML page to call Simility API

Copy

<!DOCTYPE HTML>
<html>
  <head>
    <title>Sample</title>
    <script type="text/javascript" charset="utf-8" src="cordova-2.0.0.js"></script>
  </head>
  <body>
    <h1>PhoneGap Sample App</h1>
    <script type="text/javascript">
    (function(){
        window.MainActivity.callSimilityScript();
    })();
    </script>
  </body>
</html>

Data Upload

You can send data to Simility via –

  • Fronent Javascript API : Use this to send data from your frontend (web, iOS, android) using DeviceRecon integration
  • Backend API : Use this to send data from your backend server to Simility backend.
  • Feedback API : Use this to send explicit feedback i.e. decision labels for your existing data e.g. Fraudulent Users, Checkedback Transactions
  • One Off File Upload : Use this to upload oneoff files for bulk data. We support uploading CSV file upload to our backend using Simility UI.

Frontend Javascript API

Our DeviceRecon collects device data for browser, iOS and Android devices. In addition to collecting device data you can use the beacon JS snippet to send additional data from frontend to Simility.
This additional data can be packaged in the trasnactionInfo object which is available on JS Web, Adnroid or iOS integration. Please refer to the Device Recon Integration.

Backend Data API

Simility backend API is flexible to handle custom JSON objects, including arrays and objects within your data object. Simility backend schema is flexible and the json payload
can be customized as per your requirements.

We recommend using a JSON validator to make sure your JSON file is formatted properly.
After you post some data, you can check whether it uploaded successfully by running a SQL query in your Simility app to search for it.

Url Parameters

  • endpoint url : Default production endpoint is https://app.simility.com/. Depending on the services requested the endpoint will be https://app.simility.com/server/rest/ingress/$customer_id$/$entity$.
    The stage/test endpoint is https://stage.simility.com/
  • customer_id : This is the same simility provided customer id (e.g. “microcorp1”). See Requirements above.
  • entity : The entity you are sending data for, e.g. users or transactions.
    Check the Entities & Fields section of your Simility app to see your list of available entities or create a new one.

JSON Payload Parameters

  • entity (required, string): The entity you are sending data for, e.g. users or transactions. The Entity param in the json overrides the entity param in the URL.
  • id (required, string): This is the unique key that identifies that event/record i.e. Entity Id. Typically user_id or transaction_id. In this example, we use AA1001 and AA1002 for id values.
  • fields (required, string): This is customer defined section in our json payload. You can send any custom key-value pair json data.
    Basic datatypes of string, numeric, date etc are supported and nested data including maps, arrays are also supported to send any complex data structure.
    Individual key-value pair data inside the “fields” section can change for every POST i.e. sending a subset of fields or any additional field per call and the schema is dynamically handled on our backend.
    Note that this is an upsert API and existing record will be updated/merged based on the unique key “id” of that payload.

Substitute the customer_id and entity params in the POST URI and the “id” values with the EntityId in the json payload.

Headers

Copy
Content-Type: application/json
Authorization: Bearer [token]
POST: /server/rest/ingress/$customer_id$/$entity$
e.g. https://app.simility.com/server/rest/ingress/microcorp1/user

Body

Copy
[
  {
    "id": "AA1001",
    "entity": "user",
    "fields": {
      "first_name": "John",
      "account_age": 18,
      "interests": ["snowboarding", "hiking", "fishing"],
      "quality_status": {
        "0": "active",
        "1": "good",
        "2": "inactive",
        "3": "malicious"
      }
    }
  }
]

You can also send data for multiple records of the same entities or multiple entities in the same POST call.
For example, if you want to send information about users and orders, leave the entity names out of your URI and put them in the data object.

In this example JSON object, we’ll upload data values for the id and user entity, so leave entity name out of the URL.
Again, we’ve populated some random example data in the fields key:

Headers

Copy
Content-Type: application/json
Authorization: Bearer [token]
POST: /server/rest/ingress/$customer_id$

Body

Copy
[
  {
    "entity": "user",
    "id": "AA1001",
    "fields": {
      "first_name": "John",
      "account_age": 18,
      "interests": ["snowboarding", "hiking", "fishing"],
      "quality_status": {
        "0": "active",
        "1": "good",
        "2": "inactive",
        "3": "malicious"
      }
    }
  },
  {
    "entity": "order",
    "id": "BB901",
    "fields": {
      "cart_items": 4,
      "cart_total": 14.10
    }
  },
  {
    "entity": "order",
    "id": "BB902",
    "fields": {
      "cart_items": 34,
      "cart_total": 13.90
    }
  }
  ...
]

Response
Please refer to the section below on getting decisions from Simility for more details.

Depending on how your pipeline is setup on the Simility side (Asynchronous or Synchronous) you will get specific response back

Asynchronous

Here you will get an immediately acknowledgement from Simility backend that we received the data and a HTTP 200OK message is send as RESPONSE to the POST REQUEST.
Subsequently once the transaction is processed and decision is made Simility will post the response on your webhook url listener asynchronous.

Copy
HTTP/1.1 200 OK

Synchronous

Simility will send a RESPONSE to your POST REQUEST with a decision message payload. Please refer to the section below on getting decisions from Simility for more details.

Copy
{
  "type": "decision",
  "entries": [
    {
      "id": "ABC12345",
      "entity": "order",
      "decisionLabels": ["Not Fraud", "Active User"],
      "score": -41,
      "leadLabels": {
        "LowZipcodeCategoryVariability": -22,
        "HighRegisteredIPFirstVoucherRatio": -19
      },
      "note": "Talked to customer on the phone, verified identity",
      "queue": "Suspicious Orders",
      "timestamp": "2015-12-01 01:10:50",
      "decisionBy": "analyst_one@prudentcompany.com"
    }
  ]
}

Feedback API

When sending data via DataAPI every event you send triggers a evaluation from simility and a decision is made In normal operations, your data would not have a fraud decision yet when you are uploading it to Simility,
but we do allow you to upload decisions in case you have fraud decisions already on historical data. e.g. you want to show Simility which cases you have already blacklisted or whitelisted.
Check out the decision labels in your Simility app to see the decisions available to you.
Then you can add "decision" as a parameter within "fields": {} with the corresponding value, e.g. "Blacklist":

Note that you can send additional fields as well along with the required “decision” field.

Headers

Copy
Content-Type: application/json
Authorization: Bearer [token]
POST: /server/rest/ingress/update/$customer_id$/$entity$
Copy
[
  {
    "id": "10000",
    "fields": {
      "decision": "Approved",
    },
    "entity": "user"
  }
 ]

Optionally you can send fields in additional to the required "decision" field which will again update the entity data. 
[
 {
    "id": "A10001",
    "entity": "user",
    "fields": {
      "decision": "Fraud",
      "fname": "John",
      "lname": "Doe",
      "email": "jd@simility.com",
      "ip": "127.0.0.2",
      "decisionBy" : "Autoscript"
    }
  }
]      

One Off File upload

You can visit Simility File Upload Tool from the UI to upload CSV files.

Getting Decisions

Simility’s Data APIs allows you to get data from Simility backend – Decision, Labels, Scores, Features et. al. The response comes as a JSON object.
Your analysts can create and edit these fraud decisions labels and workflow logic in Simility UI console Simility app in Tools > Label Viewer.

You can get data (decisions, labels, raw data) from Simility via –

  • Asyncronous : Use this to get response (decision) from Simility asyncronously on your webhook listener service.
  • Syncronous : Use this to get response (decision) from Simility syncronously as a RESPONSE object to your POST request when sending Data. Refer to the Upload API above.
  • OneOff Data pull API : Use this to do a one off data pull for data from Simility backend e.g. decision labels or raw feature data for particular transactionss etc.

Decisions Message Payload

The is the standard simility message payload that is send from Simility backend for both Async, Sync and OneOff mode.

Copy
{
  "type": "decision",
  "entries": [
    {
      "id": "ABC12345",
      "entity": "order",
      "decisionLabels": ["Not Fraud", "Active User"],
      "score": -41,
      "leadLabels": {
        "LowZipcodeCategoryVariability": -22,
        "HighRegisteredIPFirstVoucherRatio": -19
      },
      "note": "Talked to customer on the phone, verified identity",
      "queue": "Suspicious Orders",
      "timestamp": "2015-12-01 01:10:50",
      "decisionBy": "analyst_one@prudentcompany.com"
    }
  ]
}
  • decisionLabels (array): These are the fraud decisions applied to your cases, such as Fraud or Not Fraud. It is an array because multiple decisions can be applied to a single case.
  • score (number): The fraud score given to a case by Simility in a range from -100 to 100. The more negative the number, the riskier it is.
  • leadLabels (object): An array of key:value pairs in the format string:number. This is a list of manual rules and their associated fraud scores applied to a case. Manual rules indicate the reason a case may have been flagged as fraudulent.
  • note (string): Any notes taken on the case. Analysts may take notes on a case to provide information on it not otherwise available in any of the other fields.
  • queue (string): The queue from which a case came, such as Suspicious Orders.
  • timestamp (timestamp): The date and time the case was last edited in the format YYYY-MM-DD HH:MM:SS.
  • decisionBy (string): The email address of the analyst responsible for the case.

Async Decision

You need to implement a webhook/ REST JSON listener which can consume Simility Decision JSON Message.

Please share the URL endpoint with Simility when the listener is available along with any specific Auth mechanisms you want to implement (e.g. Bearer token).
Please discuss with Simility support team on the response times to expect and the timeouts to set for this mode.

Sync Decision

In this case the Simility Decision payload is sent as a RESPONSE to the upload POST request when data is received. This was the customer gets decisions on every event they send on the same request.
Please discuss with Simility support team on the response times to expect and the timeouts to set for this mode.

OneOff Decision Pull

You can also do a one off pull request for adhoc data from simility backend. e.g. One off analysis or any specific end of data activity that you might require. Parameters

  • customer_id (required, string): This is the same as your Client ID. See Requirements above.
  • entity (required, string): Whatever entity you are analyzing, e.g. users or orders. Check your Simility app and click on Tools > Entities & Fields to see your list of available entities or create a new one.
  • type (required, string): You must include the key-value pair "type": "decision", since you are pulling decisions.
  • id (required in single case, string): The unique ID for each case, also known as the EID (entity identity). You can find this value in your Simility app.
  • startDate (required in date range, date in yyyy-mm-dd or yyyy-mm-dd hh:mm:ss format): The starting date of the range for which you are retrieving cases.
  • endDate (required in date range, date in yyyy-mm-dd or yyyy-mm-dd hh:mm:ss format): The end date of the range for which you are retrieving cases.

Specific Id

Copy
GET: /server/rest/decision/$customer_id$/$entity_name$?id=ABC12345

Response:

Copy
{
  "type": "decision",
  "entries": [
    {
      "id": "ABC12345",
      "entity": "order",
      "decisionLabels": ["Not Fraud", "Active User"],
      "score": -41,
      "leadLabels": {
        "LowZipcodeCategoryVariability": -22,
        "HighRegisteredIPFirstVoucherRatio": -19
      },
      "note": "Talked to customer on the phone, verified identity",
      "queue": "Suspicious Orders",
      "timestamp": "2015-12-01 01:10:50",
      "decisionBy": "analyst_one@prudentcompany.com"
    }
  ]
}

Specific Date Range:

Copy
GET: /server/rest/decision/$customer_id$/$entity$?startDate=2012-10-01&endDate=2012-10-31

Response:

Copy
{
  "type": "decision",
  "entries": [
    {
      "id": "ABC12345",
      "entity": "order",
      "decisionLabels": ["Not Fraud", "Active User"],
      "score": -24,
      "leadLabels": {
        "BillingShippingAddressMatch": 7,
        "NotFirstOrder": 10,
        "HighRegisteredIPFirstVoucherRatio": -19,
        "LowZipcodeCategoryVariability": -22
      },
      "note": "Talked to customer on the phone, verified identity",
      "queue": "Suspicious Orders",
      "timestamp": "2012-10-01 01:10:50",
      "decisionBy": "analyst_one@prudentcompany.com"
    },
    {
      "id": "ABC12346",
      "entity": "order",
      "decisionLabels": ["Fraud", "Spammer"],
      "score": -58,
      "leadLabels": {
        "LowZipcodeCategoryVariability": -22,
        "HighKeyboardVelocity": -17,
        "HighRegisteredIPFirstVoucherRatio": -19
      },
      "note": "Block account permanently",
      "queue": "Suspicious Orders",
      "timestamp": "2012-10-01 01:12:08",
      "decisionBy": "analyst_two@prudentcompany.com"
    }
    ...
  ]
}

Pin It on Pinterest