Layer 1 copy

Sift Science API Overview

The Sift Science API allows you to send user data to be analyzed and, in return, get risk assessments about the users for which you sent data. On top of this, the platform has a programmable workflow service that enables you to build automated decisioning and manual review processes to power your application's business logic.


Sending Data to Sift Science

To receive risk scores for your users, you need to send your user data to the Sift platform. Generally speaking, the more data you send to the platform, the more accurate results we can provide. The three types of data to send are:

  • Website Activity - Add the Sift JavaScript snippet to your site so that you are sending device and behavioral data.
  • User activity within your app - Use the Events API to send us event data whenever users take key actions like create an account, place an order, or post content.
  • Feedback from manual review - If your team is manually reviewing accounts within your system, send us their review decisions via the Labels API. Use this whenever you determine an account is bad (e.g. produced a chargeback) or should be blocked (e.g. order is risky). If you don't have this in place yet, you can use Sift’s Decisions and Manual Review Queues to send us feedback. Feedback on bad accounts using one of the above methods is critical for a successful integration.

Getting Risk Scores for Your Users

Once you start sending data, we will compute risk scores for your users. Scores are an indication of how risky a user is for a given type of abuse pattern. You can use these scores as a means to block bad users, add friction to users you are unsure about (e.g. SMS verification), and let good users sail right through.

There are a few ways you can get scores back from Sift Science:

  • Get scores synchronously when sending event data - Whenever you send an event, you can ask for a score to be returned in response. Any data you send along with the event will be incorporated into our analysis in real time. The score you get back will be the most up to date score. Learn how to get scores while using the Events API.
  • Get scores without sending a new event data - For instances when you have no new event data but need a score, you can query us for the most current score for a user. Learn how to get scores for users using the Score API.

Building Workflows Using Sift

Once you are up and running, you can enhance your integration by using the Sift Workflows platform. There are two key components to automating with Sift:

  • Create a Sift Workflow - You can build your application logic into Sift with our Workflow product. Workflows let you set up criteria that get evaluated whenever specified events occur. For example, you can setup a Workflow that evaluates whenever you create an account. You can specify criteria (e.g. country = Japan, score > 80, number of linked devices < 3, etc.) that when met Sift will auto-block, auto-accept, or send to a Sift Review Queue for manual review. The configuration is all up to you. Learn more about setting up Sift Workflows.
  • Use Sift Decision webhooks - Sift Decisions are the means by which you tell us what business action you are taking on a user (e.g. block user, flag to watch, approve user, etc.). They're an important way to provide feedback to Sift to improve the accuracy of scores. Sift Decisions are applied manually when your team clicks a Decision button in the Console or automatically when you setup a Sift Workflow. Whenever a Decision is made, we send a webhook to your system telling you what happened. Learn how to use Decision webhooks to connect with your system.

For more information on building any of the above, check out our list of vertical specify tutorials. They'll help customize your Sift integration to fit your unique business needs. Client libraries are also available.

Installing the JavaScript Snippet

The JavaScript snippet tracks user interaction with your website and collects device information.

Important: only include the JavaScript snippet when the page is accessed externally by a user of your website. If your internal tools offer a way to simulate logging into a user's account, for example to investigate a user or place a phone order, it is important that you do not include the JavaScript snippet in those cases so that we do not link your device and IP address with the user.

Install the JavaScript snippet

  1. Insert this JavaScript snippet onto your webpage, just after the opening <body> tag:
    <script type="text/javascript">
      var _user_id = 'al_capone'; // Set to the user's ID, username, or email address, or '' if not yet known.
      var _session_id = 'unique_session_id'; // Set to a unique session ID for the visitor's current browsing session.
    
      var _sift = window._sift = window._sift || [];
      _sift.push(['_setAccount', 'INSERT_JS_SNIPPET_KEY_HERE']);
      _sift.push(['_setUserId', _user_id]);
      _sift.push(['_setSessionId', _session_id]);
      _sift.push(['_trackPageview']);
    
     (function() {
       function ls() {
         var e = document.createElement('script');
         e.src = 'https://cdn.siftscience.com/s.js';
         document.body.appendChild(e);
       }
       if (window.attachEvent) {
         window.attachEvent('onload', ls);
       } else {
         window.addEventListener('load', ls, false);
       }
     })();
    </script>
    
  2. Change the parameter to _setAccount above to your JavaScript Snippet key.
  3. Set _session_id to a string that identifies a unique session ID for the visitor's current browsing session.
  4. Set _user_id to a string that identifies the user, e.g. a user ID, username, or email address. (Leave user_id blank if you do not yet know the ID of the user.). This user ID should be consistent with $user_id in your Events API requests.
  5. If you have a single-page app, see our help article.

Notes
  • To minimize download latency, we've hosted these files on Amazon Cloudfront. To minimize page load delay, this code executes as asynchronously as possible, yielding several times.
  • This code will set a long-lived cookie named __ssid on your domain, also known as a first-party cookie. We only use this to identify unique visitors. You can optionally set the domain for the cookie via another JavaScript parameter _setCookieDomain, _sift.push(['_setCookieDomain','subdomain.foo.com']);

Events API Reference

Use the Events API to record the core actions users take in your application. The more detail we capture about user behaviors, the better we can distinguish between good and bad users. We have two types of events:

  • Reserved events are events are sent in a standard format, allowing us to do lots of advanced analysis on the values sent. When possible, model the actions users take on your site or app with reserved events.
  • Custom events are events you create to capture actions unique to your application. If there are key actions most of your users take that are not captured by our reserved events, send these as custom event.

Each event has fields that provide details.

  • Each event accepts required, reserved, and custom fields.
  • Some fields are of type object or object list.

Events API Endpoint

Sift Science's Events API accepts event data as a JSON request body via a HTTP POST request at this endpoint:

https://api.siftscience.com/v204/events

Every event must contain your $api_key, the event $type, and a $user_id (if this is not available, you can alternatively provide a $session_id). Make sure to look at our error codes.

$create_order

Use $create_order to record when a user submits an order for products or services they intend to purchase. This API event should contain the products/services ordered, the payment instrument(s), and user identification data.

// Sample $create_order event
{
  // Required Fields
  "$type"             : "$create_order",
  "$api_key"          : "your_api_key_here",
  "$user_id"          : "billy_jones_301",

  // Supported Fields
  "$session_id"       : "gigtleqddo84l8cm15qe4il",
  "$order_id"         : "ORDER-28168441",
  "$user_email"       : "bill@gmail.com",
  "$amount"           : 115940000, // $115.94
  "$currency_code"    : "USD",
  "$billing_address"  : {
      "$name"         : "Bill Jones",
      "$phone"        : "1-415-555-6041",
      "$address_1"    : "2100 Main Street",
      "$address_2"    : "Apt 3B",
      "$city"         : "New London",
      "$region"       : "New Hampshire",
      "$country"      : "US",
      "$zipcode"      : "03257"
  },
  "$payment_methods"  : [
      {
          "$payment_type"    : "$credit_card",
          "$payment_gateway" : "$braintree",
          "$card_bin"        : "542486",
          "$card_last4"      : "4444"
      }
  ],
  "$shipping_address"  : {
      "$name"          : "Bill Jones",
      "$phone"         : "1-415-555-6041",
      "$address_1"     : "2100 Main Street",
      "$address_2"     : "Apt 3B",
      "$city"          : "New London",
      "$region"        : "New Hampshire",
      "$country"       : "US",
      "$zipcode"       : "03257"
  },
  "$expedited_shipping" : true,
  "$shipping_method"    : "$physical",
  "$items"             : [
    {
      "$item_id"        : "12344321",
      "$product_title"  : "Microwavable Kettle Corn: Original Flavor",
      "$price"          : 4990000, // $4.99
      "$upc"            : "097564307560",
      "$sku"            : "03586005",
      "$brand"          : "Peters Kettle Corn",
      "$manufacturer"   : "Peters Kettle Corn",
      "$category"       : "Food and Grocery",
      "$tags"           : ["Popcorn", "Snacks", "On Sale"],
      "$quantity"       : 4
    },
    {
      "$item_id"        : "B004834GQO",
      "$product_title"  : "The Slanket Blanket-Texas Tea",
      "$price"          : 39990000, // $39.99
      "$upc"            : "67862114510011",
      "$sku"            : "004834GQ",
      "$brand"          : "Slanket",
      "$manufacturer"   : "Slanket",
      "$category"       : "Blankets & Throws",
      "$tags"           : ["Awesome", "Wintertime specials"],
      "$color"          : "Texas Tea",
      "$quantity"       : 2
    }
  ],

  // For marketplaces, use $seller_user_id to identify the seller
  "$seller_user_id"     : "slinkys_emporium",

  "$promotions"         : [
    {
      "$promotion_id" : "FirstTimeBuyer",
      "$status"       : "$success",
      "$description"  : "$5 off",
      "$discount"     : {
        "$amount"                   : 5000000,  // $5.00
        "$currency_code"            : "USD",
        "$minimum_purchase_amount"  : 25000000  // $25.00
      }
    }
  ],

  // Sample Custom Fields
  "digital_wallet"      : "apple_pay", // "google_wallet", etc. 
  "coupon_code"         : "dollarMadness",
  "shipping_choice"     : "FedEx Ground Courier",
  "is_first_time_buyer" : false
}
import sift

client = sift.Client("your_api_key_here")

# Sample $create_order event
properties = {
  # Required Fields
  "$user_id"          : "billy_jones_301",
  # Supported Fields
  "$session_id"       : "gigtleqddo84l8cm15qe4il",
  "$order_id"         : "ORDER-28168441",
  "$user_email"       : "bill@gmail.com",
  "$amount"           : 115940000, # $115.94
  "$currency_code"    : "USD",
  "$billing_address"  : {
      "$name"         : "Bill Jones",
      "$phone"        : "1-415-555-6041",
      "$address_1"    : "2100 Main Street",
      "$address_2"    : "Apt 3B",
      "$city"         : "New London",
      "$region"       : "New Hampshire",
      "$country"      : "US",
      "$zipcode"      : "03257"
  },
  "$payment_methods"  : [
      {
          "$payment_type"    : "$credit_card",
          "$payment_gateway" : "$braintree",
          "$card_bin"        : "542486",
          "$card_last4"      : "4444"
      }
  ],
  "$shipping_address"  : {
      "$name"          : "Bill Jones",
      "$phone"         : "1-415-555-6041",
      "$address_1"     : "2100 Main Street",
      "$address_2"     : "Apt 3B",
      "$city"          : "New London",
      "$region"        : "New Hampshire",
      "$country"       : "US",
      "$zipcode"       : "03257"
  },
  "$expedited_shipping" : True,
  "$shipping_method"    : "$physical",
  "$items"             : [
    {
      "$item_id"        : "12344321",
      "$product_title"  : "Microwavable Kettle Corn: Original Flavor",
      "$price"          : 4990000, # $4.99
      "$upc"            : "097564307560",
      "$sku"            : "03586005",
      "$brand"          : "Peters Kettle Corn",
      "$manufacturer"   : "Peters Kettle Corn",
      "$category"       : "Food and Grocery",
      "$tags"           : ["Popcorn", "Snacks", "On Sale"],
      "$quantity"       : 4
    },
    {
      "$item_id"        : "B004834GQO",
      "$product_title"  : "The Slanket Blanket-Texas Tea",
      "$price"          : 39990000, # $39.99
      "$upc"            : "67862114510011",
      "$sku"            : "004834GQ",
      "$brand"          : "Slanket",
      "$manufacturer"   : "Slanket",
      "$category"       : "Blankets & Throws",
      "$tags"           : ["Awesome", "Wintertime specials"],
      "$color"          : "Texas Tea",
      "$quantity"       : 2
    }
  ],
  # For marketplaces, use $seller_user_id to identify the seller
  "$seller_user_id"     : "slinkys_emporium",

  "$promotions"         : [
    {
      "$promotion_id" : "FirstTimeBuyer",
      "$status"       : "$success",
      "$description"  : "$5 off",
      "$discount"     : {
        "$amount"                   : 5000000,  # $5.00
        "$currency_code"            : "USD",
        "$minimum_purchase_amount"  : 25000000  # $25.00
      }
    }
  ],

  # Sample Custom Fields
  "digital_wallet"      : "apple_pay", # "google_wallet", etc.
  "coupon_code"         : "dollarMadness",
  "shipping_choice"     : "FedEx Ground Courier",
  "is_first_time_buyer" : False
}

response = client.track("$create_order", properties)
require "sift"

client = Sift::Client.new(:api_key => "your_api_key_here")

# Sample $create_order event
properties = {
  # Required Fields
  "$user_id"          => "billy_jones_301",
  # Supported Fields
  "$session_id"       => "gigtleqddo84l8cm15qe4il",
  "$order_id"         => "ORDER-28168441",
  "$user_email"       => "bill@gmail.com",
  "$amount"           => 115940000, # $115.94
  "$currency_code"    => "USD",
  "$billing_address"  => {
    "$name"         => "Bill Jones",
    "$phone"        => "1-415-555-6041",
    "$address_1"    => "2100 Main Street",
    "$address_2"    => "Apt 3B",
    "$city"         => "New London",
    "$region"       => "New Hampshire",
    "$country"      => "US",
    "$zipcode"      => "03257"
  },
  "$payment_methods"  => [
    {
      "$payment_type"    => "$credit_card",
      "$payment_gateway" => "$braintree",
      "$card_bin"        => "542486",
      "$card_last4"      => "4444"
    }
  ],
  "$shipping_address"  => {
    "$name"          => "Bill Jones",
    "$phone"         => "1-415-555-6041",
    "$address_1"     => "2100 Main Street",
    "$address_2"     => "Apt 3B",
    "$city"          => "New London",
    "$region"        => "New Hampshire",
    "$country"       => "US",
    "$zipcode"       => "03257"
  },
  "$expedited_shipping" => true,
  "$shipping_method"    => "$physical",
  "$items"             => [
    {
      "$item_id"        => "12344321",
      "$product_title"  => "Microwavable Kettle Corn: Original Flavor",
      "$price"          => 4990000, # $4.99
      "$upc"            => "097564307560",
      "$sku"            => "03586005",
      "$brand"          => "Peters Kettle Corn",
      "$manufacturer"   => "Peters Kettle Corn",
      "$category"       => "Food and Grocery",
      "$tags"           => ["Popcorn", "Snacks", "On Sale"],
      "$quantity"       => 4
    },
    {
      "$item_id"        => "B004834GQO",
      "$product_title"  => "The Slanket Blanket-Texas Tea",
      "$price"          => 39990000, # $39.99
      "$upc"            => "67862114510011",
      "$sku"            => "004834GQ",
      "$brand"          => "Slanket",
      "$manufacturer"   => "Slanket",
      "$category"       => "Blankets & Throws",
      "$tags"           => ["Awesome", "Wintertime specials"],
      "$color"          => "Texas Tea",
      "$quantity"       => 2
    }
  ],
  # For marketplaces, use $seller_user_id to identify the seller
  "$seller_user_id"     => "slinkys_emporium",

  "$promotions"         => [
    {
      "$promotion_id" => "FirstTimeBuyer",
      "$status"       => "$success",
      "$description"  => "$5 off",
      "$discount"     => {
        "$amount"                   => 5000000,  # $5.00
        "$currency_code"            => "USD",
        "$minimum_purchase_amount"  => 25000000  # $25.00
      }
    }
  ],

  # Sample Custom Fields
  "digital_wallet"      => "apple_pay", # "google_wallet", etc.
  "coupon_code"         => "dollarMadness",
  "shipping_choice"     => "FedEx Ground Courier",
  "is_first_time_buyer" => false
}

response = client.track("$create_order", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'your_api_key_here'));

// Sample $create_order event
$properties = array(
  // Required Fields
  '$user_id'          => 'billy_jones_301',
  // Supported Fields
  '$session_id'       => 'gigtleqddo84l8cm15qe4il',
  '$order_id'         => 'ORDER-28168441',
  '$user_email'       => 'bill@gmail.com',
  '$amount'           => 115940000, // $115.94
  '$currency_code'    => 'USD',
  '$billing_address'  => array(
    '$name'         => 'Bill Jones',
    '$phone'        => '1-415-555-6041',
    '$address_1'    => '2100 Main Street',
    '$address_2'    => 'Apt 3B',
    '$city'         => 'New London',
    '$region'       => 'New Hampshire',
    '$country'      => 'US',
    '$zipcode'      => '03257'
  ),
  '$payment_methods'  =>array( 
    array(
      '$payment_type'    => '$credit_card',
      '$payment_gateway' => '$braintree',
      '$card_bin'        => '542486',
      '$card_last4'      => '4444'
    )
  ),
  '$shipping_address'  => array(
    '$name'          => 'Bill Jones',
    '$phone'         => '1-415-555-6041',
    '$address_1'     => '2100 Main Street',
    '$address_2'     => 'Apt 3B',
    '$city'          => 'New London',
    '$region'        => 'New Hampshire',
    '$country'       => 'US',
    '$zipcode'       => '03257'
  ),
  '$expedited_shipping' => True,
  '$shipping_method'    => '$physical',
  '$items'             => array(
    // A list of items
    array(
      '$item_id'        => '12344321',
      '$product_title'  => 'Microwavable Kettle Corn: Original Flavor',
      '$price'          => 4990000, // $4.99
      '$upc'            => '097564307560',
      '$sku'            => '03586005',
      '$brand'          => 'Peters Kettle Corn',
      '$manufacturer'   => 'Peters Kettle Corn',
      '$category'       => 'Food and Grocery',
      '$tags'           => array('Popcorn', 'Snacks', 'On Sale'),
      '$quantity'       => 4
    ),
    array(
      '$item_id'        => 'B004834GQO',
      '$product_title'  => 'The Slanket Blanket-Texas Tea',
      '$price'          => 39990000, // $39.99
      '$upc'            => '67862114510011',
      '$sku'            => '004834GQ',
      '$brand'          => 'Slanket',
      '$manufacturer'   => 'Slanket',
      '$category'       => 'Blankets & Throws',
      '$tags'           => array('Awesome', 'Wintertime specials'),
      '$color'          => 'Texas Tea',
      '$quantity'       => 2
    )
  ),
  // For marketplaces, use $seller_user_id to identify the seller
  '$seller_user_id'     => 'slinkys_emporium',

  '$promotions'         => array(
    array(
      '$promotion_id' => 'FirstTimeBuyer',
      '$status'       => '$success',
      '$description'  => '$5 off',
      '$discount'     => array(
        '$amount'                   => 5000000,  // $5.00
        '$currency_code'            => 'USD',
        '$minimum_purchase_amount'  => 25000000  // $25.00
      )
    )
  ),

  // Sample Custom Fields
  'digital_wallet'      => 'apple_pay' // 'google_wallet', etc.
  'coupon_code'         => 'dollarMadness',
  'shipping_choice'     => 'FedEx Ground Courier',
  'is_first_time_buyer' => False
);

$response = $client->track('$create_order', $properties);

  • $type
    required · String

    "$create_order"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

    The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid $user_id values here.

  • $session_id
    String

    The user's current session ID, used to tie a user's action before and after login or account creation. Required if no $user_id values is provided.

  • $order_id
    String

    The ID for tracking this order in your system.

  • $user_email
    String

    Email of the user creating this order. Note: If the user's email is also their account ID in your system, set both the $user_id and $user_email fields to their email address.

  • $amount
    Integer

    Total transaction amount in micros in the base unit of the $currency_code. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.

  • $currency_code
    String

    ISO-4217 currency code for the amount. If your site uses alternative currencies, specify them here.

  • $billing_address
    Address

    The billing address as entered by the user. Represented as an address object.

  • $payment_methods
    Array of Payment Methods

    The payment information associated with this order. Represented as an array of nested payment_method objects containing payment type, payment gateway, credit card bin, etc.

    Note: As opposed to $transaction, $create_order takes an array of $payment_method objects, so you can record orders that are paid for using multiple payments. See Payment Method under Complex Field Types for more details.

  • $shipping_address
    Address

    The shipping address as entered by the user. Represented as a nested address object.

  • $expedited_shipping
    Boolean

    Whether the user requested priority/expedited shipping on their order.

  • $items
    Array of Items

    The list of items ordered. Represented as a JSON array of $item objects.

  • $seller_user_id
    String

    For marketplace businesses, this is the seller's user ID, typically a database primary key.Follow our guidelines for $user_id values.

  • $promotions
    Array of Promotions

    The list of promotions that apply to this order. You can add one or more promotions when creating or updating an order. Represented as a JSON array of promotion objects. You can also separately add promotions to the account via the $add_promotion event.

  • $shipping_method
    String

    Indicates the method of delivery to the user.

    Allowed Values
    • "$electronic""$physical"

$update_order

Use $update_order to record when a user updates an order for products or services they intend to purchase.

  • This event contains the same fields as $create_order.
  • The existing order will be completely replaced by the values sent in $update_order. Be sure to specify all values for the order, not just those that changed.
  • If no matching $order_id found, a new order will be created.
// Sample $update_order event
{
  // Required Fields
  "$type"             : "$update_order",
  "$api_key"          : "your_api_key_here",
  "$user_id"          : "billy_jones_301",

  // Supported Fields
  "$session_id"       : "gigtleqddo84l8cm15qe4il",
  "$order_id"         : "ORDER-28168441",
  "$user_email"       : "bill@gmail.com",
  "$amount"           : 115940000, // $115.94
  "$currency_code"    : "USD",
  "$billing_address"  : {
      "$name"         : "Bill Jones",
      "$phone"        : "1-415-555-6041",
      "$address_1"    : "2100 Main Street",
      "$address_2"    : "Apt 3B",
      "$city"         : "New London",
      "$region"       : "New Hampshire",
      "$country"      : "US",
      "$zipcode"      : "03257"
  },
  "$payment_methods"  : [
      {
          "$payment_type"    : "$credit_card",
          "$payment_gateway" : "$braintree",
          "$card_bin"        : "542486",
          "$card_last4"      : "4444"
      }
  ],
  "$shipping_address"  : {
      "$name"          : "Bill Jones",
      "$phone"         : "1-415-555-6041",
      "$address_1"     : "2100 Main Street",
      "$address_2"     : "Apt 3B",
      "$city"          : "New London",
      "$region"        : "New Hampshire",
      "$country"       : "US",
      "$zipcode"       : "03257"
  },
  "$expedited_shipping" : true,
  "$shipping_method"    : "$physical",
  "$items"             : [
    {
      "$item_id"        : "12344321",
      "$product_title"  : "Microwavable Kettle Corn: Original Flavor",
      "$price"          : 4990000, // $4.99
      "$upc"            : "097564307560",
      "$sku"            : "03586005",
      "$brand"          : "Peters Kettle Corn",
      "$manufacturer"   : "Peters Kettle Corn",
      "$category"       : "Food and Grocery",
      "$tags"           : ["Popcorn", "Snacks", "On Sale"],
      "$quantity"       : 4
    },
    {
      "$item_id"        : "B004834GQO",
      "$product_title"  : "The Slanket Blanket-Texas Tea",
      "$price"          : 39990000, // $39.99
      "$upc"            : "67862114510011",
      "$sku"            : "004834GQ",
      "$brand"          : "Slanket",
      "$manufacturer"   : "Slanket",
      "$category"       : "Blankets & Throws",
      "$tags"           : ["Awesome", "Wintertime specials"],
      "$color"          : "Texas Tea",
      "$quantity"       : 2
    }
  ],

  // For marketplaces, use $seller_user_id to identify the seller
  "$seller_user_id"     : "slinkys_emporium",

  "$promotions"         : [
    {
      "$promotion_id" : "FirstTimeBuyer",
      "$status"       : "$success",
      "$description"  : "$5 off",
      "$discount"     : {
        "$amount"                   : 5000000,  // $5.00
        "$currency_code"            : "USD",
        "$minimum_purchase_amount"  : 25000000  // $25.00
      }
    }
  ],

  // Sample Custom Fields
  "digital_wallet"      : "apple_pay", // "google_wallet", etc. 
  "coupon_code"         : "dollarMadness",
  "shipping_choice"     : "FedEx Ground Courier",
  "is_first_time_buyer" : false
}
import sift

client = sift.Client("your_api_key_here")

