Sift Overview

We’ve made it easy to integrate. Integration guides and client libraries are also available.

There are three key parts to an integration:

1. Send User Events

Collect device information and browsing behavior, and send the key actions your users take.

Frontend Events:
  • JavaScript snippet: send device and behavioral information for users that visit your website.
Backend Events:
  • Events API: send information when users take key actions such as posting content, making a purchase, or creating an account.

2. Send Feedback

Let Sift know when you find a fraudulent user to improve your prediction accuracy.

  • Labels API: send your manual review and chargeback feedback to Sift.

3. Make Decisions

Take actions on orders and users.

  • Automation APIs: make automated decisions and stay alerted to changes in a user's risk profile.

Other Use Cases

We offer additional APIs to accommodate the following use cases:

  • Device Fingerprinting API: label and block devices used by fraudsters. Note that this API is for customers using the Device Fingerprint only product and that our other products collect device information.
  • Partner API: use our Partner API when you need to create sub-accounts for merchants. This API is commonly used by e-commerce platforms and payment gateways/processors.

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_BEACON_KEY_HERE']);
  _sift.push(['_setUserId', _user_id]);
  _sift.push(['_setSessionId', _session_id]);
  _sift.push(['_trackPageview']);

 (function() {
   function ls() {
     var e = document.createElement('script');
     var s = document.getElementsByTagName('script')[0];
     e.src = 'https://cdn.sift.com/s.js';
     s.parentNode.insertBefore(e, s);
   }
   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 Google CDN. 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's Events API accepts event data as a JSON request body via a HTTP POST request at this endpoint:

https://api.sift.com/v203/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.

  • $type
    required · String

    is "$create_order"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · 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.

  • $session_id
    required · if no User ID is provided

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

  • $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. occurred a nested address object. See Address under Complex Field Types for more details.

  • $payment_methods
    Array of Payment Methods

    The payment information associated with this order. occurred 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. occurred a nested address object. See Address under Complex Field Types for more details.

  • $expedited_shipping
    Boolean

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

  • $items
    Array of Items

    The list of items ordered. occurred a JSON array of $item objects, as specified under $item. See See Payment Method under Complex Field Types for more details.

  • $seller_user_id
    String

    For marketplace businesses, this is the seller's user ID, typically a database primary key. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

  • $shipping_method
    String

    Indicates the method of delivery to the user.

    Allowed Values
    • $electronic$physical
  • $ip
    String

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

// Sample $create_order event
{
  // Required Fields
  "$type"             : "$create_order",
  "$api_key"          : "YOUR_API_KEY",
  "$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
    }
  ],
  "$ip"                 : "54.208.214.78",

  // 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")

# 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
    }
  ],
  "$ip"                 : "54.208.214.78",

  # 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("$create_order", properties)

require "sift"

client = Sift::Client.new("YOUR_API_KEY")

# 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
    }
  ],
  "$ip"                 => "54.208.214.78",

  # 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("$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('YOUR_API_KEY');

// 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
    )
  ),
  '$ip'                 => '54.208.214.78',

  // 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('$create_order', $properties);

$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. Important: the existing order will be completely replaced by the values specified in $update_order, so be sure to specify all relevant values for the order, not just those that changed. If no matching $order_id found, a new order will be created.

  • $type
    required · String

    is "$update_order"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · 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.

  • $session_id
    required · if no User ID is provided

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

  • $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. occurred a nested address object. See Address under Complex Field Types for more details.

  • $payment_methods
    Array of Payment Methods

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

    Note: As opposed to $transaction, $update_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. occurred a nested address object. See Address under Complex Field Types for more details.

  • $expedited_shipping
    Boolean

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

  • $items
    Array of Items

    The list of items ordered. occurred a JSON array of $item objects, as specified under $item. See See Payment Method under Complex Field Types for more details.

  • $seller_user_id
    String

    For marketplace businesses, this is the seller's user ID, typically a database primary key. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

  • $shipping_method
    String

    Indicates the method of delivery to the user.

    Allowed Values
    • $electronic$physical
  • $ip
    String

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

// Sample $update_order event
{
  // Required Fields
  "$type"             : "$update_order",
  "$api_key"          : "YOUR_API_KEY",
  "$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
    }
  ],
  "$ip"                 : "54.208.214.78",

  // 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")

