Simility API Documentation

Introduction

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.

This API documentation is broken into three sections:

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

Introduction

Device Recon is a script that 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 riskiness of the device and the user.

JavaScript

Below are 4 types of JavaScript integration. Choose the one that best serves your needs and paste the corresponding JavaScript snippet in the <body> section of specific pages on your website.

JS1: Test

Use this setup to quickly test correct installation. It is not recommended in production.

<script>
  var similityContext = {
    "customer_id": "microcorpinc1"  //required; provided to you by Simility during signup
  };
</script>
<script type="application/javascript" src="https://cdn.simility.com/b.js"></script>

JS2: Standard

This is the standard production setup.

<script>
  var similityContext = {
    "customer_id": "microcorpinc1",  //required; provided to you by simility during signup
    "session_id": your.page.session.id.variable,  // recommended; unique per user session, typically persistent by your backend
    "user_id": your.page.user.id.variable,  // recommended; user_is variable from your session, typically persistent on your backend
  };
</script>
<script type="application/javascript" src="https://cdn.simility.com/b.js"></script>

session_id, user_id - We strongly recommend you set the user_id and/or session_id variables that are 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).

"session_id": your.page.session.id.variable

JS3: Custom Data

Use this setup when sending custom data in addition to device data, e.g. User or Transaction data. The data is collected when the web page loads.

<script>
 var similityContext = {
  "customer_id": "microcorpinc1",  // required; customer_id is provided by Simility during signup
  "session_id": your.page.session.id.variable,  // recommended; your user session id variable
  "user_id" : your.user.id.variable,  // optional; if your user is logged in this could be the user id or email id
  "simility_lite": true,  // optional; true by default

  "transaction_info": [{ // optional; additional data associated with this session
    "entity": "orders",  // required if sending transaction_info; entity type of this data
    "id": "order1001",   // required if sending transaction_info; unique id of transaction data
    "fields": {          // required if sending transaction_info; can contain any ad hoc payload data about this order (or user)
      "first_name": "John",
      "last_name": "Doe",
      "user_id": "user2321",
      "email": "johndoe@somedomain.pr",
      "order_categories": ["210", "334", "213"],
      "order_details": { "is_first_order": true, "num_retries": 2 },
      "cart_total": 203.44
     }
   }]
  };
</script>
<script type="application/javascript" src="https://cdn.simility.com/b.js"></script>

The transaction_info field contains any additional payload you choose to send. The only required elements here are entity and id. You can send any ad hoc JSON inside the fields sections. We are very flexible in what we can accept and recommend sending existing variables from your current data flows inside the fields section.
e.g. For a SignUp or Login page you can send user payload, with id = userid or email.
e.g. For a CheckOut page you can send OrderTransaction data with id = transaction id.
You can send any complex payload with multiple entities and nested data.

"entity": "orders" // entity type of this payload. e.g. user, orders, transactions, applications, profile, etc.
"id": "order1001",  // unique id of this data payload, e.g. orderid, userid, emailid, etc.
"fields": {         // actual payload for this additional data
  "first_name": "John",
  "last_name": "Doe" //...Any complex nested JSON could be sent here
}

simility_lite This is true by default. If set to false, we request some additional information from your customers, like geo-location, mouse movements, etc. Please discuss with our support team if you'd like to understand the full details of this setting.

"simility_lite": true

JS4: Event Trigger

Use this setup if you want to trigger device data collection on an event, like a button click, instead of on page load. This allows Simility to collect data your customers enter into fields on your web page.

In this example, the customer fills out fields on your web page with their first name, email, and a cart total, then clicks Checkout. The values in these fields are passed to the Simility script when the customer clicks the Checkout button. This is a popular setup when using a single page application.

<form>
  First Name: <input type="text" name="f-name">
  Email: <input type="text" name="email">
  Cart Total: <input type="number" name="grand-total">
</form>
<button id="checkout-button">Checkout</button>

Example JavaScript code to add just before the closing </body> tag on your webpage where you are collecting data:

<script>
  $('#checkout-button').click(function() {
    if (window.SimilityScript) {
      var d = document;
      var first_name = d.getElementsByName("f-name")[0].value;
      var cart_total = d.getElementsByName("grand-total")[0].value;
      var similityContext = {
        "customer_id": "microcorp1",
        "session_id": your.page.session.id.variable,
        "simility_lite": true,
        "transaction_info": [{
          "entity": "orders",
          "id": "AA1001",
          "fields": {
            "first_name": first_name,
            "cart_total": cart_total
            //... additional custom data fields
          }
        }]
      };
      var ss = new SimilityScript(similityContext);
      ss.execute();
    }
  });
</script>
<script type="application/javascript" src="https://cdn.simility.com/b.js" data-autoexecute="false"></script>