# Sample $update_order event
properties = {
  # Required Fields
  "$user_id"          : "billy_jones_301",
  # Supported Fields
  "$session_id"       : "gigtleqddo84l8cm15qe4il",
  "$order_id"         : "ORDER-28168441",
  "$user_email"       : "bill@gmail.com",
  "$amount"           : 115940000, # $115.94
  "$currency_code"    : "USD",
  "$billing_address"  : {
      "$name"         : "Bill Jones",
      "$phone"        : "1-415-555-6041",
      "$address_1"    : "2100 Main Street",
      "$address_2"    : "Apt 3B",
      "$city"         : "New London",
      "$region"       : "New Hampshire",
      "$country"      : "US",
      "$zipcode"      : "03257"
  },
  "$payment_methods"  : [
      {
          "$payment_type"    : "$credit_card",
          "$payment_gateway" : "$braintree",
          "$card_bin"        : "542486",
          "$card_last4"      : "4444"
      }
  ],
  "$shipping_address"  : {
      "$name"          : "Bill Jones",
      "$phone"         : "1-415-555-6041",
      "$address_1"     : "2100 Main Street",
      "$address_2"     : "Apt 3B",
      "$city"          : "New London",
      "$region"        : "New Hampshire",
      "$country"       : "US",
      "$zipcode"       : "03257"
  },
  "$expedited_shipping" : True,
  "$shipping_method"    : "$physical",
  "$items"             : [
    {
      "$item_id"        : "12344321",
      "$product_title"  : "Microwavable Kettle Corn: Original Flavor",
      "$price"          : 4990000, # $4.99
      "$upc"            : "097564307560",
      "$sku"            : "03586005",
      "$brand"          : "Peters Kettle Corn",
      "$manufacturer"   : "Peters Kettle Corn",
      "$category"       : "Food and Grocery",
      "$tags"           : ["Popcorn", "Snacks", "On Sale"],
      "$quantity"       : 4
    },
    {
      "$item_id"        : "B004834GQO",
      "$product_title"  : "The Slanket Blanket-Texas Tea",
      "$price"          : 39990000, # $39.99
      "$upc"            : "67862114510011",
      "$sku"            : "004834GQ",
      "$brand"          : "Slanket",
      "$manufacturer"   : "Slanket",
      "$category"       : "Blankets & Throws",
      "$tags"           : ["Awesome", "Wintertime specials"],
      "$color"          : "Texas Tea",
      "$quantity"       : 2
    }
  ],
  # For marketplaces, use $seller_user_id to identify the seller
  "$seller_user_id"     : "slinkys_emporium",

  "$promotions"         : [
    {
      "$promotion_id" : "FirstTimeBuyer",
      "$status"       : "$success",
      "$description"  : "$5 off",
      "$discount"     : {
        "$amount"                   : 5000000,  # $5.00
        "$currency_code"            : "USD",
        "$minimum_purchase_amount"  : 25000000  # $25.00
      }
    }
  ],

  # Sample Custom Fields
  "digital_wallet"      : "apple_pay", # "google_wallet", etc.
  "coupon_code"         : "dollarMadness",
  "shipping_choice"     : "FedEx Ground Courier",
  "is_first_time_buyer" : False
}

response = client.track("$update_order", properties)
require "sift"

client = Sift::Client.new(:api_key => "your_api_key_here")

# Sample $update_order event
properties = {
  # Required Fields
  "$user_id"          => "billy_jones_301",
  # Supported Fields
  "$session_id"       => "gigtleqddo84l8cm15qe4il",
  "$order_id"         => "ORDER-28168441",
  "$user_email"       => "bill@gmail.com",
  "$amount"           => 115940000, # $115.94
  "$currency_code"    => "USD",
  "$billing_address"  => {
    "$name"         => "Bill Jones",
    "$phone"        => "1-415-555-6041",
    "$address_1"    => "2100 Main Street",
    "$address_2"    => "Apt 3B",
    "$city"         => "New London",
    "$region"       => "New Hampshire",
    "$country"      => "US",
    "$zipcode"      => "03257"
  },
  "$payment_methods"  => [
    {
      "$payment_type"    => "$credit_card",
      "$payment_gateway" => "$braintree",
      "$card_bin"        => "542486",
      "$card_last4"      => "4444"
    }
  ],
  "$shipping_address"  => {
    "$name"          => "Bill Jones",
    "$phone"         => "1-415-555-6041",
    "$address_1"     => "2100 Main Street",
    "$address_2"     => "Apt 3B",
    "$city"          => "New London",
    "$region"        => "New Hampshire",
    "$country"       => "US",
    "$zipcode"       => "03257"
  },
  "$expedited_shipping" => true,
  "$shipping_method"    => "$physical",
  "$items"             => [
    {
      "$item_id"        => "12344321",
      "$product_title"  => "Microwavable Kettle Corn: Original Flavor",
      "$price"          => 4990000, # $4.99
      "$upc"            => "097564307560",
      "$sku"            => "03586005",
      "$brand"          => "Peters Kettle Corn",
      "$manufacturer"   => "Peters Kettle Corn",
      "$category"       => "Food and Grocery",
      "$tags"           => ["Popcorn", "Snacks", "On Sale"],
      "$quantity"       => 4
    },
    {
      "$item_id"        => "B004834GQO",
      "$product_title"  => "The Slanket Blanket-Texas Tea",
      "$price"          => 39990000, # $39.99
      "$upc"            => "67862114510011",
      "$sku"            => "004834GQ",
      "$brand"          => "Slanket",
      "$manufacturer"   => "Slanket",
      "$category"       => "Blankets & Throws",
      "$tags"           => ["Awesome", "Wintertime specials"],
      "$color"          => "Texas Tea",
      "$quantity"       => 2
    }
  ],
  # For marketplaces, use $seller_user_id to identify the seller
  "$seller_user_id"     => "slinkys_emporium",

  "$promotions"         => [
    {
      "$promotion_id" => "FirstTimeBuyer",
      "$status"       => "$success",
      "$description"  => "$5 off",
      "$discount"     => {
        "$amount"                   => 5000000,  # $5.00
        "$currency_code"            => "USD",
        "$minimum_purchase_amount"  => 25000000  # $25.00
      }
    }
  ],

  # Sample Custom Fields
  "digital_wallet"      => "apple_pay", # "google_wallet", etc.
  "coupon_code"         => "dollarMadness",
  "shipping_choice"     => "FedEx Ground Courier",
  "is_first_time_buyer" => false
}

response = client.track("$update_order", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'your_api_key_here'));

// Sample $update_order event
$properties = array(
  // Required Fields
  '$user_id'          => 'billy_jones_301',
  // Supported Fields
  '$session_id'       => 'gigtleqddo84l8cm15qe4il',
  '$order_id'         => 'ORDER-28168441',
  '$user_email'       => 'bill@gmail.com',
  '$amount'           => 115940000, // $115.94
  '$currency_code'    => 'USD',
  '$billing_address'  => array(
    '$name'         => 'Bill Jones',
    '$phone'        => '1-415-555-6041',
    '$address_1'    => '2100 Main Street',
    '$address_2'    => 'Apt 3B',
    '$city'         => 'New London',
    '$region'       => 'New Hampshire',
    '$country'      => 'US',
    '$zipcode'      => '03257'
  ),
  '$payment_methods'  =>array( 
    array(
      '$payment_type'    => '$credit_card',
      '$payment_gateway' => '$braintree',
      '$card_bin'        => '542486',
      '$card_last4'      => '4444'
    )
  ),
  '$shipping_address'  => array(
    '$name'          => 'Bill Jones',
    '$phone'         => '1-415-555-6041',
    '$address_1'     => '2100 Main Street',
    '$address_2'     => 'Apt 3B',
    '$city'          => 'New London',
    '$region'        => 'New Hampshire',
    '$country'       => 'US',
    '$zipcode'       => '03257'
  ),
  '$expedited_shipping' => True,
  '$shipping_method'    => '$physical',
  '$items'             => array(
    // A list of items
    array(
      '$item_id'        => '12344321',
      '$product_title'  => 'Microwavable Kettle Corn: Original Flavor',
      '$price'          => 4990000, // $4.99
      '$upc'            => '097564307560',
      '$sku'            => '03586005',
      '$brand'          => 'Peters Kettle Corn',
      '$manufacturer'   => 'Peters Kettle Corn',
      '$category'       => 'Food and Grocery',
      '$tags'           => array('Popcorn', 'Snacks', 'On Sale'),
      '$quantity'       => 4
    ),
    array(
      '$item_id'        => 'B004834GQO',
      '$product_title'  => 'The Slanket Blanket-Texas Tea',
      '$price'          => 39990000, // $39.99
      '$upc'            => '67862114510011',
      '$sku'            => '004834GQ',
      '$brand'          => 'Slanket',
      '$manufacturer'   => 'Slanket',
      '$category'       => 'Blankets & Throws',
      '$tags'           => array('Awesome', 'Wintertime specials'),
      '$color'          => 'Texas Tea',
      '$quantity'       => 2
    )
  ),
  // For marketplaces, use $seller_user_id to identify the seller
  '$seller_user_id'     => 'slinkys_emporium',

  '$promotions'         => array(
    array(
      '$promotion_id' => 'FirstTimeBuyer',
      '$status'       => '$success',
      '$description'  => '$5 off',
      '$discount'     => array(
        '$amount'                   => 5000000,  // $5.00
        '$currency_code'            => 'USD',
        '$minimum_purchase_amount'  => 25000000  // $25.00
      )
    )
  ),

  // Sample Custom Fields
  'digital_wallet'      => 'apple_pay' // 'google_wallet', etc.
  'coupon_code'         => 'dollarMadness',
  'shipping_choice'     => 'FedEx Ground Courier',
  'is_first_time_buyer' => False
);

$response = $client->track('$update_order', $properties);

  • $type
    required · String

    "$update_order"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

    The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid $user_id values here.

  • $session_id
    String

    The user's current session ID, used to tie a user's action before and after login or account creation. Required if no $user_id values is provided.

  • $order_id
    String

    The ID for tracking this order in your system.

  • $user_email
    String

    Email of the user creating this order. Note: If the user's email is also their account ID in your system, set both the $user_id and $user_email fields to their email address.

  • $amount
    Integer

    Total transaction amount in micros in the base unit of the $currency_code. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros and 1 for 1 micoBitcoin.

  • $currency_code
    String

    ISO-4217 currency code for the amount. If your site uses alternative currencies, specify them here.

  • $billing_address
    Address

    The billing address as entered by the user. Represented as a nested address object.

  • $payment_methods
    Array of Payment Methods

    The payment information associated with this order. Represented as an array of nested payment_method objects. As opposed to $transaction, $create_order takes an array of $payment_method objects, so you can record orders that are paid for using multiple payments.

  • $shipping_address
    Address

    The shipping address as entered by the user. Represented as a nested address object.

  • $expedited_shipping
    Boolean

    Whether the user requested priority/expedited shipping on their order.

  • $items
    Array of Items

    The list of items ordered. Represented as a JSON array of $item objects.

  • $seller_user_id
    String

    For marketplace businesses, this is the seller's user ID, typically a database primary key.Follow our guidelines for $user_id values.

  • $promotions
    Array of Promotions

    The list of promotions that apply to this order. You can add one or more promotions when creating or updating an order. Represented as a JSON array of promotion objects. You can also separately add promotions to the account via the $add_promotion event.

  • $shipping_method
    String

    Indicates the method of delivery to the user.

    Allowed Values
    • "$electronic""$physical"

$transaction

Use $transaction to record attempts to exchange money, credit or other tokens of value.

// Sample $transaction event
{
  // Required Fields
  "$type"             : "$transaction",
  "$api_key"          : "your_api_key_here",
  "$user_id"          : "billy_jones_301",
  "$amount"           : 506790000, // $506.79
  "$currency_code"    : "USD",

  // Supported Fields
  "$user_email"       : "bill@gmail.com",
  "$transaction_type" : "$sale",
  "$transaction_status" : "$success",
  "$order_id"         : "ORDER-123124124",
  "$transaction_id"   : "719637215",

  "$billing_address"  : {
      "$name"         : "Bill Jones",
      "$phone"        : "1-415-555-6041",
      "$address_1"    : "2100 Main Street",
      "$address_2"    : "Apt 3B",
      "$city"         : "New London",
      "$region"       : "New Hampshire",
      "$country"      : "US",
      "$zipcode"      : "03257"
  },
  // Credit card example
  "$payment_method"   : {
      "$payment_type"    : "$credit_card",
      "$payment_gateway" : "$braintree",
      "$card_bin"        : "542486",
      "$card_last4"      : "4444"
  },

  // Bank account example
  //"$payment_method"   : {
  //    "$payment_type"    : "$electronic_fund_transfer",
  //    "$routing_number"  : "021001088"
  //},
  // See other payment method options in field description below

  // Supported Fields
  "$shipping_address" : {
      "$name"         : "Bill Jones",
      "$phone"        : "1-415-555-6041",
      "$address_1"    : "2100 Main Street",
      "$address_2"    : "Apt 3B",
      "$city"         : "New London",
      "$region"       : "New Hampshire",
      "$country"      : "US",
      "$zipcode"      : "03257"
  },
  "$session_id"       : "gigtleqddo84l8cm15qe4il",

  // For marketplaces, use $seller_user_id to identify the seller
  "$seller_user_id"     : "slinkys_emporium",

  // Sample Custom Fields
  "digital_wallet"      : "apple_pay", // "google_wallet", etc.
  "coupon_code"         : "dollarMadness",
  "shipping_choice"     : "FedEx Ground Courier",
  "is_first_time_buyer" : false
}
import sift

client = sift.Client("your_api_key_here")

# Sample $transaction event
properties = {
  # Required Fields
  "$user_id"          : "billy_jones_301",
  "$amount"           : 506790000, # $506.79
  "$currency_code"    : "USD",

  # Supported Fields
  "$user_email"       : "bill@gmail.com",
  "$transaction_type" : "$sale",
  "$transaction_status" : "$success",
  "$order_id"         : "ORDER-123124124",
  "$transaction_id"   : "719637215",

  "$billing_address"  : {
      "$name"         : "Bill Jones",
      "$phone"        : "1-415-555-6041",
      "$address_1"    : "2100 Main Street",
      "$address_2"    : "Apt 3B",
      "$city"         : "New London",
      "$region"       : "New Hampshire",
      "$country"      : "US",
      "$zipcode"      : "03257"
  },
  # Credit card example
  "$payment_method"   : {
      "$payment_type"    : "$credit_card",
      "$payment_gateway" : "$braintree",
      "$card_bin"        : "542486",
      "$card_last4"      : "4444"
  },

  # Bank account example
  #"$payment_method"   : {
  #    "$payment_type"    : "$electronic_fund_transfer",
  #    "$routing_number"  : "021001088"
  #},
  # See other payment method options in field description below

  # Supported Fields
  "$shipping_address" : {
      "$name"         : "Bill Jones",
      "$phone"        : "1-415-555-6041",
      "$address_1"    : "2100 Main Street",
      "$address_2"    : "Apt 3B",
      "$city"         : "New London",
      "$region"       : "New Hampshire",
      "$country"      : "US",
      "$zipcode"      : "03257"
  },
  "$session_id"       : "gigtleqddo84l8cm15qe4il",

  # For marketplaces, use $seller_user_id to identify the seller
  "$seller_user_id"     : "slinkys_emporium",

  # Sample Custom Fields
  "digital_wallet"      : "apple_pay", # "google_wallet", etc.
  "coupon_code"         : "dollarMadness",
  "shipping_choice"     : "FedEx Ground Courier",
  "is_first_time_buyer" : False
}

response = client.track("$transaction", properties)
require "sift"

client = Sift::Client.new(:api_key => "your_api_key_here")

# Sample $transaction event
properties = {
  # Required Fields
  "$user_id"          => "billy_jones_301",
  "$amount"           => 506790000, # $506.79
  "$currency_code"    => "USD",

  # Supported Fields
  "$user_email"       => "bill@gmail.com",
  "$transaction_type" => "$sale",
  "$transaction_status" => "$success",
  "$order_id"         => "ORDER-123124124",
  "$transaction_id"   => "719637215",

  "$billing_address"  => {
      "$name"         => "Bill Jones",
      "$phone"        => "1-415-555-6041",
      "$address_1"    => "2100 Main Street",
      "$address_2"    => "Apt 3B",
      "$city"         => "New London",
      "$region"       => "New Hampshire",
      "$country"      => "US",
      "$zipcode"      => "03257"
  },
  # Credit card example
  "$payment_method"   => {
      "$payment_type"    => "$credit_card",
      "$payment_gateway" => "$braintree",
      "$card_bin"        => "542486",
      "$card_last4"      => "4444"
  },

  # Bank account example
  #"$payment_method"   => {
  #    "$payment_type"    => "$electronic_fund_transfer",
  #    "$routing_number"  => "021001088"
  #},
  # See other payment method options in field description below

  # Supported Fields
  "$shipping_address" => {
      "$name"         => "Bill Jones",
      "$phone"        => "1-415-555-6041",
      "$address_1"    => "2100 Main Street",
      "$address_2"    => "Apt 3B",
      "$city"         => "New London",
      "$region"       => "New Hampshire",
      "$country"      => "US",
      "$zipcode"      => "03257"
  },
  "$session_id"       => "gigtleqddo84l8cm15qe4il",

  # For marketplaces, use $seller_user_id to identify the seller
  "$seller_user_id"     => "slinkys_emporium",

  # Sample Custom Fields
  "digital_wallet"      => "apple_pay", # "google_wallet", etc.
  "coupon_code"         => "dollarMadness",
  "shipping_choice"     => "FedEx Ground Courier",
  "is_first_time_buyer" => false
}

response = client.track("$transaction", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'your_api_key_here'));

// Sample $transaction event
$properties = array(
  // Required Fields
  '$user_id'          => 'billy_jones_301',
  '$amount'           => 506790000, // $506.79
  '$currency_code'    => 'USD',

  // Supported Fields
  '$user_email'       => 'bill@gmail.com',
  '$transaction_type' => '$sale',
  '$transaction_status' => '$success',
  '$order_id'         => 'ORDER-123124124',
  '$transaction_id'   => '719637215',

  '$billing_address'  => array(
      '$name'         => 'Bill Jones',
      '$phone'        => '1-415-555-6041',
      '$address_1'    => '2100 Main Street',
      '$address_2'    => 'Apt 3B',
      '$city'         => 'New London',
      '$region'       => 'New Hampshire',
      '$country'      => 'US',
      '$zipcode'      => '03257'
  ),
  // Credit card example
  '$payment_method'   => array(
      '$payment_type'    => '$credit_card',
      '$payment_gateway' => '$braintree',
      '$card_bin'        => '542486',
      '$card_last4'      => '4444'
  ),

  // Bank account example
  //"$payment_method"   => array(
  //    "$payment_type"    => "$electronic_fund_transfer",
  //    "$routing_number"  => "021001088"
  //),
  // See other payment method options in field description below

  // Supported Fields
  '$shipping_address' => array(
      '$name'         => 'Bill Jones',
      '$phone'        => '1-415-555-6041',
      '$address_1'    => '2100 Main Street',
      '$address_2'    => 'Apt 3B',
      '$city'         => 'New London',
      '$region'       => 'New Hampshire',
      '$country'      => 'US',
      '$zipcode'      => '03257'
  ),
  '$session_id'       => 'gigtleqddo84l8cm15qe4il',

  // For marketplaces, use $seller_user_id to identify the seller
  '$seller_user_id'     => 'slinkys_emporium',

  // Sample Custom Fields
  'digital_wallet'      => 'apple_pay' // 'google_wallet', etc.
  'coupon_code'         => 'dollarMadness',
  'shipping_choice'     => 'FedEx Ground Courier',
  'is_first_time_buyer' => False
);

$response = $client->track('$transaction', $properties);
  • $type
    required · String

    "$transaction"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

    The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid $user_id values here.

  • $user_email
    String

    Email of the user creating this order. Note: If the user's email is also their account ID in your system, set both the $user_id and $user_email fields to their email address.

  • $transaction_type
    String

    The type of transaction being recorded. There are eight types:

    Allowed Values
    • $saleAuthorization and capture of a payment performed together in one step. This is the most commonly used transaction type. This is the default $transaction_type if the transaction type is not provided.
    • $authorizeAuthorizing a payment by reserving the payment amount from the buyer's account. Money does not change hands until capture.
    • $captureCapturing a payment reserved in the authorization step.
    • $voidCancelling a pending authorization or capture.
    • $refundReturning part or all of a captured payment to the buyer.
    • $depositDepositing money into an account.
    • $withdrawalWithdrawing money from an account.
    • $transferTransferring money from one account to another.
  • $transaction_status
    String

    Use $transaction_status to indicate the status of the transaction. The value can be "$success" (default value), "$failure" or "$pending". For instance, If the transaction was rejected by the payment gateway, set the value to "$failure".

  • $amount
    Required · Integer

    Total transaction amount in micros in the base unit of the $currency_code. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. Send as a positive number for all $transaction_type values. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros. Use 1 for 1 microBitcoin.

  • $currency_code
    Required · String

    ISO-4217 currency code for the amount. e.g., USD, CAD, HKD. If your site uses alternative currencies, like bitcoin or points systems, specify that here.

  • $order_id
    String

    The ID for this order in your system. Used for cross referencing an order in your internal systems.

  • $transaction_id
    String

    The ID for identifying this transaction. Important for tracking transactions, and linking different parts of the same transaction together, e.g., linking a refund to its original transaction.

  • $billing_address
    Address

    The billing address as entered by the user. Represented as a nested address object.

  • $payment_method
    Payment Method Object

    The payment information associated with this transaction. Represented as a single payment_method object containing payment method, payment gateway, credit card bin, etc.

  • $shipping_address
    Address

    The shipping address as entered by the user. Represented as a nested address object.

  • $session_id
    String

    The user's current session ID, used to tie a user's action before and after log in or account creation.

  • $seller_user_id
    String

    are case sensitive. You may need to normalize the capitalization of your user IDs. Follow our guidelines for $user_id values.

  • $transfer_recipient_user_id
    String

    For transfer transactions, the user ID of the user receiving the transfer. If $transfer_recipient_user_id is specified, $transaction_type must be set to "$transfer"; otherwise, the system will give an error.Follow our guidelines for $user_id values.

$create_content

Use $create_content to tell Sift Science whenever a user creates content on your site. Some examples of content are a job posting, product for sale, apartment for rent, dating profile, and blog post.

// Sample $create_content event
{
  // Required Fields
  "$type"       : "$create_content",
  "$api_key"    : "YOUR_API_KEY_HERE",
  "$user_id"    : "billy_jones_301",

  // Supported Fields
  "$contact_email"    : "bill@example.com",
  "$contact_phone"    : "1-415-555-6040",
  "$content_id"       : "9671500641",
  "$subject"          : "2 Bedroom Apartment for Rent",
  "$content"          : "Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.",
  "$amount"           : 2300000000, // $2300
  "$currency_code"    : "USD",
  "$categories"       : [
    "Housing",
    "Apartments",
    "2 Bedrooms"
  ],
  "$locations"        : [
    {
      "$city"       : "Seattle",
      "$region"     : "Washington",
      "$country"    : "US",
      "$zipcode"    : "98112"
    }
  ],
  "$image_hashes"     : [
    "912ec803b2ce49e4a541068d495ab570", // MD5 hash of the image
    "4be4b314caafaa3e12bfcb8d16df3aff"
  ],
  "$expiration_time"  : 1471003200000, // UNIX timestamp in milliseconds
  "$status"           : "$active"
}
import sift

client = sift.Client("your_api_key_here")

# Sample $create_content event
properties = {

  # Required Fields
  "$user_id"    : "billy_jones_301",

  # Supported Fields
  "$contact_email"    : "bill@example.com",
  "$contact_phone"    : "1-415-555-6040",
  "$content_id"       : "9671500641",
  "$subject"          : "2 Bedroom Apartment for Rent",
  "$content"          : "Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.",
  "$amount"           : 2300000000, # $2300
  "$currency_code"    : "USD",
  "$categories"       : [
    "Housing",
    "Apartments",
    "2 Bedrooms"
  ],
  "$locations"        : [
    {
      "$city"       : "Seattle",
      "$region"     : "Washington",
      "$country"    : "US",
      "$zipcode"    : "98112"
    }
  ],
  "$image_hashes"     : [
    "912ec803b2ce49e4a541068d495ab570", # MD5 hash of the image
    "4be4b314caafaa3e12bfcb8d16df3aff"
  ],
  "$expiration_time"  : 1471003200000, # UNIX timestamp in milliseconds
  "$status"           : "$active"
}

response = client.track("$create_content", properties)
require "sift"

client = Sift::Client.new(:api_key => "your_api_key_here")

# Sample $create_content event
properties = {

  # Required Fields
  "$user_id"    => "billy_jones_301",

  # Supported Fields
  "$contact_email"    => "bill@example.com",
  "$contact_phone"    => "1-415-555-6040",
  "$content_id"       => "9671500641",
  "$subject"          => "2 Bedroom Apartment for Rent",
  "$content"          => "Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.",
  "$amount"           => 2300000000, # $2300
  "$currency_code"    => "USD",
  "$categories"       => [
    "Housing",
    "Apartments",
    "2 Bedrooms"
  ],
  "$locations"        => [
    {
      "$city"       => "Seattle",
      "$region"     => "Washington",
      "$country"    => "US",
      "$zipcode"    => "98112"
    }
  ],
  "$image_hashes"     => [
    "912ec803b2ce49e4a541068d495ab570", # MD5 hash of the image
    "4be4b314caafaa3e12bfcb8d16df3aff"
  ],
  "$expiration_time"  => 1471003200000, # UNIX timestamp in milliseconds
  "$status"           => "$active"
}