# 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
    }
  ],
  "$ip"                 : "54.208.214.78",

  # 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("$update_order", properties)

require "sift"

client = Sift::Client.new("YOUR_API_KEY")

# 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
    }
  ],
  "$ip"                 => "54.208.214.78",

  # 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("$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('YOUR_API_KEY');

// 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
    )
  ),
  '$ip'                 => '54.208.214.78',

  // 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('$update_order', $properties);

$transaction

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

  • $type
    required · String

    is "$transaction"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

    The user's account ID according to your systems. 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.

  • $user_email
    required · String

    Email of the user executing this transaction. 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.

  • $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. occurred a nested address object. See Address under Complex Field Types for more details.

  • $payment_method
    Payment Method

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

    Note: As opposed to $create_order, there should be only one $payment_method per $transaction. See Payment Method under Complex Field Types for more details.

  • $shipping_address
    Address

    The shipping address as entered by the user. occurred a nested address object. See Address under Complex Field Types for more details.

  • $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

    For marketplace businesses, this is the seller's user ID, typically a database primary key. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

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

  • $ip
    String

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

// Sample $transaction event
{
  // Required Fields
  "$type"             : "$transaction",
  "$api_key"          : "YOUR_API_KEY",
  "$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"
  },
  "$payment_method"   : {
      "$payment_type"    : "$credit_card",
      "$payment_gateway" : "$braintree",
      "$card_bin"        : "542486",
      "$card_last4"      : "4444"
  },

  // 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",
  "$ip"               : "54.208.214.78",

  // 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")

# 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"
  },
  "$payment_method"   : {
      "$payment_type"    : "$credit_card",
      "$payment_gateway" : "$braintree",
      "$card_bin"        : "542486",
      "$card_last4"      : "4444"
  },

  # 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",
  "$ip"               : "54.208.214.78",

  # 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("YOUR_API_KEY")

# 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"
  },
  "$payment_method"   => {
      "$payment_type"    => "$credit_card",
      "$payment_gateway" => "$braintree",
      "$card_bin"        => "542486",
      "$card_last4"      => "4444"
  },

  # 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",
  "$ip"               => "54.208.214.78",

  # 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('YOUR_API_KEY');

// 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'
  ),
  '$payment_method'   => array(
      '$payment_type'    => '$credit_card',
      '$payment_gateway' => '$braintree',
      '$card_bin'        => '542486',
      '$card_last4'      => '4444'
  ),

  // 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',
  '$ip'               => '54.208.214.78',
  // 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);

$create_content

Use $create_content to record when a user creates content on your site (for example, a job posting, sale listing, or blog post).

  • $type
    required · String

    is "$create_content"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

    The user's account ID according to your systems. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

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

  • $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 message.

  • $content
    String

    The text content of the message.

  • $ip
    String

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

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

  // Supported Fields
  "$contact_email" : "bill@gmail.com",
  "$contact_phone" : "1-415-555-6040",
  "$subject"    : "Job available now",
  "$content"    : "Contact me for more details.",
  "$ip"         : "54.208.214.78"
}

import sift

client = sift.Client("YOUR_API_KEY")

# Sample $create_content event
properties = {
  # Required Fields

  "$user_id"    : "billy_jones_301",

  # Supported Fields
  "$contact_email" : "bill@gmail.com",
  "$contact_phone" : "1-415-555-6040",
  "$subject"    : "Job available now",
  "$content"    : "Contact me for more details.",
  "$ip"         : "54.208.214.78"
}

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

require "sift"

client = Sift::Client.new("YOUR_API_KEY")

# Sample $send_message event
properties = {
  # Required Fields

  "$user_id"    => "billy_jones_301",

  # Supported Fields
  "$contact_email" => "bill@gmail.com",
  "$contact_phone" => "1-415-555-6040",
  "$subject" => "Job available now",
  "$content"  => "Contact me for more details.",
  "$ip"       => "54.208.214.78"
}

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('YOUR_API_KEY');

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

  '$user_id'    => 'billy_jones_301',

  // Supported Fields
  '$contact_email' => 'bill@gmail.com',
  '$contact_phone' => '1-415-555-6040',
  '$subject' => 'Job available now',
  '$content'  => 'Contact me for more details.',
  '$ip'       => '54.208.214.78'
);

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