If you have already defined window.similityContext along with applicable parameters and don’t want to change parameters later, you do not need to pass similityContext:

  <script>
    $('#confirmOrder').click(function() {
      if (window.SimilityScript) {
          var ss = new SimilityScript();
          ss.execute();
      }
    });
  </script>

If you prefer to populate the fields and send to Simility automatically without an event such as a click function, remove the .click function in the previous example and change data-autoexecute to "true":

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

iOS

Simility’s iOS API allows you to collect data for fraud detection from your iOS application. Once this API is invoked, it will collect data and send 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.

Parameters

customerId (required, NSString): See Requirements above.
sessionId (required, NSString): See Requirements above.
userId (optional, NSString): The User ID of the current user. This can be whatever internal identification you use in your organization.
metadata (optional, NSDictionary): The <key, value> entries of NSDictionary must be of type <string, string>. It can be used to specify additional information like category, location, etc.
transactionSubCustomerId (optional, NSString): If you are a channel partner or payment gateway, you can set this field to distinguish among your own customers.
transactionInfo (optional, NSString): Use this to send transaction data. You can use a JSON object, which follows the same format as described in the Upload Data > REST API section below.
requestEndpoint (optional, NSString): If your prefer your request to be sent to your internal server first and forwarded later to Simility servers, you can specify your endpoint URL here.

You should link Foundation, UIKit, CoreTelephony, Security and CommonCrypto Frameworks/Lib if they are not already being used in your application. You also need to link AdSupport framework as well if your app is serving advertisements.

Declarations

+ (void) initBeacon:(NSString *) customerId sessionId:(NSString *) sessionId;

+ (void) initBeacon:(NSString *) customerId sessionId:(NSString *) sessionId userId:(NSString *) userId;

+ (void) initBeacon:(NSString *) customerId sessionId:(NSString *) sessionId userId:(NSString *) userId metadata:(NSDictionary *) metadata;

+ (void) initBeacon:(NSString *) customerId sessionId:(NSString *) sessionId userId:(NSString *) userId metadata:(NSDictionary *) metadata requestEndpoint:(NSString *) requestEndpoint;

+ (void)initBeacon:(NSString *) customerId sessionId:(NSString *) sessionId userId:(NSString *) userId metadata:(NSDictionary *) metadata transactionInfo:(NSString *)transactionInfo;

+ (void)initBeacon:(NSString *) customerId sessionId:(NSString *) sessionId userId:(NSString *) userId metadata:(NSDictionary *) metadata transactionInfo:(NSString *)transactionInfo requestEndpoint:(NSString *) requestEndpoint;

+ (void) initBeacon:(NSString *) customerId sessionId:(NSString *) sessionId userId:(NSString *) userId metadata:(NSDictionary *) metadata transactionSubCustomerId:(NSString *) transactionSubCustomerId transactionInfo:(NSString *) transactionInfo;

+ (void) initBeacon:(NSString *) customerId sessionId:(NSString *) sessionId userId:(NSString *) userId metadata:(NSDictionary *) metadata transactionSubCustomerId:(NSString *) transactionSubCustomerId transactionInfo:(NSString *) transactionInfo requestEndpoint:(NSString *) requestEndpoint;

Objective C Applications

Download and extract the zip file Or download this one if your application displays advertisements.
Create a new Xcode project and open the existing project
Drag the extracted files to the supporting files group
From the options dialog for adding files, opt to copy items if needed and add to targets
Import the SimilityBeacon header file and add the code for calling the Simility API (see below)
Build and run

Sample code for calling the Simility API:

  #import "ViewController.h"
  #import "SimilityBeacon.h"

  @interface ViewController ()

  @end

  @implementation ViewController

  - (void)viewDidLoad {
      [super viewDidLoad];
      // Do any additional setup after loading the view, typically from a nib.
      NSDictionary *metadata = @{@"orderId" : @"order_no_8765456"};
      NSString *customerId = @"customer_id_issued_by_simility";
      [SimilityBeacon initBeacon:customerId sessionId:@"cae1234567" userId:@"user1" metadata:metadata];
  }

  - (void)didReceiveMemoryWarning {
      [super didReceiveMemoryWarning];
      // Dispose of any resources that can be recreated.
  }

  @end

Swift Applications

Download and extract the zip file Or download this one if your application displays advertisements.
If your project does not have an existing Objectivce C bridging header file, create a dummy Objective C file and place it along with the extracted files
Create a new Xcode project and open the existing project
Drag the extracted files to the supporting files group
From the options dialog for adding files, opt to copy items if needed and add to targets
When prompted to create bridging header file, choose create.
Create a new group of supporting files and move the files to this group. You can delete the dummy Objective C file if you used it earlier.
Import the SimilityBeacon header file in Objective C bridging header file and add the code for calling the Simility API (see below)
Build and run