response = client.track("$create_content", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'your_api_key_here'));

# Sample $create_content event
properties = array(

  // Required Fields
  '$user_id'    => 'billy_jones_301',

  // Supported Fields
  '$contact_email'    => 'bill@example.com',
  '$contact_phone'    => '1-415-555-6040',
  '$content_id'       => '9671500641',
  '$subject'          => '2 Bedroom Apartment for Rent',
  '$content'          => 'Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.',
  '$amount'           => 2300000000, // $2300
  '$currency_code'    => 'USD',
  '$categories'       => array(
    'Housing',
    'Apartments',
    '2 Bedrooms'
  ),
  '$locations'        => array(
    array(
      '$city'       => 'Seattle',
      '$region'     => 'Washington',
      '$country'    => 'US',
      '$zipcode'    => '98112'
    )
  ),
  '$image_hashes'     => array(
    '912ec803b2ce49e4a541068d495ab570', // MD5 hash of the image
    '4be4b314caafaa3e12bfcb8d16df3aff'
  ),
  '$expiration_time'  => 1471003200000, // UNIX timestamp in milliseconds
  '$status'           => '$active'
);

$response = $client->track('$create_content', $properties);
  • $type
    required · String

    "$create_content"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

    The user's internal account ID. Users without an assigned $user_id will not show up in the console. Find valid $user_id values here.

  • $session_id
    String

    The user's current session ID, used to tie a user's action before and after login or account creation.

  • $content_id
    String

    The unique ID that you assign to an individual piece content in your system. Note: content IDs are case sensitive.

  • $contact_email
    String

    The contact email provided with the posting.

  • $contact_phone
    String

    The primary phone number of the user associated with this posting. Provide the phone number as a string starting with the country code. Use E.164 format or send in the standard national format of number's origin. For example: "+14155556041" or "1-415-555-6041" for a U.S. number.

  • $subject
    String

    The subject of the posting.

  • $content
    String

    The text content of the posting.

  • $amount
    Integer

    A price associated with this content in micros in the base unit of the $currency_code. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.

  • $currency_code
    String

    ISO-4217 currency code for the amount. If your site uses alternative currencies, specify them here.

  • $categories
    Array of Strings

    The category or categories you associate with the content you are posting. For example, a job posting might contain industry and position (e.g. ["Computer Hardware", "Engineer"]) or marketplace might contain the type of good it is (e.g. ["Furniture", "Outdoor", "Patio", "Tables"]). If you need to include location of the good, use the $locations field to pass that instead.

  • $locations
    Array of Addresses

    The locations associated with this posting. Represented as an array of nested address objects. You can pass one or more addresses that are associated with your posting. Pass as much information as you have. Partial addresses such as just city and state are fine if that’s all you have.

  • $image_hashes
    Array of Strings

    The MD5 hash of any images associated with the posting. Pass one or multiple image hashes when creating or updating your content. A hash for a single file will look like this: 18E927C7E1229DC8F088643B7A65F978

  • $expiration_time
    Integer

    The UNIX timestamp in milliseconds when the posting will expire. Only set if posting is time bound in some way (e.g. car auction is active 14 days from date of posting).

  • $status
    String

    The status of the posting. After you create a posting, you can also update its status via the $content_status event.

    Allowed Values
    • $draftThe posting has not yet been submitted by the user to go live.
    • $pendingThe user has submitted the posting but has not gone live. This may be because the posting needs to be reviewed, the user needs to add payment details, or because of some other processes within your business.
    • $activeThe posting is live and active on your site. Other users can see the posting.
    • $pausedThe posting has been paused by the user and may return back to $active at a later date.
    • $deleted_by_userThe posting has been deleted or archived by the user.
    • $deleted_by_companyThe posting has been deleted or archived by your company due to violation of terms of service or other policies.

$update_content

Use $update_content to record changes to a posting.

  • This event contains the same fields as $create_content.
  • The existing content will be completely replaced by the values specified in $update_content. Be sure to specify all values for the content, not just those that changed.
  • For postings created prior to integrating with Sift, there's no need to call $create_content before $update_content. Simply call $update_content and we'll infer that content was created before your integration with Sift Science.
// Sample $update_content event
{
  // Required Fields
  "$type"       : "$update_content",
  "$api_key"    : "YOUR_API_KEY_HERE",
  "$user_id"    : "billy_jones_301",

  // Supported Fields
  "$contact_email"    : "bill@example.com",
  "$contact_phone"    : "1-415-555-6040",
  "$content_id"       : "9671500641",
  "$subject"          : "2 Bedroom Apartment for Rent",
  "$content"          : "Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.",
  "$amount"           : 2300000000, // $2300
  "$currency_code"    : "USD",
  "$categories"       : [
    "Housing",
    "Apartments",
    "2 Bedrooms"
  ],
  "$locations"        : [
    {
      "$city"       : "Seattle",
      "$region"     : "Washington",
      "$country"    : "US",
      "$zipcode"    : "98112"
    }
  ],
  "$image_hashes"     : [
    "912ec803b2ce49e4a541068d495ab570", // MD5 hash of the image
    "4be4b314caafaa3e12bfcb8d16df3aff"
  ],
  "$expiration_time"  : 1471003200000, // UNIX timestamp in milliseconds
  "$status"           : "$active"
}
import sift

client = sift.Client("your_api_key_here")

# Sample $update_content event
properties = {

  # Required Fields
  "$type"       : "$update_content",

  # Supported Fields
  "$contact_email"    : "bill@example.com",
  "$contact_phone"    : "1-415-555-6040",
  "$content_id"       : "9671500641",
  "$subject"          : "2 Bedroom Apartment for Rent",
  "$content"          : "Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.",
  "$amount"           : 2300000000, # $2300
  "$currency_code"    : "USD",
  "$categories"       : [
    "Housing",
    "Apartments",
    "2 Bedrooms"
  ],
  "$locations"        : [
    {
      "$city"       : "Seattle",
      "$region"     : "Washington",
      "$country"    : "US",
      "$zipcode"    : "98112"
    }
  ],
  "$image_hashes"     : [
    "912ec803b2ce49e4a541068d495ab570", # MD5 hash of the image
    "4be4b314caafaa3e12bfcb8d16df3aff"
  ],
  "$expiration_time"  : 1471003200000, # UNIX timestamp in milliseconds
  "$status"           : "$active"
}

response = client.track("$update_content", properties)
require "sift"

client = Sift::Client.new(:api_key => "your_api_key_here")

# Sample $update_content event
properties = {

  # Required Fields
  "$type"       => "$update_content",

  # Supported Fields
  "$contact_email"    => "bill@example.com",
  "$contact_phone"    => "1-415-555-6040",
  "$content_id"       => "9671500641",
  "$subject"          => "2 Bedroom Apartment for Rent",
  "$content"          => "Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.",
  "$amount"           => 2300000000, # $2300
  "$currency_code"    => "USD",
  "$categories"       => [
    "Housing",
    "Apartments",
    "2 Bedrooms"
  ],
  "$locations"        => [
    {
      "$city"       => "Seattle",
      "$region"     => "Washington",
      "$country"    => "US",
      "$zipcode"    => "98112"
    }
  ],
  "$image_hashes"     => [
    "912ec803b2ce49e4a541068d495ab570", # MD5 hash of the image
    "4be4b314caafaa3e12bfcb8d16df3aff"
  ],
  "$expiration_time"  => 1471003200000, # UNIX timestamp in milliseconds
  "$status"           => "$active"
}

response = client.track("$update_content", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'your_api_key_here'));

# Sample $update_content event
properties = array(

  // Required Fields
  '$type'       => '$update_content',

  // Supported Fields
  '$contact_email'    => 'bill@example.com',
  '$contact_phone'    => '1-415-555-6040',
  '$content_id'       => '9671500641',
  '$subject'          => '2 Bedroom Apartment for Rent',
  '$content'          => 'Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.',
  '$amount'           => 2300000000, // $2300
  '$currency_code'    => 'USD',
  '$categories'       => array(
    'Housing',
    'Apartments',
    '2 Bedrooms'
  ),
  '$locations'        => array(
    array(
      '$city'       => 'Seattle',
      '$region'     => 'Washington',
      '$country'    => 'US',
      '$zipcode'    => '98112'
    )
  ),
  '$image_hashes'     => array(
    '912ec803b2ce49e4a541068d495ab570', // MD5 hash of the image
    '4be4b314caafaa3e12bfcb8d16df3aff'
  ),
  '$expiration_time'  => 1471003200000, // UNIX timestamp in milliseconds
  '$status'           => '$active'
);

$response = $client->track('$update_content', $properties);
  • $type
    required · String

    "$update_content"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

    The user's internal account ID. Users without an assigned $user_id will not show up in the console. Find valid $user_id values here.

  • $session_id
    String

    The user's current session ID, used to tie a user's action before and after log in or account creation.

  • $content_id
    String

    The unique ID that you assign to an individual piece content in your system. Note: content IDs are case sensitive.

  • $contact_email
    String

    The contact email provided with the posting.

  • $contact_phone
    String

    The primary phone number of the user associated with this posting. Provide the phone number as a string starting with the country code. Use E.164 format or send in the standard national format of number's origin. For example: "+14155556041" or "1-415-555-6041" for a U.S. number.

  • $subject
    String

    The subject of the posting.

  • $content
    String

    The text content of the posting.

  • $amount
    Integer

    A price associated with this content in micros in the base unit of the $currency_code. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.

  • $currency_code
    String

    ISO-4217 currency code for the amount. If your site uses alternative currencies, specify them here.

  • $categories
    Array of Strings

    The category or categories you associate with the content you are posting. For example, a job posting might contain industry and position (e.g. ["Computer Hardware", "Engineer"]) or marketplace might contain the type of good it is (e.g. ["Furniture", "Outdoor", "Patio", "Tables"]). If you need to include location of the good, use the $locations field to pass that instead.

  • $locations
    Array of Addresses

    The locations associated with this posting. Represented as an array of nested address objects. You can pass one or more addresses that are associated with your posting. Pass as much information as you have. Partial addresses such as just city and state are fine if that’s all you have.

  • $image_hashes
    Array of Strings

    The MD5 hash of any images associated with the posting. Pass one or multiple image hashes when creating or updating your content. A hash for a single file will look like this: 18E927C7E1229DC8F088643B7A65F978

  • $expiration_time
    Integer

    The UNIX timestamp in milliseconds when the posting will expire. Only set if posting is time bound in some way (e.g. car auction is active 14 days from date of posting).

  • $status
    String

    The status of the posting. After you create a posting, you can also update its status via the $content_status event.

    Allowed Values
    • $draftThe posting has not yet been submitted by the user to go live.
    • $pendingThe user has submitted the posting but has not gone live. This may be because the posting needs to be reviewed, the user needs to add payment details, or because of some other processes within your business.
    • $activeThe posting is live and active on your site. Other users can see the posting.
    • $pausedThe posting has been paused by the user and may return back to $active at a later date.
    • $deleted_by_userThe posting has been deleted or archived by the user.
    • $deleted_by_companyThe posting has been deleted or archived by your company due to violation of terms of service or other policies.

$content_status

Use $content_status to update the status of content that you’ve already sent to Sift Science. If the status is the only thing that’s changing about the content, use this as a convenient way to change it without having to resend the rest of the content's information. Useful for long lived content such as rentals, dating profiles, and job postings. Status can also be set using $create_content or $update_content.

// Sample $content_status event
{
  // Required Fields
  "$type"       : "$content_status",
  "$api_key"    : "your_api_key_here",
  "$user_id"    : "billy_jones_301",
  "$content_id" : "9671500641",
  "$status"     : "$paused"
}
import sift

client = sift.Client("your_api_key_here")

# Sample $content_status event
properties = {
  # Required Fields
  "$user_id"    : "billy_jones_301",
  "$content_id" : "9671500641",
  "$status"     : "$paused"
}

response = client.track("$content_status", properties)
require "sift"

client = Sift::Client.new(:api_key => "your_api_key_here")

# Sample $content_status event
properties = {
  # Required Fields
  "$user_id"    => "billy_jones_301",
  "$content_id" => "9671500641",
  "$status":    => "$paused"
}

response = client.track("$content_status", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'your_api_key_here'));

// Sample $content_status event
$properties = array(
  // Required Fields
  '$user_id'    => 'billy_jones_301',
  '$content_id' => '9671500641',
  '$status'     => '$paused'
);

$response = $client->track('$content_status', $properties);
  • $type
    required · String

    is "$content_status"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

    The user's internal account ID. Users without an assigned $user_id will not show up in the console. Find valid $user_id values here.

  • $content_id
    required · String

    The unique ID for the piece of content that you’re updating the status of. Note: content IDs are case sensitive.

  • $status
    required · String

    The status of the posting.

    Allowed Values
    • $draftThe posting has not yet been submitted by the user to go live.
    • $pendingThe user has submitted the posting but has not gone live. This may be because the posting needs to be reviewed, the user needs to add payment details, or because of some other processes within your business.
    • $activeThe posting is live and active on your site. Other users can see the posting.
    • $pausedThe posting has been paused by the user and may return back to $active at a later date.
    • $deleted_by_userThe posting has been deleted or archived by the user.
    • $deleted_by_companyThe posting has been deleted or archived by your company due to violation of terms of service or other policies.

$flag_content

Use $flag_content to let us know when another user reports that this user's content may violate your company’s policies. If you have a feature like "Report this posting" or "Flag this update", send that event to us using this reserved event.

// Sample $flag_content event
{
  // Required Fields
  "$type"       : "$flag_content", 
  "$api_key"    : "your_api_key_here",
  "$user_id"    : "billy_jones_301", // content creator
  "$content_id" : "9671500641",

  // Supported Fields
  "$flagged_by" : "jamieli89"
}
import sift

client = sift.Client("your_api_key_here")

# Sample $flag_content event
properties = {
  # Required Fields
  "$user_id"    : "billy_jones_301", # content creator
  "$content_id" : "9671500641",

  # Supported Fields
  "$flagged_by" : "jamieli89"
}

response = client.track("$flag_content", properties)
require "sift"

client = Sift::Client.new(:api_key => "your_api_key_here")

# Sample $flag_content event
properties = {
  # Required Fields
  "$user_id"    => "billy_jones_301", # content creator
  "$content_id" => "9671500641",

  # Supported Fields
  "$flagged_by" => "jamieli89"
}

response = client.track("$flag_content", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'your_api_key_here'));

// Sample $flag_content event
$properties = array(
  // Required Fields
  '$user_id'    => 'billy_jones_301', // content creator
  '$content_id' => '9671500641',

  # Supported Fields
  '$flagged_by' => 'jamieli89'
);

$response = $client->track('$flag_content', $properties);
  • $type
    required · String

    is "$flag_content"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

    The content creator's account ID according to your systems. Note: User IDs are case sensitive. Find valid $user_id values here.

  • $content_id
    required · String

    The unique ID for the piece of content that is being flagged. Note: content IDs are case sensitive.

  • $flagged_by
    String

    The account ID of the user who is flagging the content. Note: User IDs are case sensitive.

$add_promotion

Use $add_promotion to record when a user adds one or more promotions to their account.

// Sample $add_promotion event
{
  // Required fields.
  "$type"       : "$add_promotion",
  "$api_key"    : "your_api_key",
  "$user_id"    : "billy_jones_301",

  // Supported fields.
  "$promotions" : [
    // Example of a promotion for monetary discounts off good or services
    {
      "$promotion_id"     : "NewRideDiscountMay2016",
      "$status"           : "$success",
      "$description"      : "$5 off your first 5 rides",
      "$referrer_user_id" : "elon-m93903",
      "$discount"         : {
        "$amount"         : 5000000,  // $5
        "$currency_code"  : "USD"
      }
    }
  ]
}
import sift

client = sift.Client("your_api_key_here")

# Sample $add_promotion event
properties = {
  # Required fields.
  "$user_id"    : "billy_jones_301",

  # Supported fields.
  "$promotions" : [
    # Example of a promotion for monetary discounts off good or services
    {
      "$promotion_id"     : "NewRideDiscountMay2016",
      "$status"           : "$success",
      "$description"      : "$5 off your first 5 rides",
      "$referrer_user_id" : "elon-m93903",
      "$discount"         : {
        "$amount"         : 5000000,  # $5
        "$currency_code"  : "USD"
      }
    }
  ]
}

response = client.track("$add_promotion", properties)
require "sift"

client = Sift::Client.new(:api_key => "your_api_key_here")

# Sample $add_promotion event
properties = {
  # Required fields.
  "$user_id"    => "billy_jones_301",

  # Supported fields.
  "$promotions" => [
    # Example of a promotion for monetary discounts off good or services
    {
      "$promotion_id"     => "NewRideDiscountMay2016",
      "$status"           => "$success",
      "$description"      => "$5 off your first 5 rides",
      "$referrer_user_id" => "elon-m93903",
      "$discount"         => {
        "$amount"         => 5000000,  # $5
        "$currency_code"  => "USD"
      }
    }
  ]
}

response = client.track("$add_promotion", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'your_api_key_here'));

// Sample $add_promotion event
$properties = array(
  // Required fields.
  '$user_id'    => 'billy_jones_301',

  // Supported fields.
  '$promotions' => array(
    // Example of a promotion for monetary discounts off good or services
    array(
      '$promotion_id'     => 'NewRideDiscountMay2016',
      '$status'           => '$success',
      '$description'      => '$5 off your first 5 rides',
      '$referrer_user_id' => 'elon-m93903',
      '$discount'         => array(
        '$amount'         => 5000000,  // $5
        '$currency_code'  => 'USD'
      )
    )
  )
);

$response = $client->track('$add_promotion', $properties);
  • $type
    required · String

    "$add_promotion"

  • $user_id
    required · String

    The user's account ID according to your systems. Note: User IDs are case sensitive. Find valid $user_id values here.

  • $promotions
    Array of Promotions

    Contains all promotions that have been newly applied to the referenced user.

$add_item_to_cart

Use $add_item_to_cart to record when a user adds an item to their shopping cart or list.

// Sample $add_item_to_cart event
{
  // Required Fields
  "$type"       : "$add_item_to_cart",
  "$api_key"    : "your_api_key_here",
  "$user_id"    : "billy_jones_301",

  // Supported Fields
  "$session_id" : "gigtleqddo84l8cm15qe4il",
  "$item"       : {
    "$item_id"        : "B004834GQO",
    "$product_title"  : "The Slanket Blanket-Texas Tea",
    "$price"          : 39990000, // $39.99
    "$currency_code"  : "USD",
    "$upc"            : "67862114510011",
    "$sku"            : "004834GQ",
    "$brand"          : "Slanket",
    "$manufacturer"   : "Slanket",
    "$category"       : "Blankets & Throws",
    "$tags"           : ["Awesome", "Wintertime specials"],
    "$color"          : "Texas Tea",
    "$quantity"       : 16
  }
}
import sift

client = sift.Client("your_api_key_here")

# Sample $add_item_to_cart event
properties = {
  # Required Fields
  "$user_id"    : "billy_jones_301",

  # Supported Fields
  "$session_id" : "gigtleqddo84l8cm15qe4il",
  "$item"       : {
    "$item_id"        : "B004834GQO",
    "$product_title"  : "The Slanket Blanket-Texas Tea",
    "$price"          : 39990000, # $39.99
    "$currency_code"  : "USD",
    "$upc"            : "67862114510011",
    "$sku"            : "004834GQ",
    "$brand"          : "Slanket",
    "$manufacturer"   : "Slanket",
    "$category"       : "Blankets & Throws",
    "$tags"           : ["Awesome", "Wintertime specials"],
    "$color"          : "Texas Tea",
    "$quantity"       : 16
  }
}

response = client.track("$add_item_to_cart", properties)
require "sift"

client = Sift::Client.new(:api_key => "your_api_key_here")

# Sample $add_item_to_cart event
properties = {
  # Required Fields
  "$user_id"    => "billy_jones_301",

  # Supported Fields
  "$session_id" => "gigtleqddo84l8cm15qe4il",
  "$item"       => {
    "$item_id"        => "B004834GQO",
    "$product_title"  => "The Slanket Blanket-Texas Tea",
    "$price"          => 39990000, # $39.99
    "$currency_code"  => "USD",
    "$upc"            => "67862114510011",
    "$sku"            => "004834GQ",
    "$brand"          => "Slanket",
    "$manufacturer"   => "Slanket",
    "$category"       => "Blankets & Throws",
    "$tags"           => ["Awesome", "Wintertime specials"],
    "$color"          => "Texas Tea",
    "$quantity"       => 16
  }
}

response = client.track("$add_item_to_cart", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'your_api_key_here'));

// Sample $add_item_to_cart event
$properties = array(
  // Required Fields
  '$user_id'    => 'billy_jones_301',

  // Supported Fields
  '$session_id' => 'gigtleqddo84l8cm15qe4il',
  '$item'       => array(
    '$item_id'        => 'B004834GQO',
    '$product_title'  => 'The Slanket Blanket-Texas Tea',
    '$price'          => 39990000, // $39.99
    '$currency_code'  => 'USD',
    '$upc'            => '67862114510011',
    '$sku'            => '004834GQ',
    '$brand'          => 'Slanket',
    '$manufacturer'   => 'Slanket',
    '$category'       => 'Blankets & Throws',
    '$tags'           => array('Awesome', 'Wintertime specials'),
    '$color'          => 'Texas Tea',
    '$quantity'       => 16
  )
);

$response = $client->track('$add_item_to_cart', $properties);
  • $type
    required · String

    "$add_item_to_cart"

  • $api_key
    required · String

    Your Sift REST API key.

  • $session_id
    required if no User ID is provided · String

    The user's current session ID, used to tie a user's action before and after log in or account creation.

  • $user_id
    send if known · String

    The user's account ID according to your systems. Note: User IDs are case sensitive. Find valid $user_id values here.

  • $item
    Item

    The product item added to cart. Represented as a nested $item object. Required subfields are $item_id, $product_title, and $price. The $quantity is specified as a subfield.

$remove_item_from_cart

Use $remove_item_from_cart to record when a user removes an item from their shopping cart or list.

// Sample $remove_item_from_cart event
{
  // Required Fields
  "$type"       : "$remove_item_from_cart",
  "$api_key"    : "your_api_key_here",
  "$user_id"    : "billy_jones_301",

  // Supported Fields
  "$session_id" : "gigtleqddo84l8cm15qe4il",
  "$item"       : {
    "$item_id"        : "B004834GQO",
    "$product_title"  : "The Slanket Blanket-Texas Tea",
    "$price"          : 39990000, // $39.99
    "$currency_code"  : "USD",
    "$quantity"       : 2,
    "$upc"            : "67862114510011",
    "$sku"            : "004834GQ",
    "$brand"          : "Slanket",
    "$manufacturer"   : "Slanket",
    "$category"       : "Blankets & Throws",
    "$tags"           : ["Awesome", "Wintertime specials"],
    "$color"          : "Texas Tea"
  }
}
import sift

client = sift.Client("your_api_key_here")

# Sample $remove_item_from_cart event
properties = {
  # Required Fields
  "$user_id"    : "billy_jones_301",

  # Supported Fields
  "$session_id" : "gigtleqddo84l8cm15qe4il",
  "$item"       : {
    "$item_id"        : "B004834GQO",
    "$product_title"  : "The Slanket Blanket-Texas Tea",
    "$price"          : 39990000, # $39.99
    "$currency_code"  : "USD",
    "$quantity"       : 2,
    "$upc"            : "67862114510011",
    "$sku"            : "004834GQ",
    "$brand"          : "Slanket",
    "$manufacturer"   : "Slanket",
    "$category"       : "Blankets & Throws",
    "$tags"           : ["Awesome", "Wintertime specials"],
    "$color"          : "Texas Tea"
  }
}

response = client.track("$remove_item_from_cart", properties)
require "sift"

client = Sift::Client.new(:api_key => "your_api_key_here")

# Sample $remove_item_from_cart event
properties = {
  # Required Fields
  "$user_id"    => "billy_jones_301",

  # Supported Fields
  "$session_id" => "gigtleqddo84l8cm15qe4il",
  "$item"       => {
    "$item_id"        => "B004834GQO",
    "$product_title"  => "The Slanket Blanket-Texas Tea",
    "$price"          => 39990000, # $39.99
    "$currency_code"  => "USD",
    "$quantity"       => 2,
    "$upc"            => "67862114510011",
    "$sku"            => "004834GQ",
    "$brand"          => "Slanket",
    "$manufacturer"   => "Slanket",
    "$category"       => "Blankets & Throws",
    "$tags"           => ["Awesome", "Wintertime specials"],
    "$color"          => "Texas Tea"
  }
}

response = client.track("$remove_item_from_cart", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'your_api_key_here'));