$add_item_to_cart

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

  • $type
    required · String

    is "$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 knownString

    The user's account ID according to your systems. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

  • $item
    Item

    The product item added to cart. occurred a nested $item object. Required subfields are $item_id, $product_title, and $price. The $quantity is specified as a subfield. See Item under Complex Field Types for more details.

  • $ip
    String

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

// Sample $add_item_to_cart event
{
  // Required Fields
  "$type"       : "$add_item_to_cart",
  "$api_key"    : "YOUR_API_KEY",
  "$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
  },
  "$ip"         : "54.208.214.78"
}

import sift

client = sift.Client("YOUR_API_KEY")

# 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
  },
  "$ip"         : "54.208.214.78"
}

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

require "sift"

client = Sift::Client.new("YOUR_API_KEY")

# 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
  },
  "$ip"         => "54.208.214.78"
}

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('YOUR_API_KEY');

// 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
  ),
  '$ip'         => '54.208.214.78',
);

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

$remove_item_from_cart

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

  • $type
    required · String

    is "$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
    send if knownString

    The user's account ID according to your systems. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

  • $item
    Item

    The product item removed from cart. occurred a nested $item object. Strongly recommended subfields are $item_id, $product_title, and $price. The $quantity is specified as a subfield. See Item under Complex Field Types for more details.

  • $ip
    String

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

// Sample $remove_item_from_cart event
{
  // Required Fields
  "$type"       : "$remove_item_from_cart",
  "$api_key"    : "YOUR_API_KEY",
  "$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"
  },
  "$ip"         : "54.208.214.78"
}

import sift

client = sift.Client("YOUR_API_KEY")

# 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"
  },
  "$ip"         : "54.208.214.78"
}

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

require "sift"

client = Sift::Client.new("YOUR_API_KEY")

# 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"
  },
  "$ip"         => "54.208.214.78"
}

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('YOUR_API_KEY');

// 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'
  ),
  '$ip'         => '54.208.214.78'
);

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

$submit_review

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

  • $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"
  • $ip
    String

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

// Sample $submit_review event
{
  // Required Fields
  "$type"              : "$submit_review",
  "$api_key"           : "YOUR_API_KEY",
  "$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",
  "$ip"                : "54.208.214.78",

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

import sift

client = sift.Client("YOUR_API_KEY")

# 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",
  "$ip"                : "54.208.214.78",

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

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

require "sift"

client = Sift::Client.new("YOUR_API_KEY")

# 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",
  "$ip"                => "54.208.214.78",

  # 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('YOUR_API_KEY');

// 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',
  '$ip'                => '54.208.214.78',

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

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

    is "$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: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

  • $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: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

  • $content
    String

    The text content of review submitted.

  • $submission_status
    Status

    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.

  • $type
    required · String

    is "$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: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

  • $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

    The ID of the user receiving the message. Required to compute network graphs. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

  • $subject
    String

    The subject of the message.

  • $content
    String

    The text content of the message.

  • $ip
    String

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

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

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

import sift

client = sift.Client("YOUR_API_KEY")

# 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.",
  "$ip"         : "54.208.214.78"
}

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

require "sift"

client = Sift::Client.new("YOUR_API_KEY")

# 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.",
  "$ip"         => "54.208.214.78"
}

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('YOUR_API_KEY');

// 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.',
  '$ip'         => '54.208.214.78'
);

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

$logout

Use $logout to record when a user logs out.

  • $type
    required · String

    is "$logout"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

    The user's account ID according to your systems. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

  • $ip
    String

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

// Sample $logout event
{
  // Required Fields
  "$type"      : "$logout",
  "$api_key"   : "YOUR_API_KEY",
  "$user_id"   : "billy_jones_301",

  // Supported Fields
  "$ip"        : "54.208.214.78"
}

import sift

client = sift.Client("YOUR_API_KEY")

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

  # Supported Fields
  "$ip"        : "54.208.214.78"
}

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

require "sift"

client = Sift::Client.new("YOUR_API_KEY")

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

  # Supported Fields
  "$ip"        => "54.208.214.78"
}

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('YOUR_API_KEY');

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

  // Supported Fields
  '$ip'        => '54.208.214.78'
);

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

$link_session_to_user

Use $link_session_to_user to associate data from a specific session to a user. Generally used only in anonymous checkout workflows.

  • $type
    required · String

    is "$link_session_to_user"

  • $api_key
    required · String

    Your Sift REST API key.

  • $session_id
    required · String

    The user's current session ID, used to associate Javascript page events with their REST API counterparts.

  • $user_id
    required · String

    The user's account ID according to your systems. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

  • $ip
    String

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