Sample code for calling the Simility API:

  import UIKit

  class ViewController: UIViewController {

      override func viewDidLoad() {
          super.viewDidLoad()
          // Do any additional setup after loading the view, typically from a nib.
          let customerId = "customer_id_issued_by_simility"
          let metadata = ["order_id":"order_no_865432"]
          SimilityBeacon.initBeacon(customerId, sessionId: "cae876543", userId: "user1", metadata: metadata)
      }

      override func didReceiveMemoryWarning() {
          super.didReceiveMemoryWarning()
          // Dispose of any resources that can be recreated.
      }

  }

Android

Simility’s Android API allows you to collect data for fraud detection from your Android application. Simility will provide a prebuilt file called beacon_sdk.jar. As soon as a client triggers Simility’s API, it will compute signals in the background without affecting any UI operations. Signals are collected on the basis of Manifest permissions in the host Application.

Parameters

context (required, context): Context of application/calling activity
customerId (required, string): See Requirements above.
sessionId (required, string): See Requirements above.
userId (optional, string): The User ID of the current user. This can be whatever internal identification you use in your organization.
metadata (optional, map): The <key, value> entries of map must be of type <string, string>. It can be used to specify additional information like category, location, etc.
transactionSubCustomerId (optional, string): If you are a channel partner or payment gateway, you can set this field to distinguish among your own customers.
transactionInfo (optional, string): Use this to send transaction data. You can use a JSON object, which follows the same format as described in the Upload Data > REST API section below.
requestEndpoint (optional, string): If your prefer your request to be sent to your internal server first and forwarded later to Simility servers, you can specify your endpoint URL here.

Declarations

public static void initBeacon(Context context, String customerId, String sessionId)

public static void initBeacon(Context context, String customerId, String sessionId, String userId)

public static void initBeacon(Context context, String customerId, String sessionId, String userId, Map<String, String> metadata)

public static void initBeacon(Context context, String customerId, String sessionId, String userId, Map<String, String> metadata, String requestEndpoint)

public static void initBeacon(Context context, String customerId, String sessionId, String userId, Map<String, String> metadata, String transactionSubCustomerId, String transactionInfo)

public static void initBeacon(Context context, String customerId, String sessionId, String userId, Map<String, String> metadata, String transactionSubCustomerId, String transactionInfo, String requestEndpoint)

Eclipse IDE

Download and extract the .jar file
Create a new Android Application project and open the existing project
Create a new folder called libs in your project's root folder, if it does not exist already
Copy the JAR files to this libs folder
Import com.simility.beacon.SimilityBeacon and call the Simility API with applicable parameters (see below)
Build and run

Android Studio IDE

Download and extract the .jar file
Create a new Android Application project and open the existing project
Go to Project Structure in the left pane and locate the libs folder under app
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
Import com.simility.beacon.SimilityBeacon and call the Simility API with applicable parameters (see below)
Build and run

Sample code for calling the Simility API:

package com.example.androidintegratiodemo;

import java.util.HashMap;
import java.util.Map;

import com.simility.beacon.SimilityBeacon;

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

public class MainActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        String customerId = "your_simility_customer_id";
        Map<String, String> metadata = new HashMap<String, String>();
        metadata.put("order_id", "order_no_8765542");
        SimilityBeacon.initBeacon(getApplicationContext(), customerId, "cae8765432", "user1", metadata);
    }
}

PhoneGap/Cordava

Follow steps for adding JAR file as shown above
To call the Simility API, 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

package com.simility.phonegaptestapp;

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

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 callSimilityBeacon() {
        String customerId = "your_simility_customer_id";
        Map<String, String> metadata = new HashMap<String, String>();
        metadata.put("order_id", "order_no_8765542");
        SimilityBeacon.initBeacon(super.getActivity(), customerId, "cae8765432", "user1", metadata);
  }
}

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)
In your webpage source code, add the code for Javascript to call SimilityBeacon

Sample code on HTML page to call Simility API

<!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.callSimilityBeacon();
    })();
    </script>
  </body>
</html>

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

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

[
  {
    "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

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

Body

[
  {
    "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.

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.

{
  "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

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

[
  {
    "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.

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.

{
  "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

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

Response:

{
  "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:

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

Response:

{
  "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"
    }
    ...
  ]
}

Simility API Documentation

Overview

Introduction

Device Recon

Introduction

JavaScript

JS1: Test

JS2: Standard

JS3: Custom Data

JS4: Event Trigger

iOS

Parameters

Declarations

Objective C Applications

Swift Applications

Android

Parameters

Declarations

Eclipse IDE

Android Studio IDE

PhoneGap/Cordava

Data Upload

Frontend Javascript API

Backend Data API

Url Parameters

JSON Payload Parameters

Feedback API

One Off File upload

Getting Decisions

Decisions Message Payload

Async Decision

Sync Decision

OneOff Decision Pull