// Sample $remove_item_from_cart event
$properties = array(
  // Required Fields
  '$user_id'    => 'billy_jones_301',

  // Supported Fields
  '$session_id' => 'gigtleqddo84l8cm15qe4il',
  '$item'       => array(
    '$item_id'        => 'B004834GQO',
    '$product_title'  => 'The Slanket Blanket-Texas Tea',
    '$price'          => 39990000, // $39.99
    '$currency_code'  => 'USD',
    '$quantity'       => 2,
    '$upc'            => '67862114510011',
    '$sku'            => '004834GQ',
    '$brand'          => 'Slanket',
    '$manufacturer'   => 'Slanket',
    '$category'       => 'Blankets & Throws',
    '$tags'           => array('Awesome', 'Wintertime specials'),
    '$color'          => 'Texas Tea'
  )
);

$response = $client->track('$remove_item_from_cart', $properties);
  • $type
    required · String

    "$remove_item_to_cart"

  • $api_key
    required · String

    Your Sift REST API key.

  • $session_id
    required if no User ID is provided · String

    The user's current session ID, used to tie a user's action before and after log in or account creation.

  • $user_id
    required · String

    The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid $user_id values here.

  • $item
    Item

    The product item removed from cart. Represented as a nested $item object. Strongly recommended subfields are $item_id, $product_title, and $price. The $quantity is specified as a subfield.

$submit_review

Use $submit_review to record a user-submitted review of a product or other users. e.g., a seller on your site.

// Sample $submit_review event
{
  // Required Fields
  "$type"              : "$submit_review",
  "$api_key"           : "your_api_key_here",
  "$user_id"           : "billy_jones_301",


  // Supported Fields
  "$content"           : "Text content of submitted review goes here.",
  "$review_title"      : "Title of Review Goes Here",
  "$item_id"           : "V4C3D5R2Z6",
  "$reviewed_user_id"  : "billy_jones_301",
  "$submission_status" : "$success",

  // Sample Custom Fields
  "rating"             : "5"
}
import sift

client = sift.Client("your_api_key_here")

# Sample $submit_review event
properties = {
  # Required Fields

  "$user_id"           : "billy_jones_301",


  # Supported Fields
  "$content"           : "Text content of submitted review goes here.",
  "$review_title"      : "Title of Review Goes Here",
  "$item_id"           : "V4C3D5R2Z6",
  "$reviewed_user_id"  : "billy_jones_301",
  "$submission_status" : "$success",

  # Sample Custom Fields
  "rating"             : "5"
}

response = client.track("$submit_review", properties)
require "sift"

client = Sift::Client.new(:api_key => "your_api_key_here")

# Sample $submit_review event
properties = {
  # Required Fields
  "$user_id"           => "billy_jones_301",


  # Supported Fields
  "$content"           => "Text content of submitted review goes here.",
  "$review_title"      => "Title of Review Goes Here",
  "$item_id"           => "V4C3D5R2Z6",
  "$reviewed_user_id"  => "billy_jones_301",
  "$submission_status" => "$success",

  # Sample Custom Fields
  "rating"             => "5"
}

response = client.track("$submit_review", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'your_api_key_here'));

// Sample $submit_review event
$properties = array(
  // Required Fields
  '$user_id'           => 'billy_jones_301',


  // Supported Fields
  '$content'           => 'Text content of submitted review goes here.',
  '$review_title'      => 'Title of Review Goes Here',
  '$item_id'           => 'V4C3D5R2Z6',
  '$reviewed_user_id'  => 'billy_jones_301',
  '$submission_status' => '$success',

  // Sample Custom Fields
  'rating'             => '5'
);

$response = $client->track('$submit_review', $properties);
  • $type
    required · String

    "$submit_review"

  • $api_key
    required · String

    Your Sift REST API key.

  • $session_id
    required if no User ID is provided · String

    The user's current session ID, used to tie a user's action before and after log in or account creation.

  • $user_id
    send if known · String

    The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid $user_id values here.

  • $content
    String

    The text content of review submitted.

  • $review_title
    String

    The title of review submitted.

  • $item_id
    String

    The ID of the product or service being reviewed.

  • $reviewed_user_id
    String

    The user's account ID according to your systems. Note that user IDs are case sensitive. guidelines for $user_id values.

  • $content
    String

    The text content of review submitted.

  • $submission_status
    String

    If reviews in your system must be approved, use $submission_status to represent the status of the review.

    Allowed Values
    • "$success" "$failure" "$pending"

$send_message

Use $send_message to record when a user sends a message to another user i.e. the recipient.

// Sample $send_message event
{
  // Required Fields
  "$type"       : "$send_message",
  "$api_key"    : "your_api_key_here",
  "$user_id"    : "billy_jones_301",

  // Supported Fields
  "$recipient_user_id" : "512924123",
  "$subject"    : "Subject line of the message.",
  "$content"    : "Text content of message."
}
import sift

client = sift.Client("your_api_key_here")

# Sample $send_message event
properties = {
  # Required Fields

  "$user_id"    : "billy_jones_301",

  # Supported Fields
  "$recipient_user_id" : "512924123",
  "$subject"    : "Subject line of the message.",
  "$content"    : "Text content of message."
}

response = client.track("$send_message", properties)
require "sift"

client = Sift::Client.new(:api_key => "your_api_key_here")

# Sample $send_message event
properties = {
  # Required Fields

  "$user_id"    => "billy_jones_301",

  # Supported Fields
  "$recipient_user_id" => "512924123",
  "$subject"    => "Subject line of the message.",
  "$content"    => "Text content of message."
}

response = client.track("$send_message", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'your_api_key_here'));

// Sample $send_message event
$properties = array(
  // Required Fields

  '$user_id'    => 'billy_jones_301',

  // Supported Fields
  '$recipient_user_id' => '512924123',
  '$subject'    => 'Subject line of the message.',
  '$content'    => 'Text content of message.'
);

$response = $client->track('$send_message', $properties);
  • $type
    required · String

    "$send_message"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

    The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid $user_id values here.

  • $session_id
    required if no User ID is provided · String

    The user's current session ID, used to tie a user's action before and after log in or account creation.

  • $recipient_user_id
    String

    Follow our guidelines for $user_id values.

  • $subject
    String

    The subject of the message.

  • $content
    String

    The text content of the message.

$logout

Use $logout to record when a user logs out.

// Sample $logout event
{
  // Required Fields
  "$type"      : "$logout",
  "$api_key"   : "209f490k25lb9021",
  "$user_id"   : "billy_jones_301"
}
import sift

client = sift.Client("your_api_key_here")

# Sample $logout event
properties = {
  # Required Fields
  "$user_id"   : "billy_jones_301"
}

response = client.track("$logout", properties)
require "sift"

client = Sift::Client.new(:api_key => "your_api_key_here")

# Sample $logout event
properties = {
  # Required Fields
  "$user_id"   => "billy_jones_301"
}

response = client.track("$logout", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'your_api_key_here'));

// Sample $logout event
$properties = array(
  // Required Fields
  '$user_id'   => 'billy_jones_301'
);

$response = $client->track('$logout', $properties);
  • $type
    required · String

    "$logout"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

    The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid $user_id values here.

$chargeback

Use $chargeback to capture a chargeback reported on a transaction. This event can be called multiple times to record changes to the chargeback state.

Note: When you send a $chargeback event you also need to send a label event if you want to prevent the user from making another purchase.

// Sample $chargeback event
{
  // Required Fields
  "$type"              : "$chargeback",
  "$api_key"           : "your_api_key_here",
  "$user_id"           : "billy_jones_301",
  "$order_id"          : "ORDER-123124124",
  "$transaction_id"    : "719637215",

  // Recommended Fields
  "$chargeback_state"  : "$lost",
  "$chargeback_reason" : "$duplicate"
}
import sift

client = sift.Client("your_api_key_here")

# Sample $chargeback event
properties = {
  # Required Fields
  "$user_id"           : "billy_jones_301",
  "$order_id"          : "ORDER-123124124",
  "$transaction_id"    : "719637215",

  # Recommended Fields
  "$chargeback_state"  : "$lost",
  "$chargeback_reason" : "$duplicate"
}

response = client.track("$chargeback", properties)
require "sift"

client = Sift::Client.new(:api_key => "your_api_key_here")

# Sample $chargeback event
properties = {
  # Required Fields
  "$user_id"        => "billy_jones_301",
  "$order_id"       => "ORDER-123124124",
  "$transaction_id" => "719637215",

  # Recommended Fields
  "$chargeback_state"  => "$lost",
  "$chargeback_reason" => "$duplicate"
}

response = client.track("$chargeback", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'your_api_key_here'));

// Sample $chargeback event
$properties = array(
  // Required Fields
  '$user_id'        => 'billy_jones_301',
  '$order_id'       => 'ORDER-123124124',
  '$transaction_id' => '719637215',

  // Recommended Fields
  '$chargeback_state'  => '$lost',
  '$chargeback_reason' => '$duplicate'
);

$response = $client->track('$chargeback', $properties);
  • $type
    required · String

    "$chargeback"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

    The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid $user_id values here.

  • $order_id
    required · String

    The ID for the order that this chargeback is filed against. This field is not required if this chargeback was filed against a transaction with no $order_id.

  • $transaction_id
    required · String

    The ID for the transaction that this chargeback is filed against.

  • $chargeback_state
    String

    The current state of the chargeback.

    Allowed Values
    • "$received" "$accepted" "$disputed" "$won" "$lost"
  • $chargeback_reason
    String

    This field can be used to capture the reason given.

    Allowed Values
    • "$fraud" "$duplicate" "$product_not_received" "$product_unacceptable" "$other"

$order_status

Use $order_status to track the order processing workflow of a previously submitted order. For example, $order_status can be used to indicate that an order has been held for review, canceled due to suspected fraud, or fulfilled. This event can be called multiple times to record changes an order's status.

// Sample $order_status event
{
  // Required Fields
  "$type"             : "$order_status",
  "$api_key"          : "your_api_key_here",
  "$user_id"          : "billy_jones_301",
  "$order_id"         : "ORDER-28168441",
  "$order_status"     : "$canceled",

  // Optional Fields
  "$reason"           : "$payment_risk",
  "$source"           : "$manual_review",
  "$analyst"          : "someone@your-site.com",
  "$webhook_id"       : "3ff1082a4aea8d0c58e3643ddb7a5bb87ffffeb2492dca33",
  "$description"      : "Canceling because multiple fraudulent users on device"
}
import sift

client = sift.Client("your_api_key_here")

# Sample $order_status event
properties = {
  # Required Fields
  "$user_id"          : "billy_jones_301",
  "$order_id"         : "ORDER-28168441",
  "$order_status"     : "$canceled",

  # Optional Fields
  "$reason"           : "$payment_risk",
  "$source"           : "$manual_review", 
  "$analyst"          : "someone@your-site.com",
  "$webhook_id"       : "3ff1082a4aea8d0c58e3643ddb7a5bb87ffffeb2492dca33",
  "$description"      : "Canceling because multiple fraudulent users on device"
}

response = client.track("$order_status", properties)
require "sift"

client = Sift::Client.new(:api_key => "your_api_key_here")

# Sample $order_status event
properties = {
  # Required Fields
  "$user_id"          => "billy_jones_301",
  "$order_id"         => "ORDER-28168441",
  "$order_status"     => "$canceled",

  # Optional Fields
  "$reason"           => "$payment_risk",
  "$webhook_id"       => "3ff1082a4aea8d0c58e3643ddb7a5bb87ffffeb2492dca33",
  "$source"           => "$manual_review", 
  "$analyst"          => "someone@your-site.com",
  "$description"      => "Canceling because multiple fraudulent users on device"
}

response = client.track("$order_status", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'your_api_key_here'));

// Sample $order_status event
$properties = array(
  // Required Fields
  '$user_id'          => 'billy_jones_301',
  '$order_id'         => 'ORDER-28168441',
  '$order_status'     => '$canceled',

  // Optional Fields
  '$reason'           => '$payment_risk',
  '$source'           => '$manual_review', 
  '$analyst'          => 'someone@your-site.com',
  '$webhook_id'       => '3ff1082a4aea8d0c58e3643ddb7a5bb87ffffeb2492dca33',
  '$description'      => 'Canceling because multiple fraudulent users on device'
);

$response = $client->track('$order_status', $properties);
  • $type
    required · String

    "$order_status"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

    The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid $user_id values here.

  • $order_id
    required · String

    The ID for tracking this order in your system.

  • $order_status
    required · String

    Indicates the high-level state of the order.

    Allowed Values
    • "$approved" "$canceled" "$held" "$fulfilled" "$returned"
  • $reason
    String

    The reason for a cancellation.

    Allowed Values
    • "$payment_risk" "$abuse" "$policy" "$other"
  • $source
    String

    The source of a decision.

    Allowed Values
    • "$automated" "$manual_review"
  • $analyst
    String

    The analyst who made the decision, if manual.

  • $webhook_id
    String

    An alternative to using $source and $analyst, this is the ID of the Sift Science Action webhook that triggered the status change.

  • $description
    String

    Any additional information about this order status change.

Custom Events and Fields

Custom events and fields capture user behavior and differences not covered by our reserved events and fields. For example, a voice over IP (VOIP) business can create a custom event called make_call with custom fields that are relevant:

// Sample make_call event
{
  "$type"              : "make_call",
  "$api_key"           : "your_api_key_here",
  "$user_id"           : "billy_jones_301",
  "recipient_user_id"  : "marylee819",
  "call_duration"      : 4428
}
import sift

client = sift.Client("your_api_key_here")

# Sample make_call event
properties = {
  "$user_id"           : "billy_jones_301",
  "recipient_user_id"  : "marylee819",
  "call_duration"      : 4428
}

response = client.track("make_call", properties)
require "sift"

client = Sift::Client.new(:api_key => "your_api_key_here")

# Sample make_call event
properties = {
  "$user_id"           => "billy_jones_301",
  "recipient_user_id"  => "marylee819",
  "call_duration"      => 4428
}

response = client.track("make_call", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'your_api_key_here'));

// Sample make_call event
$properties = array(
  '$user_id'           => 'billy_jones_301',
  'recipient_user_id'  => 'marylee819',
  'call_duration'      => 4428
);


$response = $client->track('make_call', $properties);

For every custom event, three fields are required:

  • the $type field where you specify the name of the custom event you're creating. Note that the leading $ denotes reserved events, and may not be used in custom events. Custom event names may only include alphanumeric characters and _.
  • the $api_key field where you provide your REST API key.
  • the $user_id or, if not available, the $session_id which identifies the user taking this action.

For guidance on how to create custom events, see our Custom Events and Fields guide.

Custom Field Suffixes

The following the suffixes should be used for custom fields when relevant:

  • Email
    _email · String

    Sift performs a number of fraud detection algorithms on emails, including matching against throwaway email domains, and looking for similarity to known fraudsters in the past.


    Send any other emails associated with the user in field names like secondary_email.

  • Phone
    _phone · String

    Sift can perform lookups to identify country and region of phone numbers if the data is well formed. The contact phone number provided with the posting. Provide the phone number as a string starting with the country code. Use E.164 format or send in the standard national format of number's origin. For example: "+14155556041" ro "1-415-555-6041" for a U.S. number.


    Send phone numbers in field names like secondary_phone and mobile_phone.

  • Latitude
    _lat · Float

    Sent as a floating point number with at least two significant figures. Sift uses this data tocalculate location and movement, which are particularly useful for businesses where location is an important part of the transaction and for mobile transactions. Typically used along with longitude.


    Send latitudes in field names like dropoff_location_lat.

  • Longitude
    _lng · Float

    Sent as a floating point number with at least two significant figures. Sift uses this data to calculate location and movement, which are particularly useful for businesses where location is an important part of the transaction and for mobile transactions. Typically used along with latitude.


    Send longitudes in field names like dropoff_location_lng.

  • ID
    _id · String

    ID of a user or other entity. Valid characters in IDs are alphanumeric characters (without space) and:=, ., -, _, +, @, :, &, ^, %, !, $.


    Send IDs in field names like buyer_user_id or store_id.

  • Status
    _status · String

    Status of an event.

    Allowed Values
    • $success
    • $failure
    • $pending

    Many events (e.g., payment authorization, email verification) result in somepermission or verification state. End field names with _status to capture these permission states.

  • User-entered text
    _title, _desc, _message, _name, · String

    When users enter text in a form, send with one of the supported suffixes to take advantage of additional machine learning features.


    Send user-entered text in field names like post_title, job_desc, profile_message, or user_name.

Reserved Fields

Reserved fields are fields that begin with a $. These are fields that, due to sending in a consistent format across customers, we do lots of analysis on. We also share learning across our global network for these fields, giving you a big added benefit.

Note: When you don't have a value for a given field, send the value as null, nil, None, etc, or omit the field altogether.

Required

The following reserved fields are required in every event.

  • $api_key
    String

    Your Sift REST API key.

  • $user_id
    String

    The user’s internal account ID. This field is required on all events performed by the user while logged in. Users without an assigned $user_id will not show up in the console. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs. Only the following characters may be used:a-z,A-Z,0-9,=, ., -, _, +, @, :, &, ^, %, !, $

  • $session_id
    required iF no User ID provided · String

    The user's current session ID, used to tie a user's action before and after log in or account creation.

  • $type
    String

    The name of the event, for example $create_order.

Optional

Each reserved event lists additional reserved fields that add accuracy to your fraud predictions. Send as many as you can. In addition to the reserved fields listed with each event, the following reserved fields can be sent in any event, including custom events.

  • $ip
    String

    IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.

  • $time
    Integer

    Represents the time the event occured in your system. Send as a UNIX timestamp in milliseconds as shown in the historical backfill tutorial.

Address

The Address field type represents a physical address, such as a billing or shipping address. The value must be a nested object with the appropriate address subfields. We extract many geolocation features from these values. An address is represented as a nested JSON object.


Fields of this type: $billing_address, $shipping_address

// Sample $address field value
"$billing_address"  : {  // or "$shipping_address"
  "$name"         : "Bill Jones",
  "$phone"        : "1-415-555-6041",
  "$address_1"    : "2100 Main Street",
  "$address_2"    : "Apt 3B",
  "$city"         : "New London",
  "$region"       : "New Hampshire",
  "$country"      : "US",
  "$zipcode"      : "03257"
}
# Sample $address field value
billing_address  = {  # or shipping_address
  "$name"         : "Bill Jones",
  "$phone"        : "1-415-555-6041",
  "$address_1"    : "2100 Main Street",
  "$address_2"    : "Apt 3B",
  "$city"         : "New London",
  "$region"       : "New Hampshire",
  "$country"      : "US",
  "$zipcode"      : "03257"
}
# Sample $address field value
billing_address  = {  # or shipping_address
  "$name"         => "Bill Jones",
  "$phone"        => "1-415-555-6041",
  "$address_1"    => "2100 Main Street",
  "$address_2"    => "Apt 3B",
  "$city"         => "New London",
  "$region"       => "New Hampshire",
  "$country"      => "US",
  "$zipcode"      => "03257"
}
// Sample $address field value
$billingAddress  = array(  // or $shippingAddress
  '$name'         => 'Bill Jones',
  '$phone'        => '1-415-555-6041',
  '$address_1'    => '2100 Main Street',
  '$address_2'    => 'Apt 3B',
  '$city'         => 'New London',
  '$region'       => 'New Hampshire',
  '$country'      => 'US',
  '$zipcode'      => '03257'
);

Subfields in Address

  • $name
    String

    Provide the full name associated with the address here. Concatenate first name and last name together if you collect them separately in your system.

  • $address_1
    String

    Address first line, e.g., "2100 Main Street".

  • $address_2
    String

    Address second line, e.g., "Apt 3B".

  • $city
    String

    The city or town name.

  • $region
    String

    The region portion of the address. In the USA, this corresponds to the state.

  • $country
    String

    The ISO-3166 country code for the billing address.

  • $zipcode
    String

    The postal code associated with the address, e.g., "90210". Send +4 postal codes with a '-', e.g. "90210-3344"

  • $phone
    String

    The phone number associated with this address. Provide the phone number as a string starting with the country code. Use E.164 format or send in the standard national format of number's origin. For example: "+14155556041" or "1-415-555-6041" for a U.S. number.

Item

The Item field type represents a product or service for sale in your business. The value must be a nested object with the appropriate item subfields. Generally used in the $add_item_to_cart and $remove_item_from_cart events. An item is representedas a nested JSON object.

// Example 1
"$item" : {
  "$item_id"        : "B004834GQO",
  "$product_title"  : "The Slanket Blanket-Texas Tea",
  "$price"          : 39990000,  // $39.99
  "$currency_code"  : "USD",
  "$upc"            : "67862114510011",
  "$sku"            : "004834GQ",
  "$brand"          : "Slanket",
  "$manufacturer"   : "Slanket",
  "$category"       : "Blankets & Throws",
  "$tags"           : ["Awesome", "Wintertime specials"],
  "$color"          : "Texas Tea",
  "$quantity"       : 6
}

// Example 2
"$item" : {
  "$item_id"        : "10101042",
  "$product_title"  : "Delivering Happiness [eBook edition]",
  "$price"          : 6990000, // $6.99
  "$currency_code"  : "CDN",
  "$isbn"           : "0446576220",
  "$sku"            : "10101042",
  "$brand"          : "Writers of the Round Table Press",
  "$manufacturer"   : "eBook Digital Services, Inc.",
  "$category"       : "Business books",
  "$tags"           : ["reprint", "paperback", "Tony Hsieh"],
  "$quantity"       : 1
}
# Example 1
item = {
  "$item_id"        : "B004834GQO",
  "$product_title"  : "The Slanket Blanket-Texas Tea",
  "$price"          : 39990000,  # $39.99
  "$currency_code"  : "USD",
  "$upc"            : "67862114510011",
  "$sku"            : "004834GQ",
  "$brand"          : "Slanket",
  "$manufacturer"   : "Slanket",
  "$category"       : "Blankets & Throws",
  "$tags"           : ["Awesome", "Wintertime specials"],
  "$color"          : "Texas Tea",
  "$quantity"       : 6
}

# Example 2
item = {
  "$item_id"        : "10101042",
  "$product_title"  : "Delivering Happiness [eBook edition]",
  "$price"          : 6990000, # $6.99
  "$currency_code"  : "CDN",
  "$isbn"           : "0446576220",
  "$sku"            : "10101042",
  "$brand"          : "Writers of the Round Table Press",
  "$manufacturer"   : "eBook Digital Services, Inc.",
  "$category"       : "Business books",
  "$tags"           : ["reprint", "paperback", "Tony Hsieh"],
  "$quantity"       : 1
}
# Example 1
item = {
  "$item_id"        => "B004834GQO",
  "$product_title"  => "The Slanket Blanket-Texas Tea",
  "$price"          => 39990000,  # $39.99
  "$currency_code"  => "USD",
  "$upc"            => "67862114510011",
  "$sku"            => "004834GQ",
  "$brand"          => "Slanket",
  "$manufacturer"   => "Slanket",
  "$category"       => "Blankets & Throws",
  "$tags"           => ["Awesome", "Wintertime specials"],
  "$color"          => "Texas Tea",
  "$quantity"       => 6
}

# Example 2
item = {
  "$item_id"        => "10101042",
  "$product_title"  => "Delivering Happiness [eBook edition]",
  "$price"          => 6990000, # $6.99
  "$currency_code"  => "CDN",
  "$isbn"           => "0446576220",
  "$sku"            => "10101042",
  "$brand"          => "Writers of the Round Table Press",
  "$manufacturer"   => "eBook Digital Services, Inc.",
  "$category"       => "Business books",
  "$tags"           => ["reprint", "paperback", "Tony Hsieh"],
  "$quantity"       => 1
}
// Example 1
$item = array(
  '$item_id'        => 'B004834GQO',
  '$product_title'  => 'The Slanket Blanket-Texas Tea',
  '$price'          => 39990000,  // $39.99
  '$currency_code'  => 'USD',
  '$upc'            => '67862114510011',
  '$sku'            => '004834GQ',
  '$brand'          => 'Slanket',
  '$manufacturer'   => 'Slanket',
  '$category'       => 'Blankets & Throws',
  '$tags'           => ['Awesome', 'Wintertime specials'],
  '$color'          => 'Texas Tea',
  '$quantity'       => 6
);

// Example 2
$item = array(
  '$item_id'        => '10101042',
  '$product_title'  => 'Delivering Happiness [eBook edition]',
  '$price'          => 6990000, // $6.99
  '$currency_code'  => 'CDN',
  '$isbn'           => '0446576220',
  '$sku'            => '10101042',
  '$brand'          => 'Writers of the Round Table Press',
  '$manufacturer'   => 'eBook Digital Services, Inc.',
  '$category'       => 'Business books',
  '$tags'           => ['reprint', 'paperback', 'Tony Hsieh'],
  '$quantity'       => 1
);