// Sample $link_session_to_user event
{
  // Required Fields
  "$type"       : "$link_session_to_user",
  "$api_key"    : "YOUR_API_KEY",
  "$user_id"    : "billy_jones_301",
  "$session_id" : "gigtleqddo84l8cm15qe4il",

  // Supported Fields
  "$ip"         : "54.208.214.78"
}

import sift

client = sift.Client("YOUR_API_KEY")

# Sample $link_session_to_user event
properties = {
  # Required Fields
  "$user_id"    : "billy_jones_301",
  "$session_id" : "gigtleqddo84l8cm15qe4il",

  # Supported Fields
  "$ip"         : "54.208.214.78"
}

response = client.track("$link_session_to_user", properties)

require "sift"

client = Sift::Client.new("YOUR_API_KEY")

# Sample $link_session_to_user event
properties = {
  # Required Fields
  "$user_id"    => "billy_jones_301",
  "$session_id" => "gigtleqddo84l8cm15qe4il",

  # Supported Fields
  "$ip"         => "54.208.214.78"
}

response = client.track("$link_session_to_user", 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('YOUR_API_KEY');

// Sample $link_session_to_user event
$properties = array(
  // Required Fields
  '$user_id'    => 'billy_jones_301',
  '$session_id' => 'gigtleqddo84l8cm15qe4il',

  // Supported Fields
  '$ip'         => '54.208.214.78'
);

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

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

  • $type
    required · String

    is "$chargeback"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

    The user's account ID according to your systems. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

  • $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
  • $ip
    String

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

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

  // Recommended Fields
  "$chargeback_state"  : "$lost",
  "$chargeback_reason" : "$duplicate",

  // Supported Fields
  "$ip"                : "54.208.214.78"
}

import sift

client = sift.Client("YOUR_API_KEY")

# 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",

  # Supported Fields
  "$ip"                : "54.208.214.78"
}

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

require "sift"

client = Sift::Client.new("YOUR_API_KEY")

# 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",

  # Supported Fields
  "$ip"                => "54.208.214.78"
}

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('YOUR_API_KEY');

// 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',

  // Supported Fields
  '$ip'                => '54.208.214.78'
);

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

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

  • $type
    required · String

    is "$order_status"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required if known · 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.

  • $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 Action webhook that triggered the status change.

  • $description
    String

    Any additional information about this order status change.

  • $ip
    String

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

// Sample $order_status event
{
  // Required Fields
  "$type"             : "$order_status",
  "$api_key"          : "YOUR_API_KEY",
  "$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",
  "$ip"               : "54.208.214.78"
}
import sift

client = sift.Client("YOUR_API_KEY")

# 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",
  "$ip"               : "54.208.214.78"
}

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

require "sift"

client = Sift::Client.new("YOUR_API_KEY")

# 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",
  "$ip"               => "54.208.214.78"
}

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('YOUR_API_KEY');

// 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',
  '$ip'               => '54.208.214.78'
);

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

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 or omit the field.

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.

  • $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 occurred 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 occurred a nested JSON object.


Fields of this type: $billing_address, $shipping_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 billingaddress.

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

// 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'
);

Item

The Item field type represents a product or service for salein 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.

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

// 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
);

Payment Method

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

  • $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$edgil_payway$elavon$epayeu$eprocessing_network$eway$first_atlantic_commerce$first_data$g2apay$giropay$global_payments$global_payways$globalcollect$gocardless$hdfc_fssnet$hipay$ingenico$internetsecure$intuit_quickbooks_payments$iugu$jabong$mastercard_payment_gateway$maxipago$mercadopago$merchant_esolutions$mirjeh$moip$mollie$moneris_solutions$moneygram$nmi$ogone$okpay$omise$openpaymx$optimal_payments$pagar_me$pagseguro$pagofacil $paxum$payeer$payfast$paygate$payment_express$paymentwall$paymill$payone$paypal$paysera$paysimple$paystation$paytrace$paytrail$payture$payu$payulatam$payza$peach_payments$perfect_money$pinpayments$pivotal_payments$planet_payment$princeton_payment_solutions$psigate$qiwi$quickpay$raberil$ratepay$rbkmoney$rede$redpagos$redsys$rewardspay$rietumu$rocketgate$sagepay$sermepa$shopify_payments$simplify_commerce$skrill$smart2pay$smartcoin$sofort$sps_decidir$stone$stripe$synapsepay$telerecargas$towah$tnspay$transact_pro$transfirst$trustcommerce$trustly$twocheckout$unionpay$usa_epay$vantiv$veritrans$venmo$versapay$vesta$vindicia$virtual_card_services$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.

  • $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 failureset the value to $failure.

  • $routing_number
    String

    This is the ABA routing number used for electronic fund transfers.

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