Subfields in Item

  • $item_id
    String

    The item's unique identifier according to your systems. Use the same ID that you would use to look up items on your website's database.

  • $product_title
    String

    The item's name, e.g., "Men's Running Springblade Drive Shoes, US10".

  • $price
    Integer

    The item unit price in micros, in the base unit of the $currency_code. 1 cent = 10,000 micros.$1.23 USD = 123 cents = 1,230,000 micros.

  • $currency_code
    String

    ISO-4217 currency code for the price.

  • $quantity
    Integer

    Quantity of the item.

  • $upc
    String

    If the item has a Universal Product Code (UPC), provide it here.

  • $sku
    String

    If the item has a Stock-keeping Unit ID (SKU), provide it here.

  • $isbn
    String

    If the item is a book with an International Standard Book Number (ISBN), provide it here.

  • $brand
    String

    The brand name of the item.

  • $manufacturer
    String

    Name of the item's manufacturer.

  • $category
    String

    The category this item is listed under in your business. e.g., "kitchen appliance", "menswear > pants".

  • $tags
    Array of Strings

    The tags used to describe this item in your business. e.g., "funny", "halloween".

  • $color
    String

    The color of the item.

  • $size
    String

    The size of the item.

Payment Method

The payment_method field type represents information about thepayment methods provided by the user. The value must be a nested object with the appropriate item subfields for the given payment method. Generally usedwith the $create_order or $transaction events.

// A Credit Card Payment and a Gift Card used together,
// as $payment_methods in $create_order.
// Note: A $create_order event can have multiple payment
// methods, and thus takes an array of objects.
"$payment_methods" : [
  {
    "$payment_type"    : "$credit_card",
    "$payment_gateway" : "$stripe",
    "$card_bin"        : "542486",
    "$card_last4"      : "4242",
    "$cvv_result_code" : "M",
    "$avs_result_code" : "Y",
    "$stripe_address_line1_check" : "pass",
    "$stripe_address_line2_check" : "pass",
    "$stripe_address_zip_check"   : "pass"
  },
  {
    "$payment_type"    : "$gift_card"
  }
]

// A Electronic Fund Transfer Payment,
// as it would appear in a $create_order event.
"$payment_methods" : [
  {
    "$payment_type"  : "$electronic_fund_transfer",
    "$routing_number"  : "021001088"
  }
]

// A Paypal Payment, as it would appear 
// in a $create_order event.
"$payment_methods" : [
  {
    "$payment_type"  : "$third_party_processor",
    "$payment_gateway" : "$paypal",
    "$paypal_payer_id" : "7E7MGXCWKTKK2",
    "$paypal_payer_email" : "bill@gmail.com",
  }
]

// A Points or Alternative Currency Payment,
// as it would appear in a $transaction event.
// Note: There is one payment method per $transaction.
"$payment_method" : {
  "$payment_type"  : "$points"
}
# A Credit Card Payment and a Gift Card used together,
# as $payment_methods in $create_order.
# Note: A $create_order event can have multiple payment
# methods, and thus takes an array of objects.
payment_methods = [
  {
    "$payment_type"    : "$credit_card",
    "$payment_gateway" : "$stripe",
    "$card_bin"        : "542486",
    "$card_last4"      : "4242",
    "$cvv_result_code" : "M",
    "$avs_result_code" : "Y",
    "$stripe_address_line1_check" : "pass",
    "$stripe_address_line2_check" : "pass",
    "$stripe_address_zip_check"   : "pass"
  },
  {
    "$payment_type"    : "$gift_card"
  }
]

# A Electronic Fund Transfer Payment,
# as it would appear in a $create_order event.
payment_methods = [
  {
    "$payment_type"  : "$electronic_fund_transfer",
    "$routing_number"  : "021001088"
  }
]

# A Paypal Payment, as it would appear 
# in a $create_order event.
payment_methods = [
  {
    "$payment_type"  : "$third_party_processor",
    "$payment_gateway" : "$paypal",
    "$paypal_payer_id" : "7E7MGXCWKTKK2",
    "$paypal_payer_email" : "bill@gmail.com",
  }
]

# A Points or Alternative Currency Payment,
# as it would appear in a $transaction event.
# Note: There is one payment method per $transaction.
payment_method = {
  "$payment_type"  : "$points"
}
# A Credit Card Payment and a Gift Card used together,
# as $payment_methods in $create_order.
# Note: A $create_order event can have multiple payment
# methods, and thus takes an array of objects.
payment_methods = [
  {
    "$payment_type"    => "$credit_card",
    "$payment_gateway" => "$stripe",
    "$card_bin"        => "542486",
    "$card_last4"      => "4242",
    "$cvv_result_code" => "M",
    "$avs_result_code" => "Y",
    "$stripe_address_line1_check" => "pass",
    "$stripe_address_line2_check" => "pass",
    "$stripe_address_zip_check"   => "pass"
  },
  {
    "$payment_type"    => "$gift_card"
  }
]

# A Electronic Fund Transfer Payment,
# as it would appear in a $create_order event.
payment_methods = [
  {
    "$payment_type"  => "$electronic_fund_transfer",
    "$routing_number"  => "021001088"
  }
]

# A Paypal Payment, as it would appear 
# in a $create_order event.
payment_methods = [
  {
    "$payment_type"  => "$third_party_processor",
    "$payment_gateway" => "$paypal",
    "$paypal_payer_id" => "7E7MGXCWKTKK2",
    "$paypal_payer_email" => "bill@gmail.com",
  }
]

# A Points or Alternative Currency Payment,
# as it would appear in a $transaction event.
# Note: There is one payment method per $transaction.
payment_method = {
  "$payment_type"  => "$points"
}
// A Credit Card Payment and a Gift Card used together,
// as $payment_methods in $create_order.
// Note: A $create_order event can have multiple payment
// methods, and thus takes an array of objects.
$paymentMethods = array(
  array(
    '$payment_type'    => '$credit_card',
    '$payment_gateway' => '$stripe',
    '$card_bin'        => '542486',
    '$card_last4'      => '4242',
    '$cvv_result_code' => 'M',
    '$avs_result_code' => 'Y',
    '$stripe_address_line1_check' => 'pass',
    '$stripe_address_line2_check' => 'pass',
    '$stripe_address_zip_check'   => 'pass'
  ),
  array(
    '$payment_type'    => '$gift_card'
  )
);

// A Electronic Fund Transfer Payment,
// as it would appear in a $create_order event.
$paymentMethods = array(
  array(
    '$payment_type'  => '$electronic_fund_transfer',
    '$routing_number'  => '021001088'
  )
);

// A Paypal Payment, as it would appear 
// in a $create_order event.
"$payment_methods" : [
  {
    "$payment_type"  : "$third_party_processor",
    "$payment_gateway" : "$paypal",
    "$paypal_payer_id" : "7E7MGXCWKTKK2",
    "$paypal_payer_email" : "bill@gmail.com",
  }
]



// A Points or Alternative Currency Payment,
// as it would appear in a $transaction event.
// Note: There is one payment method per $transaction.
$paymentMethod = array(
  '$payment_type'  => '$points'
);

Subfields in Payment Method

  • $payment_type
    String
    Allowed Values
    • $cash$check$credit_card$crypto_currency$electronic_fund_transfer$financing$gift_card$interac$invoice$money_order$masterpass$points$store_credit$third_party_processor$voucher

    If your payment system is not covered by one of the values above, contact us.

  • $payment_gateway
    String

    The payment processor used for this payment.

    Allowed Values
    • $adyen$affirm$alipay$altapay$amazon_payments$astropay$authorizenet$avangate$balanced$banwire$beanstream$blockchain$bluepay$bluesnap$braintree$buckaroo$ccavenue$chain_commerce$chase_paymentech$checkoutcom$cielo$cofinoga$coinbase$collector$compropago$conekta$cuentadigital$culqi$cybersource$datacash$debitway$dibs$digital_river$dragonpay$ecopayz$edgil_payway$elavon$empcorp$epayeu$eprocessing_network$euteller$eway$first_atlantic_commerce$first_data$g2apay$giropay$globalcollect$global_payments$global_payways$gocardless$hdfc_fssnet$hipay$ingenico$internetsecure$intuit_quickbooks_payments$iugu$jabong$klarna$logon$mastercard_payment_gateway$maxipago$mercadopago$merchant_esolutions$mirjeh$moip$mollie$moneris_solutions$moneygram$mundipagg$neteller$nmi$ogone$okpay$omise$openpaymx$optimal_payments$pagar_me$pagofacil$pagseguro$paxum$payeer$payfast$payflow$paygate$paymentwall$payment_express$paymill$payone$paypal$paysera$paysimple$paystation$paytrace$paytrail$payture$payu$payulatam$payza$peach_payments$perfect_money$pinpayments$pivotal_payments$planet_payment$princeton_payment_solutions$przelewy24$psigate$qiwi$quickpay$raberil$ratepay$rbkmoney$rede$redpagos$redsys$rewardspay$rietumu$rocketgate$safetypay$sagepay$securepay$sermepa$shopify_payments$simplify_commerce$skrill$smart2pay$smartcoin$sofort$sps_decidir$stone$stripe$swedbank$synapsepay$telerecargas$tnspay$towah$tpaga$transact_pro$transfirst$trustcommerce$trustly$twoc2p$twocheckout$unionpay$usa_epay$vantiv$venmo$veritrans$versapay$vesta$vindicia$virtual_card_services$visa$vme$webmoney$webpay_oneclick$wepay$western_union$wirecard$worldpay$worldspan$xipay$yandex_money

    If the payment gateway you use is not supported, please contact support and we'll add it.

  • $card_bin
    String

    The first six digits of the credit card number. These numbers contain information about the card issuer, the geography and other card details.

  • $card_last4
    String

    The last four digits of the credit card number.

  • $avs_result_code
    String

    Response code from the AVS address verification system. Used in payments involving credit cards.

  • $cvv_result_code
    String

    Response code from the credit card company indicating if the CVV number entered matches the number on record. Used in payments involving credit cards.

  • $verification_status
    String

    Use $verification_status to indicate the payment method has been verified. The value can be $success, $failure or $pending. For instance, if you request payment method verification from a payment processor and receive a failure set the value to $failure.

    For instance, if you request payment method verification from a payment processor and receive a failureset the value to $failure.

  • $routing_number
    String

    This is the ABA routing number or SWIFT code used.

  • $decline_reason_code
    String

    In case of a declined payment, response code received from the payment processor indicating the reason for the decline.

  • $paypal_payer_id
    String

    Payer ID returned by Paypal.

  • $paypal_payer_email
    String

    Payer email address returned by Paypal.

  • $paypal_payer_status
    String

    Payer status returned by Paypal.

  • $paypal_address_status
    String

    Payer address status returned by Paypal.

  • $paypal_protection_eligibility
    String

    Seller protection eligibility returned by Paypal.

  • $paypal_payment_status
    String

    Payment status returned by Paypal.

  • $stripe_cvc_check
    String

    CVC verification result returned by Stripe.

  • $stripe_address_line1_check
    String

    Address line 1 verification result returned by Stripe.

  • $stripe_address_line2_check
    String

    Address line 2 verification result returned by Stripe.

  • $stripe_address_zip_check
    String

    Address zip code verification result returned by Stripe.

  • $stripe_funding
    String

    Funding source returned by Stripe.

  • $stripe_brand
    String

    Card brand returned by Stripe.

Promotion

The Promotion field type generically models different kinds of promotions such as referrals, coupons, free trials, etc. The value must be a nested JSON object which you populate with the appropriate information to describe the promotion. Not all sub-fields will likely apply to a given promotion. Populate only those that apply.

A promotion can be added when creating or updating an account, creating or updating an order, or on its own using the $add_promotion event. The promotion object supports both monetary (e.g. $25 coupon on first order) and non-monetary (e.g. "1000 in game points to refer a friend").

// Example of a promotion for monetary discounts off goods or services
{
  "$promotion_id"      : "SPRING-1009",
  "$status"            : "$failed",
  "$failure_reason"    : "$already_used",
  "$description"       : "Spring coupon",
  "$discount"          : {
    "$percentage_off"          : 0.2,  // 20% off
    "$amount"                  : 115940000,  // $115.94
    "$currency_code"           : "USD",
    "$minimum_purchase_amount" : 50000000  // $50
  }
}

// Example of a promotion for account credits
{
  "$promotion_id"      : "NewCustomerReferral2016",
  "$status"            : "$success",
  "$description"       : "Signup bonus for new customers in 2016",
  "$referrer_user_id"  : "john_smith_0123",
  "$credit_point"      : {
    "$amount"             : 5000,
    "$credit_point_type"  : "character xp points"
  }
}
# Example of a promotion for monetary discounts off goods or services
{
  "$promotion_id"      : "SPRING-1009",
  "$status"            : "$failed",
  "$failure_reason"    : "$already_used",
  "$description"       : "Spring coupon",
  "$discount"          : {
    "$percentage_off"          : 0.2,  # 20% off
    "$amount"                  : 115940000,  # $115.94
    "$currency_code"           : "USD",
    "$minimum_purchase_amount" : 50000000  # $50
  }
}

# Example of a promotion for account credits
{
  "$promotion_id"      : "NewCustomerReferral2016",
  "$status"            : "$success",
  "$description"       : "Signup bonus for new customers in 2016",
  "$referrer_user_id"  : "john_smith_0123",
  "$credit_point"      : {
    "$amount"             : 5000,
    "$credit_point_type"  : "character xp points"
  }
}
# Example of a promotion for monetary discounts off goods or services
{
  "$promotion_id"      => "SPRING-1009",
  "$status"            => "$failed",
  "$failure_reason"    => "$already_used",
  "$description"       => "Spring coupon",
  "$discount"          => {
    "$percentage_off"          => 0.2,  # 20% off
    "$amount"                  => 115940000,  # $115.94
    "$currency_code"           => "USD",
    "$minimum_purchase_amount" => 50000000  # $50
  }
}

# Example of a promotion for account credits
{
  "$promotion_id"      => "NewCustomerReferral2016",
  "$status"            => "$success",
  "$description"       => "Signup bonus for new customers in 2016",
  "$referrer_user_id"  => "john_smith_0123",
  "$credit_point"      => {
    "$amount"             => 5000,
    "$credit_point_type"  => "character xp points"
  }
}
// Example of a promotion for monetary discounts off goods or services
array(
  '$promotion_id'      => 'SPRING-1009',
  '$status'            => '$failed',
  '$failure_reason'    => '$already_used',
  '$description'       => 'Spring coupon',
  '$discount'          => array(
    '$percentage_off'          => 0.2,  // 20% off
    '$amount'                  => 115940000,  // $115.94
    '$currency_code'           => 'USD',
    '$minimum_purchase_amount' => 50000000  // $50
  )
);

// Example of a promotion for account credits
array(
  '$promotion_id'      => 'NewCustomerReferral2016',
  '$status'            => '$success',
  '$description'       => 'Signup bonus for new customers in 2016',
  '$referrer_user_id'  => 'john_smith_0123',
  '$credit_point'      => array(
    '$amount'             => 5000,
    '$credit_point_type'  => 'character xp points'
  )
);

Subfields in Promotion

  • $promotion_id
    String

    The ID within your system that you use to represent this promotion. This ID is ideally unique to the promotion across users (e.g. "BackToSchool2016").

  • $status
    String

    The status of the addition of promotion to an account. Best used with the $add_promotion event. This way you can pass to Sift Science both successful and failed attempts when using a promotion. May be useful in spotting potential abuse.

    Allowed Values
    • $success $failure
  • $failure_reason
    String

    When adding a promotion fails, use this to describe why it failed.

    Allowed Values
    • $already_used $invalid_code $not_applicable $expired
  • $description
    String

    Freeform text to describe the promotion.

  • $referrer_user_id
    String

    The unique account ID of the user who referred the user to this promotion. Note: User IDs are case sensitive.

  • $discount
    Discount

    The $discount field type generically models monetary discounts that are associated with a promotion (e.g. $25 off an order of $100 or more, 10% off, etc). Most promotions likely require a discount object or credit_point object to describe them, though both can be set for a given promotion.

  • $credit_point
    Credit Point

    The credit_point field type generically models monetary and non-monetary rewards (e.g. in-game currency, stored account value, MBs storage, frequent flyer miles, etc.) for a promotion. Most promotions likely require a credit_point object or discount object to describe them, though both can be set for a given promotion.

Discount

The Discount field type generically models monetary discounts that are associated with a promotion (e.g. $25 off an order of $100 or more, 10% off, etc). Discounts are usually used for promotions that apply at the order level. The value must be a nested JSON object populated with the appropriate information to describe the discount. Not all sub-fields will likely apply to a given discount. Populate only those that apply.

A discount is an object that gets included as part of promotion object. Learn more about promotions.

// Example of a monetary discount off goods or services
{
  "$percentage_off"          : 0.2,  // 20% off
  "$amount"                  : 115940000,  // $115.94
  "$currency_code"           : "USD",
  "$minimum_purchase_amount" : 50000000  // $50
}
# Example of a monetary discount off goods or services
{
  "$percentage_off"          : 0.2,  # 20% off
  "$amount"                  : 115940000,  # $115.94
  "$currency_code"           : "USD",
  "$minimum_purchase_amount" : 50000000  # $50
}
# Example of a monetary discount off goods or services
{
  "$percentage_off"          => 0.2,  # 20% off
  "$amount"                  => 115940000,  # $115.94
  "$currency_code"           => "USD",
  "$minimum_purchase_amount" => 50000000  # $50
}
// Example of a monetary discount off goods or services
array(
  '$percentage_off'          => 0.2,  // 20% off
  '$amount'                  => 115940000,  // $115.94
  '$currency_code'           => 'USD',
  '$minimum_purchase_amount' => 50000000  // $50
);

Subfields in Discount

  • $percentage_off
    Float

    The percentage discount. If the discount is 10% off, you would send "0.1".

  • $amount
    Integer

    The amount of the discount that the promotion offers in micros in the base unit of the $currency_code. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.

  • $currency_code
    String

    ISO-4217 currency code for the amount. e.g., USD, CAD, HKD. If your site uses alternative currencies, like bitcoin or points systems, specify that here.

  • $minimum_purchase_amount
    Integer

    The minimum amount someone must spend in order for the promotion to be applied. The amount should be in micros in the base unit of the $currency_code. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.

Credit Point

The Credit Point field type generically models monetary and non-monetary rewards (e.g. in-game currency, stored account value, MBs storage, frequent flyer miles, etc) associated with a promotion. Credit points are usually used for promotions that apply at the account level. The value must be a nested JSON object populated with the appropriate information to describe the credit_point. All values are required.

A credit_point is an object that gets included as part of promotion object. Learn more about promotions.

// Example of a credit point for an in-game currency
{
  "$amount"             : 5000,
  "$credit_point_type"  : "character xp points"
}
# Example of a credit point for an in-game currency
{
  "$amount"             : 5000,
  "$credit_point_type"  : "character xp points"
}
# Example of a credit point for an in-game currency
{
  "$amount"             => 5000,
  "$credit_point_type"  => "character xp points"
}
// Example of a credit point for an in-game currency
array(
  '$amount'             => 5000,
  '$credit_point_type'  => 'character xp points'
);

Subfields in Credit Point

  • $amount
    Required · Integer

    The amount of credits the promotion is worth.

  • $credit_point_type
    Required · String

    The type of credit point. Particularly useful if you have multiple types of credit points that you give out. Enables us to distinguish amongst them to find patterns (e.g. days of free service, karma, frequent flyer miles, MBs of storage, etc.).

Error Codes

A successful API request will respond with an HTTP 200. An invalid API request will respond with an HTTP 400. The response body will be a JSON object describing why the request failed.

Any non-zero status indicates an error

{
    "status" : 51,         // Non-zero status indicates an error!
    "error_message" : "Invalid API Key. Please check your credentials and try again.",
    "time" : 1327604222,   // When we received the original request (as seconds since the epoch)
    "request" : "{ \"$api_key\": \"XXXXXXXXXXX\", \"$type\": \"$capture_payment\"... }"
}
# To check if the call was successfull:
response.is_ok() # returns true on successful calls, false on failed score requests.

response.api_status         # returns Sift Error Code, 51 in this case.

response.api_error_message  # returns the error message associated with the api_status, "Invalid API Key. Please check your credentials and try again." in this case.
# To check if the call was successfull:
response.ok? # returns true on successful calls, false on failed score requests.

response.api_status         # returns Sift Error Code, 51 in this case.

response.api_error_message  # returns the error message associated with the api_status, "Invalid API Key. Please check your credentials and try again." in this case.
// To check if the call was successfull:
response->isOk() // returns true on successful calls, false on failed score requests.

response->apiStatus         // returns Sift Error Code, 51 in this case.

response->apiErrorMessage  // returns the error message associated with the api_status, "Invalid API Key. Please check your credentials and try again." in this case.

Possible status codes

  • -4

    Service currently unavailable. Please try again later.

  • -3

    Server-side timeout processing request. Please try again later.

  • -2

    Unexpected server-side error

  • -1

    Unexpected server-side error

  • 0

    Success

  • 51

    Invalid API key

  • 52

    Invalid characters in field name

  • 53

    Invalid characters in field value

  • 55

    Missing required field

  • 56

    Invalid JSON in request

  • 57

    Invalid HTTP body

  • 60

    Rate limited

  • 104

    Invalid API version

  • 105

    Not a valid reserved field


If our servers are dealing with unexpected problems, you'll likely see an HTTP 500 response.

Partner API Guide

The Partner API allows e-commerce platforms, agencies, and payment gateways/processors to programmatically create Sift Science accounts for their own merchants, and to interact with those accounts on behalf of their merchants.

Client libraries

We have written client libraries in several languages to make using this API even easier.

Capabilities

Partners can:

  • Create new Sift Science accounts on behalf of their customers
  • List the set of accounts they have created, along with the API keys for those accounts.
  • Set an HTTP notification threshold and callback endpoint which will apply across all accounts they have created.
  • Submit events and labels, or request scores on behalf of their customers

Access

Before using the Partner API, please contact our support team and ask to be enabled as a partner.

The operations below will require two credentialing pieces of information:

  • The Partner Account ID, which can be found in the "Settings" section of the Sift Console.
  • The partner's Production REST API key which can be found in the "API Keys" console page.

Terminology

In the following document "partner" will be the organization which is creating and using Sift accounts on behalf of a group of parties. We'll refer to those other parties as "merchants".

Authentication

All authentication is based on API keys.

When acting as a Partner

When doing partner-level or administrative actions (i.e. creating new accounts, configuring notifications, or listing merchant accounts), the partner's API key should be included in the request header under the Authorization key, with the Basic scheme. See the Account Creation curl example below for a concrete example.

When acting on behalf of a Merchant

When performing actions at the level of a specific existing merchant account, use the API key associated with that merchant (which is included in the response when the merchant's Sift account is first created). When using the existing Events API or Labels API this will mean placing this API key into the JSON body. When making requests against the Scores API, the API key will appear as a query parameter.

Configure notifications

PUT   /v3/accounts/{id}/config

Webhooks/HTTP Notifications allow merchants to receive notifications to a specified URL when a score is above a provided threshold. Ordinarily these settings are configured independently for each account. However, rather than require that partners configure these settings for each merchant account under their control, all merchants created by a given partner will defer to the notification configuration on the originating partner account.

URL as a Template

Partners should provide a notification url which is structured as a template, containing a single instance of %s. On individual notification calls, the %s will be replaced by the account id of the merchant. For example, if the partner's notification url is set to http://api.partner.com/notify?account=%s, and the merchant account with id54125bfee4b0beea0dfebfb9 triggers a notification, it will be POSTed to http://api.partner.com/notify?account=54125bfee4b0beea0dfebfb9.

In order to set these values, PUT a JSON body to https://partner.siftscience.com/v3/accounts/{id}/config where id is the id of the partner's account

Example Request

After this request, any time we score a user above 0.5 we will make a POST request to https://api.partner.com/notify?account={merchant_id}.

$ curl -XPUT 'https://api3.siftscience.com/v3/accounts/529cee26fe6b7cf31f00116e/config' \ -H 'Content-Type: application/json' \ -u {API_KEY}: \ -d '{ "http_notification_url" : "https://api.partner.com/notify?account=%s", "http_notification_threshold" : 0.5 }'
Example Response
{ "http_notification_url" : "https://api.partner.com/notify?account=%s", "http_notification_threshold" : 0.5 }

Parameters

  • id
    required · string

    The account id of the merchant whose account you would like to configure

Entity

  • http_notification_url
    string

    The URL to which HTTP notifications will be POSTed. Partners must include %s somewhere in the URL string. This will be replaced by the merchant's account id.

  • http_notification_threshold
    number

    The threshold (in the range 0 to 1) of Sift score above which HTTP notifications will be triggered.

Response

  • http_notification_url
    string

    The URL to which HTTP notifications will be POSTed. Partners must include %s somewhere in the URL string. This will be replaced by the merchant's account id.

  • http_notification_threshold
    number

    The threshold (in the range 0 to 1) of Sift score above which HTTP notifications will be triggered.

Listing accounts

GET   /v3/partners/{id}/accounts

This endpoint allows you to list all of the accounts you have created for your users.

Example Request

$ curl -XGET 'https://api3.siftscience.com/v3/partners/541752da89f0b8620624f17f/accounts' \ -H 'Content-Type: application/json' \ -u {API_KEY}:
Example Response
{ "schema" : "partner_account.json", "total_results" : 1, "data" : [ { "account_id" : "545d48e84d6963acf1000000", "production" : { "api_keys" : [ { "id" : "545d491c4d6963acf12d0000", "state" : "ACTIVE", "key" : "34fc67af86069804" } ], "beacon_keys" : [ { "id" : "545d491c4d6963acf12e0000", "state" : "ACTIVE", "key" : "735ea65235" } ] }, "sandbox" : { "api_keys" : [ { "id" : "545d491c4d6963acf1300000", "state" : "ACTIVE", "key" : "1f46f7f726607c1b" } ], "beacon_keys" : [ { "id" : "545d491c4d6963acf1310000", "state" : "ACTIVE", "key" : "63d0d7605c" } ] } } ] }

Parameters

  • id
    required · string

    Your partner account id

Response

  • schema
    required · string

    Reference to the json schema that the data in the array conforms to

  • data
    required · array

    A list of data items

    • production
      required · object

      API keys for the production account

      • api_keys
        array

        Keys used to access Sift's REST APIs

        • id
          string

          Identifier for this API keys

        • state
          string

          State of the API key. Only ACTIVE keys can make requests.

          Allowed Values
          • ACTIVEThis key is active, and may be used for API requests.
          • DISABLEDThis key has been disabled, and will not be accepted unless reactivated.
          • DELETED
        • key
          string

          The actual key to be used for authenticated API requests

      • beacon_keys
        array

        Keys used for the JavaScript integration

        • id
          string

          Identifier for this API keys

        • state
          string

          State of the API key. Only ACTIVE keys can make requests.

          Allowed Values
          • ACTIVEThis key is active, and may be used for API requests.
          • DISABLEDThis key has been disabled, and will not be accepted unless reactivated.
          • DELETED
        • key
          string

          The actual key to be used for authenticated API requests

    • sandbox
      required · object

      API keys for the production account

      • api_keys
        array

        Keys used to access Sift's REST APIs

        • id
          string

          Identifier for this API keys

        • state
          string

          State of the API key. Only ACTIVE keys can make requests.

          Allowed Values
          • ACTIVEThis key is active, and may be used for API requests.
          • DISABLEDThis key has been disabled, and will not be accepted unless reactivated.
          • DELETED
        • key
          string

          The actual key to be used for authenticated API requests

      • beacon_keys
        array

        Keys used for the JavaScript integration

        • id
          string

          Identifier for this API keys

        • state
          string

          State of the API key. Only ACTIVE keys can make requests.

          Allowed Values
          • ACTIVEThis key is active, and may be used for API requests.
          • DISABLEDThis key has been disabled, and will not be accepted unless reactivated.
          • DELETED
        • key
          string

          The actual key to be used for authenticated API requests

    • account_id
      required · string

  • has_more
    boolean

    Whether there are more results

  • next_ref
    string

    A link to the next set of data, if available

  • total_results
    integer

    The total number of results, if known

Device Fingerprinting Integration Guide

The Device Fingerprinting API is a separate product from our machine learning products. Our machine learning uses device fingerprints in making risk assessments and connecting fraudulent users, but does not provide access to this API. For an overview and a use case example, see our Device Fingerprinting API tutorial.

Using the Device Fingerprinting API requires that you have installed our JavaScript snippet.

Device Information

GET   /v3/accounts/{accountId}/devices/{deviceId}

You can use the data returned from this endpoint to help investigate suspicious devices. Data like the first time you've seen a device in addition to how the Sift Science network has labeled a device can help you determine whether to allow a user to continue interacting with your site.

Example Request

$ curl -XGET 'https://api3.siftscience.com/v3/accounts/529def32fe6b73f31300126e/devices/0ef840778p8q3j3jfs654q0vvk' \ -H 'Content-Type: application/json' \ -u {API_KEY}:
Example Response
{ "id" : "0ef840778p8q3j3jfs654q0vvk", "label" : "bad", "labeled_at" : 1241241214000, "first_seen" : 1412990802000, "users" : { "data" : [ { "id" : "bob123", "href" : "https://api3.siftscience.com/v3/accounts/529def32fe6b73f31300126e/users/bob123" } ] }, "network" : { "first_seen" : 1412386033000, "score" : 0.8 }, "sessions" : { "has_more" : false, "total_results" : 1, "data" : [ { "time" : 1412990802000 } ] } }

Parameters

  • accountId
    required · string

    Your Sift Science Account ID, which can be found in the Sift Science Console under the Developer Tab

  • deviceId
    required · string

    Device Fingerprints are strings that are 26 characters in length, e.g. "0ef840778p8q3j3jfs654q0vvk"

Response

  • id
    required · string

    Device Fingerprints are strings that are 26 characters in length, e.g. '0ef840778p8q3j3jfs654q0vvk'

  • first_seen
    integer

    The time (represented as POSIX time in milliseconds) when Sift Science first identified this device on your site

  • users
    object

    A list of references to external entities that this object is associated with

    • data
      required · array

      The list of data elements

      • id
        required · string

        id of the referenced resource

    • has_more
      boolean

      True if there are more data elements available

    • next_ref
      string

      A link to the next set of data elements, if available

    • total_results
      integer

      The total number of results, if known

  • sessions
    object

    A list of sessions in which this device has been seen

    • data
      required · array

      A list of data related to sessions in which this device has been seen

      • time
        integer

        The time at which this Session ID was first set in the Sift Science JavaScript snippet.

    • has_more
      boolean

      True if there are more sessions available

    • next_ref
      string

      A link to the next set of sessions, if available

    • total_results
      integer

      The total number of results, if known

  • label
    string

    The label applied to this device. If no label has been applied, this field is undefined

    Allowed Values
    • badThis device has exhibited behavior that is fraudulent or otherwise detrimental to your business
    • not_badThis device is not fraudulent
  • labeled_at
    integer

    The time at which the latest label was applied to this device. If no label has been applied, this field is null

  • network
    object

    Data from our network of customers can help you make decisions on devices you've never seen before or haven't yet exhibited suspicious behavior.

    • first_seen
      integer

      The time (represented as POSIX time in milliseconds) when Sift Science first identified this device within our network of customers.

    • score
      number

      A representation of how likely this device is bad based on labels we've received from our network of customers. The range of values is 0 to 1, where 1 represents a device that almost certainly is bad.

    • pervasiveness
      string

      NOT YET AVAILABLE. A representation of how often Sift Science has seen this device in our network of customers. You might consider scores where pervasiveness is 'low' less strongly than scores where pervasiveness is 'medium' or 'high'.

      Allowed Values
      • low
      • medium
      • high

Label a Device

PUT   /v3/accounts/{accountId}/devices/{deviceId}/label

Use this endpoint to flag devices as either "bad" or "not_bad". Most likely you will need to link some concept of a user (e.g. email address or user id) to a Device Fingerprint at some point in your product flow. Then, when you find a user to be fraudulent, you should use this endpoint to flag the device the user originated from. You will prevent this device from interacting from your site using the /v3/accounts/{accountId}/session endpoint.

Example Request

$ curl -XPUT 'https://api3.siftscience.com/v3/accounts/529def32fe6b73f31300126e/devices/0ef840778p8q3j3jfs654q0vvk/label' \ -H 'Content-Type: application/json' \ -u {API_KEY}: \ -d '{ "label" : "bad" }'
Example Response
{ "label" : "bad" }

Parameters

  • accountId
    required · string

    Your Sift Science Account ID, which can be found in the Sift Science Console under the Developer Tab

  • deviceId
    required · string

    Device Fingerprints are strings that are 26 characters in length, e.g. "0ef840778p8q3j3jfs654q0vvk"

Entity

  • label
    string

    Allowed Values
    • badThis device has exhibited behavior that is fraudulent or otherwise detrimental to your business
    • not_badThis device is not fraudulent

Response

  • label
    string

    Allowed Values
    • badThis device has exhibited behavior that is fraudulent or otherwise detrimental to your business
    • not_badThis device is not fraudulent

Session Information

GET   /v3/accounts/{accountId}/sessions/{sessionId}

Call this endpoint to determine whether you should allow the device seen for a given session id to continue interacting with your site. Embedded in the response is whether you've seen this device before as well as how you've labeled the device, if at all. If you've labeled a Device Fingerprint "bad" in the past, you should most likely restrict this device's ability to interact with your site.

Example Request

$ curl -XGET 'https://api3.siftscience.com/v3/accounts/529def32fe6b73f31300126e/sessions/465733823' \ -H 'Content-Type: application/json' \ -u {API_KEY}:
Example Response
{ "id" : 465733823, "time" : 1412990802000, "device" : { "id" : "0ef840778p8q3j3jfs654q0vvk", "label" : "bad", "labeled_at" : 1241241214000, "first_seen" : 1412990802000, "network" : { "first_seen" : 1412386033000, "score" : 0.8 }, "sessions" : { "total_results" : 1, "has_more" : false, "data" : [ { "time" : 1412990802000 } ] } } }

Parameters

  • accountId
    required · string

    Your Sift Science Account ID, which can be found in the Sift Science Console under the Developer Tab

  • sessionId
    required · string

    Session IDs should be initially set in our JavaScript snippet. Use the same session id to retrieve the device associated with this session. You should only call this endpoint from your server, and not from the client.

Response

  • time
    integer

    The time at which this Session ID was first set in the Sift Science JavaScript snippet.

  • device
    object

    Data related to a Device Fingerprint

    • id
      required · string

      Device Fingerprints are strings that are 26 characters in length, e.g. '0ef840778p8q3j3jfs654q0vvk'

    • first_seen
      integer

      The time (represented as POSIX time in milliseconds) when Sift Science first identified this device on your site

    • users
      object

      A list of references to external entities that this object is associated with

      • data
        required · array

        The list of data elements

        • id
          required · string

          id of the referenced resource

      • has_more
        boolean

        True if there are more data elements available

      • next_ref
        string

        A link to the next set of data elements, if available

      • total_results
        integer

        The total number of results, if known

    • sessions
      object

      A list of sessions in which this device has been seen

      • data
        required · array

        A list of data related to sessions in which this device has been seen

        • time
          integer

          The time at which this Session ID was first set in the Sift Science JavaScript snippet.

      • has_more
        boolean

        True if there are more sessions available

      • next_ref
        string

        A link to the next set of sessions, if available

      • total_results
        integer

        The total number of results, if known

    • label
      string

      The label applied to this device. If no label has been applied, this field is undefined

      Allowed Values
      • badThis device has exhibited behavior that is fraudulent or otherwise detrimental to your business
      • not_badThis device is not fraudulent
    • labeled_at
      integer

      The time at which the latest label was applied to this device. If no label has been applied, this field is null

    • network
      object

      Data from our network of customers can help you make decisions on devices you've never seen before or haven't yet exhibited suspicious behavior.

      • first_seen
        integer

        The time (represented as POSIX time in milliseconds) when Sift Science first identified this device within our network of customers.

      • score
        number

        A representation of how likely this device is bad based on labels we've received from our network of customers. The range of values is 0 to 1, where 1 represents a device that almost certainly is bad.

      • pervasiveness
        string

        NOT YET AVAILABLE. A representation of how often Sift Science has seen this device in our network of customers. You might consider scores where pervasiveness is 'low' less strongly than scores where pervasiveness is 'medium' or 'high'.

        Allowed Values
        • low
        • medium
        • high

Device Information for Users

GET   /v3/accounts/{accountId}/users/{userId}/devices

Call this endpoint to determine the devices associated for a given user_id

Example Request

$ curl -XGET 'https://api3.siftscience.com/v3/accounts/529def32fe6b73f31300126e/users/465733823/devices' \ -H 'Content-Type: application/json' \ -u {API_KEY}:
Example Response
{ "data" : [ { "id" : "0ef840778p8q3j3jfs654q0vvk", "href" : "https://api3.siftscience.com/v3/accounts/529def32fe6b73f31300126e/devices/0ef840778p8q3j3jfs654q0vvk" }, { "id" : "043ef45323q33ks3kkd3q234df", "href" : "https://api3.siftscience.com/v3/accounts/529def32fe6b73f31300126e/devices/043ef45323q33ks3kkd3q234df" } ] }

Parameters

  • accountId
    required · string

    Your Sift Science Account ID, which can be found in the Sift Science Console under the Developer Tab

  • userId
    required · string

    User IDs should be initially set in our JavaScript snippet. Use the same user id to retrieve the devices associated with this user. You should only call this endpoint from your server, and not from the client.

Response

  • schema
    required · string

    Reference to the json schema that the data in the array conforms to

  • data
    required · array

    A list of data items

    • id
      required · string

      id of the referenced resource

  • has_more
    boolean

    Whether there are more results

  • next_ref
    string

    A link to the next set of data, if available

  • total_results
    integer

    The total number of results, if known

Workflows API Overview

The Workflow APIs allow you to consume the output/query the status of a Workflow you've configured in the Sift Science Console. If you still need to create Workflows, please read our Creating a Workflow tutorial, which will walk you through the process of creating Workflows and attaching Decisions/Review Queues to them. There are two ways for you to query and consume Workflow output:

  • Synchronously when you send Sift Science any REST API event using the return_workflow_status URL parameter. This is best for when you need to know the output of the Workflow immediately after the triggering event occurs to make a time sensitive decision.
  • Asynchronously using the Workflow Status API. This is best for when you want to query a Workflow after the triggering event has passed. A common use case is for reporting needs.

Automated Decisions

There are two ways to consume an automated decision:

  1. Synchronously retrieve the Workflow's output when you send the triggering event.
  2. Use Decision Webhooks to consume the workflow's output.

Synchronous

If you want to consume the automed Decision synchronously, you simply need to add return_workflow_status=true to the URL parameters when you are sending Sift Science a Reserved or Custom event. Here is an example API call which will return the automated Decision of the Workflow associated with this event:

Request

curl -X POST https://api.siftscience.com/v204/events?return_workflow_status=true
-H "Accept: application/json"
-d '{
  "$api_key": "YOUR_REST_API_KEY",
  "$type": "$create_order",
  "$user_id": "test_user"
}'
import sift

client = sift.Client('your_api_key_here')

properties = {
  '$user_id'    : 'test_user',
  '$user_email' : 'sample_user@gmail.com'
} 
response = client.track('$create_order', properties, return_workflow_status=True, 
                         abuse_types=['promo_abuse', 'content_abuse', 'payment_abuse'])
require 'sift'

client = Sift::Client.new(:api_key => 'your_api_key_here')

properties = {
  '$user_id'    => 'sample_user',
  '$user_email' => 'sample_user@gmail.com'
}
response = client.track('$create_order', properties, :return_worflow_status => true,
                        :abuse_types => ['promo_abuse', 'payment_abuse'])
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'your_api_key_here'));

$properties = array(
  '$user_id' => 'sample_user51', 
  '$user_email' => 'sample_user@gmail.com'
);
$opts = array(
          'return_workflow_status' => True,
          'abuse_types' =>  array(
                              'promo_abuse', 
                              'payment_abuse'
                            )
        ));
$response = $client->track('$create_order', $properties, $opts);

Response

{
  "http_status_code": 200
  "body": {
    "status": 0,
    "error_message": "OK",
    "request": "body_of_the_request_you_sent",
    "time": 1454517138,
    "score_response": {
      "status": 0, 
      "error_message": "OK", 
      "user_id": "billy_jones_301",
      "scores": {
        "payment_abuse": {
          "score": 0.898391231245,
          "reasons": [
            {
              "name": "UsersPerDevice",
              "value": 4,
              "details": {
                "users": "a, b, c, d"
              }
            }
          ]
        },
        "promotion_abuse": {
          "score": 0.472838192111,
          "reasons": []
        },
      },
      "latest_labels": {
        "payment_abuse": {
          "is_bad": true,
          "time": 1352201880,
          "description": "received a chargeback"
        },
        "promotion_abuse": {
          "is_bad": false,
          "time": 1362205000
        }
      },
      "workflow_statuses": [
        {
          "id": "6dbq76qbaaaaa",
          "state": "running",
          "config": {
            "id": "pv3u5hyaaa",
            "version": "1468013109122"
          },
          "config_display_name": "my create order flow",
          "abuse_types": ["payment_abuse", "legacy"],
          "entity": {
            "type": "user",
            "id": "test"
          },
          "history": [
            {
              "app": "decision",
              "name": "ban user",
              "state": "running",
              "config": {
               "decision_id": "ban-user-payment-abuse"
            }
            },
            {
              "app": "review_queue",
              "name": "risky user queue",
              "state": "finished"
              "config": {
                "buttons": [
                  { "id": "ban-user-payment-abuse", "name": "Ban User" },
                  { "id": "suspend-user-payment-abuse", "name": "Ban User" },
                  { "id": "accept-user-payment-abuse", "name": "Ban User" }
                ]
              }
            },
            {
              "app": "user_scorer",
              "name": "Entity",
              "state": "finished"
            },
            {
              "app": "event_processor",
              "name": "Event",
              "state": "finished"
            }
          ]
        }
      ]
    }
  }
}

Response Fields

  • http_status_code
    Integer

    The HTTP status code of this Events API

  • body
    Object

    The body of the response.

    • status
      Integer

      The success or error code (see relevant error codes below).

    • error_message
      String

      Description of error or success.

    • request
      String

      The content of the event you sent.

    • time
      Integer

      The time the request was processed.

    • score_response
      Object

      The id of the user, matching what was passed in the Score API call.

      • status
        Integer

        The status of the requested re-scoring and Formula check this event initiated.

      • error_message
        String

        Description of error or success.

      • user_id
        String

        The id of the user, matching what was passed in the Events API call.

      • scores
        Map

        The scores map contains all computed scores for all applicable abuse types for a given user. The map is keyed by abuse type, which could be one of: payment_abuse, account_abuse, content_abuse, promotion_abuse. The values in this map are objects which containthe following fields:

        • score
          Float

          Score for the user between 0.0 and 1.0. A score of 0.5 translates to a score a 50 in the console.

        • reasons
          Array

          A list of the most significant reasons for the score and the values associated with the user. The included values will vary based on the user. Includes related users in the details object when applicable.

          • name
            String

            Name of the risk signal.

          • value
            String

            Value of the risk signal.

          • details
            Object

            Additional details. Provided only when relevant. E.g., may contain a details field which contains the IDs of related users.

      • latest_labels
        Map

        The latest_labels map contains entries for all abuse types for which the given user has been labeled. Note that the content of this map is not subject to the abuse types specified in the request; we always include all labels that have been applied to the given user. The map is keyed by abuse type, which could be one of: payment_abuse, account_abuse, content_abuse, promotion_abuse. The values in this map are objects which contain the following fields:

        • is_bad
          Boolean

          true if the user is labeled Bad, false if the user is labeled Not Bad.

        • time
          Long

          The time this label was applied to the user. It is a UNIX timestamp in seconds.

        • description
          String

          Freeform text description of the user and/or incident triggering the label.

      • workflow_statuses
        [Object]

        A list of objects containing the responses of any Workflows that were triggered by this event. There will be one list item per Workflow triggered.

        • id
          String

          The run ID of this Workflow, identifying this specific instance of the Workflow. Use this with theWorkflow Status API to query the status of a Workflow run directly.

        • state
          String

          The state of this Workflow instance.

          Possible Values
          • running
            This Workflow instance is still running, either because it is still sending the webhook or the user/order was put into a manual review queue
          • finished
            This Workflow instance is finished running and there is a Decision associated with it in the history section discussed below
          • failed
            This Workflow instance has failed to run.
        • config
          Object

          An object containing the configuration information for this Workflow.

          • id
            String

            The configuration ID of the Workflow. This is the unique identifier of this Workflow, but not this Workflow instance.

          • version
            String

            The version of this Workflow.

        • config_display_name
          String

          The display name given to this Workflow in the Workflow editor.

        • abuse_types
          [String]

          A list of abuse types configured in this workflow

          Possible Values
          • payment_abuse
            This Workflow is configured to give Decisions on the Payment Abuse abuse type.
          • promo_abuse
            This Workflow is configured to give Decisions on the Promo Abuse abuse type.
          • content_abuse
            This Workflow is configured to give Decisions on the Content Abuse abuse type.
          • account_abuse
            This Workflow is configured to give Decisions on the Account Abuse abuse type.
          • legacy
            This Workflow is configured to give Decisions on the Legacy abuse type.
        • entity
          Object

          The entity object containing information on the entity on which the Decision was taken.

          • type
            String

            The type of entity on which the Decision was taken.

            Possible Values
            • user
              This entity is a user and so the following id field will be a $user_id
            • order
              This entity is an order and so the following id field will be an $order_id
          • id
            String

            The unique identifier of the entity on which the Decision was taken.

        • history
          [Object]

          A list of object containing information on each app that was run in chronological order. The first item in the list is the most recent app to run.

          Note: The first 2 apps that ran ('event_processor' and 'user_scorer'/'order_scorer') are run on every Workflow and are not associated with any configured Routes.

          • app
            String

            The type of app which was run.

            Possible Values
            • decision
              This is a Decision app, and is the result of either an automated Decision or a Decision from a manual review queue
            • review_queue
              This is a Manual Review Queue app, and indicates that the user/order went to a Manual Review Queue.
            • user_scorer
              This is a scoring app, specific to the user entity. This is a static app and always appears on Workflows triggered for the user entity.
            • order_scorer
              This is a scoring app, specific to the order entity. This is a static app and always appears on Workflows triggered for the order entity.
            • event_processor
              This is an event processing app. This is a static app and appears on every Workflow.
          • name
            String

            The display name of the app which was run.

          • state
            String

            The state of this app.

            Possible Values
            • running
              This app is still running, either because it is still sending a Decision webhook or the user/order is still in a manual review queue
            • finished
              This app is finished running.
            • failed
              This app has failed to run.
          • config
            Object

            The configuration information of the app.

            • decision_id
              String

              The unique identifier of the Decision taken in this app.


              Note: This field only exists if the value for app is decision

            • buttons
              [Object]

              A list of button objects associated with this Manual Review Queue.


              Note: This field only exists if the value for app is review_queue

              • id
                String

                The unique Decision ID for this button.

              • name
                String

                The display name for this button.

Error Codes

  • -4

    Service currently unavailable. Please try again later.

  • -3

    Server-side timeout processing request. Please try again later.

  • -2

    Unexpected server-side error

  • -1

    Unexpected server-side error

  • 0

    OK

  • 51

    Invalid API key

  • 54
  • 60

    Rate limited; too many events have been received in a short period of time

Webhooks

If you wish to use webhooks to consume the Workflow's output, please see the Decision Webhooks documentation.

Decisions From Review Queues

When a user/order arrives in a Review Queue, which you can verify by looking at the first item in the history section of the Workflow Status, someone on your review team will take a look and make a Decision by choosing one of the available Decision Buttons in the queue. There are two available methods to capture and act on these Decisions:

  • Decision Webhooks
  • The Decision Status API

The Webhooks will push a notification to you when a Decision is made, while the Decision Status API allows you to query the latest Decisions on a user/order at any time. Choose the method that best fits your workflow.

Workflow Status

The Workflow Status API allows you to query the status of a specific instance of a Workflow. In order to use this API you need the instance's Run ID. You can get this by using the Synchronous Workflow Status API when you send the triggering event for the Workflow. This API is useful for gathering information on previously executed Workflows.

To use this API, make the following request:

Request

curl -XGET  https://api3.siftscience.com/v3/accounts/{accountId}/workflows/runs/{workflow_run_id}
-H "Accept: application/json" \
-u {API_KEY}:
import sift

client = sift.Client(api_key='{API_KEY}', account_id='{accountId}')

workflow_run_id = '123' # obtained in response of 'return_workflow_status=true' call
response = client.get_workflow_status(workflow_run_id)
require 'sift'

client = Sift::Client.new(:api_key = > '{API_KEY}', :account_id => '{accountId}')

workflow_run_id = '123' # obtained in response of 'return_workflow_status=true' call
response = client.get_workflow_status(workflow_run_id)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => '{API_KEY}', 'account_id' => '{accountId}'));

$workflow_run_id = '123' // obtained in response of 'return_workflow_status=True' call
$response = $client->getWorkflowStatus($workflow_run_id);

Be sure to replace {accountId} with your Sift Science account ID, found on the Profile Tab on the Console. Also, make sure to replace {workflow_run_id} with the Workflow Run ID. Lastly, replace {API_KEY} with your REST API key, found on the API Keys tab of the Developer page on the Console. You will receive a response in the following format:

Response

{
  "id": "6dbq76qbaaaaa",
  "state": "running",
  "config": {
    "id": "pv3u5hyaaa",
    "version": "1468013109122"
  },
  "config_display_name": "my create order flow",
  "abuse_types": ["payment_abuse", "legacy"],
  "entity": {
    "type": "user",
    "id": ""dracula@vampires.com""
  },
  "history": [
    {
      "app": "decision",
      "name": "ban user",
      "state": "running",
      "config": {
         "decision_id": "ban-user-payment-abuse"
      }
    },
    {
      "app": "review_queue",
      "name": "risky user queue",
      "state": "finished",
      "config": {
        "buttons": [
          { "id": "ban-user-payment-abuse", "name": "Ban User" },
          { "id": "suspend-user-payment-abuse", "name": "Ban User" },
          { "id": "accept-user-payment-abuse", "name": "Ban User" }
        ]
      }
    },
    {
      "app": "user_scorer", // name TBD
      "name": "Entity",
      "state": "finished",
    },
    {
      "app": "event_processor", // name TBD
      "name": "Event",
      "state": "finished",
    }
  ]
}