// 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'
);

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",
  "$user_id"           : "billy_jones_301",
  "recipient_user_id"  : "marylee819",
  "call_duration"      : 4428
}

import sift

client = sift.Client("YOUR_API_KEY")

# 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("YOUR_API_KEY")

# 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('YOUR_API_KEY');

// 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 throw-away 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 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 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 some permission 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.

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

Anonymous Events

Anonymous events are events that do not have a $user_id. This can happen when a user visits a website for the first time, when a customer user has not logged in, or during a guest checkout flow.

Anonymous Events Restrictions

Anonymous events are not allowed to be scored synchronously because there is no user associated with the event. Anonymous event promotion is not supported for synchronous events.

Anonymous Event Promotion

When an anonymous event is sent to Sift we will try to fill in the $user_id based on past or future non-anonymous events. When we find an event that can promote the anonymous event to a non-anonymous event then we promote this event asynchronously. When the event is promoted the event is scored, workflows are not run on the event, and the event can be seen in the user’s activity log.

Additional Resources

Tracking Anonymous User Activity

Automation APIs overview

There are many ways to automate with Sift.

  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.
  3. The Score API is best for situations when you do not need to make a decision about a user at the moment they take an action and you do not have a webhook set up.

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 thatshould be taken on the user, order, or posting, such as block or review. Your fraud team can setup 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.sift.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("YOUR_API_KEY")

# define event_properties here
response = client.track("$create_order", event_properties, return_action=True)

require "sift"
client = Sift::Client.new("YOUR_API_KEY")

# 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('YOUR_API_KEY');

// 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_fraud": 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_fraud'] 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://sift.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_fraud'] : 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://sift.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://sift.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://sift.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 (optional)

      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_fraud
        Boolean

        True if the user is labeled Fraud, false if the user is labeled Not Fraud. 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.

    • 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 inyour console. Our unique id for this particular application of the action tothis 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 in milliseconds.

      • triggers
        String

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

Error Codes

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

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.

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

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 inyour console. Our unique id for this particular application of the action tothis 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 in milliseconds.

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

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'.
Switch to one of the programming language tabs for the specific language implementation of webhook signature verification.

import json
from hashlib import sha256
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!
  # 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 = "sha256={}".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!
  # 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('sha256')
  calculated_hmac = OpenSSL::HMAC.hexdigest(digest, SIFT_WEBHOOK_SECRET_KEY, request.body)
  verification_signature = "sha256=#{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!
# 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  = "sha256=" . hash_hmac('sha256', $requestBody, $SIFT_WEBHOOK_SECRET_KEY);

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

Score API Reference

The Score API is ideal for situations when you do not need to make a decision about a user at the moment they take an action and you do not have a webhook set up. For example, when you need to act on the user after you hear back from a third party.

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.
curl -i https://api.sift.com/v203/score/USER_ID_HERE/?api_key=YOUR_API_KEY

import sift

client = sift.Client("YOUR_API_KEY")

response = client.score("USER_ID_HERE")

require "sift"

client = Sift::Client.new("YOUR_API_KEY")

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('YOUR_API_KEY');

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

Response

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

{
  "status": 0,
  "error_message": "OK",
  "score": 0.5124965408964449,
  "reasons": [{
    "name": "UsersPerDevice",
    "value": 4,
    "details": {
      "users": "a, b, c, d"
    }
  }],
  "user_id": "al_capone",
  "latest_label": {
    "is_fraud": true,
    "time": 1350201660000,
    "reasons": [
      "$chargeback",
      "$spam"
    ],
    "description": "known fraudster"
  },
  "actions": [{
    "id" : "975b19da08c979dd90311b4e23f88d407ffffeb0d1878d83",
    "action": {
      "id": "5586447de4b0b24f2b992b87"
    },
    "entity": {
      "id": "al_capone",
    },
    "time": 1436982891721,
    "triggers": [{
      "type": "formula",
      "source": "score_api",
      "trigger": {
        "id": "55ce74d5e4b08533f12eac97"
      }
    }, {
      "type": "formula",
      "source": "score_api",
      "trigger": {
        "id": "55ce74d5e4b08533f12ead21"
      }
    }]
  }]
}

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_fraud'] if 'latest_label' in response.body else None

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