Response Fields

  • id
    String

    The run ID of this Workflow, identifying this specific instance of the Workflow.

  • state
    String

    The state of this Workflow instance.

    Possible Values
    • running
      This Workflow instance is still running, either because it is still sending the webhook or the user/order was put into a manual review queue
    • finished
      This Workflow instance is finished running and there is a Decision associated with it in the history section discussed below
    • failed
      This Workflow instance has failed to run.
  • config
    Object

    An object containing the configuration information for this Workflow.

    • id
      String

      The configuration ID of the Workflow. This is the unique identifier of this Workflow, but not this Workflow instance.

    • version
      String

      The version of this Workflow.

  • config_display_name
    String

    The display name given to this Workflow in the Workflow editor.

  • abuse_types
    [String]

    A list of abuse types configured in this workflow

    Possible Values
    • payment_abuse
      This Workflow is configured to give Decisions on the Payment Abuse abuse type.
    • promo_abuse
      This Workflow is configured to give Decisions on the Promo Abuse abuse type.
    • content_abuse
      This Workflow is configured to give Decisions on the Content Abuse abuse type.
    • account_abuse
      This Workflow is configured to give Decisions on the Account Abuse abuse type.
    • legacy
      This Workflow is configured to give Decisions on the Legacy abuse type.
  • entity
    Object

    The entity object containing information on the entity on which the Decision was taken.

    • type
      String

      The type of entity on which the Decision was taken.

      Possible Values
      • user
        This entity is a user and so the following id field will be a $user_id
      • order
        This entity is an order and so the following id field will be an $order_id
    • id
      String

      The unique identifier of the entity on which the Decision was taken.

  • history
    [Object]

    A list of object containing information on each app that was run in chronological order. The first item in the list is the most recent app to run.

    Note: The first 2 apps that ran ('event_processor' and 'user_scorer'/'order_scorer') are run on every Workflow and are not associated with any configured Routes.

    • app
      String

      The type of app which was run.

      Possible Values
      • decision
        This is a Decision app, and is the result of either an automated Decision or a Decision from a manual review queue
      • review_queue
        This is a Manual Review Queue app, and indicates that the user/order went to a Manual Review Queue.
      • user_scorer
        This is a scoring app, specific to the user entity. This is a static app and always appears on Workflows triggered for the user entity.
      • order_scorer
        This is a scoring app, specific to the order entity. This is a static app and always appears on Workflows triggered for the order entity.
      • event_processor
        This is an event processing app. This is a static app and appears on every Workflow.
    • name
      String

      The display name of the app which was run.

    • state
      String

      The state of this app.

      Possible Values
      • running
        This app is still running, either because it is still sending a Decision webhook or the user/order is still in a manual review queue
      • finished
        This app is finished running.
      • failed
        This app has failed to run.
    • config
      Object

      The configuration information of the app.

      • decision_id
        String

        The unique identifier of the Decision taken in this app.


        Note: This field only exists if the value for app is decision

      • buttons
        [Object]

        A list of button objects associated with this Manual Review Queue.


        Note: This field only exists if the value for app is review_queue

        • id
          String

          The unique Decision ID for this button.

        • name
          String

          The display name for this button.

Formulas and Actions API

NOTE: As of July, 2016 Formulas and Actions are a legacy option for automating fraud decisions with Sift. If you are a Sift Science customer that is already using Formulas, they will continue working as expected, but we encourage you to check out our new suite of automation tools - Workflows!

For more information on integrating Formulas and Actions, view the tutorial.

  1. Synchronous Actions are the best way to get a real-time score at your key decision point, such as $create_order, $create_content, or $create_account.
  2. Action Webhooks are the best way to get updates about a change to a user's risk score or other state outside of your key event where you make an automated decision.

Synchronous Actions

Synchronous Actions are the best way to make a decision at your key decision point, such as $create_order, $create_content, or $create_account. Once you choose the event to make your Synchronous Action call on, simply append the '?return_action=true' to our Events API url or use one of our client libraries as shown below.

Synchronous Action calls will return each user's risk score. You can enhance them to include any actions that should be taken on the user, order, or posting, such as block or review. Your fraud team can set up and configure actions in the console. Formulas and actions can be adjusted in the console at anytime without the need for developer resources. For an overview of creating Actions to enhance Synchronous Action calls, see our tutorial.

curl -X POST https://api.siftscience.com/v203/events?return_action=true
-H "Accept: application/json"
-d '{
  "$api_key": "YOUR_SANDBOX_REST_API_KEY",
  "$type": "$create_order",
  "$user_id": "test_user"
}'
import sift
client = sift.Client("REST_API_KEY_HERE")

# define event_properties here
response = client.track("$create_order", event_properties, return_action=True)
require "sift"
client = Sift::Client.new("REST_API_KEY_HERE")

# define event_properties here
response = client.track("$create_order", event_properties, timeout=2, path=nil, false, sift_api_key, return_action=true)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient('REST_API_KEY_HERE');

// define event_properties here
$response = $client->track('$create_order', $properties, $timeout = 2, $path = null, FALSE, $returnAction = TRUE)

Response

HTTP/1.1 200 OK
Content-Type: text/json;charset=UTF-8
Connection: keep-alive
{
  "body": {
    "status": 0, 
    "error_message": "OK", 
    "request": "body_of_the_request_you_sent", 
    "time": 1454517138,
    "score_response": {
      "status": 0, 
      "error_message": "OK", 
      "user_id": "sample_user2", 
      "latest_label": { # present only if user is currently labeled
        "reasons": ["$spam"],
        "is_bad": true, 
        "time": 1454517070
      }, 
      "score": 0.39944676614045643
      "reasons": [
        {
          "name": "Number of users with the same billing address", 
          "value": "3",
          "details": { # present only if there are details
            "users": "sample_user3,sample_user4" 
          }
        },
        ...
      ], 
      "actions": [
        {
          "action": {
            "id": "take_action"
          }, 
          "triggers": [
            {
              "source": "synchronous_action", 
              "trigger": {
                "id": "568c65bfe4b04102ee5aa080"
              }, 
              "type": "formula"
            }], 
          "time": 1454517138887, 
          "id": "cd089ea60de36f3ac0dd47572fc4a00a7ffffead5805ca38:take_action", 
          "entity": {
            "id": "sample_user2"
          }
        }], 
    }, 
  }, 
  "http_status_code": 200
}
response.is_ok()            # false on failed score requests.
response.http_status_code   # 200 on successful score requests.
response.api_status         # see error codes and messages below
response.api_error_message  

# check for label
bad_user = response.body['latest_label']['is_bad'] if 'latest_label' in response.body else None

# get Sift Score
sift_score = round((response.body['score_response']['score'] * 100), 1) # e.g. 74.8

# check if a certain action has been applied to a user or order
prevent_action_id = 'prevent' # create in Sift Console: https://siftscience.com/console/actions/users
entity_id = user_id
for action in response.body['score_response']['actions']:
  if action['entity']['id'] == entity_id and action['action']['id'] == action_id:
    # take some action
response.ok?()              # false on failed score requests.
response.http_status_code   # 200 on successful score requests.
response.api_status         # see error codes and messages below
response.api_error_message  

#check for label
bad_user = response.body.has_key?('latest_label') ? response.body['latest_label']['is_bad'] : nil

# get score
sift_score = (response.body['score_response']['score'] * 100).round(1) # e.g. 74.8

# check if a certain action has been applied to a user or order
prevent_action_id = 'prevent' # create in Sift Console: https://siftscience.com/console/actions/users
for action in action_list
  if action['entity']['id'] == entity_id && action['action']['id'] == action_id
      # take some action
    end
end

prevent_action_id = 'prevent' # create in Sift Console: https://siftscience.com/console/actions/users
prevent = action_in_list(prevent_action_id, user_id, response.body['score_response']['actions'])
$response->isOk()           // false on failed score requests.
$response->httpStatusCode   // 200 on successful score requests
$response->apiStatus        // 0 on successful score requests.
$response->apiErrorMessage  // see error codes and messages below

// get score
$siftScore = round(($response->body['score'] * 100), 1); //e.g. 74.8

// check if a certain action has been applied to a user or order
$preventActionID = 'take_action'; // create in Sift Console: https://siftscience.com/console/actions/users
$entityId = $userID;
foreach ($response->body['actions'] as $action) {
  if ($action['entity']['id'] == $entityId && $action['action']['id'] == $preventActionID) {
    print "action found!";
  }
}

Response Fields

  • status
    Integer

    The success or error code (see relevant error codes below).

  • error_message
    String

    Description of error or success.

  • request
    String

    The content of the event you sent.

  • time
    Integer

    The time the request was processed.

  • score_response
    Object

    The id of the user, matching what was passed in the Score API call.

    • status
      Integer

      The status of the requested re-scoring and Formula check this event initiated.

    • error_message
      String

      Description of error or success.

    • user_id
      String

      The id of the user, matching what was passed in the Events API call.

    • latest_label
      Object

      Only returned if the user is currently labeled.

      • reasons
        [String]

        A list of reasons that were given for the label. Only returned if one or more reasons were applied.

      • is_bad
        Boolean

        True if the user is labeled Bad, false if the user is labeled Not Bad. The latest_label object will not be present if the user is unlabeled.

      • time
        Integer

        The time the most recent label was applied to the user, as UNIX timestamp.

    • score
      Float

      Score for the user between 0.0 and 1.0. A score of 0.5 translates to a score a 50 in the console.

    • reasons
      [Object]

      The most significant reasons contributing to the user's risk score. The included values will vary.

      • name
        String

        Name of the risk signal.

      • value
        String

        The value for the risk signal.

      • details
        Object (optional)

        Additional details. Provided only when relevant.

        • users
          String

          Users related to the user by the risk signal

    • actions
      [Object]

      A list of any actions that have been applied to the user, with the most recent action appearing first.

      • id
        String

        Our unique id for this particular application of the action to this user. Used to reference our internal logs if needed.

      • action
        String

        Contains the id associated with the action. This is the ActionID generated when setting up the action in your console. Our unique id for this particular application of the action to this user. Used to reference our internal logs if needed.

      • entity
        String

        Contains the id of the entity the action was applied to (the user_id passed in the Score API call).

      • time
        Long

        The time the action was applied, as UNIX timestamp.

      • triggers
        String

        A list of what triggered the application of this action to the user. For example, two Formulas and their ids.

Error Codes

Send your events with a $time field in milliseconds and resend on a 60 or a negative error code value in either status field.

  • -1

    Unexpected server-side error

  • -2

    Unexpected server-side error

  • -3

    Server-side timeout processing request. Please try again later.

  • -4

    Service currently unavailable. Please try again later.

  • 0

    OK

  • 51

    Invalid API key

  • 60

    Rate limited; too many events have been received in a short period of time. Note: make sure to check the status of the 'score_response' field for this error as well.

Action webhooks

Action webhooks are the best way to get updates about a change to the risk of a user outside of your key event where you must make an instant decision. Using Action webhooks requires setting up Actions and Formulas to trigger them in your console. For an overview, see our Formulas and Actions tutorial.

See Action Webhooks Authentication for instructions on how to verify the requests you are receiving are coming from Sift Science.

{
  id: "3ff1082a4aea8d0c58e3643ddb7a5bb87ffffeb2492dca33",
  action: {
    id: "test",
    href: "https://siftscience.com/v3/accounts/5265ac265f5ce205a2bdc80f/actions/test"
  },
  entity: {
    id: "example_order",
    href: "https://siftscience.com/v3/accounts/5265ac265f5ce205a2bdc80f/orders/example_order"
  },
  time: 1454526160387,
  triggers: [
    {
      type: "formula",
      source: "formula_service",
      trigger: {
        id: "556e4a1de4b04ed910169adb",
        href: "https://siftscience.com/v3/accounts/5265ac265f5ce205a2bdc80f/formulas/556e4a1de4b04ed910169adb"
      }
    }
  ]
}

Request

  • id
    String

    Our unique id for this particular application of the action to this user. Used to reference our internal logs if needed.

  • action
    Object

    Contains the id associated with the action. This is the ActionID generated when setting up the action in your console. Our unique id for this particular application of the action to this user. Used to reference our internal logs if needed.

  • entity
    Object

    Contains the id of the entity the action was applied to (the user_id passed in the Score API call).

  • time
    Long

    The time the action was applied, as UNIX timestamp.

  • triggers
    [Object]

    A list of what triggered the application of this action to the user. For example, two Formulas and their ids.

Authentication

Take advantage of webhook authentication to ensure that the request you receive is coming from Sift Science.

Notes:

  • There can only be one active webhook key per account.
  • Generate your key on the Production API Keys page of your console.
  • The Production key is used for your Sandbox account.
  • The Signature will appear as the value for the HTTP header 'X-Sift-Science-Signature', which will arrive in the request. This header does not appear when you initially set up webhooks for Actions in the console.
Look for the request header: 'X-Sift-Science-Signature'
import json
from hashlib import sha1
import hmac

from flask import request

SIFT_WEBHOOK_SECRET_KEY = "#####"

@app.route("/webhook")
def webhook():
  # Let's check whether this webhook actually came from Sift Science!
  # First let's grab the signature from the postback's headers
  postback_signature = request.get("X-Sift-Science-Signature")

  # Next, let's try to assemble the signature on our side to verify
  postback_body = json.dumps(request.json)

  h = hmac.new(SIFT_WEBHOOK_SECRET_KEY, postback_body, sha1)
  verification_signature = "sha1={}".format(h.hexdigest())

  if verification_signature == postback_signature:
    process_webhook()
  else:
    raise SomeException()
require 'json'
require 'openssl'
require 'sinatra'

SIFT_WEBHOOK_SECRET_KEY = "#####"

post '/webhook' do
  # Let's check whether this webhook actually came from Sift Science!
  # First let's grab the signature from the postback's headers
  postback_signature = request.env['X-Sift-Science-Signature']

  # Next, let's try to assemble the signature on our side to verify
  digest  = OpenSSL::Digest.new('sha1')
  calculated_hmac = OpenSSL::HMAC.hexdigest(digest, SIFT_WEBHOOK_SECRET_KEY, request.body)
  verification_signature = "sha1=#{calculated_hmac}"

  if verification_signature == postback_signature
    puts "success"
  else
    raise Exception
  end
end
SIFT_WEBHOOK_SECRET_KEY = "#####";
BLOCK_ACTION = 'block'; #name of the Action you set up in the console

# Let's check whether this webhook actually came from Sift Science!
# First let's grab the signature from the postback's headers
$webhookSignature = $headers['X-Sift-Science-Signature'];

# Next, let's try to assemble the signature on our side to verify
$verificationSignature  = "sha1=" . hash_hmac('sha1', $requestBody, $SIFT_WEBHOOK_SECRET_KEY);

if ($webhookSignature == $verificationSignature) {
  $siftRequest = json_decode($requestBody);
  if ($siftRequest->action->id == BLOCK_ACTION) {
    ...
  }
}

Decisions API Overview

The Decisions APIs allow you to query and consume the Decisions which you've configured in the Sift Science Console. If you still need to create Decisions, please read the Connecting Decisions to Business Actions tutorial, which will explain how to create new Decisions and configure them to send webhooks if that is your preferred method of consuming Decisions. There are two ways to consume Decisions:

  • Using Decision Webhooks which you configured to be notified of Decisions applied to users/orders.
  • Using the Decision Status API to query the latest Decisions for all abuse types on a given user/order.

Decision webhooks

Decision webhooks are configured when you create a Decision in the Console. If you havent yet configured webhooks on your Decisions, read our Connecting Decisions to Business Actions tutorial to learn how. Once you've set an endpoint for the webhooks to be sent to, you will receive webhooks with the following body:

Response

{
  "entity": {
    "type": "user",
    "id": "soju12345"
  },
  "decision": {
    "id": "block_user_payment_abuse"
  },
  "time": 1461963439151
}

Response Fields

  • entity
    Object

    The entity object containing information on the entity on which the Decision was taken.

    • type
      String

      The type of entity on which the Decision was taken.

      Possible Values
      • user
        This entity is a user and so the following id field will be a $user_id
      • order
        This entity is an order and so the following id field will be an $order_id
    • id
      String

      The unique identifier of the entity on which the Decision was taken.

  • decision
    Object

    The Decision object containing information on the Decision taken.

    • id
      String

      The unique identifier of the Decision that was taken. This is generated by taking the first display name provided for the Decision, replacing spaces with underscores, and concatenating it with the fraud type for which this Decision is configured.


      Note:You cannot have two Decisions with the same initial display name for any given fraud type.

  • time
    Long

    The time the Decision was applied, as a UNIX timestamp.

Now that you know what to expect from your Decision webhooks, you need to authenticate that they are indeed coming from Sift Science and meant for you. We'll cover this in the next section.

Authentication

Take advantage of webhook authentication to ensure that the request you receive is coming from Sift Science.

Notes:

  • There can only be one active webhook key per account.
  • Generate your key on the Production API Keys page of your console.
  • The Production key is used for your Sandbox account.
  • The Signature will appear in the http header of the webhook request as 'X-Sift-Science-Signature'.
Look for the request header: 'X-Sift-Science-Signature'
import json
from hashlib import sha1
import hmac

from flask import request

SIFT_WEBHOOK_SECRET_KEY = "#####"

@app.route("/webhook")
def webhook():
  # Let's check whether this webhook actually came from Sift Science!
  # First let's grab the signature from the postback's headers
  postback_signature = request.get("X-Sift-Science-Signature")

  # Next, let's try to assemble the signature on our side to verify
  postback_body = json.dumps(request.json)

  h = hmac.new(SIFT_WEBHOOK_SECRET_KEY, postback_body, sha1)
  verification_signature = "sha1={}".format(h.hexdigest())

  if verification_signature == postback_signature:
    process_webhook()
  else:
    raise SomeException()
require 'json'
require 'openssl'
require 'sinatra'

SIFT_WEBHOOK_SECRET_KEY = "#####"

post '/webhook' do
  # Let's check whether this webhook actually came from Sift Science!
  # First let's grab the signature from the postback's headers
  postback_signature = request.env['X-Sift-Science-Signature']

  # Next, let's try to assemble the signature on our side to verify
  digest  = OpenSSL::Digest.new('sha1')
  calculated_hmac = OpenSSL::HMAC.hexdigest(digest, SIFT_WEBHOOK_SECRET_KEY, request.body)
  verification_signature = "sha1=#{calculated_hmac}"

  if verification_signature == postback_signature
    puts "success"
  else
    raise Exception
  end
end
SIFT_WEBHOOK_SECRET_KEY = "#####";
BLOCK_ACTION = 'block'; #name of the Action you set up in the console

# Let's check whether this webhook actually came from Sift Science!
# First let's grab the signature from the postback's headers
$webhookSignature = $headers['X-Sift-Science-Signature'];

# Next, let's try to assemble the signature on our side to verify
$verificationSignature  = "sha1=" . hash_hmac('sha1', $requestBody, $SIFT_WEBHOOK_SECRET_KEY);

if ($webhookSignature == $verificationSignature) {
  $siftRequest = json_decode($requestBody);
  if ($siftRequest->action->id == BLOCK_ACTION) {
    ...
  }
}

Decision Status

The Decision Status API allows you to query what the latest Decision was for each abuse type, for a user or order. In order to get this information, make the following request:

$curl -XGET https://api3.siftscience.com/v3/accounts/{accountId}/{users|orders}/{entityId}/decisions
-H 'Content-Type: application/json' \
-u {API_KEY}:
import sift

client = sift.Client(api_key='{API_KEY}', account_id='{accountId}')

response = client.get_user_decisions('the_user_id')
# or
response = client.get_order_decisions('the_order_id')
require 'sift'

client = Sift::Client.new(:api_key = > '{API_KEY}', :account_id => '{accountId}')

response = client.get_user_decisions('the_user_id')
# or
response = client.get_order_decisions('the_order_id')
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => '{API_KEY}', 'account_id' => '{accountId}'));

$response = $client->getUserDecisions('the_user_id');
// or 
$response = $client->getOrderDecisions('the_order_id');

Be sure to replace {accountId} with your Sift Science account ID, found on the Profile Tab on the Console. Also, make sure to pick an entity, either users or orders and fill in the id of the entity. Lastly, replace {API_KEY} with your REST API key, found on the API Keys tab of the Developer page in the Console. You will receive a response in the following format:

Response

{
  "decisions": {
    "payment_abuse": {
      "decision": {
        "id": "block_user_payment_abuse"
      },
      "time": 1461963439151,
      "webhook_succeeded": true
    },
    "promo_abuse": {
      "decision": {
        "id": "reject_promo_promo_abuse"
      },
      "time": 1461963431151,
      "webhook_succeeded": true
    },
    "content_abuse": {
      "decision": {
        "id": "block_post_content_abuse"
      },
      "time": 1461963429151,
      "webhook_succeeded": true
    },
    "account_abuse": {
      "decision": {
        "id": "ban_account_account_abuse"
      },
      "time": 1461963839151,
      "webhook_succeeded": true
    }
    "legacy": {
      "decision": {
        "id": "block_user_legacy"
      },
      "time": 1461966439151,
      "webhook_succeeded": false
    }

  }
}

Response Fields

  • decisions
    Object

    A map of abuse types to the associated latest Decisions for the entity.

    Possible Key Values
    • payment_abuse
      The associated JSON object is the latest Decision for the Payment Abuse abuse type
    • promo_abuse
      The associated JSON object is the latest Decision for the Promo Abuse abuse type
    • content_abuse
      The associated JSON object is the latest Decision for the Content Abuse abuse type
    • account_abuse
      The associated JSON object is the latest Decision for the Account Abuse abuse type
    • legacy
      The associated JSON object is the latest Decision for the Legacy abuse type

    Note: If a latest Decision does not exist for a particular abuse type, that key and associated JSON object will not exist in this response.

    • latest decision object
      Object

      The information associated with the latest Decision for a specific abuse type key (read above).

      • decision
        Object

        The Decision object containing information on the Decision taken.

        • id
          String

          The unique identifier of the Decision that was taken. This is generated by taking the first display name provided for the Decision, replacing spaces with hyphens, and concatenating it with the fraud type for which this Decision is configured.


          Note: You cannot have two Decisions with the same initial display name for any given fraud type.

      • time
        Long

        The time the Decision was applied, as a UNIX timestamp.

      • webhook_succeeded
        Boolean

        true if the a webhook was successfully sent, false if the webhook failed to send, null if no webhook is configured.

Score API Overview

The Sift Science APIs give you multiple ways to get a risk score for any of your users. A risk score is a measure of how likely a user is to commit abuse using your service. Scores are computed in real time from the data sent via the Events API and the Sift Javascript snippet.

Sift Science calculates risk scores for four types of abuse:

  • Payment Abuse - A user fraudulently using a credit card or other payment method.
  • Content Abuse - A user creating content (e.g. spammy/scammy posts) or sending messages on your site in an abusive manner.
  • Promotion Abuse - A user gaming the terms of a promotion in an excessive or abusive way.
  • Account Abuse - A user using your service in a manner you deem abusive (e.g. fake accounts).

You can get one or more of these abuse scores at a time. We will calculate scores for any of the abuse detection products you’ve enabled. Here is the pricing for our abuse prevention products.

There are three different ways to get scores from Sift Science:

  1. Get a score synchronously when you send an event (most common)
  2. Get a score and workflows status synchronously when you send an event
  3. Get a score at a point in time without sending an event

Getting risk scores synchronously when sending events

Whenever you send an event, you can receive a Sift Score back synchronously in the response back from the API. This is particularly useful for when you are sending an event that maps to a key decision point for your business. Typically, customers find it most useful to get scores back after creating an account, order, content, or adding a promotion, but you can get scores back after passing any of the events we support.

For events that you don't plan on using the score, it’s best that you don’t ask for the score as it will add some latency to the request.

To get scores back when sending an event, just append the query parameter return_score=true to your API request. Here’s an example:

curl -X POST "https://api.siftscience.com/v204/events?return_score=true"
  -H "Accept: application/json"
  -d '{
    "$type"             : "$create_order",
    "$api_key"          : "your_api_key_here",
    "$user_id"          : "billy_jones_301",
    "$session_id"       : "gigtleqddo84l8cm15qe4il",
    "$order_id"         : "ORDER-28168441",
    "$user_email"       : "bill@gmail.com",
    "$amount"           : 115940000, // $115.94
    "$currency_code"    : "USD"
  }'
import sift
client = sift.Client("REST_API_KEY_HERE")

# define event_properties here
response = client.track("$create_order", event_properties, return_score=True)
require "sift"
client = Sift::Client.new(:api_key => "REST_API_KEY_HERE")

# define event_properties here
response = client.track("$create_order", event_properties, :return_score => true)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'REST_API_KEY_HERE'));

// define event_properties here
$response = $client->track('$create_order', $properties, array('return_score' => true))

You can also request scores for specific abuse types using the abuse_types query parameter:

curl -X POST "https://api.siftscience.com/v204/events?return_score=true&abuse_types=payment_abuse,promotion_abuse"
  -H "Accept: application/json"
  -d '{
    "$type"             : "$create_order",
    "$api_key"          : "your_api_key_here",
    "$user_id"          : "billy_jones_301",
    "$session_id"       : "gigtleqddo84l8cm15qe4il",
    "$order_id"         : "ORDER-28168441",
    "$user_email"       : "bill@gmail.com",
    "$amount"           : 115940000, // $115.94
    "$currency_code"    : "USD"
  }'
import sift
client = sift.Client("REST_API_KEY_HERE")

# define event_properties here
response = client.track("$create_order", event_properties, return_score=True, abuse_types=['payment_abuse', 'promotion_abuse'])
require "sift"
client = Sift::Client.new(:api_key => "REST_API_KEY_HERE")

# define event_properties here
response = client.track("$create_order", event_properties, :return_score => true, :abuse_types => ["payment_abuse", "promotion_abuse"])
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'REST_API_KEY_HERE'));

// define event_properties here
$response = $client->track('$create_order', $properties, array('return_score' => true, 'abuse_types' => array('payment_abuse', 'promotion_abuse')));

Response

HTTP/1.1 200 OK
Content-Type: text/json;charset=UTF-8
Connection: keep-alive

{
  "body": {
    "status": 0, 
    "error_message": "OK", 
    "request": "body_of_the_request_you_sent", 
    "time": 1454517138,
    "score_response": {
      "status": 0, 
      "error_message": "OK", 
      "user_id": "billy_jones_301",
      "scores": {
        "payment_abuse": {
          "score": 0.898391231245,
          "reasons": [
            {
              "name": "UsersPerDevice",
              "value": 4,
              "details": {
                "users": "a, b, c, d"
              }
            }
          ]
        },
        "promotion_abuse": {
          "score": 0.472838192111,
          "reasons": []
        },
      },
      "latest_labels": {
        "payment_abuse": {
          "is_bad": true,
          "time": 1352201880,
          "description": "received a chargeback"
        },
        "promotion_abuse": {
          "is_bad": false,
          "time": 1362205000
        }
      }
    }
  }
  "http_status_code": 200
}
response.is_ok()            # false on failed score requests.
response.http_status_code   # 200 on successful score requests.
response.api_status         # see error codes and messages below
response.api_error_message  

# check for a label for a specific abuse type
bad_user = response.body['latest_labels']['payment_abuse']['is_bad'] if 'latest_labels' in response.body else None

# get Sift Score for a specific abuse type
payment_abuse_score = round((response.body['scores']['payment_abuse']['score'] * 100), 1)
response.ok?()              # false on failed score requests.
response.http_status_code   # 200 on successful score requests.
response.api_status         # see error codes and messages below
response.api_error_message  

# check for a label for a specific abuse type
bad_user = response.body.has_key?('latest_labels') ? response.body['latest_labels']['payment_abuse']['is_bad'] : nil

# get Sift Score for a specific abuse type
payment_abuse_score = (response.body['scores']['payment_abuse']['score'] * 100).round(1)
response->isOk()           # false on failed score requests.
response->httpStatusCode   # 200 on successful score requests.
response->apiStatus        # see error codes and messages below
response->apiErrorMessage  

# To grab the payment_abuse score:
$siftScore = round(($response->body['scores']['payment_abuse']['score'] * 100, 1);

Response Fields

  • status
    Integer

    The success or error code (see relevant error codes below).

  • error_message
    String

    Description of status code.

  • request
    String

    The content of the event you sent.

  • time
    Integer

    The time the request was processed, in seconds since epoch.

  • score_response
    Object

    The requested scoring information for the given user.

    • status
      Integer

      The success or error code (see relevant error codes below).

    • error_message
      String

      Description of error if applicable.

    • scores
      Map

      The scores map contains all computed scores for all applicable abuse types for a given user. The map is keyed by abuse type, which could be one of: payment_abuse, account_abuse, content_abuse, promotion_abuse. The values in this map are objects which containthe following fields:

      • score
        Float

        Score for the user between 0.0 and 1.0. A score of 0.5 translates to a score a 50 in the console.

      • reasons
        Array

        A list of the most significant reasons for the score and the values associated with the user. The included values will vary based on the user. Includes related users in the details object when applicable.

        • name
          String

          Name of the risk signal.

        • value
          String

          Value of the risk signal.

        • details
          Object

          Additional details. Provided only when relevant. E.g., may contain a details field which contains the IDs of related users.

    • user_id
      String

      The id of the user, matching what was passed in the Score API call.

    • latest_labels
      Map

      The latest_labels map contains entries for all abuse types for which the given user has been labeled. Note that the content of this map is not subject to the abuse types specified in the request; we always include all labels that have been applied to the given user. The map is keyed by abuse type, which could be one of: payment_abuse, account_abuse, content_abuse, promotion_abuse. The values in this map are objects which contain the following fields:

      • is_bad
        Boolean

        true if the user is labeled Bad, false if the user is labeled Not Bad.

      • time
        Long

        The time this label was applied to the user. It is a UNIX timestamp in seconds.

      • description
        String

        Freeform text description of the user and/or incident triggering the label.

Error Codes

  • -4

    Service currently unavailable. Please try again later.

  • -3

    Server-side timeout processing request. Please try again later.

  • -2

    Unexpected server-side error

  • -1

    Unexpected server-side error

  • 0

    OK

  • 51

    Invalid API key

  • 54
  • 60

    Rate limited; too many events have been received in a short period of time

Score API Reference

The Score API is meant to get an up to date risk score when you don’t have new event data to pass. This is useful for when there is a time gap between when you send data for a user and are performing some action where you want to check risk and there is not a natural event to send at this point. Some examples of when you may want to check the score are before:

  • Shipping out a package
  • Finalizing a money transfer
  • Giving access to a prearranged vacation rental

We do not recommend sending event data for a user and then very quickly attempting to get the score back with the Score API. If you need a score back quickly after an event, we can provide scores synchronously when events are sent. You can also synchronously get the status of a workflow and the score when you send an event.


Notes:
  • You can only pull the score for $user_id values we've received Events API events or JavaScript activity for.
  • Use your Sandbox REST API key for accessing Sandbox users when testing. Switch to your Production API key for your live integration.
  • Documentation for the previous version of the Score API can be found here.

Request all scores for a user:

curl -i "https://api.siftscience.com/v204/score/USER_ID_HERE/?api_key=REST_API_KEY_HERE"
import sift

client = sift.Client("REST_API_KEY_HERE")

response = client.score("USER_ID_HERE")
require "sift"

client = Sift::Client.new(:api_key => "REST_API_KEY_HERE")

response = client.score("USER_ID_HERE")
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'REST_API_KEY_HERE'));

$response = $client->score('USER_ID_HERE');

Request scores for specific abuse types using the abuse_types query parameter:

curl -i "https://api.siftscience.com/v204/score/USER_ID_HERE/?api_key=REST_API_KEY_HERE&abuse_types=payment_abuse,promotion_abuse"
import sift

client = sift.Client("REST_API_KEY_HERE")

response = client.score("USER_ID_HERE", abuse_types=["payment_abuse", "promotion_abuse"])
require "sift"

client = Sift::Client.new(:api_key => "REST_API_KEY_HERE")

response = client.score("USER_ID_HERE", :abuse_types => ["payment_abuse", "promotion_abuse"])
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'REST_API_KEY_HERE'));

$response = $client->score('USER_ID_HERE', array('abuse_types' => array('payment_abuse', 'promotion_abuse')));

Response

HTTP/1.1 200 OK
Content-Type: text/json;charset=UTF-8
Connection: keep-alive

{
  "status": 0, 
  "error_message": "OK", 
  "user_id": "billy_jones_301",
  "scores": {
    "payment_abuse": {
      "score": 0.898391231245,
      "reasons": [
        {
          "name": "UsersPerDevice",
          "value": 4,
          "details": {
            "users": "a, b, c, d"
          }
        }
      ]
    },
    "promotion_abuse": {
      "score": 0.472838192111,
      "reasons": []
    },
  },
  "latest_labels": {
    "payment_abuse": {
      "is_bad": true,
      "time": 1352201880,
      "description": "received a chargeback"
    },
    "promotion_abuse": {
      "is_bad": false,
      "time": 1362205000
    }
  }
}
response.is_ok()            # false on failed score requests.
response.http_status_code   # 200 on successful score requests.
response.api_status         # see error codes and messages below
response.api_error_message  

# check for a label for a specific abuse type
bad_user = response.body['latest_labels']['payment_abuse']['is_bad'] if 'latest_labels' in response.body else None

# get Sift Score for a specific abuse type
payment_abuse_score = round((response.body['scores']['payment_abuse']['score'] * 100), 1)
response.ok?()              # false on failed score requests.
response.http_status_code   # 200 on successful score requests.
response.api_status         # see error codes and messages below
response.api_error_message  

# check for a label for a specific abuse type
bad_user = response.body.has_key?('latest_labels') ? response.body['latest_labels']['payment_abuse']['is_bad'] : nil

# get Sift Score for a specific abuse type
payment_abuse_score = (response.body['scores']['payment_abuse']['score'] * 100).round(1)
response->isOk()           # false on failed score requests.
response->httpStatusCode   # 200 on successful score requests.
response->apiStatus        # see error codes and messages below
response->apiErrorMessage  

# To grab the payment_abuse score:
$siftScore = round(($response->body['scores']['payment_abuse']['score'] * 100, 1);

Response Fields

  • status
    Integer

    The success or error code (see relevant error codes below).

  • error_message
    String

    Description of error if applicable.

  • scores
    Map

    The scores map contains all computed scores for all applicable abuse types for a given user. The map is keyed by abuse type, which could be one of: payment_abuse, account_abuse, content_abuse, promotion_abuse. The values in this map are objects which containthe following fields:

    • score
      Float

      Score for the user between 0.0 and 1.0. A score of 0.5 translates to a score a 50 in the console.

    • reasons
      Array

      A list of the most significant reasons for the score and the values associated with the user. The included values will vary based on the user. Includes related users in the details object when applicable.

      • name
        String

        Name of the risk signal.

      • value
        String

        Value of the risk signal.

      • details
        Object

        Additional details. Provided only when relevant. E.g., may contain a details field which contains the IDs of related users.

  • user_id
    String

    The id of the user, matching what was passed in the Score API call.

  • latest_labels
    Map

    The latest_labels map contains entries for all abuse types for which the given user has been labeled. Note that the content of this map is not subject to the abuse types specified in the request; we always include all labels that have been applied to the given user. The map is keyed by abuse type, which could be one of: payment_abuse, account_abuse, content_abuse, promotion_abuse. The values in this map are objects which contain the following fields:

    • is_bad
      Boolean

      true if the user is labeled Bad, false if the user is labeled Not Bad.

    • time
      Long

      The time this label was applied to the user. It is a UNIX timestamp in seconds.

    • description
      String

      Freeform text description of the user and/or incident triggering the label.

Error Codes

  • -4

    Service currently unavailable. Please try again later.

  • -3

    Server-side timeout processing request. Please try again later.

  • -2

    Unexpected server-side error

  • -1

    Unexpected server-side error

  • 0

    OK

  • 51

    Invalid API key

  • 54
  • 60

    Rate limited; too many events have been received in a short period of time

Labels API Reference

The Labels API enables you to tell Sift Science which of your users are bad and which are good. By telling us who is bad and who is good, we can identify patterns that are unique to your business. Once you give this feedback, the platform instantly analyzes it and learns to identify good and bad behavior of other users more accurately.

Labeling users bad let's us give higher scores to other users who are likely to become bad. Labeling users as not bad is useful for when a user has a high score but is known to be okay; it will help lower your false positive rate.

If you want to change an existing label for a user - for example, from bad to good - all you need to do is send a new label and we'll overwrite the existing value.

If instead you want to remove labels because you are unsure whether a user is bad or good, you can use our Unlabel API.

Note: you can find the documentation for the previous version of this API here.

Labeling a User

To label a user, send an HTTP POST to our Label API endpoint:https://api.siftscience.com/v204/users/INSERT_USER_ID/labels

Be sure to replace INSERT_USER_ID with the ID of the user you are labeling. The response should have an HTTP status code of 200 and a status of 0. See our Error Codes for more information on non-zero statuses.

// Example curl request to label a user:
curl -X POST https://api.siftscience.com/v204/users/INSERT_USER_ID/labels -d \
'{ 
  "$api_key"     : "23b87a99k099fc98", 
  "$is_bad"      : true, 
  "$abuse_type"  : "payment_abuse",
  "$description" : "The user was testing cards repeatedly for a valid card", 
  "$source"      : "manual review", 
  "$analyst"     : "someone@your-site.com" 
}'

// Example of returned response:
{ 
  "time" : 1418757635 , 
  "status" : 0 , 
  "request" : 
  "{ \n  
      \"$api_key\"     : \"23b87a99k099fc98\", \n  
      \"$is_bad\"      : true, \n  
      \"$abuse_type\"  : \"payment_abuse\", \n  
      \"$description\" : \"The user was testing cards repeatedly for a valid card\", \n  
      \"$source\"      : \"manual review\", \n  
      \"$analyst\"     : \"someone@your-site.com\" \n
  }" ,
   "error_message" : "OK"
}
import sift

client = sift.Client("your_api_key_here")

properties = {
  "$is_bad"      : True, # ... or False; Required 
  "$abuse_type"  : "payment_abuse", # Required
  "$description" : "The user was testing cards repeatedly for a valid card", # Optional
  "$source"      : "manual review", # Optional
  "$analyst"     : "someone@your-site.com" # Optional
}

response = client.label("billy_jones_301", properties)
require "sift"

client = Sift::Client.new(:api_key => "your_api_key_here")

properties = {
  "$is_bad"      => true, # ... or false; Required 
  "$abuse_type"  => "payment_abuse", # Required
  "$description" => "The user was testing cards repeatedly for a valid card", # Optional
  "$source"      => "manual review", # Optional 
  "$analyst"     => "someone@your-site.com" # Optional 
}

response = client.label("billy_jones_301", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'your_api_key_here'));

$properties = array(
  '$is_bad'      => true, // ... or false; Required Field
  '$abuse_type'  => 'payment_abuse', // Required
  '$description' => 'The user was testing cards repeatedly for a valid card', // Optional
  '$source'      => 'manual review', // Optional 
  '$analyst'     => 'someone@your-site.com' // Optional 
);

$response = $client->label('billy_jones_301', $properties);
  • $api_key
    required · String

    Your Sift API key.

  • $is_bad
    required · Boolean

    Indicates whether a user is engaging in behavior deemed harmful to your business. Set to true if the user is engaging in abusive activity. Set to false if the user is engaging in valid activity.

  • $abuse_type
    required · String

    The type of abuse for which you want to send a label. It's important to send a label specific to the type of abuse the user is committing so that Sift can learn about specific patterns of behavior. You'll end up with more accurate results this way.

    Allowed values
    • payment_abuse
      A user using stolen payment information (e.g. a stolen credit card) to purchase goods or services.
    • content_abuse
      A user creating content or sending messages on your site in an abusive manner. This includes spam posts that pollute your site, fake listings intended to scam other users, spammy messages to other users, and any other fraudulent or abusive content.
    • promotion_abuse
      A user gaming the terms of a promotion in an excessive or abusive way. A promotion includes things like coupons, referral credits, limited offers, free trial periods, etc.
    • account_abuse
      A user who uses your service in a manner you deem abusive. This behavior can include creating fake/duplicate accounts or any other abusive patterns specific to your business.
  • $description
    String

    Freeform text description of the user and/or incident triggering the label. Useful as annotation on why the label was added.

  • $source
    String

    String describing the original source of the label information (e.g. payment gateway, manual review, etc.).

  • $analyst
    String

    Unique identifier (e.g. email address) of the analyst who applied the label. Useful for tracking purposes after the fact.

Unlabeling a User

If you are unsure whether a user is bad or good, you can always remove labels and leave the user in a neutral state. To unlabel a user for a particular abuse type, send an HTTP DELETE to our Labels API endpoint with the abuse_type query parameter:https://api.siftscience.com/v204/users/INSERT_USER_ID/labels?abuse_type=INSERT_ABUSE_TYPE

This API call should return an HTTP status code of 204.

In the rare case that you want to remove all labels for all abuse types for a particular user, send an HTTP DELETE to our Labels API endpoint without the abuse_type query parameter:https://api.siftscience.com/v204/users/INSERT_USER_ID/labels

If you just want to change an existing label - for example, from bad to good - all you need to do is send a new label and we'll overwrite the existing value. Learn more about labeling a user.

Note: you can find the documentation for the previous version of this API here.

// Example curl request to remove a payment abuse label:
curl -X DELETE "https://api.siftscience.com/v204/users/USER_ID/labels/?api_key=REST_API_KEY&abuse_type=payment_abuse"
import sift

client = sift.Client("your_REST_API_key_here - production key if not testing")
response = client.unlabel("billy_jones_301", abuse_type="payment_abuse")
require "sift"

client = Sift::Client.new(:api_key => "your_REST_API_key_here - production key if not testing")
response = client.unlabel("billy_jones_301", :abuse_type => "payment_abuse")
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient(array('api_key' => 'your_REST_API_key_here - production key if not testing'));
$response = $client->unlabel('billy_jones_301', array('abuse_type' => 'payment_abuse'));

iOS SDK Guide

The Sift iOS SDK enables sending in-app events and device information to Sift Science.

Capabilities

Broadly, the iOS SDK is the iOS analogue to the Sift Science javascript snippet. Just like the javascript snippet allows Sift to collect a range of browser properties, and view client-side user actions, the iOS SDK allows mobile applications to send in-app activity to Sift, as well as collect device properties.

Access

The Sift iOS SDK is presently in beta. Please fill out this form to participate in the beta.

Events

Anatomy of a Mobile Event

To make an event, an app provides:

  • a logical path, describing where in the app the activity occurred
  • an event type, indicating the kind of activity being recorded
  • an optional flat dictionary of attributes further describing the event

Events are created with eventWithType. As an example, one could imagine in the context of social app, we might write:

[Sift sharedInstance].userId = @"bob";
NSString *path = @"/user/alice/profile_view";
NSString *actionType = @"$view";
NSDictionary *viewDetails = @{@"swipe_direction": @"right"};
SFEvent *event = [SFEvent eventWithType:actionType path:path fields:viewDetails];

Pre-defined event types

Our SDK allow you to describe whatever event types, paths and additional fields are relevant to your app and business. However, Sift has pre-defined some event types which we expect to be common across customers, and to which we can associate special meaning and logic in our ML systems and console logic. As with our event api, pre-defined event types are prefixed with a dollar sign ($). The set of pre-defined types is starting out intentionally small, and will expand based on needs common to broad groups of customers. The initial set is:

  • $viewWhen the user views something within the app.

  • $button_clickedWhen the user clicks a relevant button within the app.

Pre-defined fields

Additionally, some fields are pre-defined. We expect these to be potentially useful across any event:

  • $nameA short, human-readable name.

  • $descriptionA brief, human-readable description.

Automatic events

In addition to allowing apps to explicitly send events related to their specific business logic, the SDK automatically collects/generates events which are expected to be informative across a range of clients. This presently includes two categories:

  • Events produced from notifications about the lifecycle of your app. At the moment, this list is quite limited, but we may expand it in future releases.
    • UIApplicationDidEnterBackgroundNotification
    • UIApplicationDidBecomeActiveNotification
  • Device property events, which captures a range of properties about the device's hardware and kernel. These properties are useful for determining, for example, whether the app is running in an emulator. Only diffs between subsequent device properties events are sent, to minimize network impact.

Sending Events to Sift

Basic Config

At a bare minimum, configuring your use of the Sift iOS SDK requires passing in your account id and beacon key. Your account id is retrievable by your account's admin in your profile section. The beacon key is the same key that is used in your Sift JS Snippet, and can be found in the developer section. Note in particular that this key is _not_ considered secret; a sophisticated bad actor could recover this key from your app, or from the JS beacon, and use it to submit mobile events.

The user_id can be set either at the level of the Sift sharedInstance, in which case it will be associated with all subsequent events,or it can be set on an event-by-event basis.

[Sift sharedInstance].accountId = ...;
[Sift sharedInstance].beaconKey = ...;
[Sift sharedInstance].userId = ...;

We will persist the accountId, beaconKey, and userId locally, such that you should typically only need to set them once. Please re-set the user_id after each new sign-in.

Queues: How Events get to Sift Science

Mobile apps cannot eagerly send Sift events as soon as they are generated; constantly making requests to Sift for small in-app actions may constitute an excessive use of network resources, or there could be no network connection at all when an event is generated.

To ease these burdens, our SDK centers around queues, which buffer messages locally, and can then send batches of messages together. If a batch of messages cannot be sent, due to network conditions, we retain it and reattempt to send later. Configuration for each queue gives apps control over the conditions that trigger such a batch send attempt (a combination of the age of pending events, or the data size). Apps can create multiple queues with differing configurations such that the most important events can be fast-tracked if necessary. To minimize overhead, our queues can also support only sending the differences between successive events. This is valuable when sending device properties information, or any other kind of data which is expected to be nearly identical between successive events.

By default, two queues are set up for you automatically: a default queue for app events, and a device properties queue. The device properties is only intended for use for by auto-generated device properties events. To send to the default queue you only need to do:

[[Sift sharedInstance] appendEvent:event]

To create a queue with a custom configuration (in this case, it flushes when the data is 10 seconds old) and append an event to that specific queue:

SFQueueConfig frequentQueueConfig;
memset(&frequentQueueConfig, 0, sizeof(frequentQueueConfig));  // Make sure it is zero-initialized.
frequentQueueConfig.uploadWhenOlderThan = 10;  // seconds
frequentQueueConfig.uploadWhenMoreThan = 100;  // ...or more than 100 events.
NSString *frequent = @"frequent";
[[Sift sharedInstance] addEventQueue:frequent config:frequentQueueConfig];
[[Sift sharedInstance] appendEvent:event toQueue:frequent];

You may also make your queue be the default one with:

[Sift sharedInstance].defaultQueueIdentifier = frequent;
[[Sift sharedInstance] appendEvent:event];  // Now this appends events to queue `frequent`.

Debugging and Development Support

During development you may want to confirm that events are being sent to Sift as expected, but without actually hitting Sift's services and recording data. You can override the service location to point an arbitrary location (e.g. a testing service you control).

[Sift sharedInstance].serverUrlFormat = @"http://localhost:8080";

Additionally, while in the process of integrating, you may find it slows your development cycle to wait for events to be uploaded. You may want to explicitly force uploads to occur prematurely, rather than waiting:

[[Sift sharedInstance] upload:YES];

A Healthy Integration : Best Practices and Examples

The specific events that your app sends to Sift should be tailored around the meaningful actions that users take within your app, which might be relevant to the fraud or abuse problems you're addressing. A healthy integration will send Sift enough data to construct a meaningful story about the user's interaction with your app, in a manner which complements your use of the events api. Aside from providing information to our ML systems, these events will also allow your teams analysts to trace a user's actions via the Sift Science Console.

Does your app have an ability to add or remove items to/from the cart locally, before communicating with your backend to create an order? Consider telling us about those specific actions:

NSString *path = @"/catalog/product/1234"
NSString *addToCart = @"add_to_cart";
NSDictionary *details = @{@"quantity": @"3"};
SFEvent *event = [SFEvent eventWithType:addToCart path:path fields:details];

Do your typical users spend several minutes searching and browsing your catalog and examining product details? Do your fraudsters jump immediately to a particular high-value product and immediately check-out?Then $view events will likely be important.

NSString *productPath = @"/catalog/product/1234";
SFEvent *productView = [SFEvent eventWithType:$view path:productPath fields:nil];
NSString *reviewsPath = @"/catalog/product/1234/reviews";
SFEvent *reviewsView = [SFEvent eventWithType:$view path:reviewsPath fields:nil];
NSString *searchPath = @"/catalog/search";
NSDictionary *details = @{@"query": @"labradoodles"};
SFEvent *searchView = [SFEvent eventWithType:$view path:searchPath fields:nil];

Does your app include functionality to share content or send messages through other services, which do not pass through your backend? Consider telling up about those shares/messages:

NSString *photoPath = @"/user/alice/photo/1234";
NSString *share = @"share";
NSDictionary *details = @{@"message_text": @"@alice has got her food photography skills _down_",
         @"shared_via": @"twitter"};
SFEevent *share = [SFEvent eventWithType:share path:photoPath fields:details];

In general, send us whatever in-app activity would be informative for a fraud analyst understand user behavior, and distinguish between normal and suspicious activity.