# check if a certain action has been applied to the user
prevent_action_id = 'prevent' # create in Sift Console: https://sift.com/console/actions/users
entity_id = user_id
  for action in response.body['actions']:
    if action['entity']['id'] == entity_id and action['action']['id'] == action_id:
      # take 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_fraud'] : nil

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

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

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 score:
$siftScore = round(($response->body['score'] * 100), 1);

$preventActionID = 'prevent'; // create in Sift Console: https://sift.com/console/actions/users
$entityId = $userID;
foreach ($response->body['actions'] as $action) {
  if ($action['entity']['id'] == $entityId && $action['action']['id'] == $preventActionID) {
    // take action
  }
}

Response Fields

  • status
    Integer

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

  • error_message
    String

    Description of error if applicable.

  • 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. Includes related users in the details object when applicable.

  • user_id
    String

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

  • latest_label
    String

    The label applied to the user, if applicable. Includes the time it was applied as a UNIX tiemestamp, along with any reasons and description provided through the console or Labels API.

  • actions
    Array

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

    • triggers
      String

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

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

    Specified user_id has no scoreable events

  • 60

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

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 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://api.sift.com/v3/accounts/{id}/devices/{id}' \n  -H 'Content-Type: application/json' \n  -u {YOUR_API_KEY}:
Example Response
{
  "id" : "{id}",
  "label" : "fraud",
  "labeled_at" : 1241241214000,
  "first_seen" : 1412990802000,
  "users" : {
    "data" : [ {
      "id" : "bob123",
      "href" : "https://api.sift.com/v3/accounts/{id}/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 Account ID, which can be found in the Sift Console under the Developer Tab

  • deviceId
    required · string

    Device Fingerprints are strings that are 26 characters in length, e.g. "{id}"

Response

  • id
    required · string

    Device Fingerprints are strings that are 26 characters in length, e.g. '{id}'

  • first_seen
    integer

    The time (occurred POSIX time in milliseconds) when Sift 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 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
    • fraudThis device has exhibited behavior that is fraudulent or otherwise detrimental to your business
    • not_fraudThis 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 (occurred POSIX time in milliseconds) when Sift first identified this device within our network of customers.

    • score
      number

      A representation of how likely this device is fraudulent 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 fraudulent.

    • pervasiveness
      string

      NOT YET AVAILABLE. A representation of how often Sift 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 "fraud" or "not_fraud". 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, if 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://api.sift.com/v3/accounts/{id}/devices/{id}/label' \n  -H 'Content-Type: application/json' \n  -u {YOUR_API_KEY}: \n  -d '{
  "label" : "fraud"
}'
Example Response
{
  "label" : "fraud"
}

Parameters

  • accountId
    required · string

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

  • deviceId
    required · string

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

Entity

  • label
    string

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

Response

  • label
    string

    Allowed Values
    • fraudThis device has exhibited behavior that is fraudulent or otherwise detrimental to your business
    • not_fraudThis 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 "fraud" in the past, you should most likely restrict this device's ability to interact with your site.

Example Request
$ curl -XGET 'https://api.sift.com/v3/accounts/0x012345678/sessions/465733823' \n  -H 'Content-Type: application/json' \n  -u {YOUR_API_KEY}:
Example Response
{
  "id" : 465733823,
  "time" : 1412990802000,
  "device" : {
    "id" : "{id}",
    "label" : "fraud",
    "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 Account ID, which can be found in the Sift 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 JavaScript snippet.

  • device
    object

    Data related to a Device Fingerprint

    • id
      required · string

      A device fingerprint is an identifier that represents a device.

    • first_seen
      integer

      The time (occurred POSIX time in milliseconds) when Sift 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 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
      • fraudThis device has exhibited behavior that is fraudulent or otherwise detrimental to your business
      • not_fraudThis 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 (occurred POSIX time in milliseconds) when Sift first identified this device within our network of customers.

      • score
        number

        A representation of how likely this device is fraudulent 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 fraudulent.

      • pervasiveness
        string

        NOT YET AVAILABLE. A representation of how often Sift 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://api.sift.com/v3/accounts/0x012345678/users/465733823/devices' \n  -H 'Content-Type: application/json' \n  -u {YOUR_API_KEY}:
Example Response
{
  "data" : [ {
    "id" : "{id}",
    "href" : "https://api.sift.com/v3/accounts/{id}/devices/{id}"
  }, {
    "id" : "{id}",
    "href" : "https://api.sift.com/v3/accounts/{id}/devices/{id}"
  } ]
}

Parameters

  • accountId
    required · string

    Your Sift Account ID, which can be found in the Sift 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

Partner API

The Partner API allows e-commerce platforms, agencies, and payment gateways/processors to programmatically create Sift 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 accounts on behalf of their customers
  • List the set of accounts they have created, along with the API keys for those accounts.
  • Submit events and labels, or request scores on behalf of their customers

Access

Before using the Partner API, please contact our partner 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.

Labels API Reference

The Labels API allows for labeling both fraudulent behavior and false positives (good users with high Sift Scores). Our system instantly analyzes these examples, learning to identify good and bad behavior more accurately. Unlabel to correct mistakes or indicate that the status of a user has changed.

Labeling a User

To label a user ID, send an HTTP POST to our Label API endpoint:

https://api.sift.com/v203/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.sift.com/v203/users/INSERT_USER_ID/labels -d \n'{
  "$api_key"     : "YOUR_API_KEY",
  "$is_fraud"      : true,
  "$reasons"     : ["$chargeback"],
  "$description" : "Freeform text describing the user or incident.",
  "$source"      : "Payment Gateway",
  "$analyst"     : "someone@your-site.com"
}'

// Example of returned response:
{
  "time" : 1418757635 ,
  "status" : 0 ,
  "request" :
  "{ 

      "$api_key"     : "YOUR_API_KEY", 

      "$is_fraud"      : true, 

      "$reasons"     : ["$chargeback"], 

      "$description" : "Freeform text describing the user or incident.", 

      "$source"      : "Payment Gateway", 

      "$analyst"     : "someone@your-site.com" 

  }" ,
   "error_message" : "OK"
}

import sift

client = sift.Client("YOUR_API_KEY")

properties = {
  "$is_fraud"      : True, # ... or False; Required
  "$reasons"     : ["$chargeback"], # Recommended
  "$description" : "Freeform text describing the user or incident.", # Optional
  "$source"      : "Payment Gateway", # Optional
  "$analyst"     : "someone@your-site.com" # Optional
}

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

require "sift"

client = Sift::Client.new("YOUR_API_KEY")

properties = {
  "$is_fraud"      => true, # ... or false; Required
  "$reasons"     => ["$chargeback"], # Recommended
  "$description" => "Freeform text describing the user or incident.", # Optional
  "$source"      => "Payment Gateway", # 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('YOUR_API_KEY');

$properties = array(
  '$is_fraud'      => true, // ... or false; Required Field
  '$reasons'     => ['$chargeback'], // Recommended
  '$description' => 'Freeform text describing the user or incident.', // Optional
  '$source'      => 'Payment Gateway', // Optional
  '$analyst'     => 'someone@your-site.com' // Optional
);

$response = $client->label('billy_jones_301', $properties);
  • $api_key
    required · String

    Your Sift API key.

  • $is_fraud
    required · Boolean

    Indicate whether this user is fraudulent, or otherwise engaging in activities that are negative for yourbusiness. Set to true if the user committed fraud. Set to false to label this user as"not bad", especially if this user received a high Sift Score.

  • $reasons
    recommended · Array of Strings

    A list of one or more reasons indicating why this particular user has been labeled “bad.”

    Allowed values
    • $chargeback
      Chargeback received for this user.
    • $spam
      The user is sending spam.
    • $funneling
      The user engaged in coordinated buying and selling in an effort to funnel money.
    • $fake
      The user is listing non-existent or fraudulent products or services for sale.
    • $referral
      The user engaged in various kinds of referral abuse.
    • $duplicate_account
      This user account is a duplicate of another account.

    Note: while reasons are useful, they are not required.

  • $description
    String

    Freeform text description of the user and/or incident triggering the label for your internal record-keeping.

  • $source
    String

    String describing the original source of the label information (e.g. payment gateway, manual review, etc.).

  • $analyst
    String

    String indicating the analyst who created the label event.

Beta Labels API Reference

The Labels API allows for labeling both fraudulent behavior and false positives (good users with high Sift Scores) for several different types of abuse. Our system instantly analyzes these examples, learning to identify good and bad behavior more accurately. Unlabel to correct mistakes or indicate that the status of a user has changed.

Labeling a User

To label a user, send an HTTP POST to our Label API endpoint:

https://api.sift.com/v203/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.sift.com/v203/users/INSERT_USER_ID/labels -d \n'{
  "$api_key"     : "YOUR_API_KEY",
  "$is_fraud"      : true,
  "$abuse_type"  : "payment_abuse",
  "$description" : "Freeform text describing the user or incident.",
  "$source"      : "Payment Gateway",
  "$analyst"     : "someone@your-site.com"
}'

// Example of returned response:
{
  "time" : 1418757635 ,
  "status" : 0 ,
  "request" :
  "{ 

      "$api_key"     : "YOUR_API_KEY", 

      "$is_fraud"      : true, 

      "$abuse_type"  : "payment_abuse", 

      "$description" : "Freeform text describing the user or incident.", 

      "$source"      : "Payment Gateway", 

      "$analyst"     : "someone@your-site.com" 

  }" ,
   "error_message" : "OK"
}

import sift

client = sift.Client("YOUR_API_KEY")

properties = {
  "$is_fraud"      : True, # ... or False; Required
  "$abuse_type"  : "payment_abuse", # Required
  "$description" : "Freeform text describing the user or incident.", # Optional
  "$source"      : "Payment Gateway", # Optional
  "$analyst"     : "someone@your-site.com" # Optional
}

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

require "sift"

client = Sift::Client.new("YOUR_API_KEY")

properties = {
  "$is_fraud"      => true, # ... or false; Required
  "$abuse_type"  => "payment_abuse", # Required
  "$description" => "Freeform text describing the user or incident.", # Optional
  "$source"      => "Payment Gateway", # 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('YOUR_API_KEY');

$properties = array(
  '$is_fraud'      => true, // ... or false; Required Field
  '$abuse_type'  => 'payment_abuse', // Required
  '$description' => 'Freeform text describing the user or incident.', // Optional
  '$source'      => 'Payment Gateway', // Optional
  '$analyst'     => 'someone@your-site.com' // Optional
);

$response = $client->label('billy_jones_301', $properties);
  • $api_key
    required · String

    Your Sift API key.

  • $is_fraud
    required · Boolean

    Indicate whether this user is fraudulent, or otherwise engaging in activities that are negative for yourbusiness. Set to true if the user committed fraud. Set to false to label this user as"not bad", especially if this user received a high Sift Score.

  • $abuse_type
    required · String

    The type of abuse this label applies to.

    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 spammy messages, fake listings intended to scam legitimate customers, and any other fraudulent or abusive content.
    • promotion_abuse
      A user intentionally gaming the terms of a promotional credit for their own benefit, usually through the creation of fake accounts. Promotional credits include: coupons, limited offers, referral credits, free trial periods, etc.
    • account_abuse
      A user abusing your site in any manner not captured by the other types of abuse defined above.
  • $description
    String

    Freeform text description of the user and/or incident triggering the label for your internal record-keeping.

  • $source
    String

    String describing the original source of the label information (e.g. payment gateway, manual review, etc.).

  • $analyst
    String

    String indicating the analyst who created the label event.

Unlabeling a User ID

Occasionally, you may mistakenly label a user and wish to undo this action so that Sift “forgets” what it’s learned. To remove a label from a user, send an HTTP DELETE to the Labels API endpoint:

https://api.sift.com/v203/users/INSERT_USER_ID/labels

This API call should return an HTTP status code of 204.

curl -X DELETE https://api.sift.com/v203/users/THE_USER_ID/labels/?api_key=YOUR_API_KEY
import sift

client = sift.Client("YOUR_API_KEY - production key if not testing")
response = client.unlabel("billy_jones_301")
require "sift"

client = Sift::Client.new("YOUR_API_KEY - production key if not testing")
response = client.unlabel("billy_jones_301")
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('YOUR_API_KEY - production key if not testing');
$response = $client->unlabel('billy_jones_301');