
Sift API Overview
Sift is a machine learning platform that helps stop fraud and abuse online. Sift empowers businesses to make accurate, real-time decisions that both improve user experience and increase revenue. You can use Sift whether you’re building a brand new risk system or looking to augment an existing legacy system.
Sift makes risk predictions in real-time using your own data and data from the 100s of millions of users in Sift’s global network. Our machine learning systems identify patterns of behavior across thousands of device, user, network, and transactional signals. These are often patterns that only a machine learning system can spot. Using Sift, businesses have stopped 100s billions of dollars of fraud worldwide.
There are 5 different unique types of abuse that Sift can stop:
- Payment Abuse - Reduce friction at checkout to increase revenue and stop chargebacks before they hurt your business.
- Account Abuse - Stop fake accounts from polluting your service and block bad users before they harm your business.
- Account Takeover - Stop bad actors from hijacking users accounts. Keep your users safe and ensure that they always trust your service.
- Content Abuse - Stop spammy and scammy posts from polluting your service. Keep your users safe from malicious actors.
- Promotion Abuse - Make sure you’re only rewarding real users by stopping referral rings and repeated use of promotions.
Sift easily integrates into your existing systems using modern REST APIs, Javascript snippet, and SDKs for iOS and Android. In addition, Sift offers Workflows, a powerful rules automation platform, and Review Queues. These enable you to build a complete solution with Sift.
The next sections will walk you through getting started with Sift.
Sending Data to Sift
To use Sift, we need to know about your users, what they do with your service, and what actions you take in response to your users. This includes:
- How your users are interacting on your website and/or mobile apps (eg what pages they are visiting, which devices they are using, how long they spend on each page, etc). We automatically collect this data when you add our JavaScript snippet to your website and our Mobile SDKs to your app.
- What actions your users are taking, usually key user lifecycle events (eg creating an account, placing an order, posting content to other users, etc.). You will send this data from your application to Sift via our REST API.
- What actions your business is taking in response to users (eg approve an order, ban user due to fraud, cancel order due to chargeback, etc). You will also send this data from your application to Sift via our Decisions API.
Because Sift gets smarter the more data it has about your business, you can jump start your integration by backfilling a few months worth of historical data.
If you have any questions about what data to send to Sift, check our integration guides for recommendations based on your type of business. If you have any other questions, don’t hesitate to contact us at support@sift.com.
Get Started with Sift Scores
Once you start sending data, Sift starts to make predictions about whether a user will be good or bad. Sift represents this risk with a score between 0 and 100, where risky users have higher scores. Sift generates a unique score per type of fraud you're preventing (e.g. payment fraud, content abuse, etc.), so a user could have a high score for one type of abuse and a low score for another.
Sift’s Risk Scores are generated in real-time in response to whatever data has been sent. As you send more data for a user, the predictions will become more accurate. Scores can both increase or decrease in response to new data. It all depends on whether the user is exhibiting good or risky patterns.
You’ll use Sift Risk Scores to help you make decisions about your users at key lifecycle events (e.g. creating an account, placing an order, etc.). For example, whether you want to automatically block an order, send it to manual review or approve it, all these choices can be decided based on the Sift Score. Since all businesses are different, finding your unique score thresholds that achieve your business goals is key. Don’t hesitate to email support@sift.com if you need any help choosing the score thresholds that make sense for you.
Build your Business Logic With Sift Scores
The final step to using Sift is adding business logic that makes Decisions based on the Sift Risk Score. This step is so important because the real power of Sift is using machine learning to efficiently and accurately automate decisions in your business.
Here’s an example of using Sift to stop payments fraud. When an order is created by a user, the business checks the Sift Score:
- If the score is low, automatically approve the order.
- If the score is high, automatically block the order and flag the user.
- If the score is mid range, send the order to a review queue where an analyst can decide the best next step.
To build this business logic, there are two different approaches that you can take. You should choose your approach based on your business needs.
Create a Sift Workflow
You can build your business logic on Sift with our Workflows Platform. Workflows let you set up criteria that get evaluated whenever specified events occur. For example, you can setup a Workflow that evaluates whenever a user creates an account. You can specify criteria (e.g. country = “Canada” & Sift Score > 80) that when met, Sift will auto-block, auto-accept, or send the user to a Sift Review Queue for manual review. The configuration is all up to you, and logic can be updated by your fraud manager without any developer involvement. Learn more about setting up Sift Workflows.
Create Business Logic Within Your App
You can build your business logic within your application using Sift Scores. You can request Sift Scores synchronously each time you send an event. This will allow you to implement Sift Scores into your existing internal systems and manual review tools. Note, make sure to send all of the decisions from your system to Sift as Decision events.
For more information on building any of the above, check out our list of vertical-specific tutorials. They'll help you customize your Sift integration to fit your unique business needs. Client libraries are also available.
Installing the JavaScript Snippet
The JavaScript snippet tracks user interaction with your website and collects device information.
Important: only include the JavaScript snippet when the page is accessed externally by a user of your website. If your internal tools offer a way to simulate logging into a user's account, for example to investigate a user or place a phone order, it is important that you do not include the JavaScript snippet in those cases so that we do not link your device and IP address with the user.
Install the JavaScript snippet
- 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'); e.src = 'https://cdn.sift.com/s.js'; document.body.appendChild(e); } if (window.attachEvent) { window.attachEvent('onload', ls); } else { window.addEventListener('load', ls, false); } })(); </script>
- Change the parameter to
_setAccount
above to your JavaScript Snippet key. - Set
_session_id
to a string that identifies a unique session ID for the visitor's current browsing session. - Set
_user_id
to a string that identifies the user, e.g. a user ID, username, or email address. (Leaveuser_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. - If you have a single-page app, see our help article.
Notes
- To minimize download latency, we've hosted these files on Amazon Cloudfront. To minimize page load delay, this code executes as asynchronously as possible, yielding several times.
- This code will set a long-lived cookie named
__ssid
on your domain, also known as a first-party cookie. We only use this to identify unique visitors. You can optionally set the domain for the cookie via another JavaScript parameter_setCookieDomain
,_sift.push(['_setCookieDomain','subdomain.foo.com']);
Mobile SDK Overview
The Sift Mobile SDKs collect and send device information and app life cycle events to Sift.
Broadly, the Mobile SDKs are the analogue to the Sift JavaScript snippet. Just like the JavaScript snippet allows Sift to collect a range of browser properties and client-side user actions, the Mobile SDKs allow mobile applications to collect and send device properties and application lifecycle events to Sift. These events are the foundational data that drives machine learning at Sift.
The Mobile SDKs operate at high performance and are designed to be simple, robust and easy to integrate. Performance optimizations that reduce end-user impact include batching, compression, deduplication, archiving, and many other techniques detailed in this blog post.
iOS SDK – Integrate the iOS SDK into your mobile application.
Android SDK – Integrate the Android SDK into your mobile application.
iOS SDK
Installing the library
The SDK can be installed through either CocoaPods or Carthage.
CocoaPods:
- Add this to your Podfile:
pod 'Sift'
(this uses the latest version). - Run
pod install
.
Carthage:
- Add this to your Cartfile:
github "SiftScience/sift-ios"
(this uses the latest version) - Run
carthage update
.
Configuration & Set Up:
At a bare minimum, configuring your use of the Sift iOS SDK requires passing in your account id and beacon key. Your account id is retrievable by your account's admin in your profile section. The beacon key is the same key that is used in your Sift JS Snippet, and can be found in the developer section. Note in particular that this key is not considered secret; a sophisticated bad actor could recover this key from your app, or from the JS beacon, and use it to submit mobile events.
- Initialize the Sift instance
Objective-C
The SDK works in the background, so you have to initialize it when your app starts. It usually makes most sense to initialize the SDK in
application:didFinishLaunchingWithOptions
.Here is an example of what you would do within
AppDelegate.m
:#import "Sift/Sift.h"
Add the
application:didFinishLaunchingWithOptions
instance method if it doesn't exist, and insert this code snippet (replacing the placeholder strings with your Sift account credentials):Sift *sift = [Sift sharedInstance]; [sift setAccountId:@"YOUR_ACCOUNT_ID"]; [sift setBeaconKey:@"YOUR_JAVASCRIPT_SNIPPET_KEY"];
Swift
Import the Sift framework via CocoaPods or Carthage as described above. Create a bridging header and add it to Build Settings > Swift Compiler - General > Objective-C Bridging Header.
Add the following code snippet to your
AppDelegate.swift
file (replacing the placeholder strings with your Sift account credentials):let sift = Sift.sharedInstance sift().accountId = "YOUR_ACCOUNT_ID" sift().beaconKey = "YOUR_JAVASCRIPT_SNIPPET_KEY" // Set the user ID once it is available sift().userId = "USER_ID_GOES_HERE"
- (Recommended) If your app does not use motion sensors (accelerometer, gyro, and
magnetometer), add the following to the configuration block above:
[sift setAllowUsingMotionSensors:YES];
. This enables the SDK to collect motion data in the background. - If your app uses user location data but you do not want send it to Sift, add the
following to the configuration block above:
[sift setDisallowCollectingLocationData:YES];
. - Set the user ID for the user, this allows us to associate mobile data with data
sent via Sift’s Rest API and Java Script. When the user ID is available (for example,
when user has just logged in), please set the user ID:
[[Sift sharedInstance] setUserId:@"USER_ID"];
- (Recommended) Add the following to your application’s Info.plist file. This change
allows us to detect whether or not Cydia is installed. This step is optional, but
highly recommended.
<key>LSApplicationQueriesSchemes</key> <array> <string>cydia</string> </array>
Android SDK
Installing the library
Add the latest version of the Sift SDK to your application's build.gradle
file:
dependencies { ... compile 'com.siftscience:sift-android:VERSION' ... }
If your application uses Google Play Services, you will need to configure your build.gradle
file to fix its dependency version:
compile 'com.google.android.gms:play-services-location:YOUR_GMS_VERSION'
You may also need to add the following packagingOptions
to the main android
block:
android { ... packagingOptions { exclude 'META-INF/DEPENDENCIES.txt' exclude 'META-INF/LICENSE.txt' exclude 'META-INF/NOTICE.txt' exclude 'META-INF/NOTICE' exclude 'META-INF/LICENSE' exclude 'META-INF/DEPENDENCIES' exclude 'META-INF/notice.txt' exclude 'META-INF/license.txt' exclude 'META-INF/dependencies.txt' exclude 'META-INF/LGPL2.1' } ... }
Integration
There are two different integration paths to take for incorporating Sift into your application.
The first one will be detailed below in the Application Integration section. Follow these instructions if your application flow is primarily based on Activities.
If your application flow is based on a combination of Activities and Fragments, please refer to the Custom Integration section.
Application Integration
Add Sift to your Application file
Create an Application file if you haven’t already. Create an internal class that implements the ActivityLifecycleCallbacks
interface and register Sift as shown below:
import siftscience.android.Sift; public class App extends Application { @Override public void onCreate() { super.onCreate(); registerActivityLifecycleCallbacks(new ActivityLifecycleCallbacksHandler()); } private static final class ActivityLifecycleCallbacksHandler implements ActivityLifecycleCallbacks { public void onActivityCreated(Activity activity, Bundle bundle) { Sift.open(activity, new Sift.Config.Builder() .withAccountId("YOUR_ACCOUNT_ID") .withBeaconKey("YOUR_BEACON_KEY") // Uncomment to disallow location collection // .withDisallowLocationCollection(true) .build()); Sift.collect(); } public void onActivityPaused(Activity activity) { Sift.get().save(); } public void onActivityDestroyed(Activity activity) { Sift.close(); } } }
Set the user ID
As soon as your application is aware of the user ID, set it on the Sift instance using the code below. All subsequent events will be associated with that user ID.
Sift.get().setUserId("SOME_USER_ID");
If the user logs out of your application or their session ends, you should unset the user ID:
Sift.get().unsetUserId();
Custom Integration
Initialize Sift in your main Activity
Configure the Sift object in the onCreate method of your application's main Activity
(the one that begins the application). If the user ID is known at this point, you
can set it here. Otherwise, you should set it as soon as it is known. In the main Activity, also override onDestroy
and onPause
as shown:
import siftscience.android.Sift; public class MainActivity extends AppCompatActivity { @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_hello_sift); Sift.open(this, new Sift.Config.Builder() .withAccountId("YOUR_ACCOUNT_ID") .withBeaconKey("YOUR_BEACON_KEY") // Uncomment to disallow location collection // .withDisallowLocationCollection(true) .build()); Sift.collect(); } @Override protected void onPause() { super.onPause(); Sift.get().save(); } @Override protected void onDestroy() { super.onDestroy(); Sift.close(); } }
Add Sift to your application flow
For each Activity or Fragment that represents a unique page in your application flow, override onStart
, onPause
, and onStop
:
public class OtherActivity extends AppCompatActivity { @Override protected void onStart(Bundle savedInstanceState) { super.onStart(); Sift.open(this); // For Fragments, use Sift.open(this.getActivity()) instead Sift.collect(); } @Override protected void onPause() { super.onPause(); Sift.get().save(); } @Override protected void onStop() { super.onStop(); Sift.close(); } }
Set the user ID
As soon as your application is aware of the user ID, set it on the Sift instance using the code below. All subsequent events will be associated with that user ID.
Sift.get().setUserId("SOME_USER_ID");
If the user logs out of your application or their session ends, you should unset the user ID:
Sift.get().unsetUserId();
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/v204/events
Every event must contain your $api_key
, the event $type
, and a $user_id
(if this is not available, you can alternatively provide a $session_id
). Make sure to look at our error codes.
$create_order
Use $create_order
to record when a user submits an order for products or services they intend to purchase.
This API event should contain the products/services ordered, the payment instrument(s), and user identification data.
- $typerequired · String
"$create_order"
- $api_keyrequired · String
Your Sift REST API key.
- $user_idrequired · String
The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid
$user_id
values here. - $session_idString
The user's current session ID, used to tie a user's action before and after login or account creation. Required if no
$user_id
values is provided. - $order_idString
The ID for tracking this order in your system.
- $user_emailString
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. - $amountInteger
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_codeString
ISO-4217 currency code for the amount. If your site uses alternative currencies, specify them here.
- $billing_addressAddress
The billing address as entered by the user. occurred an
address
object. - $payment_methodsArray 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_addressAddress
The shipping address as entered by the user. occurred a nested
address
object. - $expedited_shippingBoolean
Whether the user requested priority/expedited shipping on their order.
- $itemsArray of Items
The list of items ordered. occurred a JSON array of $item objects.
- $seller_user_idString
For marketplace businesses, this is the seller's user ID, typically a database primary key.Follow our guidelines for
$user_id
values. - $promotionsArray of Promotions
The list of promotions that apply to this order. You can add one or more promotions when creating or updating an order. occurred a JSON array of
promotion
objects. You can also separately add promotions to the account via the$add_promotion
event. - $shipping_methodString
Indicates the method of delivery to the user.
Allowed Values
"$electronic"
"$physical"
// 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 } ], // For marketplaces, use $seller_user_id to identify the seller "$seller_user_id" : "slinkys_emporium", "$promotions" : [ { "$promotion_id" : "FirstTimeBuyer", "$status" : "$success", "$description" : "$5 off", "$discount" : { "$amount" : 5000000, // $5.00 "$currency_code" : "USD", "$minimum_purchase_amount" : 25000000 // $25.00 } } ], // Sample Custom Fields "digital_wallet" : "apple_pay", // "google_wallet", etc. "coupon_code" : "dollarMadness", "shipping_choice" : "FedEx Ground Courier", "is_first_time_buyer" : false }
import sift client = sift.Client("YOUR_API_KEY") # Sample $create_order event properties = { # Required Fields "$user_id" : "billy_jones_301", # Supported Fields "$session_id" : "gigtleqddo84l8cm15qe4il", "$order_id" : "ORDER-28168441", "$user_email" : "bill@gmail.com", "$amount" : 115940000, # $115.94 "$currency_code" : "USD", "$billing_address" : { "$name" : "Bill Jones", "$phone" : "1-415-555-6041", "$address_1" : "2100 Main Street", "$address_2" : "Apt 3B", "$city" : "New London", "$region" : "New Hampshire", "$country" : "US", "$zipcode" : "03257" }, "$payment_methods" : [ { "$payment_type" : "$credit_card", "$payment_gateway" : "$braintree", "$card_bin" : "542486", "$card_last4" : "4444" } ], "$shipping_address" : { "$name" : "Bill Jones", "$phone" : "1-415-555-6041", "$address_1" : "2100 Main Street", "$address_2" : "Apt 3B", "$city" : "New London", "$region" : "New Hampshire", "$country" : "US", "$zipcode" : "03257" }, "$expedited_shipping" : True, "$shipping_method" : "$physical", "$items" : [ { "$item_id" : "12344321", "$product_title" : "Microwavable Kettle Corn: Original Flavor", "$price" : 4990000, # $4.99 "$upc" : "097564307560", "$sku" : "03586005", "$brand" : "Peters Kettle Corn", "$manufacturer" : "Peters Kettle Corn", "$category" : "Food and Grocery", "$tags" : ["Popcorn", "Snacks", "On Sale"], "$quantity" : 4 }, { "$item_id" : "B004834GQO", "$product_title" : "The Slanket Blanket-Texas Tea", "$price" : 39990000, # $39.99 "$upc" : "67862114510011", "$sku" : "004834GQ", "$brand" : "Slanket", "$manufacturer" : "Slanket", "$category" : "Blankets & Throws", "$tags" : ["Awesome", "Wintertime specials"], "$color" : "Texas Tea", "$quantity" : 2 } ], # For marketplaces, use $seller_user_id to identify the seller "$seller_user_id" : "slinkys_emporium", "$promotions" : [ { "$promotion_id" : "FirstTimeBuyer", "$status" : "$success", "$description" : "$5 off", "$discount" : { "$amount" : 5000000, # $5.00 "$currency_code" : "USD", "$minimum_purchase_amount" : 25000000 # $25.00 } } ], # Sample Custom Fields "digital_wallet" : "apple_pay", # "google_wallet", etc. "coupon_code" : "dollarMadness", "shipping_choice" : "FedEx Ground Courier", "is_first_time_buyer" : False } response = client.track("$create_order", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $create_order event properties = { # Required Fields "$user_id" => "billy_jones_301", # Supported Fields "$session_id" => "gigtleqddo84l8cm15qe4il", "$order_id" => "ORDER-28168441", "$user_email" => "bill@gmail.com", "$amount" => 115940000, # $115.94 "$currency_code" => "USD", "$billing_address" => { "$name" => "Bill Jones", "$phone" => "1-415-555-6041", "$address_1" => "2100 Main Street", "$address_2" => "Apt 3B", "$city" => "New London", "$region" => "New Hampshire", "$country" => "US", "$zipcode" => "03257" }, "$payment_methods" => [ { "$payment_type" => "$credit_card", "$payment_gateway" => "$braintree", "$card_bin" => "542486", "$card_last4" => "4444" } ], "$shipping_address" => { "$name" => "Bill Jones", "$phone" => "1-415-555-6041", "$address_1" => "2100 Main Street", "$address_2" => "Apt 3B", "$city" => "New London", "$region" => "New Hampshire", "$country" => "US", "$zipcode" => "03257" }, "$expedited_shipping" => true, "$shipping_method" => "$physical", "$items" => [ { "$item_id" => "12344321", "$product_title" => "Microwavable Kettle Corn: Original Flavor", "$price" => 4990000, # $4.99 "$upc" => "097564307560", "$sku" => "03586005", "$brand" => "Peters Kettle Corn", "$manufacturer" => "Peters Kettle Corn", "$category" => "Food and Grocery", "$tags" => ["Popcorn", "Snacks", "On Sale"], "$quantity" => 4 }, { "$item_id" => "B004834GQO", "$product_title" => "The Slanket Blanket-Texas Tea", "$price" => 39990000, # $39.99 "$upc" => "67862114510011", "$sku" => "004834GQ", "$brand" => "Slanket", "$manufacturer" => "Slanket", "$category" => "Blankets & Throws", "$tags" => ["Awesome", "Wintertime specials"], "$color" => "Texas Tea", "$quantity" => 2 } ], # For marketplaces, use $seller_user_id to identify the seller "$seller_user_id" => "slinkys_emporium", "$promotions" => [ { "$promotion_id" => "FirstTimeBuyer", "$status" => "$success", "$description" => "$5 off", "$discount" => { "$amount" => 5000000, # $5.00 "$currency_code" => "USD", "$minimum_purchase_amount" => 25000000 # $25.00 } } ], # Sample Custom Fields "digital_wallet" => "apple_pay", # "google_wallet", etc. "coupon_code" => "dollarMadness", "shipping_choice" => "FedEx Ground Courier", "is_first_time_buyer" => false } response = client.track("$create_order", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $create_order event $properties = array( // Required Fields '$user_id' => 'billy_jones_301', // Supported Fields '$session_id' => 'gigtleqddo84l8cm15qe4il', '$order_id' => 'ORDER-28168441', '$user_email' => 'bill@gmail.com', '$amount' => 115940000, // $115.94 '$currency_code' => 'USD', '$billing_address' => array( '$name' => 'Bill Jones', '$phone' => '1-415-555-6041', '$address_1' => '2100 Main Street', '$address_2' => 'Apt 3B', '$city' => 'New London', '$region' => 'New Hampshire', '$country' => 'US', '$zipcode' => '03257' ), '$payment_methods' =>array( array( '$payment_type' => '$credit_card', '$payment_gateway' => '$braintree', '$card_bin' => '542486', '$card_last4' => '4444' ) ), '$shipping_address' => array( '$name' => 'Bill Jones', '$phone' => '1-415-555-6041', '$address_1' => '2100 Main Street', '$address_2' => 'Apt 3B', '$city' => 'New London', '$region' => 'New Hampshire', '$country' => 'US', '$zipcode' => '03257' ), '$expedited_shipping' => True, '$shipping_method' => '$physical', '$items' => array( // A list of items array( '$item_id' => '12344321', '$product_title' => 'Microwavable Kettle Corn: Original Flavor', '$price' => 4990000, // $4.99 '$upc' => '097564307560', '$sku' => '03586005', '$brand' => 'Peters Kettle Corn', '$manufacturer' => 'Peters Kettle Corn', '$category' => 'Food and Grocery', '$tags' => array('Popcorn', 'Snacks', 'On Sale'), '$quantity' => 4 ), array( '$item_id' => 'B004834GQO', '$product_title' => 'The Slanket Blanket-Texas Tea', '$price' => 39990000, // $39.99 '$upc' => '67862114510011', '$sku' => '004834GQ', '$brand' => 'Slanket', '$manufacturer' => 'Slanket', '$category' => 'Blankets & Throws', '$tags' => array('Awesome', 'Wintertime specials'), '$color' => 'Texas Tea', '$quantity' => 2 ) ), // For marketplaces, use $seller_user_id to identify the seller '$seller_user_id' => 'slinkys_emporium', '$promotions' => array( array( '$promotion_id' => 'FirstTimeBuyer', '$status' => '$success', '$description' => '$5 off', '$discount' => array( '$amount' => 5000000, // $5.00 '$currency_code' => 'USD', '$minimum_purchase_amount' => 25000000 // $25.00 ) ) ), // Sample Custom Fields 'digital_wallet' => 'apple_pay' // 'google_wallet', etc. 'coupon_code' => 'dollarMadness', 'shipping_choice' => 'FedEx Ground Courier', 'is_first_time_buyer' => False ); $response = $client->track('$create_order', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.model.CreateOrderFieldSet; import com.siftscience.model.Address; import com.siftscience.model.Item; import com.siftscience.model.Discount; import com.siftscience.model.Promotion; import com.siftscience.model.PaymentMethod; SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new CreateOrderFieldSet() // Required Fields .setUserId("billy_jones_301") // Supported Fields .setSessionId("gigtleqddo84l8cm15qe4il") .setOrderId("ORDER-28168441") .setUserEmail("bill@gmail.com") .setAmount(115940000L) .setCurrencyCode("USD") .setBillingAddress(new Address() .setName("Bill Jones") .setPhone("1-415-555-6041") .setAddress1("2100 Main Street") .setAddress2("Apt 3B") .setCity("New London") .setRegion("New Hampshire") .setCountry("US") .setZipCode("03257")) .setPaymentMethods(Arrays.asList(new PaymentMethod() .setPaymentType("$credit_card") .setPaymentGateway("$braintree") .setCardBin("542486") .setCardLast4("4444"))) .setShippingAddress(new Address() .setName("Bill Jones") .setPhone("1-415-555-6041") .setAddress1("2100 Main Street") .setAddress2("Apt 3B") .setCity("New London") .setRegion("New Hampshire") .setCountry("US") .setZipCode("03257")) .setExpeditedShipping(true) .setShippingMethod("$physical") .setItems(Arrays.asList( new Item() .setItemId("12344321") .setProductTitle("Microwavable Kettle Corn: Original Flavor") .setPrice(4990000L) .setUpc("097564307560") .setSku("03586005") .setBrand("Peters Kettle Corn") .setManufacturer("Peters Kettle Corn") .setCategory("Food and Grocery") .setTags(Arrays.asList("Popcorn", "Snacks", "On Sale")) .setQuantity(4L), new Item() .setItemId("B004834GQO") .setProductTitle("The Slanket Blanket-Texas Tea") .setPrice(39990000L) .setUpc("67862114510011") .setSku("004834GQ") .setBrand("Slanket") .setManufacturer("Slanket") .setCategory("Blankets & Throws") .setTags(Arrays.asList("Awesome", "Wintertime specials")) .setQuantity(2L))) .setSellerUserId("slinkys_emporium") .setPromotions(Arrays.asList(new Promotion() .setPromotionId("FirstTimeBuyer") .setStatus("$success") .setDescription("$5 off") .setDiscount(new Discount() .setAmount(5000000L) .setCurrencyCode("USD") .setMinimumPurchaseAmount(25000000L)))) // Sample Custom Fields .setCustomField("digital_wallet", "apple_pay") .setCustomField("coupon_code", "dollarMadness") .setCustomField("shipping_choice", "Fedex Ground Courier") .setCustomField("is_first_time_buyer", false)); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
$update_order
Use $update_order
to record when a user updates an order for products or services they intend to purchase.
- This event contains the same fields as
$create_order
. - The existing order will be completely replaced by the values sent in
$update_order
. Be sure to specify all values for the order, not just those that changed. - If no matching
$order_id
found, a new order will be created.
- $typerequired · String
"$update_order"
- $api_keyrequired · String
Your Sift REST API key.
- $user_idrequired · String
The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid
$user_id
values here. - $session_idString
The user's current session ID, used to tie a user's action before and after login or account creation. Required if no
$user_id
values is provided. - $order_idString
The ID for tracking this order in your system.
- $user_emailString
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. - $amountInteger
Total transaction amount in micros in the base unit of the
$currency_code
. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros and 1 for 1 micro-Bitcoin. - $currency_codeString
ISO-4217 currency code for the amount. If your site uses alternative currencies, specify them here.
- $billing_addressAddress
The billing address as entered by the user. occurred a nested
address
object. - $payment_methodsArray of Payment Methods
The payment information associated with this order. occurred an array of nested
payment_method
objects. As opposed to$transaction
,$create_order
takes an array of$payment_method
objects, so you can record orders that are paid for using multiple payments. - $shipping_addressAddress
The shipping address as entered by the user. occurred a nested
address
object. - $expedited_shippingBoolean
Whether the user requested priority/expedited shipping on their order.
- $itemsArray of Items
The list of items ordered. occurred a JSON array of $item objects.
- $seller_user_idString
For marketplace businesses, this is the seller's user ID, typically a database primary key.Follow our guidelines for
$user_id
values. - $promotionsArray of Promotions
The list of promotions that apply to this order. You can add one or more promotions when creating or updating an order. occurred a JSON array of
promotion
objects. You can also separately add promotions to the account via the$add_promotion
event. - $shipping_methodString
Indicates the method of delivery to the user.
Allowed Values
"$electronic"
"$physical"
// 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 } ], // For marketplaces, use $seller_user_id to identify the seller "$seller_user_id" : "slinkys_emporium", "$promotions" : [ { "$promotion_id" : "FirstTimeBuyer", "$status" : "$success", "$description" : "$5 off", "$discount" : { "$amount" : 5000000, // $5.00 "$currency_code" : "USD", "$minimum_purchase_amount" : 25000000 // $25.00 } } ], // Sample Custom Fields "digital_wallet" : "apple_pay", // "google_wallet", etc. "coupon_code" : "dollarMadness", "shipping_choice" : "FedEx Ground Courier", "is_first_time_buyer" : false }
import sift client = sift.Client("YOUR_API_KEY") # Sample $update_order event properties = { # Required Fields "$user_id" : "billy_jones_301", # Supported Fields "$session_id" : "gigtleqddo84l8cm15qe4il", "$order_id" : "ORDER-28168441", "$user_email" : "bill@gmail.com", "$amount" : 115940000, # $115.94 "$currency_code" : "USD", "$billing_address" : { "$name" : "Bill Jones", "$phone" : "1-415-555-6041", "$address_1" : "2100 Main Street", "$address_2" : "Apt 3B", "$city" : "New London", "$region" : "New Hampshire", "$country" : "US", "$zipcode" : "03257" }, "$payment_methods" : [ { "$payment_type" : "$credit_card", "$payment_gateway" : "$braintree", "$card_bin" : "542486", "$card_last4" : "4444" } ], "$shipping_address" : { "$name" : "Bill Jones", "$phone" : "1-415-555-6041", "$address_1" : "2100 Main Street", "$address_2" : "Apt 3B", "$city" : "New London", "$region" : "New Hampshire", "$country" : "US", "$zipcode" : "03257" }, "$expedited_shipping" : True, "$shipping_method" : "$physical", "$items" : [ { "$item_id" : "12344321", "$product_title" : "Microwavable Kettle Corn: Original Flavor", "$price" : 4990000, # $4.99 "$upc" : "097564307560", "$sku" : "03586005", "$brand" : "Peters Kettle Corn", "$manufacturer" : "Peters Kettle Corn", "$category" : "Food and Grocery", "$tags" : ["Popcorn", "Snacks", "On Sale"], "$quantity" : 4 }, { "$item_id" : "B004834GQO", "$product_title" : "The Slanket Blanket-Texas Tea", "$price" : 39990000, # $39.99 "$upc" : "67862114510011", "$sku" : "004834GQ", "$brand" : "Slanket", "$manufacturer" : "Slanket", "$category" : "Blankets & Throws", "$tags" : ["Awesome", "Wintertime specials"], "$color" : "Texas Tea", "$quantity" : 2 } ], # For marketplaces, use $seller_user_id to identify the seller "$seller_user_id" : "slinkys_emporium", "$promotions" : [ { "$promotion_id" : "FirstTimeBuyer", "$status" : "$success", "$description" : "$5 off", "$discount" : { "$amount" : 5000000, # $5.00 "$currency_code" : "USD", "$minimum_purchase_amount" : 25000000 # $25.00 } } ], # Sample Custom Fields "digital_wallet" : "apple_pay", # "google_wallet", etc. "coupon_code" : "dollarMadness", "shipping_choice" : "FedEx Ground Courier", "is_first_time_buyer" : False } response = client.track("$update_order", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $update_order event properties = { # Required Fields "$user_id" => "billy_jones_301", # Supported Fields "$session_id" => "gigtleqddo84l8cm15qe4il", "$order_id" => "ORDER-28168441", "$user_email" => "bill@gmail.com", "$amount" => 115940000, # $115.94 "$currency_code" => "USD", "$billing_address" => { "$name" => "Bill Jones", "$phone" => "1-415-555-6041", "$address_1" => "2100 Main Street", "$address_2" => "Apt 3B", "$city" => "New London", "$region" => "New Hampshire", "$country" => "US", "$zipcode" => "03257" }, "$payment_methods" => [ { "$payment_type" => "$credit_card", "$payment_gateway" => "$braintree", "$card_bin" => "542486", "$card_last4" => "4444" } ], "$shipping_address" => { "$name" => "Bill Jones", "$phone" => "1-415-555-6041", "$address_1" => "2100 Main Street", "$address_2" => "Apt 3B", "$city" => "New London", "$region" => "New Hampshire", "$country" => "US", "$zipcode" => "03257" }, "$expedited_shipping" => true, "$shipping_method" => "$physical", "$items" => [ { "$item_id" => "12344321", "$product_title" => "Microwavable Kettle Corn: Original Flavor", "$price" => 4990000, # $4.99 "$upc" => "097564307560", "$sku" => "03586005", "$brand" => "Peters Kettle Corn", "$manufacturer" => "Peters Kettle Corn", "$category" => "Food and Grocery", "$tags" => ["Popcorn", "Snacks", "On Sale"], "$quantity" => 4 }, { "$item_id" => "B004834GQO", "$product_title" => "The Slanket Blanket-Texas Tea", "$price" => 39990000, # $39.99 "$upc" => "67862114510011", "$sku" => "004834GQ", "$brand" => "Slanket", "$manufacturer" => "Slanket", "$category" => "Blankets & Throws", "$tags" => ["Awesome", "Wintertime specials"], "$color" => "Texas Tea", "$quantity" => 2 } ], # For marketplaces, use $seller_user_id to identify the seller "$seller_user_id" => "slinkys_emporium", "$promotions" => [ { "$promotion_id" => "FirstTimeBuyer", "$status" => "$success", "$description" => "$5 off", "$discount" => { "$amount" => 5000000, # $5.00 "$currency_code" => "USD", "$minimum_purchase_amount" => 25000000 # $25.00 } } ], # Sample Custom Fields "digital_wallet" => "apple_pay", # "google_wallet", etc. "coupon_code" => "dollarMadness", "shipping_choice" => "FedEx Ground Courier", "is_first_time_buyer" => false } response = client.track("$update_order", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $update_order event $properties = array( // Required Fields '$user_id' => 'billy_jones_301', // Supported Fields '$session_id' => 'gigtleqddo84l8cm15qe4il', '$order_id' => 'ORDER-28168441', '$user_email' => 'bill@gmail.com', '$amount' => 115940000, // $115.94 '$currency_code' => 'USD', '$billing_address' => array( '$name' => 'Bill Jones', '$phone' => '1-415-555-6041', '$address_1' => '2100 Main Street', '$address_2' => 'Apt 3B', '$city' => 'New London', '$region' => 'New Hampshire', '$country' => 'US', '$zipcode' => '03257' ), '$payment_methods' =>array( array( '$payment_type' => '$credit_card', '$payment_gateway' => '$braintree', '$card_bin' => '542486', '$card_last4' => '4444' ) ), '$shipping_address' => array( '$name' => 'Bill Jones', '$phone' => '1-415-555-6041', '$address_1' => '2100 Main Street', '$address_2' => 'Apt 3B', '$city' => 'New London', '$region' => 'New Hampshire', '$country' => 'US', '$zipcode' => '03257' ), '$expedited_shipping' => True, '$shipping_method' => '$physical', '$items' => array( // A list of items array( '$item_id' => '12344321', '$product_title' => 'Microwavable Kettle Corn: Original Flavor', '$price' => 4990000, // $4.99 '$upc' => '097564307560', '$sku' => '03586005', '$brand' => 'Peters Kettle Corn', '$manufacturer' => 'Peters Kettle Corn', '$category' => 'Food and Grocery', '$tags' => array('Popcorn', 'Snacks', 'On Sale'), '$quantity' => 4 ), array( '$item_id' => 'B004834GQO', '$product_title' => 'The Slanket Blanket-Texas Tea', '$price' => 39990000, // $39.99 '$upc' => '67862114510011', '$sku' => '004834GQ', '$brand' => 'Slanket', '$manufacturer' => 'Slanket', '$category' => 'Blankets & Throws', '$tags' => array('Awesome', 'Wintertime specials'), '$color' => 'Texas Tea', '$quantity' => 2 ) ), // For marketplaces, use $seller_user_id to identify the seller '$seller_user_id' => 'slinkys_emporium', '$promotions' => array( array( '$promotion_id' => 'FirstTimeBuyer', '$status' => '$success', '$description' => '$5 off', '$discount' => array( '$amount' => 5000000, // $5.00 '$currency_code' => 'USD', '$minimum_purchase_amount' => 25000000 // $25.00 ) ) ), // Sample Custom Fields 'digital_wallet' => 'apple_pay' // 'google_wallet', etc. 'coupon_code' => 'dollarMadness', 'shipping_choice' => 'FedEx Ground Courier', 'is_first_time_buyer' => False ); $response = $client->track('$update_order', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.model.UpdateOrderFieldSet; import com.siftscience.model.Address; import com.siftscience.model.Item; import com.siftscience.model.Discount; import com.siftscience.model.Promotion; import com.siftscience.model.PaymentMethod; SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new UpdateOrderFieldSet() // Required Fields .setUserId("billy_jones_301") // Supported Fields .setSessionId("gigtleqddo84l8cm15qe4il") .setOrderId("ORDER-28168441") .setUserEmail("bill@gmail.com") .setAmount(115940000L) .setCurrencyCode("USD") .setBillingAddress(new Address() .setName("Bill Jones") .setPhone("1-415-555-6041") .setAddress1("2100 Main Street") .setAddress2("Apt 3B") .setCity("New London") .setRegion("New Hampshire") .setCountry("US") .setZipCode("03257")) .setPaymentMethods(Arrays.asList(new PaymentMethod() .setPaymentType("$credit_card") .setPaymentGateway("$braintree") .setCardBin("542486") .setCardLast4("4444"))) .setShippingAddress(new Address() .setName("Bill Jones") .setPhone("1-415-555-6041") .setAddress1("2100 Main Street") .setAddress2("Apt 3B") .setCity("New London") .setRegion("New Hampshire") .setCountry("US") .setZipCode("03257")) .setExpeditedShipping(true) .setShippingMethod("$physical") .setItems(Arrays.asList( new Item() .setItemId("12344321") .setProductTitle("Microwavable Kettle Corn: Original Flavor") .setPrice(4990000L) .setUpc("097564307560") .setSku("03586005") .setBrand("Peters Kettle Corn") .setManufacturer("Peters Kettle Corn") .setCategory("Food and Grocery") .setTags(Arrays.asList("Popcorn", "Snacks", "On Sale")) .setQuantity(4L), new Item() .setItemId("B004834GQO") .setProductTitle("The Slanket Blanket-Texas Tea") .setPrice(39990000L) .setUpc("67862114510011") .setSku("004834GQ") .setBrand("Slanket") .setManufacturer("Slanket") .setCategory("Blankets & Throws") .setTags(Arrays.asList("Awesome", "Wintertime specials")) .setQuantity(2L))) .setSellerUserId("slinkys_emporium") .setPromotions(Arrays.asList(new Promotion() .setPromotionId("FirstTimeBuyer") .setStatus("$success") .setDescription("$5 off") .setDiscount(new Discount() .setAmount(5000000L) .setCurrencyCode("USD") .setMinimumPurchaseAmount(25000000L)))) // Sample Custom Fields .setCustomField("digital_wallet", "apple_pay") .setCustomField("coupon_code", "dollarMadness") .setCustomField("shipping_choice", "Fedex Ground Courier") .setCustomField("is_first_time_buyer", false)); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
$transaction
Use $transaction
to record attempts to exchange money, credit or other tokens of value.
- $typerequired · String
"$transaction"
- $api_keyrequired · String
Your Sift REST API key.
- $user_idrequired · String
The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid
$user_id
values here. - $user_emailString
Email of the user creating this order. Note: If the user's email is also their account ID in your system, set both the
$user_id
and$user_email
fields to their email address. - $transaction_typeString
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.
- $saleAuthorization and capture of a payment performed together in one step.
This is the most commonly used transaction type.
This is the default
- $transaction_statusString
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"
. - $amountRequired · Integer
Total transaction amount in micros in the base unit of the
$currency_code
. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. Send as a positive number for all$transaction_type
values. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros. Use 1 for 1 microBitcoin. - $currency_codeRequired · String
ISO-4217 currency code for the amount. e.g., USD, CAD, HKD, BTC.
- $order_idString
The ID for this order in your system. Used for cross referencing an order in your internal systems.
- $transaction_idString
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_addressAddress
The billing address as entered by the user. occurred a nested
address
object. - $payment_methodPayment Method Object
The payment information associated with this transaction. occurred a single
payment_method
object containing payment method, payment gateway, credit card bin, etc. - $shipping_addressAddress
The shipping address as entered by the user. occurred a nested
address
object. - $session_idString
The user's current session ID, used to tie a user's action before and after log in or account creation.
- $seller_user_idString
are case sensitive. You may need to normalize the capitalization of your user IDs. Follow our guidelines for
$user_id
values. - $transfer_recipient_user_idString
For transfer transactions, the user ID of the user receiving the transfer. If
$transfer_recipient_user_id
is specified,$transaction_type
must be set to"$transfer"
; otherwise, the system will give an error.Follow our guidelines for$user_id
values.
// 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" }, // Credit card example "$payment_method" : { "$payment_type" : "$credit_card", "$payment_gateway" : "$braintree", "$card_bin" : "542486", "$card_last4" : "4444" }, // Bank account example //"$payment_method" : { // "$payment_type" : "$electronic_fund_transfer", // "$routing_number" : "021001088" //}, // See other payment method options in field description below // Supported Fields "$shipping_address" : { "$name" : "Bill Jones", "$phone" : "1-415-555-6041", "$address_1" : "2100 Main Street", "$address_2" : "Apt 3B", "$city" : "New London", "$region" : "New Hampshire", "$country" : "US", "$zipcode" : "03257" }, "$session_id" : "gigtleqddo84l8cm15qe4il", // For marketplaces, use $seller_user_id to identify the seller "$seller_user_id" : "slinkys_emporium", // Sample Custom Fields "digital_wallet" : "apple_pay", // "google_wallet", etc. "coupon_code" : "dollarMadness", "shipping_choice" : "FedEx Ground Courier", "is_first_time_buyer" : false }
import sift client = sift.Client("YOUR_API_KEY") # Sample $transaction event properties = { # Required Fields "$user_id" : "billy_jones_301", "$amount" : 506790000, # $506.79 "$currency_code" : "USD", # Supported Fields "$user_email" : "bill@gmail.com", "$transaction_type" : "$sale", "$transaction_status" : "$success", "$order_id" : "ORDER-123124124", "$transaction_id" : "719637215", "$billing_address" : { "$name" : "Bill Jones", "$phone" : "1-415-555-6041", "$address_1" : "2100 Main Street", "$address_2" : "Apt 3B", "$city" : "New London", "$region" : "New Hampshire", "$country" : "US", "$zipcode" : "03257" }, # Credit card example "$payment_method" : { "$payment_type" : "$credit_card", "$payment_gateway" : "$braintree", "$card_bin" : "542486", "$card_last4" : "4444" }, # Bank account example #"$payment_method" : { # "$payment_type" : "$electronic_fund_transfer", # "$routing_number" : "021001088" #}, # See other payment method options in field description below # Supported Fields "$shipping_address" : { "$name" : "Bill Jones", "$phone" : "1-415-555-6041", "$address_1" : "2100 Main Street", "$address_2" : "Apt 3B", "$city" : "New London", "$region" : "New Hampshire", "$country" : "US", "$zipcode" : "03257" }, "$session_id" : "gigtleqddo84l8cm15qe4il", # For marketplaces, use $seller_user_id to identify the seller "$seller_user_id" : "slinkys_emporium", # Sample Custom Fields "digital_wallet" : "apple_pay", # "google_wallet", etc. "coupon_code" : "dollarMadness", "shipping_choice" : "FedEx Ground Courier", "is_first_time_buyer" : False } response = client.track("$transaction", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $transaction event properties = { # Required Fields "$user_id" => "billy_jones_301", "$amount" => 506790000, # $506.79 "$currency_code" => "USD", # Supported Fields "$user_email" => "bill@gmail.com", "$transaction_type" => "$sale", "$transaction_status" => "$success", "$order_id" => "ORDER-123124124", "$transaction_id" => "719637215", "$billing_address" => { "$name" => "Bill Jones", "$phone" => "1-415-555-6041", "$address_1" => "2100 Main Street", "$address_2" => "Apt 3B", "$city" => "New London", "$region" => "New Hampshire", "$country" => "US", "$zipcode" => "03257" }, # Credit card example "$payment_method" => { "$payment_type" => "$credit_card", "$payment_gateway" => "$braintree", "$card_bin" => "542486", "$card_last4" => "4444" }, # Bank account example #"$payment_method" => { # "$payment_type" => "$electronic_fund_transfer", # "$routing_number" => "021001088" #}, # See other payment method options in field description below # Supported Fields "$shipping_address" => { "$name" => "Bill Jones", "$phone" => "1-415-555-6041", "$address_1" => "2100 Main Street", "$address_2" => "Apt 3B", "$city" => "New London", "$region" => "New Hampshire", "$country" => "US", "$zipcode" => "03257" }, "$session_id" => "gigtleqddo84l8cm15qe4il", # For marketplaces, use $seller_user_id to identify the seller "$seller_user_id" => "slinkys_emporium", # Sample Custom Fields "digital_wallet" => "apple_pay", # "google_wallet", etc. "coupon_code" => "dollarMadness", "shipping_choice" => "FedEx Ground Courier", "is_first_time_buyer" => false } response = client.track("$transaction", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $transaction event $properties = array( // Required Fields '$user_id' => 'billy_jones_301', '$amount' => 506790000, // $506.79 '$currency_code' => 'USD', // Supported Fields '$user_email' => 'bill@gmail.com', '$transaction_type' => '$sale', '$transaction_status' => '$success', '$order_id' => 'ORDER-123124124', '$transaction_id' => '719637215', '$billing_address' => array( '$name' => 'Bill Jones', '$phone' => '1-415-555-6041', '$address_1' => '2100 Main Street', '$address_2' => 'Apt 3B', '$city' => 'New London', '$region' => 'New Hampshire', '$country' => 'US', '$zipcode' => '03257' ), // Credit card example '$payment_method' => array( '$payment_type' => '$credit_card', '$payment_gateway' => '$braintree', '$card_bin' => '542486', '$card_last4' => '4444' ), // Bank account example //"$payment_method" => array( // "$payment_type" => "$electronic_fund_transfer", // "$routing_number" => "021001088" //), // See other payment method options in field description below // Supported Fields '$shipping_address' => array( '$name' => 'Bill Jones', '$phone' => '1-415-555-6041', '$address_1' => '2100 Main Street', '$address_2' => 'Apt 3B', '$city' => 'New London', '$region' => 'New Hampshire', '$country' => 'US', '$zipcode' => '03257' ), '$session_id' => 'gigtleqddo84l8cm15qe4il', // For marketplaces, use $seller_user_id to identify the seller '$seller_user_id' => 'slinkys_emporium', // Sample Custom Fields 'digital_wallet' => 'apple_pay' // 'google_wallet', etc. 'coupon_code' => 'dollarMadness', 'shipping_choice' => 'FedEx Ground Courier', 'is_first_time_buyer' => False ); $response = $client->track('$transaction', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.model.TransactionFieldSet; import com.siftscience.model.Address; import com.siftscience.model.Item; import com.siftscience.model.Discount; import com.siftscience.model.Promotion; import com.siftscience.model.PaymentMethod; SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new TransactionFieldSet() // Required Fields .setUserId(billy_jones_301) .setAmount(506790000L) .setCurrencyCode("USD") // Supported Fields .setSessionId("gigtleqddo84l8cm15qe4il") .setUserEmail("bill@gmail.com") .setTransactionType("$sale") .setTransactionStatus("$success") .setOrderId("ORDER-123124124") .setTransactionId("719637215") .setBillingAddress(new Address() .setName("Bill Jones") .setPhone("1-415-555-6041") .setAddress1("2100 Main Street") .setAddress2("Apt 3B") .setCity("New London") .setRegion("New Hampshire") .setCountry("US") .setZipCode("03257")) .setPaymentMethod(new PaymentMethod() .setPaymentType("$credit_card") .setPaymentGateway("$braintree") .setCardBin("542486") .setCardLast4("4444")) .setShippingAddress(new Address() .setName("Bill Jones") .setPhone("1-415-555-6041") .setAddress1("2100 Main Street") .setAddress2("Apt 3B") .setCity("New London") .setRegion("New Hampshire") .setCountry("US") .setZipCode("03257")) .setSellerUserId("slinkys_emporium") // Sample Custom Fields .setCustomField("digital_wallet", "apple_pay") .setCustomField("coupon_code", "dollarMadness") .setCustomField("shipping_choice", "Fedex Ground Courier") .setCustomField("is_first_time_buyer", false)); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
$create_account
Use $create_account
to capture user details at account creation. To capture updates to an account after it is initially created, use $update_account.
- $typerequired· String
"$create_account"
- $api_keyrequired · String
Your Sift REST API key.
- $user_idrequired · String
The user's internal account ID. Users without an assigned
$user_id
will not show up in the console. Find valid$user_id
values here. - $session_idString
The user's current session ID, used to tie a user's action before and after log in or account creation.
- $user_emailString
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. - $nameString
The full name of the user.
- $phoneString
The primary phone number of the user associated with this account. 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. If you collect other phone numbers for the account, provide them as additional custom fields, e.g
work_phone
- $referrer_user_idString
The ID of the user that referred the current user to your business. This field is required for detecting referral fraud. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs. Follow our guidelines for
$user_id
values. - $payment_methodsArray of Payment Methods
The payment method(s) associated with this account. occurred an array of nested
payment_method
objects. - $billing_addressAddress
The billing address associated with this user. occurred a nested
address
object. - $shipping_addressAddress
The shipping address associated with this user. occurred a nested
address
object. - $promotionsArray of Promotions
The list of promotions that apply to this account. You can add one or more promotions when creating or updating the account. It is particularly useful to add the promotion with this event if the account is receiving some referral incentive. occurred a JSON array of
promotion
objects. You can also separately add promotions to the account via the$add_promotion
event. - $social_sign_on_typeString
If the user logged in with a social identify provider, give the name here.
Allowed Values
$facebook
$google
$linkedin
$twitter
$yahoo
$other
// Sample $create_account event { // Required Fields "$type" : "$create_account", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", // Supported Fields "$session_id" : "gigtleqddo84l8cm15qe4il", "$user_email" : "bill@gmail.com", "$name" : "Bill Jones", "$phone" : "1-415-555-6040", "$referrer_user_id" : "janejane101", "$payment_methods" : [ { "$payment_type" : "$credit_card", "$card_bin" : "542486", "$card_last4" : "4444" } ], "$billing_address" : { "$name" : "Bill Jones", "$phone" : "1-415-555-6040", "$address_1" : "2100 Main Street", "$address_2" : "Apt 3B", "$city" : "New London", "$region" : "New Hampshire", "$country" : "US", "$zipcode" : "03257" }, "$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" }, "$promotions" : [ { "$promotion_id" : "FriendReferral", "$status" : "$success", "$referrer_user_id" : "janejane102", "$credit_point" : { "$amount" : 100, "$credit_point_type" : "account karma" } } ], "$social_sign_on_type" : "$twitter", // Suggested Custom Fields "twitter_handle" : "billyjones", "work_phone" : "1-347-555-5921", "location" : "New London, NH", "referral_code" : "MIKEFRIENDS", "email_confirmed_status" : "$pending", "phone_confirmed_status" : "$pending" }
import sift client = sift.Client("YOUR_API_KEY") # Sample $create_account event properties = { # Required Fields "$user_id" : "billy_jones_301", # Supported Fields "$session_id" : "gigtleqddo84l8cm15qe4il", "$user_email" : "bill@gmail.com", "$name" : "Bill Jones", "$phone" : "1-415-555-6040", "$referrer_user_id" : "janejane101", "$payment_methods" : [ { "$payment_type" : "$credit_card", "$card_bin" : "542486", "$card_last4" : "4444" } ], "$billing_address" : { "$name" : "Bill Jones", "$phone" : "1-415-555-6040", "$address_1" : "2100 Main Street", "$address_2" : "Apt 3B", "$city" : "New London", "$region" : "New Hampshire", "$country" : "US", "$zipcode" : "03257" }, "$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" }, "$promotions" : [ { "$promotion_id" : "FriendReferral", "$status" : "$success", "$referrer_user_id" : "janejane102", "$credit_point" : { "$amount" : 100, "$credit_point_type" : "account karma" } } ], "$social_sign_on_type" : "$twitter", # Suggested Custom Fields "twitter_handle" : "billyjones", "work_phone" : "1-347-555-5921", "location" : "New London, NH", "referral_code" : "MIKEFRIENDS", "email_confirmed_status" : "$pending", "phone_confirmed_status" : "$pending" } response = client.track("$create_account", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $create_account event properties = { # Required Fields "$user_id" => "billy_jones_301", # Supported Fields "$session_id" => "gigtleqddo84l8cm15qe4il", "$user_email" => "bill@gmail.com", "$name" => "Bill Jones", "$phone" => "1-415-555-6040", "$referrer_user_id" => "janejane101", "$payment_methods" => [ { "$payment_type" => "$credit_card", "$card_bin" => "542486", "$card_last4" => "4444" } ], "$billing_address" => { "$name" => "Bill Jones", "$phone" => "1-415-555-6040", "$address_1" => "2100 Main Street", "$address_2" => "Apt 3B", "$city" => "New London", "$region" => "New Hampshire", "$country" => "US", "$zipcode" => "03257" }, "$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" }, "$promotions" => [ { "$promotion_id" => "FriendReferral", "$status" => "$success", "$referrer_user_id" => "janejane102", "$credit_point" => { "$amount" => 100, "$credit_point_type" => "account karma" } } ], "$social_sign_on_type" => "$twitter", # Suggested Custom Fields "twitter_handle" => "billyjones", "work_phone" => "1-347-555-5921", "location" => "New London, NH", "referral_code" => "MIKEFRIENDS", "email_confirmed_status" => "$pending", "phone_confirmed_status" => "$pending" } response = client.track("$create_account", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $create_account event $properties = array( // Required Fields '$user_id' => 'billy_jones_301', // Supported Fields '$session_id' => 'gigtleqddo84l8cm15qe4il', '$user_email' => 'bill@gmail.com', '$name' => 'Bill Jones', '$phone' => '1-415-555-6040', '$referrer_user_id' => 'janejane101', '$payment_methods' => array( array( '$payment_type' => '$credit_card', '$card_bin' => '542486', '$card_last4' => '4444' ) ), '$billing_address' => array( '$name' => 'Bill Jones', '$phone' => '1-415-555-6040', '$address_1' => '2100 Main Street', '$address_2' => 'Apt 3B', '$city' => 'New London', '$region' => 'New Hampshire', '$country' => 'US', '$zipcode' => '03257' ), '$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' ), '$promotions' => array( array( '$promotion_id' => 'FriendReferral', '$status' => '$success', '$referrer_user_id' => 'janejane102', '$credit_point' => array( '$amount' => 100, '$credit_point_type' => 'account karma' ) ) ), '$social_sign_on_type' => '$twitter', // Suggested Custom Fields 'twitter_handle' => 'billyjones', 'work_phone' => '1-347-555-5921', 'location' => 'New London, NH', 'referral_code' => 'MIKEFRIENDS', 'email_confirmed_status' => "$pending", 'phone_confirmed_status' => "$pending" ); $response = $client->track('$create_account', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.model.CreateAccountFieldSet; import com.siftscience.model.Address; import com.siftscience.model.Discount; import com.siftscience.model.Promotion; import com.siftscience.model.PaymentMethod; SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new CreateAccountFieldSet() // Required Fields .setUserId("billy_jones_301") // Supported Fields .setSessionId("gigtleqddo84l8cm15qe4il") .setUserEmail("bill@gmail.com") .setName("Bill Jones") .setPhone("1-415-555-6040") .setReferrerUserId("janejane101") .setPaymentMethods(Arrays.asList(new PaymentMethod() .setPaymentType("$credit_card") .setPaymentGateway("$braintree") .setCardBin("542486") .setCardLast4("4444"))) .setBillingAddress(new Address() .setName("Bill Jones") .setPhone("1-415-555-6041") .setAddress1("2100 Main Street") .setAddress2("Apt 3B") .setCity("New London") .setRegion("New Hampshire") .setCountry("US") .setZipCode("03257")) .setShippingAddress(new Address() .setName("Bill Jones") .setPhone("1-415-555-6041") .setAddress1("2100 Main Street") .setAddress2("Apt 3B") .setCity("New London") .setRegion("New Hampshire") .setCountry("US") .setZipCode("03257")) .setPromotions(Arrays.asList(new Promotion() .setPromotionId("FirstTimeBuyer") .setStatus("$success") .setDescription("$5 off") .setDiscount(new Discount() .setAmount(5000000L) .setCurrencyCode("USD") .setMinimumPurchaseAmount(25000000L)))) .setSocialSignOnType("$twitter") // Suggested Custom Fields .setCustomField("twitter_handle", "billyjones") .setCustomField("work_phone", "1-347-555-5921") .setCustomField("location", "New London, NH") .setCustomField("referral_code", "MIKEFRIENDS") .setCustomField("email_confirmed_status", "$pending") .setCustomField("phone_confirmed_status", "$pending")); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
$update_account
Use $update_account
to record changes to the user's
account information. For user accounts created prior to integrating with Sift,
there's no need to call $create_account
before $update_account
.
Simply call $update_account
and we'll infer that account was created before integration.
- $typerequired · String
"$update_account"
- $api_keyrequired · String
Your Sift REST API key.
- $user_idrequired · String
The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid
$user_id
values here. - $changed_passwordBoolean
If the user changed their password, set this field and mark as
true
. - $user_emailString
Updated value of the user's email address. 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. - $nameString
The full name of the user.
- $phoneString
The primary phone number of the user associated with this account. 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. If you collect other phone numbers for the account, provide them as additional custom fields, e.g
work_phone
- $referrer_user_idString
The ID of the user that referred the current user to your business. This field is required for detecting referral fraud. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs. Follow our guidelines for
$user_id
values. - $payment_methodsArray of Payment Methods
The payment method(s) associated with this account. occurred an array of nested
payment_method
objects. If possible, please send all payment methods associated with the account each time payment methods are updated. - $billing_addressAddress
The updated billing address. occurred a nested
address
object. - $shipping_addressAddress
The shipping address associated with this user. occurred a nested
address
object. - $social_sign_on_typeString
If the user logged in with a social identify provider, give the name here.
Allowed Values
$facebook
$google
$linkedin
$twitter
$yahoo
$other
// Sample $update_account event { // Required Fields "$type" : "$update_account", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", // Supported Fields "$changed_password" : true, "$user_email" : "bill@gmail.com", "$name" : "Bill Jones", "$phone" : "1-415-555-6040", "$referrer_user_id" : "janejane102", "$payment_methods" : [ { "$payment_type" : "$credit_card", "$card_bin" : "542486", "$card_last4" : "4444" } ], "$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" }, "$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" }, "$social_sign_on_type" : "$twitter", }
import sift client = sift.Client("YOUR_API_KEY") # Sample $update_account event properties = { # Required Fields "$user_id" : "billy_jones_301", # Supported Fields "$changed_password" : True, "$user_email" : "bill@gmail.com", "$name" : "Bill Jones", "$phone" : "1-415-555-6040", "$referrer_user_id" : "janejane102", "$payment_methods" : [ { "$payment_type" : "$credit_card", "$card_bin" : "542486", "$card_last4" : "4444" } ], "$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" }, "$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" }, "$social_sign_on_type" : "$twitter", } response = client.track("$update_account", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $update_account event properties = { # Required Fields "$user_id" => "billy_jones_301", # Supported Fields "$changed_password" => true, "$user_email" => "bill@gmail.com", "$name" => "Bill Jones", "$phone" => "1-415-555-6040", "$referrer_user_id" => "janejane102", "$payment_methods" => [ { "$payment_type" => "$credit_card", "$card_bin" => "542486", "$card_last4" => "4444" } ], "$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" }, "$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" }, "$social_sign_on_type" => "$twitter", } response = client.track("$update_account", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $update_account event $properties = array( // Required Fields '$user_id' => 'billy_jones_301', // Supported Fields '$changed_password' => True, '$user_email' => 'bill@gmail.com', '$name' => 'Bill Jones', '$phone' => '1-415-555-6040', '$referrer_user_id' => 'janejane102', '$payment_methods' => array( array( '$payment_type' => '$credit_card', '$card_bin' => '542486', '$card_last4' => '4444' ) ), '$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' ), '$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' ), '$social_sign_on_type' => '$twitter', ); $response = $client->track('$update_account', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.model.UpdateAccountFieldSet; import com.siftscience.model.Address; import com.siftscience.model.PaymentMethod; SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new UpdateAccountFieldSet() // Required Fields .setUserId("billy_jones_301") .setSessionId("gigtleqddo84l8cm15qe4il") .setChangedPassword(true) .setUserEmail("bill@gmail.com") .setName("Bill Jones") .setPhone("1-415-555-6040") .setReferrerUserId("janejane102") .setPaymentMethods(Arrays.asList(new PaymentMethod() .setPaymentType("$credit_card") .setPaymentGateway("$braintree") .setCardBin("542486") .setCardLast4("4444"))) .setBillingAddress(new Address() .setName("Bill Jones") .setPhone("1-415-555-6041") .setAddress1("2100 Main Street") .setAddress2("Apt 3B") .setCity("New London") .setRegion("New Hampshire") .setCountry("US") .setZipCode("03257")) .setShippingAddress(new Address() .setName("Bill Jones") .setPhone("1-415-555-6041") .setAddress1("2100 Main Street") .setAddress2("Apt 3B") .setCity("New London") .setRegion("New Hampshire") .setCountry("US") .setZipCode("03257")) .setSocialSignOnType("$twitter") EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
$create_content
Use $create_content
to tell Sift whenever a user creates content on your site.
Some examples of content are a job posting, product for sale, apartment for rent, dating profile, and blog post.
- $typerequired · String
"$create_content"
- $api_keyrequired · String
Your Sift REST API key.
- $user_idrequired · String
The user's internal account ID. Users without an assigned
$user_id
will not show up in the console. Find valid$user_id
values here. - $session_idString
The user's current session ID, used to tie a user's action before and after login or account creation.
- $content_idString
The unique ID that you assign to an individual piece content in your system. Note: content IDs are case sensitive.
- $contact_emailString
The contact email provided with the posting.
- $contact_phoneString
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.
- $subjectString
The subject of the posting.
- $contentString
The text content of the posting.
- $amountInteger
A price associated with this content in micros in the base unit of the
$currency_code
. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros. - $currency_codeString
ISO-4217 currency code for the amount. e.g., USD, CAD, HKD, BTC.
- $categoriesArray of Strings
The category or categories you associate with the content you are posting. For example, a job posting might contain industry and position (e.g. ["Computer Hardware", "Engineer"]) or marketplace might contain the type of good it is (e.g. ["Furniture", "Outdoor", "Patio", "Tables"]). If you need to include location of the good, use the
$locations
field to pass that instead. - $locationsArray of Addresses
The locations associated with this posting. occurred an array of nested
address
objects. You can pass one or more addresses that are associated with your posting. Pass as much information as you have. Partial addresses such as just city and state are fine if that’s all you have. - $image_hashesArray of Strings
The MD5 hash of any images associated with the posting. Pass one or multiple image hashes when creating or updating your content. A hash for a single file will look like this:
18E927C7E1229DC8F088643B7A65F978
- $expiration_timeInteger
The UNIX timestamp in milliseconds when the posting will expire. Only set if posting is time bound in some way (e.g. car auction is active 14 days from date of posting).
- $statusString
The status of the posting. After you create a posting, you can also update its status via the
$content_status
event.Allowed Values
- $draftThe posting has not yet been submitted by the user to go live.
- $pendingThe user has submitted the posting but has not gone live. This may be because the posting needs to be reviewed, the user needs to add payment details, or because of some other processes within your business.
- $activeThe posting is live and active on your site. Other users can see the posting.
- $pausedThe posting has been paused by the user and may return back to
$active
at a later date. - $deleted_by_userThe posting has been deleted or archived by the user.
- $deleted_by_companyThe posting has been deleted or archived by your company due to violation of terms of service or other policies.
// Sample $create_content event { // Required Fields "$type" : "$create_content", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", // Supported Fields "$contact_email" : "bill@example.com", "$contact_phone" : "1-415-555-6040", "$content_id" : "9671500641", "$subject" : "2 Bedroom Apartment for Rent", "$content" : "Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.", "$amount" : 2300000000, // $2300 "$currency_code" : "USD", "$categories" : [ "Housing", "Apartments", "2 Bedrooms" ], "$locations" : [ { "$city" : "Seattle", "$region" : "Washington", "$country" : "US", "$zipcode" : "98112" } ], "$image_hashes" : [ "912ec803b2ce49e4a541068d495ab570", // MD5 hash of the image "4be4b314caafaa3e12bfcb8d16df3aff" ], "$expiration_time" : 1471003200000, // UNIX timestamp in milliseconds "$status" : "$active" }
import sift client = sift.Client("YOUR_API_KEY") # Sample $create_content event properties = { # Required Fields "$user_id" : "billy_jones_301", # Supported Fields "$contact_email" : "bill@example.com", "$contact_phone" : "1-415-555-6040", "$content_id" : "9671500641", "$subject" : "2 Bedroom Apartment for Rent", "$content" : "Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.", "$amount" : 2300000000, # $2300 "$currency_code" : "USD", "$categories" : [ "Housing", "Apartments", "2 Bedrooms" ], "$locations" : [ { "$city" : "Seattle", "$region" : "Washington", "$country" : "US", "$zipcode" : "98112" } ], "$image_hashes" : [ "912ec803b2ce49e4a541068d495ab570", # MD5 hash of the image "4be4b314caafaa3e12bfcb8d16df3aff" ], "$expiration_time" : 1471003200000, # UNIX timestamp in milliseconds "$status" : "$active" } response = client.track("$create_content", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $create_content event properties = { # Required Fields "$user_id" => "billy_jones_301", # Supported Fields "$contact_email" => "bill@example.com", "$contact_phone" => "1-415-555-6040", "$content_id" => "9671500641", "$subject" => "2 Bedroom Apartment for Rent", "$content" => "Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.", "$amount" => 2300000000, # $2300 "$currency_code" => "USD", "$categories" => [ "Housing", "Apartments", "2 Bedrooms" ], "$locations" => [ { "$city" => "Seattle", "$region" => "Washington", "$country" => "US", "$zipcode" => "98112" } ], "$image_hashes" => [ "912ec803b2ce49e4a541068d495ab570", # MD5 hash of the image "4be4b314caafaa3e12bfcb8d16df3aff" ], "$expiration_time" => 1471003200000, # UNIX timestamp in milliseconds "$status" => "$active" } response = client.track("$create_content", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); # Sample $create_content event properties = array( // Required Fields '$user_id' => 'billy_jones_301', // Supported Fields '$contact_email' => 'bill@example.com', '$contact_phone' => '1-415-555-6040', '$content_id' => '9671500641', '$subject' => '2 Bedroom Apartment for Rent', '$content' => 'Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.', '$amount' => 2300000000, // $2300 '$currency_code' => 'USD', '$categories' => array( 'Housing', 'Apartments', '2 Bedrooms' ), '$locations' => array( array( '$city' => 'Seattle', '$region' => 'Washington', '$country' => 'US', '$zipcode' => '98112' ) ), '$image_hashes' => array( '912ec803b2ce49e4a541068d495ab570', // MD5 hash of the image '4be4b314caafaa3e12bfcb8d16df3aff' ), '$expiration_time' => 1471003200000, // UNIX timestamp in milliseconds '$status' => '$active' ); $response = $client->track('$create_content', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.model.CreateContentFieldSet; import com.siftscience.model.Address; import com.siftscience.model.PaymentMethod; SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new CreateContentFieldSet() // Required Fields .setUserId("billy_jones_301") // Supported Fields .setSessionId("gigtleqddo84l8cm15qe4il") .setContactEmail("bill@example.com") .setContactPhone("1-415-555-6040") .setContentId("9671500641") .setSubject("2 Bedroom Apartment for Rent") .setContent("Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.") .setAmount(2300000000L) .setCurrencyCode("USD") .setCategories(Arrays.asList("Housing", "Apartments", "2 Bedrooms")) .setLocations(Arrays.asList(new Address() .setCity("Seattle") .setRegion("Washington") .setCountry("US") .setZipCode("98112"))) .setImageHashes(Arrays.asList( "912ec803b2ce49e4a541068d495ab570", "4be4b314caafaa3e12bfcb8d16df3aff")) .setExpirationTime(1471003200000L) .setStatus("$active")); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
$update_content
Use $update_content
to record changes to a posting.
- This event contains the same fields as
$create_content
. - The existing content will be completely replaced by the values specified in
$update_content
. Be sure to specify all values for the content, not just those that changed. - For postings created prior to integrating with Sift, there's no need to call
$create_content
before$update_content
. Simply call$update_content
and we'll infer that content was created before your integration with Sift.
- $typerequired · String
"$update_content"
- $api_keyrequired · String
Your Sift REST API key.
- $user_idrequired · String
The user's internal account ID. Users without an assigned
$user_id
will not show up in the console. Find valid$user_id
values here. - $session_idString
The user's current session ID, used to tie a user's action before and after log in or account creation.
- $content_idString
The unique ID that you assign to an individual piece content in your system. Note: content IDs are case sensitive.
- $contact_emailString
The contact email provided with the posting.
- $contact_phoneString
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.
- $subjectString
The subject of the posting.
- $contentString
The text content of the posting.
- $amountInteger
A price associated with this content in micros in the base unit of the
$currency_code
. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros. - $currency_codeString
ISO-4217 currency code for the amount. e.g., USD, CAD, HKD, BTC.
- $categoriesArray of Strings
The category or categories you associate with the content you are posting. For example, a job posting might contain industry and position (e.g. ["Computer Hardware", "Engineer"]) or marketplace might contain the type of good it is (e.g. ["Furniture", "Outdoor", "Patio", "Tables"]). If you need to include location of the good, use the
$locations
field to pass that instead. - $locationsArray of Addresses
The locations associated with this posting. occurred an array of nested
address
objects. You can pass one or more addresses that are associated with your posting. Pass as much information as you have. Partial addresses such as just city and state are fine if that’s all you have. - $image_hashesArray of Strings
The MD5 hash of any images associated with the posting. Pass one or multiple image hashes when creating or updating your content. A hash for a single file will look like this:
18E927C7E1229DC8F088643B7A65F978
- $expiration_timeInteger
The UNIX timestamp in milliseconds when the posting will expire. Only set if posting is time bound in some way (e.g. car auction is active 14 days from date of posting).
- $statusString
The status of the posting. After you create a posting, you can also update its status via the
$content_status
event.Allowed Values
- $draftThe posting has not yet been submitted by the user to go live.
- $pendingThe user has submitted the posting but has not gone live. This may be because the posting needs to be reviewed, the user needs to add payment details, or because of some other processes within your business.
- $activeThe posting is live and active on your site. Other users can see the posting.
- $pausedThe posting has been paused by the user and may return back to
$active
at a later date. - $deleted_by_userThe posting has been deleted or archived by the user.
- $deleted_by_companyThe posting has been deleted or archived by your company due to violation of terms of service or other policies.
// Sample $update_content event { // Required Fields "$type" : "$update_content", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", // Supported Fields "$contact_email" : "bill@example.com", "$contact_phone" : "1-415-555-6040", "$content_id" : "9671500641", "$subject" : "2 Bedroom Apartment for Rent", "$content" : "Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.", "$amount" : 2300000000, // $2300 "$currency_code" : "USD", "$categories" : [ "Housing", "Apartments", "2 Bedrooms" ], "$locations" : [ { "$city" : "Seattle", "$region" : "Washington", "$country" : "US", "$zipcode" : "98112" } ], "$image_hashes" : [ "912ec803b2ce49e4a541068d495ab570", // MD5 hash of the image "4be4b314caafaa3e12bfcb8d16df3aff" ], "$expiration_time" : 1471003200000, // UNIX timestamp in milliseconds "$status" : "$active" }
import sift client = sift.Client("YOUR_API_KEY") # Sample $update_content event properties = { # Required Fields "$type" : "$update_content", # Supported Fields "$contact_email" : "bill@example.com", "$contact_phone" : "1-415-555-6040", "$content_id" : "9671500641", "$subject" : "2 Bedroom Apartment for Rent", "$content" : "Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.", "$amount" : 2300000000, # $2300 "$currency_code" : "USD", "$categories" : [ "Housing", "Apartments", "2 Bedrooms" ], "$locations" : [ { "$city" : "Seattle", "$region" : "Washington", "$country" : "US", "$zipcode" : "98112" } ], "$image_hashes" : [ "912ec803b2ce49e4a541068d495ab570", # MD5 hash of the image "4be4b314caafaa3e12bfcb8d16df3aff" ], "$expiration_time" : 1471003200000, # UNIX timestamp in milliseconds "$status" : "$active" } response = client.track("$update_content", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $update_content event properties = { # Required Fields "$type" => "$update_content", # Supported Fields "$contact_email" => "bill@example.com", "$contact_phone" => "1-415-555-6040", "$content_id" => "9671500641", "$subject" => "2 Bedroom Apartment for Rent", "$content" => "Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.", "$amount" => 2300000000, # $2300 "$currency_code" => "USD", "$categories" => [ "Housing", "Apartments", "2 Bedrooms" ], "$locations" => [ { "$city" => "Seattle", "$region" => "Washington", "$country" => "US", "$zipcode" => "98112" } ], "$image_hashes" => [ "912ec803b2ce49e4a541068d495ab570", # MD5 hash of the image "4be4b314caafaa3e12bfcb8d16df3aff" ], "$expiration_time" => 1471003200000, # UNIX timestamp in milliseconds "$status" => "$active" } response = client.track("$update_content", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); # Sample $update_content event properties = array( // Required Fields '$type' => '$update_content', // Supported Fields '$contact_email' => 'bill@example.com', '$contact_phone' => '1-415-555-6040', '$content_id' => '9671500641', '$subject' => '2 Bedroom Apartment for Rent', '$content' => 'Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.', '$amount' => 2300000000, // $2300 '$currency_code' => 'USD', '$categories' => array( 'Housing', 'Apartments', '2 Bedrooms' ), '$locations' => array( array( '$city' => 'Seattle', '$region' => 'Washington', '$country' => 'US', '$zipcode' => '98112' ) ), '$image_hashes' => array( '912ec803b2ce49e4a541068d495ab570', // MD5 hash of the image '4be4b314caafaa3e12bfcb8d16df3aff' ), '$expiration_time' => 1471003200000, // UNIX timestamp in milliseconds '$status' => '$active' ); $response = $client->track('$update_content', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.model.UpdateContentFieldSet; import com.siftscience.model.Address; SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new UpdateContentFieldSet() // Required Fields .setUserId("billy_jones_301") // Supported Fields .setSessionId("gigtleqddo84l8cm15qe4il") .setContactEmail("bill@example.com") .setContactPhone("1-415-555-6040") .setContentId("9671500641") .setSubject("2 Bedroom Apartment for Rent") .setContent("Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.") .setAmount(2300000000L) .setCurrencyCode("USD") .setCategories(Arrays.asList("Housing", "Apartments", "2 Bedrooms")) .setLocations(Arrays.asList(new Address() .setCity("Seattle") .setRegion("Washington") .setCountry("US") .setZipCode("98112"))) .setImageHashes(Arrays.asList( "912ec803b2ce49e4a541068d495ab570", "4be4b314caafaa3e12bfcb8d16df3aff")) .setExpirationTime(1471003200000L) .setStatus("$active")); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
$content_status
Use $content_status
to update the status of content that you’ve already sent to Sift.
If the status is the only thing that’s changing about the content, use this as a convenient way to change it
without having to resend the rest of the content's information. Useful for long lived content such as rentals,
dating profiles, and job postings. Status can also be set using $create_content
or
$update_content
.
- $typerequired · String
is "$content_status"
- $api_keyrequired · String
Your Sift REST API key.
- $user_idrequired · String
The user's internal account ID. Users without an assigned
$user_id
will not show up in the console. Find valid$user_id
values here. - $content_idrequired · String
The unique ID for the piece of content that you’re updating the status of. Note: content IDs are case sensitive.
- $statusrequired · String
The status of the posting.
Allowed Values
- $draftThe posting has not yet been submitted by the user to go live.
- $pendingThe user has submitted the posting but has not gone live. This may be because the posting needs to be reviewed, the user needs to add payment details, or because of some other processes within your business.
- $activeThe posting is live and active on your site. Other users can see the posting.
- $pausedThe posting has been paused by the user and may return back to
$active
at a later date. - $deleted_by_userThe posting has been deleted or archived by the user.
- $deleted_by_companyThe posting has been deleted or archived by your company due to violation of terms of service or other policies.
// Sample $content_status event { // Required Fields "$type" : "$content_status", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", "$content_id" : "9671500641", "$status" : "$paused" }
import sift client = sift.Client("YOUR_API_KEY") # Sample $content_status event properties = { # Required Fields "$user_id" : "billy_jones_301", "$content_id" : "9671500641", "$status" : "$paused" } response = client.track("$content_status", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $content_status event properties = { # Required Fields "$user_id" => "billy_jones_301", "$content_id" => "9671500641", "$status": => "$paused" } response = client.track("$content_status", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $content_status event $properties = array( // Required Fields '$user_id' => 'billy_jones_301', '$content_id' => '9671500641', '$status' => '$paused' ); $response = $client->track('$content_status', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.model.ContentStatusFieldSet; // Sample $content_status event SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new ContentStatusFieldSet() // Required Fields .setUserId("billy_jones_301") .setContentId("9671500641") .setStatus("$paused")); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
$flag_content
Use $flag_content
to let us know when another user reports that this user's content may violate your
company’s policies. If you have a feature like "Report this posting" or "Flag this update", send that event to
us using this reserved event.
- $typerequired · String
is "$flag_content"
- $api_keyrequired · String
Your Sift REST API key.
- $user_idrequired · String
The content creator's account ID according to your systems. Note: User IDs are case sensitive. Find valid
$user_id
values here. - $content_idrequired · String
The unique ID for the piece of content that is being flagged. Note: content IDs are case sensitive.
- $flagged_byString
The account ID of the user who is flagging the content. Note: User IDs are case sensitive.
// Sample $flag_content event { // Required Fields "$type" : "$flag_content", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", // content creator "$content_id" : "9671500641", // Supported Fields "$flagged_by" : "jamieli89" }
import sift client = sift.Client("YOUR_API_KEY") # Sample $flag_content event properties = { # Required Fields "$user_id" : "billy_jones_301", # content creator "$content_id" : "9671500641", # Supported Fields "$flagged_by" : "jamieli89" } response = client.track("$flag_content", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $flag_content event properties = { # Required Fields "$user_id" => "billy_jones_301", # content creator "$content_id" => "9671500641", # Supported Fields "$flagged_by" => "jamieli89" } response = client.track("$flag_content", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $flag_content event $properties = array( // Required Fields '$user_id' => 'billy_jones_301', // content creator '$content_id' => '9671500641', // Supported Fields '$flagged_by' => 'jamieli89' ); $response = $client->track('$flag_content', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.EventResponse; import com.siftscience.model.FlagContentFieldSet; // Sample $flag_content event SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new FlagContentFieldSet() // Required Fields .setUserId("billy_jones_301") .setContentId("9671500641") // Supported Fields .setFlaggedBy("jamieli89")); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
$add_promotion
Use $add_promotion
to record when a user adds one or more promotions to their account.
- $typerequired · String
"$add_promotion"
- $user_idrequired · String
The user's account ID according to your systems. Note: User IDs are case sensitive. Find valid
$user_id
values here. - $promotionsArray of Promotions
Contains all promotions that have been newly applied to the referenced user.
// Sample $add_promotion event { // Required fields. "$type" : "$add_promotion", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", // Supported fields. "$promotions" : [ // Example of a promotion for monetary discounts off good or services { "$promotion_id" : "NewRideDiscountMay2016", "$status" : "$success", "$description" : "$5 off your first 5 rides", "$referrer_user_id" : "elon-m93903", "$discount" : { "$amount" : 5000000, // $5 "$currency_code" : "USD" } } ] }
import sift client = sift.Client("YOUR_API_KEY") # Sample $add_promotion event properties = { # Required fields. "$user_id" : "billy_jones_301", # Supported fields. "$promotions" : [ # Example of a promotion for monetary discounts off good or services { "$promotion_id" : "NewRideDiscountMay2016", "$status" : "$success", "$description" : "$5 off your first 5 rides", "$referrer_user_id" : "elon-m93903", "$discount" : { "$amount" : 5000000, # $5 "$currency_code" : "USD" } } ] } response = client.track("$add_promotion", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $add_promotion event properties = { # Required fields. "$user_id" => "billy_jones_301", # Supported fields. "$promotions" => [ # Example of a promotion for monetary discounts off good or services { "$promotion_id" => "NewRideDiscountMay2016", "$status" => "$success", "$description" => "$5 off your first 5 rides", "$referrer_user_id" => "elon-m93903", "$discount" => { "$amount" => 5000000, # $5 "$currency_code" => "USD" } } ] } response = client.track("$add_promotion", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $add_promotion event $properties = array( // Required fields. '$user_id' => 'billy_jones_301', // Supported fields. '$promotions' => array( // Example of a promotion for monetary discounts off good or services array( '$promotion_id' => 'NewRideDiscountMay2016', '$status' => '$success', '$description' => '$5 off your first 5 rides', '$referrer_user_id' => 'elon-m93903', '$discount' => array( '$amount' => 5000000, // $5 '$currency_code' => 'USD' ) ) ) ); $response = $client->track('$add_promotion', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.EventResponse; import com.siftscience.model.AddPromotionFieldSet; import com.siftscience.model.Discount; import com.siftscience.model.Promotion; // Sample $add_promotion event SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new AddPromotionFieldSet() // Required Fields .setUserId("billy_jones_301") // Supported Fields .setPromotions(Arrays.asList(new Promotion() .setPromotionId("NewRideDiscountMay2016") .setStatus("$success") .setDescription("$5 off your first 5 rides") .setReferrerUserId("elon-m93903") .setDiscount(new Discount() .setAmount(5000000L) .setCurrencyCode("USD") .setMinimumPurchaseAmount(25000000L)))) EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
$add_item_to_cart
Use $add_item_to_cart
to record when a user adds an item to their shopping cart or list.
- $typerequired · String
"$add_item_to_cart"
- $api_keyrequired · String
Your Sift REST API key.
- $session_idrequired 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_idsend if known · String
The user's account ID according to your systems. Note: User IDs are case sensitive. Find valid
$user_id
values here. - $itemItem
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.
// 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 } }
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 } } response = client.track("$add_item_to_cart", properties)
require "sift" client = Sift::Client.new(:api_key => "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 } } response = client.track("$add_item_to_cart", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $add_item_to_cart event $properties = array( // Required Fields '$user_id' => 'billy_jones_301', // Supported Fields '$session_id' => 'gigtleqddo84l8cm15qe4il', '$item' => array( '$item_id' => 'B004834GQO', '$product_title' => 'The Slanket Blanket-Texas Tea', '$price' => 39990000, // $39.99 '$currency_code' => 'USD', '$upc' => '67862114510011', '$sku' => '004834GQ', '$brand' => 'Slanket', '$manufacturer' => 'Slanket', '$category' => 'Blankets & Throws', '$tags' => array('Awesome', 'Wintertime specials'), '$color' => 'Texas Tea', '$quantity' => 16 ) ); $response = $client->track('$add_item_to_cart', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.EventResponse; import com.siftscience.model.AddItemToCartFieldSet; import com.siftscience.model.Item; // Sample $add_item_to_cart event SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new AddItemToCartFieldSet() // Required Fields .setUserId("billy_jones_301") // Supported Fields .setSessionId("gigtleqddo84l8cm15qe4il") .setItem(new Item() .setItemId("B004834GQO") .setProductTitle("The Slanket Blanket-Texas Tea") .setPrice(39990000L) .setUpc("67862114510011") .setSku("004834GQ") .setBrand("Slanket") .setManufacturer("Slanket") .setCategory("Blankets & Throws") .setTags(Arrays.asList("Awesome", "Wintertime specials")) .setQuantity(16L))); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
$remove_item_from_cart
Use $remove_item_from_cart
to record when a user removes an item from their shopping cart or list.
- $typerequired · String
"$remove_item_to_cart"
- $api_keyrequired · String
Your Sift REST API key.
- $session_idrequired 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_idrequired · String
The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid
$user_id
values here. - $itemItem
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.
// 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" } }
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" } } response = client.track("$remove_item_from_cart", properties)
require "sift" client = Sift::Client.new(:api_key => "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" } } response = client.track("$remove_item_from_cart", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $remove_item_from_cart event $properties = array( // Required Fields '$user_id' => 'billy_jones_301', // Supported Fields '$session_id' => 'gigtleqddo84l8cm15qe4il', '$item' => array( '$item_id' => 'B004834GQO', '$product_title' => 'The Slanket Blanket-Texas Tea', '$price' => 39990000, // $39.99 '$currency_code' => 'USD', '$quantity' => 2, '$upc' => '67862114510011', '$sku' => '004834GQ', '$brand' => 'Slanket', '$manufacturer' => 'Slanket', '$category' => 'Blankets & Throws', '$tags' => array('Awesome', 'Wintertime specials'), '$color' => 'Texas Tea' ) ); $response = $client->track('$remove_item_from_cart', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.EventResponse; import com.siftscience.model.RemoveItemFromCartFieldSet; import com.siftscience.model.Item; // Sample $remove_item_from_cart event SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new RemoveItemFromCartFieldSet() // Required Fields .setUserId("billy_jones_301") // Supported Fields .setSessionId("gigtleqddo84l8cm15qe4il") .setItem(new Item() .setItemId("B004834GQO") .setProductTitle("The Slanket Blanket-Texas Tea") .setPrice(39990000L) .setUpc("67862114510011") .setSku("004834GQ") .setBrand("Slanket") .setManufacturer("Slanket") .setCategory("Blankets & Throws") .setTags(Arrays.asList("Awesome", "Wintertime specials")) .setQuantity(16L))); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
$submit_review
Use $submit_review
to record a user-submitted review of a product or other users. e.g., a
seller on your site.
- $typerequired · String
"$submit_review"
- $api_keyrequired · String
Your Sift REST API key.
- $session_idrequired 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_idsend 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. - $contentString
The text content of review submitted.
- $review_titleString
The title of review submitted.
- $item_idString
The ID of the product or service being reviewed.
- $reviewed_user_idString
The user's account ID according to your systems. Note that user IDs are case sensitive. guidelines for
$user_id
values. - $contentString
The text content of review submitted.
- $submission_statusString
If reviews in your system must be approved, use
$submission_status
to represent the status of the review.Allowed Values
"$success"
"$failure"
"$pending"
// 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", // 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", # Sample Custom Fields "rating" : "5" } response = client.track("$submit_review", properties)
require "sift" client = Sift::Client.new(:api_key => "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", # Sample Custom Fields "rating" => "5" } response = client.track("$submit_review", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $submit_review event $properties = array( // Required Fields '$user_id' => 'billy_jones_301', // Supported Fields '$content' => 'Text content of submitted review goes here.', '$review_title' => 'Title of Review Goes Here', '$item_id' => 'V4C3D5R2Z6', '$reviewed_user_id' => 'billy_jones_301', '$submission_status' => '$success', // Sample Custom Fields 'rating' => '5' ); $response = $client->track('$submit_review', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.EventResponse; import com.siftscience.model.SubmitReviewFieldSet; // Sample $submit_review event SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new SubmitReviewFieldSet() // Required Fields .setUserId("billy_jones_301") // Supported Fields .setContent("Text content of submitted review goes here.") .setReviewTitle("Title of Review Goes Here") .setItemId("V4C3D5R2Z6") .setReviewedUserId("billy_jones_301") .setSubmissionStatus("$success") // Sample Custom Fields .setCustomField("rating", 5)); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
$login
Use $login
to record when a user attempts to log in.
- $typerequired · String
"$login"
- $api_keyrequired · String
Your Sift REST API key.
- $user_idRecommended [Required for ATO] · String
The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid
$user_id
values here. - $session_idRecommended [Required for ATO] · String
The user's current session ID, used to tie a user's action before and after log in or account creation. NOTE: this is required if no
$user_id
is provided. - $login_statusRecommended [Required for ATO] · String
Use
$login_status
to represent the success or failure of the login attempt.Allowed Values
"$success"
"$failure"
- $ipOPTIONAL [Required for ATO] · String
IP address of the user that is logging in.
- $browserOPTIONAL [Required for ATO] · Browser
The user agent of the browser that is logging in. Represented by the
$browser
object. Note: cannot be used in conjunction with$app
. - $appOPTIONAL [Required for ATO] · App
The details of the app, os, and device that is logging in. Represented by the
$app
object. Note: cannot be used in conjunction with$browser
.
// Sample $login event { // Required Fields "$type" : "$login", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", "$login_status" : "$success", // Required only if using the ATO Product "$session_id" : "gigtleqddo84l8cm15qe4il", "$ip" : "128.148.1.135", "$browser" : { "$user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36" } }
import sift client = sift.Client("YOUR_API_KEY") # Sample $login event properties = { # Required Fields "$user_id" : "billy_jones_301", "$login_status" : "$success", # Required only if using the ATO Product "$session_id" : "gigtleqddo84l8cm15qe4il", "$ip" : "128.148.1.135", "$browser" : { "$user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36" } } response = client.track("$login", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $login event properties = { # Required Fields "$user_id" => "billy_jones_301", "$login_status" => "$success", # Required only if using the ATO Product "$session_id" => "gigtleqddo84l8cm15qe4il", "$ip" => "128.148.1.135", "$browser" => { "$user_agent" => "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36" } } response = client.track("$login", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $login event $properties = array( // Required Fields '$user_id' => 'billy_jones_301', '$login_status' => '$success', // Required only if using the ATO Product '$session_id' => 'gigtleqddo84l8cm15qe4il', '$ip' => '128.148.1.135', '$browser' => array( '$user_agent' => 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36' ) ); $response = $client->track('$login', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.EventResponse; import com.siftscience.model.LoginFieldSet; // Sample $login event SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new LoginFieldSet() // Required Fields .setUserId("billy_jones_301") .setLoginStatus("$success") // Required only if using the ATO product .setSessionId("gigtleqddo84l8cm15qe4il") .setIp("128.148.1.135") .setBrowser(new Browser() .setUserAgent("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36"))); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
$logout
Use $logout
to record when a user logs out.
- $typerequired · String
"$logout"
- $api_keyrequired · String
Your Sift REST API key.
- $user_idrequired · String
The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid
$user_id
values here.
// Sample $logout event { // Required Fields "$type" : "$logout", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301" }
import sift client = sift.Client("YOUR_API_KEY") # Sample $logout event properties = { # Required Fields "$user_id" : "billy_jones_301" } response = client.track("$logout", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $logout event properties = { # Required Fields "$user_id" => "billy_jones_301" } response = client.track("$logout", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $logout event $properties = array( // Required Fields '$user_id' => 'billy_jones_301' ); $response = $client->track('$logout', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.EventResponse; import com.siftscience.model.LogoutFieldSet; // Sample $logout event SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new LogoutFieldSet() // Required Fields .setUserId("billy_jones_301")); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
$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.
- $typerequired · String
"$link_session_to_user"
- $api_keyrequired · String
Your Sift REST API key.
- $session_idrequired · String
The user's current session ID, used to associate Javascript page events with their REST API counterparts.
- $user_idrequired · String
The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid
$user_id
values here.
// 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" }
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" } response = client.track("$link_session_to_user", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $link_session_to_user event properties = { # Required Fields "$user_id" => "billy_jones_301", "$session_id" => "gigtleqddo84l8cm15qe4il" } 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(array('api_key' => 'YOUR_API_KEY')); // Sample $link_session_to_user event $properties = array( // Required Fields '$user_id' => 'billy_jones_301', '$session_id' => 'gigtleqddo84l8cm15qe4il' ); $response = $client->track('$link_session_to_user', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.EventResponse; import com.siftscience.model.LinkSessionToUserFieldSet; // Sample $link_session_to_user event SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new LinkSessionToUserFieldSet() // Required Fields .setUserId("billy_jones_301") .setSessionId("gigtleqddo84l8cm15qe4il")); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
$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 Decision event with a source of CHARGEBACK if you want to prevent the user from making another purchase.
- $typerequired · String
"$chargeback"
- $api_keyrequired · String
Your Sift REST API key.
- $user_idrequired · String
The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid
$user_id
values here. - $order_idrequired · 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_idrequired · String
The ID for the transaction that this chargeback is filed against.
- $chargeback_stateString
The current state of the chargeback.
Allowed Values
"$received"
"$accepted"
"$disputed"
"$won"
"$lost"
- $chargeback_reasonString
This field can be used to capture the reason given.
Allowed Values
"$fraud"
"$duplicate"
"$product_not_received"
"$product_unacceptable"
"$other"
// 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" }
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" } response = client.track("$chargeback", properties)
require "sift" client = Sift::Client.new(:api_key => "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" } response = client.track("$chargeback", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $chargeback event $properties = array( // Required Fields '$user_id' => 'billy_jones_301', '$order_id' => 'ORDER-123124124', '$transaction_id' => '719637215', // Recommended Fields '$chargeback_state' => '$lost', '$chargeback_reason' => '$duplicate' ); $response = $client->track('$chargeback', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.EventResponse; import com.siftscience.model.ChargebackFieldSet; // Sample $chargeback event SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new ChargebackFieldSet() // Required Fields .setUserId("billy_jones_301") .setOrderId("ORDER-123124124") .setTransactionId("719637215") // Recommended Fields .setChargebackState("$lost") .setChargebackReason("$duplicate")); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
$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.
- $typerequired · String
"$order_status"
- $api_keyrequired · String
Your Sift REST API key.
- $user_idrequired · String
The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid
$user_id
values here. - $order_idrequired · String
The ID for tracking this order in your system.
- $order_statusrequired · String
Indicates the high-level state of the order.
Allowed Values
"$approved"
"$canceled"
"$held"
"$fulfilled"
"$returned"
- $reasonString
The reason for a cancellation.
Allowed Values
"$payment_risk"
"$abuse"
"$policy"
"$other"
- $sourceString
The source of a decision.
Allowed Values
"$automated"
"$manual_review"
- $analystString
The analyst who made the decision, if manual.
- $webhook_idString
An alternative to using
$source
and$analyst
, this is the ID of the Sift Action webhook that triggered the status change. - $descriptionString
Any additional information about this order status change.
// 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" }
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" } response = client.track("$order_status", properties)
require "sift" client = Sift::Client.new(:api_key => "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" } response = client.track("$order_status", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $order_status event $properties = array( // Required Fields '$user_id' => 'billy_jones_301', '$order_id' => 'ORDER-28168441', '$order_status' => '$canceled', // Optional Fields '$reason' => '$payment_risk', '$source' => '$manual_review', '$analyst' => 'someone@your-site.com', '$webhook_id' => '3ff1082a4aea8d0c58e3643ddb7a5bb87ffffeb2492dca33', '$description' => 'Canceling because multiple fraudulent users on device' ); $response = $client->track('$order_status', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.EventResponse; import com.siftscience.model.OrderStatusFieldSet; // Sample $order_status event SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new OrderStatusFieldSet() // Required Fields .setUserId("billy_jones_301") .setOrderId("ORDER-28168441") .setOrderStatus("$canceled") // Supported Fields .setReason("$payment_risk") .setSource("$manual_review") .setAnalyst("someone@your-site.com") .setWebhookId("3ff1082a4aea8d0c58e3643ddb7a5bb87ffffeb2492dca33") .setDescription("Canceling because multiple fraudulent users on device")); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
$verification
When you receive a login attempt that you deem risky, you will likely want to verify whether the user is who
they say they are. This is traditionally done by asking the user to enter an additional one time passcode that is sent to the user’s email, phone, or app. Sift models this interaction with the $verification
event.
- $typerequired · String
"$verification"
- $api_keyrequired · String
Your Sift REST API key.
- $user_idRecommended [Required for ATO] · String
The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid
$user_id
values here. - $session_idRequired · String
The user's current session ID, used to tie a user's action before and after log in or account creation.
- $statusRequired · String
The status of the verification event.
Allowed Values
- $pendingVerification has been sent to your customer but the customer has not attempted to perform the verification attempt.
- $successYour customer has attempted and passed the verification process.
- $failureYour customer has attempted and failed the verification process.
- $verification_typeOptional · String
The type of verification being performed.
Allowed Values
- $smsAn SMS is sent to the user's phone containing a code, URL or other process to authenticate the user.
- $phone_callA phone call is made to the user's phone containing a code or other process to authenticate the user.
- $emailAn email is sent to the user's email address containing a code, URL or other process to authenticate the user.
- $app_tfaA passcode is generated for the user via an application.
- $captchaA captcha is used to detect and stop possible automated or scripted activity (e.g. bots).
- $verified_valueOptional · String
The phone number (e.g. 14155551212, 442072193000) or email address (e.g. bob@example.com) used for verification. This value should be passed when the
$verification_type
is set to$sms
,$phone_call
, or$email
.
// Sample $verification event { // Required Fields "$type" : "$verification", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", "$session_id" : "gigtleqddo84l8cm15qe4il", "$status" : "$pending", // Optional fields if applicable "$verification_type" : "$sms", "$verified_value" : "14155551212" }
import sift client = sift.Client("YOUR_API_KEY") # Sample $verification event properties = { # Required Fields "$type" : "$verification", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", "$session_id" : "gigtleqddo84l8cm15qe4il", "$status" : "$pending", # Optional fields if applicable "$verification_type" : "$sms", "$verified_value" : "14155551212" } response = client.track("$verification", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $verification event properties = { # Required Fields "$type" => "$verification", "$api_key" => "YOUR_API_KEY", "$user_id" => "billy_jones_301", "$session_id" => "gigtleqddo84l8cm15qe4il", "$status" => "$pending", # Optional fields if applicable "$verification_type" => "$sms", "$verified_value" => "14155551212" } response = client.track("$verification", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $verification event properties = array( // Required Fields '$type' => '$verification', '$api_key' => 'YOUR_API_KEY', '$user_id' => 'billy_jones_301', '$session_id' => 'gigtleqddo84l8cm15qe4il', '$status' => '$pending', // Optional fields if applicable '$verification_type' => '$sms', '$verified_value' => '14155551212' ); $response = $client->track('$verification', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.EventResponse; import com.siftscience.model.VerificationFieldSet; // Sample $verification event SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new VerificationFieldSet() // Required Fields .setUserId("billy_jones_301") .setSessionId("gigtleqddo84l8cm15qe4il") .setStatus("$pending") // Optional fields if applicable .setVerificationType("$sms") .setVerifiedValue("14155551212")); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
$security_notification
When you identify suspicious activity on a user account, you may want to notify the user of this activity.
For example, a login may seem suspicious because the login attempt was made from a new device.
You may choose to inform the user that this incident happened. Ideally, these notifications should
contain a summary of the activity and also have a response mechanism where the user may confirm or deny if the suspicious activity was them. The $security_notification
event is used to capture this lifecycle of issuing the notification and the user response.
- $typerequired · String
"$security_notification"
- $api_keyrequired · String
Your Sift REST API key.
- $user_idRequired · String
The user's account ID according to your systems. Note that user IDs are case sensitive. Find valid
$user_id
values here. - $session_idRecommended · String
The user's current session ID, used to tie a user's action before and after log in or account creation.
- $notification_typeRecommended · String/Enum
The type of notification issued.
Allowed Values
- $emailThe notification was sent via email.
- $smsThe notification was sent via sms.
- $pushThe notification was sent as a push notification via your mobile app.
- $notified_valueOptional · String
The phone number (e.g. 14155551212, 442072193000) or email address (e.g. bob@example.com) to which the notification was sent. This value should be passed when the
$notification_type
is set to$sms
or$email
. - $notification_statusRequired · String/Enum
The status of the verification event.
Allowed Values
- $sentThe notification was sent to your user but no action has been taken by the user in response
- $safeThe user has reported that the suspicious activity was performed by the user themselves
- $compromisedThe user has reported that the suspicious activity was an unknown third-party
// Sample $security_notification event { // Required and Recommended Fields "$type" : "$security_notification", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", "$session_id" : "gigtleqddo84l8cm15qe4il", "$notification_status" : "$sent", // Optional fields if applicable "$notification_type" : "$email", "$notified_value" : "billy123@domain.com" }
import sift client = sift.Client("YOUR_API_KEY") # Sample $security_notification event properties = { # Required Fields "$type" : "$security_notification", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", "$session_id" : "gigtleqddo84l8cm15qe4il", "$status" : "$sent", # Optional fields if applicable "$notification_type" : "$email", "$notified_value" : "billy123@domain.com" } response = client.track("$security_notification", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $security_notification event properties = { # Required Fields "$type" => "$security_notification", "$api_key" => "YOUR_API_KEY", "$user_id" => "billy_jones_301", "$session_id" => "gigtleqddo84l8cm15qe4il", "$notification_status" => "$sent", # Optional fields if applicable "$notification_type" => "$email", "$notified_value" => "billy123@domain.com" } response = client.track("$security_notification", properties)
require 'sift-php/lib/Services_JSON- 1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $security_notification event properties = array( // Required Fields '$type' => '$security_notification', '$api_key' => 'YOUR_API_KEY', '$user_id' => 'billy_jones_301', '$session_id' => 'gigtleqddo84l8cm15qe4il', '$status' => '$sent', // Optional fields if applicable '$notification_type' => '$email', '$notified_value' => 'billy123@domain.com' ); $response = $client->track('$security_notification', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.EventResponse; import com.siftscience.model.SecurityNotificationFieldSet; // Sample $security_notification event SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new SecurityNotificationFieldSet() // Required Fields .setUserId("billy_jones_301") .setSessionId("gigtleqddo84l8cm15qe4il") .setStatus("$sent") // Optional fields if applicable .setNotificationType("$email") .setNotifiedValue("billy123@domain.com")); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
Reserved Fields
Reserved fields are fields that begin with a $
. These are fields that, due to sending in a consistent format across customers, we do lots of analysis on. We also share learning across
our global network for these fields, giving you a big added benefit.
Note: When you don't have a value for a given field, send the value as null, nil, None
, etc, or omit the field altogether.
Required
The following reserved fields are required in every event.
- $api_keyString
Your Sift REST API key.
- $user_idString
The user’s internal account ID. This field is required on all events performed by the user while logged in. Users without an assigned
$user_id
will not show up in the console. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs. Only the following characters may be used:a-z,A-Z,0-9,=, ., -, _, +, @, :, &, ^, %, !, $
- $session_idrequired 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.
- $typeString
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.
- $ipString
IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
- $timeInteger
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
- $nameString
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_1String
Address first line, e.g., "2100 Main Street".
- $address_2String
Address second line, e.g., "Apt 3B".
- $cityString
The city or town name.
- $regionString
The region portion of the address. In the USA, this corresponds to the state.
- $countryString
The ISO-3166 country code for the billing address.
- $zipcodeString
The postal code associated with the address, e.g., "90210". Send +4 postal codes with a '-', e.g. "90210-3344"
- $phoneString
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' );
import com.siftscience.model.Address; // Sample $address field value Address address = new Address() .setName("Bill Jones") .setPhone("1-415-555-6041") .setAddress1("2100 Main Street") .setAddress2("Apt 3B") .setCity("New London") .setRegion("New Hampshire") .setCountry("US") .setZipCode("03257");
Item
The Item field type represents a product or service for sale in your business. The value must be a nested object with the appropriate item subfields. Generally used in the $add_item_to_cart
and $remove_item_from_cart
events. An item
is representedas a nested JSON object.
- $item_idString
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_titleString
The item's name, e.g., "Men's Running Springblade Drive Shoes, US10".
- $priceInteger
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_codeString
ISO-4217 currency code for the price.
- $quantityInteger
Quantity of the item.
- $upcString
If the item has a Universal Product Code (UPC), provide it here.
- $skuString
If the item has a Stock-keeping Unit ID (SKU), provide it here.
- $isbnString
If the item is a book with an International Standard Book Number (ISBN), provide it here.
- $brandString
The brand name of the item.
- $manufacturerString
Name of the item's manufacturer.
- $categoryString
The category this item is listed under in your business. e.g., "kitchen appliance", "menswear > pants".
- $tagsArray of Strings
The tags used to describe this item in your business. e.g., "funny", "halloween".
- $colorString
The color of the item.
- $sizeString
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 );
import com.siftscience.model.Item; // Example 1 Item item1 = new Item() .setItemId("B004834GQO") .setProductTitle("The Slanket Blanket-Texas Tea") .setPrice(39990000L) // $39.99 .setCurrencyCode("USD") .setUpc("67862114510011") .setSku("004834GQ") .setBrand("Slanket") .setManufacturer("Slanket") .setCategory("Blankets & Throws") .setTags(Arrays.asList("Awesome", "Wintertime specials")) .setColor("Texas Tea") .setQuantity(6L); // Example 2 Item item2 = new Item() .setItemId("10101042") .setProductTitle("Delivering Happiness [eBook edition]") .setPrice(6990000L) // $6.99 .setCurrencyCode("CDN") .setIsbn("0446576220") .setSku("10101042") .setBrand("Writers of the Round Table Press") .setManufacturer("Writers of the Round Table Press") .setCategory("Business books") .setTags(Arrays.asList("reprint", "paperback", "Tony Hsieh")) .setQuantity(1L);
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_typeString
The general type of payment being used.
Allowed Values
$cash
$check
$credit_card
$crypto_currency
$digital_wallet
$electronic_fund_transfer
$financing
$gift_card
$invoice
$money_order
$points
$store_credit
$third_party_processor
$voucher
If your payment system is not covered by one of the values above please contact support.
- $payment_gatewayString
The specific gateway, company, product, etc. being used to process payment.
Allowed Values
$acapture
$adyen
$affirm
$afterpay
$alipay
$altapay
$amazon_payments
$android_pay
$apple_pay
$astropay
$authorizenet
$avangate
$balanced
$banorte
$banwire
$barclays
$beanstream
$bitgo
$bitpay
$blockchain
$bluepay
$bluesnap
$braintree
$bread
$buckaroo
$cardconnect
$ccavenue
$chain_commerce
$chase_paymentech
$checkoutcom
$cielo
$citrus_pay
$clearsettle
$clearcommerce
$cloudpayments
$cofinoga
$coinbase
$collector
$compropago
$conekta
$credsystem
$cuentadigital
$culqi
$cybersource
$datacash
$debitway
$democracy_engine
$dibs
$digital_river
$dotpay
$dragonpay
$ecopayz
$edgil_payway
$elavon
$empcorp
$epayeu
$eprocessing_network
$esitef
$euteller
$eway
$e_xact
$first_atlantic_commerce
$first_data
$getnet
$g2apay
$giropay
$globalcollect
$global_payments
$global_payways
$gmopg
$gocardless
$hdfc_fssnet
$hipay
$ideal
$ikajo
$ingenico
$instamojo
$interac
$internetsecure
$intuit_quickbooks_payments
$isignthis
$iugu
$iyzico
$jabong
$juspay
$kash
$klarna
$kushki
$lemonway
$limelight
$logon
$mastercard_payment_gateway
$masterpass
$maxipago
$maxpay
$meikopay
$mercadopago
$merchant_esolutions
$mirjeh
$moip
$mollie
$moneris_solutions
$moneygram
$mpesa
$multibanco
$netbilling
$neteller
$network_for_good
$nmi
$ogone
$okpay
$omise
$openpaymx
$optimal_payments
$pagar_me
$pagofacil
$pagseguro
$paxum
$pay_zone
$payeer
$payfast
$payflow
$paygate
$payjunction
$paylike
$paymentwall
$payment_express
$paymill
$payone
$payoneer
$paypal
$paypal_express
$paysafecard
$paysera
$paysimple
$paystation
$paytm
$paytrace
$paytrail
$payture
$payu
$payulatam
$payvector
$payza
$peach_payments
$perfect_money
$pinpayments
$pivotal_payments
$planet_payment
$poli
$princeton_payment_solutions
$prismpay
$processing
$przelewy24
$psigate
$pulse
$qiwi
$quickpay
$raberil
$rakuten_checkout
$ratepay
$razorpay
$rbkmoney
$rede
$redpagos
$redsys
$rewardspay
$rietumu
$rocketgate
$safecharge
$safetypay
$sagepay
$samsung_pay
$securionpay
$securepay
$sermepa
$shopify_payments
$simplify_commerce
$skrill
$smart2pay
$smartcoin
$sofort
$splash_payments
$sps_decidir
$square
$stone
$stripe
$swedbank
$synapsepay
$telerecargas
$tnspay
$towah
$tpaga
$transact_pro
$transfirst
$trustcommerce
$trustly
$tu_compra
$twoc2p
$twocheckout
$unionpay
$usa_epay
$vantiv
$venmo
$veritrans
$versapay
$vesta
$vindicia
$virtual_card_services
$visa
$vme
$vpos
$webmoney
$webpay_oneclick
$wepay
$western_union
$wirecard
$worldpay
$worldspan
$xipay
$yandex_money
$zipmoney
$zooz_paymentsos
If the payment gateway you use is not supported, contact support and we'll add it.
- $card_binString
The first six digits of the credit card number. These numbers contain information about the card issuer, the geography and other card details.
- $card_last4String
The last four digits of the credit card number.
- $avs_result_codeString
Response code from the AVS address verification system. Used in payments involving credit cards.
- $cvv_result_codeString
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_statusString
Use
$verification_status
to indicate the payment method has been verified. The value can be$success
,$failure
or$pending
. For instance, if you request payment method verification from a payment processor and receive a failure set the value to$failure
. - $routing_numberString
This is the ABA routing number or SWIFT code used.
- $decline_reason_codeString
In case of a declined payment, response code received from the payment processor indicating the reason for the decline.
- $paypal_payer_idString
Payer ID returned by Paypal.
- $paypal_payer_emailString
Payer email address returned by Paypal.
- $paypal_payer_statusString
Payer status returned by Paypal.
- $paypal_address_statusString
Payer address status returned by Paypal.
- $paypal_protection_eligibilityString
Seller protection eligibility returned by Paypal.
- $paypal_payment_statusString
Payment status returned by Paypal.
- $stripe_cvc_checkString
CVC verification result returned by Stripe.
- $stripe_address_line1_checkString
Address line 1 verification result returned by Stripe.
- $stripe_address_line2_checkString
Address line 2 verification result returned by Stripe.
- $stripe_address_zip_checkString
Address zip code verification result returned by Stripe.
- $stripe_fundingString
Funding source returned by Stripe.
- $stripe_brandString
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' );
import com.siftscience.model.PaymentMethod; // 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 a list of objects. ListpaymentMethods = Arrays.asList( new PaymentMethod() .setPaymentType("$credit_card") .setPaymentGateway("$stripe") .setCardBin("542486") .setCardLast4("4242") .setCvvResultCode("M") .setAvsResultCode("Y") .setStripeAddressLine1Check("pass") .setStripeAddressLine2Check("pass") .setStripeAddressZipCheck("pass"), new PaymentMethod() .setPaymentType("$gift_card") ); // A Electronic Fund Transfer Payment, // as it would appear in a $create_order event. paymentMethods = Arrays.asList( new PaymentMethod() .setPaymentType("$electronic_fund_transfer") .setRoutingNumber("021001088") ); // A Paypal Payment, as it would appear // in a $create_order event. paymentMethods = Arrays.asList( new PaymentMethod() .setPaymentType("$third_party_processor") .setPaymentGateway("$paypal") .setPaypalPayerId("7E7MGXCWKTKK2") .setPaypalPayerEmail("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. paymentMethods = Arrays.asList( new PaymentMethod() .setPaymentType("$gift_card") );
Promotion
The Promotion field type generically models different kinds of promotions such as referrals, coupons, free trials, etc. The value must be a nested JSON object which you populate with the appropriate information to describe the promotion. Not all sub-fields will likely apply to a given promotion. Populate only those that apply.
A promotion can be added when creating or updating
an account, creating or updating an order, or on its own using the $add_promotion
event. The promotion object supports both monetary (e.g. $25 coupon on first order) and non-monetary (e.g. "1000 in game points to refer a friend").
- $promotion_idString
The ID within your system that you use to represent this promotion. This ID is ideally unique to the promotion across users (e.g. "BackToSchool2016").
- $statusString
The status of the addition of promotion to an account. Best used with the
$add_promotion
event. This way you can pass to Sift both successful and failed attempts when using a promotion. May be useful in spotting potential abuse.Allowed Values
$success
$failure
- $failure_reasonString
When adding a promotion fails, use this to describe why it failed.
Allowed Values
$already_used
$invalid_code
$not_applicable
$expired
- $descriptionString
Freeform text to describe the promotion.
- $referrer_user_idString
The unique account ID of the user who referred the user to this promotion. Note: User IDs are case sensitive.
- $discountDiscount
The
$discount
field type generically models monetary discounts that are associated with a promotion (e.g. $25 off an order of $100 or more, 10% off, etc). Most promotions likely require adiscount
object orcredit_point
object to describe them, though both can be set for a given promotion. - $credit_pointCredit Point
The
credit_point
field type generically models monetary and non-monetary rewards (e.g. in-game currency, stored account value, MBs storage, frequent flyer miles, etc.) for a promotion. Most promotions likely require acredit_point
object ordiscount
object to describe them, though both can be set for a given promotion.
// Example of a promotion for monetary discounts off goods or services { "$promotion_id" : "SPRING-1009", "$status" : "$failed", "$failure_reason" : "$already_used", "$description" : "Spring coupon", "$discount" : { "$percentage_off" : 0.2, // 20% off "$amount" : 115940000, // $115.94 "$currency_code" : "USD", "$minimum_purchase_amount" : 50000000 // $50 } } // Example of a promotion for account credits { "$promotion_id" : "NewCustomerReferral2016", "$status" : "$success", "$description" : "Signup bonus for new customers in 2016", "$referrer_user_id" : "john_smith_0123", "$credit_point" : { "$amount" : 5000, "$credit_point_type" : "character xp points" } }
# Example of a promotion for monetary discounts off goods or services { "$promotion_id" : "SPRING-1009", "$status" : "$failed", "$failure_reason" : "$already_used", "$description" : "Spring coupon", "$discount" : { "$percentage_off" : 0.2, # 20% off "$amount" : 115940000, # $115.94 "$currency_code" : "USD", "$minimum_purchase_amount" : 50000000 # $50 } } # Example of a promotion for account credits { "$promotion_id" : "NewCustomerReferral2016", "$status" : "$success", "$description" : "Signup bonus for new customers in 2016", "$referrer_user_id" : "john_smith_0123", "$credit_point" : { "$amount" : 5000, "$credit_point_type" : "character xp points" } }
# Example of a promotion for monetary discounts off goods or services { "$promotion_id" => "SPRING-1009", "$status" => "$failed", "$failure_reason" => "$already_used", "$description" => "Spring coupon", "$discount" => { "$percentage_off" => 0.2, # 20% off "$amount" => 115940000, # $115.94 "$currency_code" => "USD", "$minimum_purchase_amount" => 50000000 # $50 } } # Example of a promotion for account credits { "$promotion_id" => "NewCustomerReferral2016", "$status" => "$success", "$description" => "Signup bonus for new customers in 2016", "$referrer_user_id" => "john_smith_0123", "$credit_point" => { "$amount" => 5000, "$credit_point_type" => "character xp points" } }
// Example of a promotion for monetary discounts off goods or services array( '$promotion_id' => 'SPRING-1009', '$status' => '$failed', '$failure_reason' => '$already_used', '$description' => 'Spring coupon', '$discount' => array( '$percentage_off' => 0.2, // 20% off '$amount' => 115940000, // $115.94 '$currency_code' => 'USD', '$minimum_purchase_amount' => 50000000 // $50 ) ); // Example of a promotion for account credits array( '$promotion_id' => 'NewCustomerReferral2016', '$status' => '$success', '$description' => 'Signup bonus for new customers in 2016', '$referrer_user_id' => 'john_smith_0123', '$credit_point' => array( '$amount' => 5000, '$credit_point_type' => 'character xp points' ) );
import com.siftscience.model.Promotion; import com.siftscience.model.Discount; import com.siftscience.model.CreditPoint; // Example of a promotion for monetary discounts off goods or services Promotion promotion = new Promotion() .setPromotionId("SPRING-1009") .setStatus("$failed") .setFailureReason("$already_used") .setDescription("Spring coupon") .setDiscount(new Discount() .setPercentageOff(0.2) // 20% off .setAmount(115940000L) // $115.94 .setCurrencyCode("USD") .setMinimumPurchaseAmount(50000000L) // $50 ); // Example of a promotion for account credits promotion = new Promotion() .setPromotionId("NewCustomerReferral2016") .setStatus("$success") .setDescription("Signup bonus for new customers in 2016") .setReferrerUserId("john_smith_0123") .setCreditPoint(new CreditPoint() .setAmount(5000L) .setCreditPointType("character xp points"));
Discount
The Discount field type generically models monetary discounts that are associated with a promotion (e.g. $25 off an order of $100 or more, 10% off, etc). Discounts are usually used for promotions that apply at the order level. The value must be a nested JSON object populated with the appropriate information to describe the discount. Not all sub-fields will likely apply to a given discount. Populate only those that apply.
A discount
is an object that gets included as part of promotion object. Learn more about promotions.
- $percentage_offFloat
The percentage discount. If the discount is 10% off, you would send "0.1".
- $amountInteger
The amount of the discount that the promotion offers in micros in the base unit of the
$currency_code
. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros. - $currency_codeString
ISO-4217 currency code for the amount. e.g., USD, CAD, HKD. If your site uses alternative currencies, like bitcoin or points systems, specify that here.
- $minimum_purchase_amountInteger
The minimum amount someone must spend in order for the promotion to be applied. The amount should be in micros in the base unit of the
$currency_code
. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.
// Example of a monetary discount off goods or services { "$percentage_off" : 0.2, // 20% off "$amount" : 115940000, // $115.94 "$currency_code" : "USD", "$minimum_purchase_amount" : 50000000 // $50 }
# Example of a monetary discount off goods or services { "$percentage_off" : 0.2, # 20% off "$amount" : 115940000, # $115.94 "$currency_code" : "USD", "$minimum_purchase_amount" : 50000000 # $50 }
# Example of a monetary discount off goods or services { "$percentage_off" => 0.2, # 20% off "$amount" => 115940000, # $115.94 "$currency_code" => "USD", "$minimum_purchase_amount" => 50000000 # $50 }
// Example of a monetary discount off goods or services array( '$percentage_off' => 0.2, // 20% off '$amount' => 115940000, // $115.94 '$currency_code' => 'USD', '$minimum_purchase_amount' => 50000000 // $50 );
import com.siftscience.model.Discount; // Example of a monetary discount off goods or services Discount discount = new Discount() .setPercentageOff(0.2) // 20% off .setAmount(115940000L) // $115.94 .setCurrencyCode("USD") .setMinimumPurchaseAmount(50000000L); // $50
Credit Point
The Credit Point field type generically models monetary and non-monetary rewards (e.g. in-game currency, stored account value, MBs storage, frequent flyer miles, etc) associated with a promotion. Credit points are usually used for promotions that apply at the account level. The value must be a nested JSON object populated with the appropriate information to describe the credit_point. All values are required.
A credit_point
is an object that gets included as part of promotion object. Learn more about promotions.
- $amountRequired · Integer
The amount of credits the promotion is worth.
- $credit_point_typeRequired · String
The type of credit point. Particularly useful if you have multiple types of credit points that you give out. Enables us to distinguish amongst them to find patterns (e.g. days of free service, karma, frequent flyer miles, MBs of storage, etc.).
// Example of a credit point for an in-game currency { "$amount" : 5000, "$credit_point_type" : "character xp points" }
# Example of a credit point for an in-game currency { "$amount" : 5000, "$credit_point_type" : "character xp points" }
# Example of a credit point for an in-game currency { "$amount" => 5000, "$credit_point_type" => "character xp points" }
// Example of a credit point for an in-game currency array( '$amount' => 5000, '$credit_point_type' => 'character xp points' );
import com.siftscience.model.CreditPoint; // Example of a credit point for an in-game currency CreditPoint creditPoint = new CreditPoint() .setAmount(5000L) .setCreditPointType("character xp points");
App
The app field type represents the details of an application as well as the device and OS it's running on. $app
is currently only used in the $login
event when using the Sift Account Takeover Prevention product.
- $os
The operating system on which application is running. (e.g. iOS, Android)
- $os_version
The operating system version on which application is running. (e.g. 10.3.1, 7.1.1)
- $device_manufacturer
The manufacturer of the device on which application is running. . (e.g. Samsung, Apple, LG)
- $device_model
The model of the device on which application is running. (e.g. SM-G920x, iPhone8,1)
- $device_unique_id
The unique ID of the device on which application is running. For iOS, send the IFV identifier. For Android, send the Android ID.
- $app_name
The name of your application.
- $app_version
The version of your application.
// Example for the iOS Calculator app. { "$os" : "iOS", "$os_version" : "10.1.3", "$device_manufacturer" : "Apple", "$device_model" : "iPhone 4,2", "$device_unique_id" : "A3D261E4-DE0A-470B-9E4A-720F3D3D22E6", "$app_name" : "Calculator", "$app_version" : "3.2.7" }
# Example for the iOS Calculator app. { "$os" : "iOS", "$os_version" : "10.1.3", "$device_manufacturer" : "Apple", "$device_model" : "iPhone 4,2", "$device_unique_id" : "A3D261E4-DE0A-470B-9E4A-720F3D3D22E6", "$app_name" : "Calculator", "$app_version" : "3.2.7" }
# Example for the iOS Calculator app. { "$os" => "iOS", "$os_version" => "10.1.3", "$device_manufacturer" => "Apple", "$device_model" => "iPhone 4,2", "$device_unique_id" => "A3D261E4-DE0A-470B-9E4A-720F3D3D22E6", "$app_name" => "Calculator", "$app_version" => "3.2.7" }
// Example for the iOS Calculator app. array( '$os' => 'iOS', '$os_version' => '10.1.3', '$device_manufacturer' => 'Apple', '$device_model' => 'iPhone 4,2', '$device_unique_id' => 'A3D261E4-DE0A-470B-9E4A-720F3D3D22E6', '$app_name' => 'Calculator', '$app_version' => '3.2.7' )
import com.siftscience.model.App; // Example for the iOS Calculator app. App app = new App() .setOperatingSystem("iOS") .setOperatingSystemVersion("10.1.3") .setDeviceManufacturer("Apple") .setDeviceModel("iPhone 4,2") .setDeviceUniqueId("A3D261E4-DE0A-470B-9E4A-720F3D3D22E6") .setAppName("Calculator") .setAppVersion("3.2.7");
Browser
The $browser
field type contains information about the browser. $browser
is currently only used in the $login
event when using the Sift Account Takeover Prevention product. For all other use cases, the Sift Javascript Snippet automatically sends this information.
- $user_agentRequired · String
The user agent of the browser that is interacting with your website.
{ "$user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36" }
{ "$user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36" }
{ "$user_agent" => "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36" }
// Example for the iOS Calculator app. array( '$user_agent' => 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36' )
import com.siftscience.model.Browser; Browser browser = new Browser() .setUserAgent("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36");
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(:api_key => "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(array('api_key' => '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);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.model.CustomEventFieldSet; SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new CustomEventFieldSet() .setUserId("billy_jones_301") .setEventType("make_call") .setCustomField("recipient_user_id", "marylee819") .setCustomField("call_duration", 4428) ); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
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 includealphanumeric 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
· StringSift performs a number of fraud detection algorithms on emails, including matching against throwaway email domains, and looking for similarity to known fraudsters in the past.
Send any other emails associated with the user in field names like
secondary_email
. - Phone
_phone
· StringSift 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
andmobile_phone
. - Latitude
_lat
· FloatSent 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
· FloatSent 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
· StringID 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
orstore_id
. - Status
_status
· StringStatus 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
, · StringWhen 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
, oruser_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.
// To check if the call was successful: response.isOk(); // returns true on successful calls, false on failed score requests. response.getApiStatus(); // returns Sift Error Code, 51 in this case. response.getApiErrorMessage(); // 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.
Decisions Overview
Decisions represent business actions taken on a user, order, or session (eg "Block Order", "Approve User", etc). You use Decisions to record of what has happened. Sift uses this information to continuously improve the accuracy of your risk scores.
When integrating with Sift, you need to create Decisions that represent the different business actions your team takes. These will vary based on your business but some examples could include: "Accept Order”, “Approve Posting”, “Put User on Watchlist”, “Block Order”, “Ban User”, etc. Decisions are entirely customizable by you to meet the needs of your business. Decisions are created and updated using the Decisions page of the Console.
Using Decisions
Decisions can be applied from within the Sift console, sent by your application to the Sift API, or from a Sift Workflow. Whenever a Decision is applied, it should be accompanied by some business action you are taking on your side. For example:
- From the Sift console - When an analyst manually reviews a user and decides an order should be blocked, the analyst would click a Decision button in the console to cancel the order. Once it’s clicked, Sift sends a webhook to your system so that you can cancel the order within your system.
- From your application - When your application logic decides to block an order, you’d first block the order within your system and then send that Decision to the Sift API to record what took place.
- From a Workflow - When your Sift Workflow logic determines to block an order (eg Payment Abuse Score > 95), Sift generates the Decision on that user, and sends a Webhook to your system so you can block the order within your system.
Decision Properties
{ "id": "credit_card_fraud_payment_abuse", "name": "Credit Card Fraud", "description": "cancel and refund all of the user's pending order.", "entity_type": "user", "abuse_type": "payment_abuse", "category": "block", "webhook_url": "http://webhook.example.com", "created_at": 1468005577348, "created_by": "admin@example.com", "updated_at": 1469229177756, "updated_by": "billy@exmaple.com" }
A Decision object includes the following:
id
a unique ID within Sift that is set when the Decision is created.name
The name of the Decision that is shown to analysts within the Sift console.description
a human friendly description of the Decision. This is displayed along with the decision name in the Console to help your users better understand what action they are taking.entity_type
describes whether the decision is related to an order, user, or session.abuse_type
The type of abuse the Decision is related to. Sift can learn the different patterns of abuse you face. The possible values are:payment_abuse
,account_abuse
content_abuse
promotion_abuse
category
describes the type of action being taken. The 3 possible categories are:BLOCK
: You are taking a negative action. (eg "Stop Order", "Blacklist User", "Ban Listing", etc)WATCH
: Your team is not ready to fully block or accept this user. (eg "Require Verification", "Limit Order Amount", "Freeze Listing", etc)ACCEPT
: You are taking a positive action. (eg "Ship Order", "Approve User", "Publish Listing", etc)webhook_url
URl Sift will send a webhook to when a Decision is made within the Sift Console or from a Sift Workflow
When you apply a Decision, it represents a business action taken at a specific point in time. As a result, once a Decision is made, it can't be deleted or modified. However, you can represent updates by applying a subsequent Decision to that entity. This way, you'll have a full and complete record of what occurred. You can always retrieve the most recent Decision by using the Decision Status API.
Decisions API Overview
The Decisions APIs allow you to:
- Apply Decisions from your application when you take business actions on an entity like user, order, or session.
- Get the latest Decisions Status for an entity.
- Get the list of Decisions you've created within Sift.
- Receive webhooks about Decisions made by your Sift Workflows.
Apply Decisions
The Apply Decisions API allows you to apply Decisions to users, orders, or sessions. This is important so that Sift can track the actions you've taken within your system and learn from them. You can only apply Decisions that are active and already configured for your account in the Decisions section in the Console.
When you send a Decision via the API, we will not send a webhook back to you as you'll already have a record within your system of what occurred. However, if you were to apply that same Decision in the Sift Console, we would send a webhook to your application so that you can update your system.
The Request
Applying a decision to a user
NOTE: To apply a Decision on a user you must provide the user ID.
$ curl -XPOST https://api.sift.com/v3/accounts/{accountId}/users/{userId}/decisions -H 'Content-Type: application/json' \ -u {YOUR_API_KEY}: -d \ '{ "decision_id" : "block_user_payment_abuse", "source" : "MANUAL_REVIEW", "analyst" : "analyst@example.com", "description" : "User linked to three other payment abusers and ordering high value items" }'
import sift client = sift.Client(api_key='{YOUR_API_KEY}', account_id='{accountId}') applyDecisionRequest = { 'decision_id' : 'block_user_payment_abuse', 'source' : 'MANUAL_REVIEW', 'analyst' : 'analyst@example.com', 'description' : 'User linked to three other payment abusers and ordering high value items' } response = self.client.apply_user_decision(user_id, applyDecisionRequest)
import com.siftscience.SiftClient; import com.siftscience.DecisionStatusResponse; import com.siftscience.DecisionStatusRequest; import com.siftscience.model.DecisionStatusFieldSet; SiftClient client = new SiftClient("{YOUR_API_KEY}"); ApplyDecisionRequest request; ApplyDecisionRequest request = client.buildRequest( new ApplyDecisionFieldSet() .setAccountId("accountId") .setUserId("userId") .setDecisionId("block_user_payment_abuse") .setAnalyst("analyst@example.com") .setSource(DecisionSource.MANUAL_REVIEW)) .setDescription("User linked to three other payment abusers and ordering high value items"); ApplyDecisionResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); } DecisionLog decisionLog = response.getDecisionLog();
require "sift" client = Sift::Client.new(api_key: "{YOUR_API_KEY}", account_id: "{accountId}") response = client.apply_decision({ decision_id: "block_user_payment_abuse", description: "User linked to three other payment abusers and ordering high value items", source: "manual_review", analyst: "analyst@example.com", user_id: "userId" }) if (!response.ok?) puts "Unable to apply decision: " + response.api_error_message end
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); $options = array( 'analyst' => 'analyst@example.com', 'description' => 'User linked to three other payment abusers and ordering high value items' ); $response = $client->applyDecisionToUser('userId', 'block_user_payment_abuse', 'MANUAL_REVIEW', $options);
Applying a decision to an order
NOTE: To apply a Decision on an order you must provide both the user and order ID.
$ curl -XPOST https://api.sift.com/v3/accounts/{accountId}/users/{userId}/orders/{orderId}/decisions -H 'Content-Type: application/json' \ -u {YOUR_API_KEY}: -d \ '{ "decision_id" : "block_order_payment_abuse", "source" : "AUTOMATED_RULE", "description" : "Auto block pending order as score exceeded risk threshold of 90" }'
import sift client = sift.Client(api_key='{YOUR_API_KEY}', account_id='{accountId}') applyDecisionRequest = { 'decision_id': 'block_order_payment_abuse', 'source': 'AUTOMATED_RULE', 'description': 'Auto block pending order as score exceeded risk threshold of 90' } response = self.client.apply_order_decision(user_id, order_id, applyDecisionRequest)
import com.siftscience.SiftClient; import com.siftscience.DecisionStatusResponse; import com.siftscience.DecisionStatusRequest; import com.siftscience.model.DecisionStatusFieldSet; SiftClient client = new SiftClient("{YOUR_API_KEY}"); ApplyDecisionRequest request; ApplyDecisionRequest request = client.buildRequest( new ApplyDecisionFieldSet() .setAccountId("accountId") .setUserId("userId") .setOrderId("orderId") .setDecisionId("block_order_payment_abuse") .setSource(DecisionSource.AUTOMATED_RULE)); ApplyDecisionResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); } DecisionLog decisionLog = response.getDecisionLog();
require "sift" client = Sift::Client.new(api_key: "{YOUR_API_KEY}", account_id: "accountId") response = client.apply_decision({ decision_id: "block_order_payment_abuse", description: "applied via the high priority queue, queued user because their risk score exceeded 85", source: "AUTOMATED_RULE", user_id: "userId", order_id: "orderId" }) if (!response.ok?) puts "Unable to apply decision: " + response.api_error_message end
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); $options = array( 'analyst' => 'analyst@example.com', 'description' => 'applied via the high priority queue, queued user because their risk score exceeded 85' ); $response = $client->applyDecisionToOrder('userId', 'order_id', 'user_looks_ok_payment_decision', 'MANUAL_REVIEW', $options);
Applying a Decision to a session
NOTE: To apply a Decision on a session you must provide both the user and session ID.
$ curl -XPOST https://api.sift.com/v3/accounts/{accountId}/users/{userId}/sessions/{sessionId}/decisions -H 'Content-Type: application/json' \ -u {YOUR_API_KEY}: -d \ '{ "decision_id" : "session_looks_bad_account_takeover", "source" : "MANUAL_REVIEW", "analyst" : "analyst@example.com", "description" : "compromised account reported to customer service" }'
Request fields
- decision_idrequired · String
The unique identifier of the Decision to be applied to an entity.
decision_id
and descriptions can be retrieved using the GET decisions API Note: A Decision configured withentity_type=user
can only be applied to a user. Similarly, a Decision configured withentity_type=order
can only be applied to an order. - sourcerequired · String
The source of this Decision.
Allowed Values
- MANUAL_REVIEWThis Decision was applied by an analyst during review of a user/order.
- AUTOMATED_RULEThis Decision was applied to a user/order by an automated rules engine or internal system. There was no human analysis before this Decision was made.
- CHARGEBACKThis Decision was applied to a user/order in response to a chargeback received. Source of CHARGEBACK should only be used for Decisions your system automatically takes in response to a Chargeback. Note: Whether or not you take automated action in response to Chargebacks, you should send Sift the Chargeback events.
- analystString
Analyst who applied the Decision, only required when source is set to
manual_review
. Does not need to be an email, can be any analyst identifier. - timeoptional · Long
The time the Decision was applied, as a UNIX timestamp in milliseconds. This is only necessary to send for historical backfill.
- descriptionoptional · String
A description of the Decision that will be applied.
Response
For successful requests, the response will have an
HTTP status code of
200
.
{ "entity": { "id" : {entity_id} "type" : "{entity_type}" }, "decision": { "id": "{decision_id}" }, "time": "1461963439151" } }
Response Fields
- entityObject
The entity object containing information on the entity on which the Decision was applied.
- idString
The id of the entity on which the Decision was applied.
- typeString
Type of entity, (user or order), to which Decision was applied.
- decisionString
The Decision object containing information on the Decision that was applied.
- idString
The id of the Decision that was applied.
- timeLong
The time the Decision was applied, as a UNIX timestamp in milliseconds.
Get Decisions
Get Decisions API allows you to retrieve the list of all Decisions you've configured for your account. Currently, Decisions can only be created in the Decisions section in the Console.
Getting available decisions
$ curl -XGET https://api.sift.com/v3/accounts/{account_id}/decisions?abuse_types=payment_abuse,legacy&entity_type=user&from=5&limit=10 -u {YOUR_API_KEY}:
import sift client = sift.Client(api_key='{YOUR_API_KEY}', account_id='{account_id}') response = client.get_decisions(entity_type='user', limit=10, start_from=5, abuse_types='legacy,payment_abuse')
import com.siftscience.SiftClient; import com.siftscience.DecisionStatusResponse; import com.siftscience.DecisionStatusRequest; import com.siftscience.model.DecisionStatusFieldSet; SiftClient client = new SiftClient("{YOUR_API_KEY}"); GetDecisions request = client.buildRequest(new GetDecisionsFieldSet() .setAccountId("account_id")) .setEntityType(EntityType.USER) .setAbuseTypes(ImmutableList.of(AbuseType.PAYMENT_ABUSE, AbuseType.LEGACY) .setFrom(5) .setLimit(10)); GetDecisionsResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); } List<Decision> decisions = response.getDecisions();
require "sift" client = Sift::Client.new(api_key: "{YOUR_API_KEY}", account_id: "{account_id}") response = client.decisions({ abuse_types: ["payment_abuse", "legacy"], entity_type: "user", from: 5, limit: 10 }) if (response.ok?) { decision = response.body["data"].find do |decision_hash| decision_hash["id"] == "block_bad_user" end }
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); $options = array( 'abuse_types' => array('payment_abuse', 'legacy'), 'entity_type' => 'user', 'from' => 5, 'limit' => 10 ); $response = $client.getDecisions($options);
Query Parameters
- entity_typeoptional · String
Return only decisions applicable to the specified
entity_type
.Allowed Values
- USERThis Decision should be applied to users.
- ORDERThis Decision should be applied to orders.
- abuse_typesoptional · Comma-separated strings
Return only decisions applicable to specified abuse_types.
Allowed Values
- LEGACYReturn Decisions associated with the Legacy product.
- PAYMENT_ABUSEReturn Decisions associated with the Payment Abuse product.
- ACCOUNT_ABUSEReturn Decisions associated with the Account Abuse product.
- CONTENT_ABUSEReturn Decisions associated with the Content Abuse product.
- PROMO_ABUSEReturn Decisions associated with the Promotion Abuse product.
- ACCOUNT_TAKEOVERReturn Decisions associated with the Account Takeover product.
- limitoptional · integer
Used in conjunction with the
from
parameter to paginate results.limit
sets the maximum number of results to return from each request. The default value for limit is 100. - fromoptional · integer
Used in conjunction with
limit
parameter to page through the result set. By default, result set is sorted by id. The fieldfrom
specifies the index of the first entry in a collection to return. The default value forfrom
is 0. For example iffrom
is set to 10 you will receive the 11th decision +limit
.
Response
For successful requests, the response should have an
HTTP status code of
200
. You will receive a response in the following format:
{ "data": [ { "id": "block_user_payment_abuse", "name": "Block user", "description": "cancel and refund all of the user's pending order.", "entity_type": "user", "abuse_type": "payment_abuse", "category": "block", "webhook_url": "http://webhook.example.com", "created_at": 1468005577348, "created_by": "admin@example.com", "updated_at": 1469229177756, "updated_by": "billy@exmaple.com" }, { "id": "user_looks_ok_legacy", "name": "User looks ok", "description": "legacy decision for users that looks ok", "entity_type": "user", "abuse_type": "legacy", "category": "accept", "webhook_url": "http://webhook.example.com", "created_at": 1468005577348, "created_by": "admin@example.com", "updated_at": 1469229177756, "updated_by": "billy@exmaple.com" } ], "has_more": "true", "next_ref": "https://api.sift.com/v3/accounts/{account_id}/decisions?entity_type=user&abuse_types=payment_abuse,legacy&from=15&limit=10" }
Response Fields
- dataArray
An array of decisions.
- idString
The id of the decision. This is auto generated when the Decision is created based on the initial display name of the Decision.
- nameString
Display name of the decision.
- descriptionString
A description of the Decision. This field is intended as a way to describe the business action(s) associated with the Decision.
- entity_typeString
Entity type to which this Decision is applicable.
Possible Values
- USERThis Decision should be applied to users.
- ORDERThis Decision should be applied to orders.
- SESSIONThe Decision should be applied to sessions.
- abuse_typeString
Abuse type which this Decision describes.
Possible Values
- LEGACYReturn Decisions associated with the Legacy product.
- PAYMENT_ABUSEReturn Decisions associated with the Payment Abuse product.
- ACCOUNT_ABUSEReturn Decisions associated with the Account Abuse product.
- CONTENT_ABUSEReturn Decisions associated with the Content Abuse product.
- PROMO_ABUSEReturn Decisions associated with the Promotion Abuse product.
- categoryString
Roughly categorizes the type of business action that this Decision represents. For example, if the Decision was named "Cancel Order" and every time this Decision was applied your application was configured to cancel the user’s order, this should be categorized as a
BLOCK
Decision.Possible Values
- ACCEPTAccept entity
- WATCHWatch entity
- BLOCKBlock entity
- webhook_urlString
URL configured as webhook for this Decision. This is an optional field, only necessary if you are receiving Webhooks. When a Decision with a webhook is applied via API, no webhook notification will be sent.
- created_atinteger
Time at which the Decision was created, as a UNIX timestamp in milliseconds.
- created_byString
User who created decision.
- updated_atinteger
Time at which the Decision was last updated, as a UNIX timestamp in milliseconds.
- updated_byString
User who last updated the Decision.
- has_moreboolean
For result sets that span multiple requests, the
has_more
field indicates whether more results may be retrieved. Used in conjunction withnext_ref
to paginate result sets. - next_refboolean
For paginated results,
next_ref
contains a URL where the next set of results can be retrieved
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'.
Look for the request header: 'X-Sift-Science-Signature'
import json from hashlib import sha1 import hmac from flask import request SIFT_WEBHOOK_SECRET_KEY = "#####" @app.route("/webhook") def webhook(): # Let's check whether this webhook actually came from Sift! # First let's grab the signature from the postback's headers postback_signature = request.get("X-Sift-Science-Signature") # Next, let's try to assemble the signature on our side to verify postback_body = json.dumps(request.json) h = hmac.new(SIFT_WEBHOOK_SECRET_KEY, postback_body, sha1) verification_signature = "sha1={}".format(h.hexdigest()) if verification_signature == postback_signature: process_webhook() else: raise SomeException()
require 'json' require 'openssl' require 'sinatra' SIFT_WEBHOOK_SECRET_KEY = "#####" post '/webhook' do # Let's check whether this webhook actually came from Sift! # First let's grab the signature from the postback's headers postback_signature = request.env['X-Sift-Science-Signature'] # Next, let's try to assemble the signature on our side to verify digest = OpenSSL::Digest.new('sha1') calculated_hmac = OpenSSL::HMAC.hexdigest(digest, SIFT_WEBHOOK_SECRET_KEY, request.body) verification_signature = "sha1=#{calculated_hmac}" if verification_signature == postback_signature puts "success" else raise Exception end end
SIFT_WEBHOOK_SECRET_KEY = "#####"; BLOCK_ACTION = 'block'; #name of the Action you set up in the console # Let's check whether this webhook actually came from Sift! # First let's grab the signature from the postback's headers $webhookSignature = $headers['X-Sift-Science-Signature']; # Next, let's try to assemble the signature on our side to verify $verificationSignature = "sha1=" . hash_hmac('sha1', $requestBody, $SIFT_WEBHOOK_SECRET_KEY); if ($webhookSignature == $verificationSignature) { $siftRequest = json_decode($requestBody); if ($siftRequest->action->id == BLOCK_ACTION) { ... } }
import org.apache.commons.codec.digest.HmacUtils; String SIFT_WEBHOOK_SECRET_KEY = "#####"; // Get the "X-Sift-Science-Signature" request header. String webhookSignature = requestHeaders.get("X-Sift-Science-Signature"); String verificationSignature = "sha1=" + HmacUtils.hmacSha1Hex( SIFT_WEBHOOK_SECRET_KEY.getBytes(), requestBody); if (!webhookSignature.equals(verificationSignature)) { // Handle unauthenticated webhook }
Decision Status
The Decision Status API allows you to query the latest Decision for an entity. Sift returns the latest Decision status for each abuse type so that you have a full view of the entity.
curl -XGET https://api.sift.com/v3/accounts/{accountId}/{users}/{userId}/decisions # or curl -XGET https://api.sift.com/v3/accounts/{accountId}/orders/{orderId}/decisions # or curl -XGET https://api.sift.com/v3/accounts/{accountId}/users/{userId}/sessions/{sessionId}/decisions -H 'Content-Type: application/json' \ -u {YOUR_API_KEY}:
import sift client = sift.Client(api_key='{YOUR_API_KEY}', account_id='{accountId}') response = client.get_user_decisions('the_user_id') # or response = client.get_order_decisions('the_order_id')
require 'sift' client = Sift::Client.new(:api_key = > '{YOUR_API_KEY}', :account_id => '{accountId}') response = client.get_user_decisions('the_user_id') # or response = client.get_order_decisions('the_order_id')
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => '{YOUR_API_KEY}', 'account_id' => '{accountId}')); $response = $client->getUserDecisions('the_user_id'); // or $response = $client->getOrderDecisions('the_order_id');
import com.siftscience.SiftClient; import com.siftscience.DecisionStatusResponse; import com.siftscience.DecisionStatusRequest; import com.siftscience.model.DecisionStatusFieldSet; SiftClient client = new SiftClient("YOUR_API_KEY"); DecisionStatusRequest request; request = client.buildRequest(new DecisionStatusFieldSet() .setAccountId("4e1a50e172beb95cf1e4ae54") .setEntity(DecisionStatusFieldSet.ENTITY_ORDERS) .setEntityId("the_order_id")); // or request = client.buildRequest(new DecisionStatusFieldSet() .setAccountId("4e1a50e172beb95cf1e4ae54") .setEntity(DecisionStatusFieldSet.ENTITY_USERS) .setEntityId("the_user_id")); DecisionStatusResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); } Map<String, LatestDecision> decisionStatuses = response.getDecisionStatuses();
Be sure to replace {accountId}
with your Sift account ID, found on the
Profile Tab on the Console. Also, make sure to pick an
entity, either users
or orders
or sessions
to fill in the id of the entity. Lastly, replace
{YOUR_API_KEY}
with your REST API key, found in the
API Keys tab of the Developer
page in the Console. You will receive a response in the following format:
Response
{ "decisions": { "payment_abuse": { "decision": { "id": "block_user_payment_abuse" }, "time": 1461963439151, "webhook_succeeded": true }, "promo_abuse": { "decision": { "id": "reject_promo_promo_abuse" }, "time": 1461963431151, "webhook_succeeded": true }, "content_abuse": { "decision": { "id": "block_post_content_abuse" }, "time": 1461963429151, "webhook_succeeded": true }, "account_abuse": { "decision": { "id": "ban_account_account_abuse" }, "time": 1461963839151, "webhook_succeeded": true } "legacy": { "decision": { "id": "block_user_legacy" }, "time": 1461966439151, "webhook_succeeded": false } } }
Response Fields
- decisionsObject
A map of abuse types to the associated latest Decisions for the entity.
Possible Key Values
- payment_abuseThe associated JSON object is the latest Decision for the Payment Abuse abuse type.
- promo_abuseThe associated JSON object is the latest Decision for the Promo Abuse abuse type.
- content_abuseThe associated JSON object is the latest Decision for the Content Abuse abuse type.
- account_abuseThe associated JSON object is the latest Decision for the Account Abuse abuse type.
- legacyThe associated JSON object is the latest Decision for the Legacy abuse type.
- account_takeoverThe associated JSON object is the latest Decision for the Account Takeover abuse type.
Note:If a latest Decision does not exist for a particular abuse type, that key and associated JSON object will not exist in this response.
- latest decision objectObject
The information associated with the latest Decision for a specific abuse type key (read above).
- decisionObject
The Decision object containing information on the Decision taken.
- idString
The unique identifier of the Decision that was taken. This is generated by taking the first display name provided for the Decision, replacing spaces with hyphens, and concatenating it with the fraud type for which this Decision is configured.
Note: You cannot have two Decisions with the same initial display name for any given fraud type.
- timeLong
The time the Decision was applied, as a UNIX timestamp.
- webhook_succeededBoolean
true
if the webhook was successfully sent,false
if the webhook failed to send,null
if no webhook is configured.
Workflows API Overview
The Workflow APIs allow you to consume the output/query the status of a Workflow you've configured in the Sift Console. If you still need to create Workflows, please read our Creating a Workflow tutorial, which will walk you through the process of creating Workflows and attaching Decisions/Review Queues to them. There are two ways for you to query and consume Workflow output:
- Synchronously when you send Sift any REST API event using the
return_workflow_status
URL parameter. This is best for when you need to know the output of the Workflow immediately after the triggering event occurs to make a time sensitive decision. - Asynchronously using the Workflow Status API. This is best for when you want to query a Workflow after the triggering event has passed. A common use case is for reporting needs.
Automated Decisions
There are two ways to consume an automated decision:
- Synchronously retrieve the Workflow's output when you send the triggering event.
- Use Decision Webhooks to consume the workflow's output.
Synchronous
If you want to consume the automated Decision synchronously, you simply need to add return_workflow_status=true
to the URL parameters when you are sending Sift a Reserved or Custom event. You can also request scores for specific abuse types using the abuse_types
query parameter.
Request
curl -X POST "https://api.sift.com/v204/events?return_workflow_status=true&abuse_types=legacy" -H "Accept: application/json" -d '{ "$api_key": "YOUR_API_KEY", "$type": "$create_order", "$user_id": "test_user" }'
import sift client = sift.Client('YOUR_API_KEY') properties = { '$user_id' : 'test_user', '$user_email' : 'sample_user@gmail.com' } response = client.track('$create_order', properties, return_workflow_status=True, abuse_types=['promo_abuse', 'content_abuse', 'payment_abuse'])
require 'sift' client = Sift::Client.new(:api_key => 'YOUR_API_KEY') properties = { '$user_id' => 'sample_user', '$user_email' => 'sample_user@gmail.com' } response = client.track('$create_order', properties, :return_workflow_status => true, :abuse_types => ['promo_abuse', 'payment_abuse'])
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); $properties = array( '$user_id' => 'sample_user51', '$user_email' => 'sample_user@gmail.com' ); $opts = array( 'return_workflow_status' => True, 'abuse_types' => array( 'promo_abuse', 'payment_abuse' ) )); $response = $client->track('$create_order', $properties, $opts);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.EventResponse; import com.siftscience.exception.SiftException; import com.siftscience.model.CreateOrderFieldSet; SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest( new CreateOrderFieldSet() .setUserId("sample_user51") .setUserEmail("sample_user@gmail.com")) .withWorkflowStatus() .withScores("promo_abuse", "payment_abuse"); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; }
If you are an existing customer who has not yet upgraded to our abuse-specific scores, you will need to set abuse_types
to legacy
to get a score.
Response
{ "http_status_code": 200 "body": { "status": 0, "error_message": "OK", "request": "body_of_the_request_you_sent", "time": 1454517138, "score_response": { "status": 0, "error_message": "OK", "user_id": "billy_jones_301", "scores": { "payment_abuse": { "score": 0.898391231245, "reasons": [ { "name": "UsersPerDevice", "value": 4, "details": { "users": "a, b, c, d" } } ] }, "promotion_abuse": { "score": 0.472838192111, "reasons": [] }, }, "latest_labels": { "payment_abuse": { "is_fraud": true, "time": 1352201880, "description": "received a chargeback" }, "promotion_abuse": { "is_fraud": false, "time": 1362205000 } }, "workflow_statuses": [ { "id": "6dbq76qbaaaaa", "state": "running", "config": { "id": "pv3u5hyaaa", "version": "1468013109122" }, "config_display_name": "my create order flow", "abuse_types": ["payment_abuse", "legacy"], "entity": { "type": "user", "id": "test" }, "history": [ { "app": "decision", "name": "ban user", "state": "running", "config": { "decision_id": "ban-user-payment-abuse" } }, { "app": "review_queue", "name": "risky user queue", "state": "finished" "config": { "buttons": [ { "id": "ban-user-payment-abuse", "name": "Ban User" }, { "id": "suspend-user-payment-abuse", "name": "Ban User" }, { "id": "accept-user-payment-abuse", "name": "Ban User" } ] } }, { "app": "user_scorer", "name": "Entity", "state": "finished" }, { "app": "event_processor", "name": "Event", "state": "finished" } ] } ] } } }
Response Fields
- http_status_codeInteger
The HTTP status code of this Events API
- bodyObject
The body of the response.
- statusInteger
The success or error code (see relevant error codes below).
- error_messageString
Description of error or success.
- requestString
The content of the event you sent.
- timeInteger
The time the request was processed.
- score_responseObject
The requested scoring information for the given user.
- statusInteger
The status of the requested re-scoring and Formula check this event initiated.
- error_messageString
Description of error or success.
- user_idString
The id of the user, matching what was passed in the Events API call.
- scoresMap
The
scores
map contains all computed scores for all applicable abuse types for a given user. The map is keyed by abuse type, which could be one of:payment_abuse
,account_abuse
,content_abuse
,promotion_abuse
. The values in this map are objects which contain the following fields: - scoreFloat
Score for the user between 0.0 and 1.0. A score of 0.5 translates to a score a 50 in the console.
- reasonsArray
A list of the most significant reasons for the score and the values associated with the user. The included values will vary based on the user. Includes related users in the
details
object when applicable. - nameString
Name of the risk signal.
- valueString
Value of the risk signal.
- detailsObject
Additional details. Provided only when relevant. E.g., may contain a
details
field which contains the IDs of related users. - latest_labelsMap
NOTE: Latest Labels section is only intended for customers using the Labels API.
The
latest_labels
map contains entries for all abuse types for which the given user has been labeled. Note that the content of this map is not subject to the abuse types specified in the request; we always include all labels that have been applied to the given user. The map is keyed by abuse type, which could be one of:payment_abuse
,account_abuse
,content_abuse
,promotion_abuse
. The values in this map are objects which contain the following fields: - is_fraudBoolean
true
if the user is labeled Fraud,false
if the user is labeled Not Fraud. - timeLong
The time this label was applied to the user. It is a UNIX timestamp in seconds.
- descriptionString
Freeform text description of the user and/or incident triggering the label.
- workflow_statuses[Object]
A list of objects containing the responses of any Workflows that were triggered by this event. There will be one list item per Workflow triggered.
- idString
The run ID of this Workflow, identifying this specific instance of the Workflow. Use this with theWorkflow Status API to query the status of a Workflow run directly.
- stateString
The state of this Workflow instance.
Possible Values
- runningThis Workflow instance is still running, either because it is still sending the webhook or the user/order was put into a manual review queue
- finishedThis Workflow instance is finished running and there is a Decision associated with it in the history section discussed below
- failedThis Workflow instance has failed to run.
- configObject
An object containing the configuration information for this Workflow.
- idString
The configuration ID of the Workflow. This is the unique identifier of this Workflow, but not this Workflow instance.
- versionString
The version of this Workflow.
- config_display_nameString
The display name given to this Workflow in the Workflow editor.
- abuse_types[String]
A list of abuse types configured in this workflow
Possible Values
- payment_abuseThis Workflow is configured to give Decisions on the Payment Abuse abuse type.
- promo_abuseThis Workflow is configured to give Decisions on the Promo Abuse abuse type.
- content_abuseThis Workflow is configured to give Decisions on the Content Abuse abuse type.
- account_abuseThis Workflow is configured to give Decisions on the Account Abuse abuse type.
- legacyThis Workflow is configured to give Decisions on the Legacy abuse type.
- entityObject
The entity object containing information on the entity on which the Decision was taken.
- typeString
The type of entity on which the Decision was taken.
Possible Values
- userThis entity is a user and so the following
id
field will be a$user_id
- orderThis entity is an order and so the following
id
field will be an$order_id
- idString
The unique identifier of the entity on which the Decision was taken.
- history[Object]
A list of object containing information on each app that was run in chronological order. The first item in the list is the most recent app to run.
Note: The first 2 apps that ran ('event_processor' and 'user_scorer'/'order_scorer') are run on every Workflow and are not associated with any configured Routes.
- appString
The type of app which was run.
Possible Values
- decisionThis is a Decision app, and is the result of either an automated Decision or a Decision from a manual review queue
- review_queueThis is a Manual Review Queue app, and indicates that the user/order went to a Manual Review Queue.
- user_scorerThis is a scoring app, specific to the user entity. This is a static app and always appears on Workflows triggered for the user entity.
- order_scorerThis is a scoring app, specific to the order entity. This is a static app and always appears on Workflows triggered for the order entity.
- event_processorThis is an event processing app. This is a static app and appears on every Workflow.
- nameString
The display name of the app which was run.
- stateString
The state of this app.
Possible Values
- runningThis app is still running, either because it is still sending a Decision webhook or the user/order is still in a manual review queue
- finishedThis app is finished running.
- failedThis app has failed to run.
- configObject
The configuration information of the app.
- decision_idString
The unique identifier of the Decision taken in this app.
Note: This field only exists if the value for
app
isdecision
- buttons[Object]
A list of button objects associated with this Manual Review Queue.
Note: This field only exists if the value for
app
isreview_queue
- idString
The unique Decision ID for this button.
- nameString
The display name for this button.
Error Codes
-4
Service currently unavailable. Please try again later.
-3
Server-side timeout processing request. Please try again later.
-2
Unexpected server-side error
-1
Unexpected server-side error
0
OK
51
Invalid API key
54
60
Rate limited; too many events have been received in a short period of time
Webhooks
If you wish to use webhooks to consume the Workflow's output, please see the Decision Webhooks documentation.
Decisions From Review Queues
When a user/order arrives in a Review Queue, which you can verify by looking at the first item in the history section of the Workflow Status, someone on your review team will take a look and make a Decision by choosing one of the available Decision Buttons in the queue. There are two available methods to capture and act on these Decisions:
- Decision Webhooks
- The Decision Status API
The Webhooks will push a notification to you when a Decision is made, while the Decision Status API allows you to query the latest Decisions on a user/order at any time. Choose the method that best fits your workflow.
Workflow Status
The Workflow Status API allows you to query the status of a specific instance of a Workflow. In order to use this API you need the instance's Run ID. You can get this by using the Synchronous Workflow Status API when you send the triggering event for the Workflow. This API is useful for gathering information on previously executed Workflows.
To use this API, make the following request:
Request
curl -XGET https://api.sift.com/v3/accounts/{accountId}/workflows/runs/{workflow_run_id} -H "Accept: application/json" \ -u {YOUR_API_KEY}:
import sift client = sift.Client(api_key='{YOUR_API_KEY}', account_id='{accountId}') workflow_run_id = '123' # obtained in response of 'return_workflow_status=true' call response = client.get_workflow_status(workflow_run_id)
require 'sift' client = Sift::Client.new(:api_key = > '{YOUR_API_KEY}', :account_id => '{accountId}') workflow_run_id = '123' # obtained in response of 'return_workflow_status=true' call response = client.get_workflow_status(workflow_run_id)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => '{YOUR_API_KEY}', 'account_id' => '{accountId}')); $workflow_run_id = '123' // obtained in response of 'return_workflow_status=True' call $response = $client->getWorkflowStatus($workflow_run_id);
import com.siftscience.SiftClient; import com.siftscience.WorkflowStatusResponse; import com.siftscience.WorkflowStatusRequest; import com.siftscience.model.WorkflowStatusFieldSet; SiftClient client = new SiftClient("YOUR_API_KEY"); WorkflowStatusRequest request = client.buildRequest(new WorkflowStatusFieldSet() .setWorkflowRunId("avm4jezvb4aaa") .setAccountId("4e1a50e172beb95cf1e4ae54")); WorkflowStatusResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.getBody().getState(); // "running", "finished", or "failed"
Be sure to replace {accountId}
with your Sift account ID, found on the Profile Tab on the Console. Also,
make sure to replace {workflow_run_id}
with the Workflow Run ID. Lastly, replace {YOUR_API_KEY}
with your REST API key, found on the API Keys tab of the Developer page on the Console. You will receive a response in the following format:
Response
{ "id": "6dbq76qbaaaaa", "state": "running", "config": { "id": "pv3u5hyaaa", "version": "1468013109122" }, "config_display_name": "my create order flow", "abuse_types": ["payment_abuse", "legacy"], "entity": { "type": "user", "id": ""dracula@vampires.com"" }, "history": [ { "app": "decision", "name": "ban user", "state": "running", "config": { "decision_id": "ban-user-payment-abuse" } }, { "app": "review_queue", "name": "risky user queue", "state": "finished", "config": { "buttons": [ { "id": "ban-user-payment-abuse", "name": "Ban User" }, { "id": "suspend-user-payment-abuse", "name": "Ban User" }, { "id": "accept-user-payment-abuse", "name": "Ban User" } ] } }, { "app": "user_scorer", // name TBD "name": "Entity", "state": "finished", }, { "app": "event_processor", // name TBD "name": "Event", "state": "finished", } ] }
Response Fields
- idString
The run ID of this Workflow, identifying this specific instance of the Workflow.
- stateString
The state of this Workflow instance.
Possible Values
- runningThis Workflow instance is still running, either because it is still sending the webhook or the user/order was put into a manual review queue
- finishedThis Workflow instance is finished running and there is a Decision associated with it in the history section discussed below
- failedThis Workflow instance has failed to run.
- configObject
An object containing the configuration information for this Workflow.
- idString
The configuration ID of the Workflow. This is the unique identifier of this Workflow, but not this Workflow instance.
- versionString
The version of this Workflow.
- config_display_nameString
The display name given to this Workflow in the Workflow editor.
- abuse_types[String]
A list of abuse types configured in this workflow
Possible Values
- payment_abuseThis Workflow is configured to give Decisions on the Payment Abuse abuse type.
- promo_abuseThis Workflow is configured to give Decisions on the Promo Abuse abuse type.
- content_abuseThis Workflow is configured to give Decisions on the Content Abuse abuse type.
- account_abuseThis Workflow is configured to give Decisions on the Account Abuse abuse type.
- legacyThis Workflow is configured to give Decisions on the Legacy abuse type.
- entityObject
The entity object containing information on the entity on which the Decision was taken.
- typeString
The type of entity on which the Decision was taken.
Possible Values
- userThis entity is a user and so the following
id
field will be a$user_id
- orderThis entity is an order and so the following
id
field will be an$order_id
- idString
The unique identifier of the entity on which the Decision was taken.
- history[Object]
A list of object containing information on each app that was run in chronological order. The first item in the list is the most recent app to run.
Note: The first 2 apps that ran ('event_processor' and 'user_scorer'/'order_scorer') are run on every Workflow and are not associated with any configured Routes.
- appString
The type of app which was run.
Possible Values
- decisionThis is a Decision app, and is the result of either an automated Decision or a Decision from a manual review queue
- review_queueThis is a Manual Review Queue app, and indicates that the user/order went to a Manual Review Queue.
- user_scorerThis is a scoring app, specific to the user entity. This is a static app and always appears on Workflows triggered for the user entity.
- order_scorerThis is a scoring app, specific to the order entity. This is a static app and always appears on Workflows triggered for the order entity.
- event_processorThis is an event processing app. This is a static app and appears on every Workflow.
- nameString
The display name of the app which was run.
- stateString
The state of this app.
Possible Values
- runningThis app is still running, either because it is still sending a Decision webhook or the user/order is still in a manual review queue
- finishedThis app is finished running.
- failedThis app has failed to run.
- configObject
The configuration information of the app.
- decision_idString
The unique identifier of the Decision taken in this app.
Note: This field only exists if the value for
app
isdecision
- buttons[Object]
A list of button objects associated with this Manual Review Queue.
Note: This field only exists if the value for
app
isreview_queue
- idString
The unique Decision ID for this button.
- nameString
The display name for this button.
Formulas and Actions API
NOTE: As of July, 2016 Formulas and Actions are a legacy option for automating fraud decisions with Sift. If you are a Sift customer that is already using Formulas, they will continue working as expected, but we encourage you to check out our new suite of automation tools - Workflows!
For more information on integrating Formulas and Actions, view the tutorial.
- 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
. - Action Webhooks are the best way to get updates about a change to a user's risk score or other state outside of your key event where you make an automated decision.
Synchronous Actions
Synchronous Actions are the best way to make a decision at your key decision point, such as $create_order
, $create_content
, or $create_account
. Once you choose the event to make your Synchronous Action call on, simply append the
'?return_action=true' to our Events API url or use one of our client libraries as shown below.
Synchronous Action calls will return each user's risk score. You can enhance them to include any actions that should be taken on the user, order, or posting, such as block
or review
. Your fraud team can set up and configure actions in the console. Formulas and actions can be adjusted in the console at anytime without
the need for developer resources. For an overview of creating Actions to enhance Synchronous Action calls, see our tutorial.
curl -X POST https://api.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
- statusInteger
The success or error code (see relevant error codes below).
- error_messageString
Description of error or success.
- requestString
The content of the event you sent.
- timeInteger
The time the request was processed.
- score_responseObject
The id of the user, matching what was passed in the Score API call.
- statusInteger
The status of the requested re-scoring and Formula check this event initiated.
- error_messageString
Description of error or success.
- user_idString
The id of the user, matching what was passed in the Events API call.
- latest_labelObject
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_fraudBoolean
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.
- timeInteger
The time the most recent label was applied to the user, as UNIX timestamp.
- scoreFloat
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.
- nameString
Name of the risk signal.
- valueString
The value for the risk signal.
- detailsObject (optional)
Additional details. Provided only when relevant.
- usersString
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.
- idString
Our unique id for this particular application of the action to this user. Used to reference our internal logs if needed.
- actionString
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.
- entityString
Contains the id of the entity the action was applied to (the user_id passed in the Score API call).
- timeLong
The time the action was applied, as UNIX timestamp.
- triggersString
A list of what triggered the application of this action to the user. For example, two Formulas and their ids.
Error Codes
Send your events with a $time field in milliseconds and resend on a 60 or a negative error code value in either status field.
-1
Unexpected server-side error
-2
Unexpected server-side error
-3
Server-side timeout processing request. Please try again later.
-4
Service currently unavailable. Please try again later.
0
OK
51
Invalid API key
60
Rate limited; too many events have been received in a short period of time. Note: make sure to check the status of the 'score_response' field for this error as well.
Action webhooks
Action webhooks are the best way to get updates about a change to the risk of a user outside of your key event where you must make an instant decision. Using Action webhooks requires setting up Actions and Formulas to trigger them in your console. For an overview, see our Formulas and Actions tutorial.
See Action Webhooks Authentication for instructions on how to verify the requests you are receiving are coming from Sift.
{ id: "3ff1082a4aea8d0c58e3643ddb7a5bb87ffffeb2492dca33", action: { id: "test", href: "https://sift.com/v3/accounts/5265ac265f5ce205a2bdc80f/actions/test" }, entity: { id: "example_order", href: "https://sift.com/v3/accounts/5265ac265f5ce205a2bdc80f/orders/example_order" }, time: 1454526160387, triggers: [ { type: "formula", source: "formula_service", trigger: { id: "556e4a1de4b04ed910169adb", href: "https://sift.com/v3/accounts/5265ac265f5ce205a2bdc80f/formulas/556e4a1de4b04ed910169adb" } } ] }
Request
- idString
Our unique id for this particular application of the action to this user. Used to reference our internal logs if needed.
- actionObject
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.
- entityObject
Contains the id of the entity the action was applied to (the user_id passed in the Score API call).
- timeLong
The time the action was applied, as UNIX timestamp.
- triggers[Object]
A list of what triggered the application of this action to the user. For example, two Formulas and their ids.
Authentication
Take advantage of webhook authentication to ensure that the request you receive is coming from Sift.
Notes:
- There can only be one active webhook key per account.
- Generate your key on the Production API Keys page of your console.
- The Production key is used for your Sandbox account.
- The Signature will appear as the value for the HTTP header 'X-Sift-Science-Signature', which will arrive in the request. This header does not appear when you initially set up webhooks for Actions in the console.
Look for the request header: 'X-Sift-Science-Signature'
import json from hashlib import sha1 import hmac from flask import request SIFT_WEBHOOK_SECRET_KEY = "#####" @app.route("/webhook") def webhook(): # Let's check whether this webhook actually came from Sift! # First let's grab the signature from the postback's headers postback_signature = request.get("X-Sift-Science-Signature") # Next, let's try to assemble the signature on our side to verify postback_body = json.dumps(request.json) h = hmac.new(SIFT_WEBHOOK_SECRET_KEY, postback_body, sha1) verification_signature = "sha1={}".format(h.hexdigest()) if verification_signature == postback_signature: process_webhook() else: raise SomeException()
require 'json' require 'openssl' require 'sinatra' SIFT_WEBHOOK_SECRET_KEY = "#####" post '/webhook' do # Let's check whether this webhook actually came from Sift! # First let's grab the signature from the postback's headers postback_signature = request.env['X-Sift-Science-Signature'] # Next, let's try to assemble the signature on our side to verify digest = OpenSSL::Digest.new('sha1') calculated_hmac = OpenSSL::HMAC.hexdigest(digest, SIFT_WEBHOOK_SECRET_KEY, request.body) verification_signature = "sha1=#{calculated_hmac}" if verification_signature == postback_signature puts "success" else raise Exception end end
SIFT_WEBHOOK_SECRET_KEY = "#####"; BLOCK_ACTION = 'block'; #name of the Action you set up in the console # Let's check whether this webhook actually came from Sift! # First let's grab the signature from the postback's headers $webhookSignature = $headers['X-Sift-Science-Signature']; # Next, let's try to assemble the signature on our side to verify $verificationSignature = "sha1=" . hash_hmac('sha1', $requestBody, $SIFT_WEBHOOK_SECRET_KEY); if ($webhookSignature == $verificationSignature) { $siftRequest = json_decode($requestBody); if ($siftRequest->action->id == BLOCK_ACTION) { ... } }
Score API Overview
The Sift APIs give you multiple ways to get a risk score for any of your users. A risk score is a measure of how likely a user is to commit abuse using your service. Scores are computed in real time from the data sent via the Events API and the Sift Javascript snippet.
Sift calculates risk scores for four types of abuse:
- Payment Abuse - A user fraudulently using a credit card or other payment method.
- Content Abuse - A user creating content (e.g. spammy/scammy posts) or sending messages on your site in an abusive manner.
- Promotion Abuse - A user gaming the terms of a promotion in an excessive or abusive way.
- Account Abuse - A user using your service in a manner you deem abusive (e.g. fake accounts).
You can get one or more of these abuse scores at a time. We will calculate scores for any of the abuse detection products you’ve enabled. Here is the pricing for our abuse prevention products.
There are three different ways to get scores from Sift:
- Get a score synchronously when you send an event (most common)
- Get a score and workflows status synchronously when you send an event
- Get a score at a point in time without sending an event
Getting risk scores synchronously when sending events
Whenever you send an event, you can receive a Sift Score back synchronously in the response back from the API. This is particularly useful for when you are sending an event that maps to a key decision point for your business. Typically, customers find it most useful to get scores back after creating an account, order, content, or adding a promotion, but you can get scores back after passing any of the events we support.
For events that you don't plan on using the score, it’s best that you don’t ask for the score as it will add some latency to the request.
To get scores back when sending an event, just append the query parameter return_score=true
to your API request. You can also request scores for specific abuse types using the abuse_types
query parameter.
curl -X POST "https://api.sift.com/v204/events?return_score=true&abuse_types=payment_abuse,promotion_abuse" -H "Accept: application/json" -d '{ "$type" : "$create_order", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", "$session_id" : "gigtleqddo84l8cm15qe4il", "$order_id" : "ORDER-28168441", "$user_email" : "bill@gmail.com", "$amount" : 115940000, // $115.94 "$currency_code" : "USD" }'
import sift client = sift.Client("YOUR_API_KEY") # define event_properties here response = client.track("$create_order", event_properties, return_score=True, abuse_types=['payment_abuse', 'promotion_abuse'])
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # define event_properties here response = client.track("$create_order", event_properties, :return_score => true, :abuse_types => ["payment_abuse", "promotion_abuse"])
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // define event_properties here $response = $client->track('$create_order', $properties, array('return_score' => true, 'abuse_types' => array('payment_abuse', 'promotion_abuse')));
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.EventResponse; import com.siftscience.exception.SiftException; SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(fieldSet).withScores(); // or with specific abuse types request = client.buildRequest(fieldSet) .withScores("payment_abuse", "promotion_abuse"); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; }
If you are an existing customer who has not yet upgraded to our abuse-specific scores, you will need to set abuse_types
to legacy
to get a score.
Response
HTTP/1.1 200 OK Content-Type: text/json;charset=UTF-8 Connection: keep-alive { "body": { "status": 0, "error_message": "OK", "request": "body_of_the_request_you_sent", "time": 1454517138, "score_response": { "status": 0, "error_message": "OK", "user_id": "billy_jones_301", "scores": { "payment_abuse": { "score": 0.898391231245, "reasons": [ { "name": "UsersPerDevice", "value": 4, "details": { "users": "a, b, c, d" } } ] }, "promotion_abuse": { "score": 0.472838192111, "reasons": [] }, }, "latest_labels": { "payment_abuse": { "is_fraud": true, "time": 1352201880, "description": "received a chargeback" }, "promotion_abuse": { "is_fraud": false, "time": 1362205000 } } } } "http_status_code": 200 }
response.is_ok() # false on failed score requests. response.http_status_code # 200 on successful score requests. response.api_status # see error codes and messages below response.api_error_message # check for a label for a specific abuse type bad_user = response.body['latest_labels']['payment_abuse']['is_fraud'] if 'latest_labels' in response.body else None # get Sift Score for a specific abuse type payment_abuse_score = round((response.body['scores']['payment_abuse']['score'] * 100), 1)
response.ok?() # false on failed score requests. response.http_status_code # 200 on successful score requests. response.api_status # see error codes and messages below response.api_error_message # check for a label for a specific abuse type bad_user = response.body.has_key?('latest_labels') ? response.body['latest_labels']['payment_abuse']['is_fraud'] : nil # get Sift Score for a specific abuse type payment_abuse_score = (response.body['scores']['payment_abuse']['score'] * 100).round(1)
response->isOk() # false on failed score requests. response->httpStatusCode # 200 on successful score requests. response->apiStatus # see error codes and messages below response->apiErrorMessage # To grab the payment_abuse score: $siftScore = round(($response->body['scores']['payment_abuse']['score'] * 100, 1);
import com.siftscience.model.Reason; response.isOk(); // false on failed score requests. response.getHttpStatusCode(); // 200 on successful score requests. response.getApiStatus(); // see error codes and messages below response.getApiErrorMessage(); // check for a label for a specific abuse type response.getBody().getScoreResponse().getLatestLabels().get("payment_abuse"); // get Sift Score for a specific abuse type Long paymentAbuseScore = Math.round(response.getScore("payment_abuse") * 100); // get reasons for a Sift Score List<Reason> reasons = response.getReasons("payment_abuse");
Response Fields
- statusInteger
The success or error code (see relevant error codes below).
- error_messageString
Description of status code.
- requestString
The content of the event you sent.
- timeInteger
The time the request was processed, in seconds since epoch.
- score_responseObject
The requested scoring information for the given user.
- statusInteger
The success or error code (see relevant error codes below).
- error_messageString
Description of error if applicable.
- scoresMap
The
scores
map contains all computed scores for all applicable abuse types for a given user. The map is keyed by abuse type, which could be one of:payment_abuse
,account_abuse
,content_abuse
,promotion_abuse
,account_takeover
. The values in this map are objects which contain the following fields: - scoreFloat
Score for the user between 0.0 and 1.0. A score of 0.5 translates to a score a 50 in the console.
- reasonsArray
A list of the most significant reasons for the score and the values associated with the user. The included values will vary based on the user. Includes related users in the
details
object when applicable. - nameString
Name of the risk signal.
- valueString
Value of the risk signal.
- detailsObject
Additional details. Provided only when relevant. E.g., may contain a
details
field which contains the IDs of related users. - user_idString
The id of the user, matching what was passed in the Score API call.
- latest_labelsMap
NOTE: Latest Labels section is only intended for customers using the Labels API.
The
latest_labels
map contains entries for all abuse types for which the given user has been labeled. Note that the content of this map is not subject to the abuse types specified in the request; we always include all labels that have been applied to the given user. The map is keyed by abuse type, which could be one of:payment_abuse
,account_abuse
,content_abuse
,promotion_abuse
. The values in this map are objects which contain the following fields: - is_fraudBoolean
true
if the user is labeled Fraud,false
if the user is labeled Not Fraud. - timeLong
The time this label was applied to the user. It is a UNIX timestamp in seconds.
- descriptionString
Freeform text description of the user and/or incident triggering the label.
Error Codes
-4
Service currently unavailable. Please try again later.
-3
Server-side timeout processing request. Please try again later.
-2
Unexpected server-side error
-1
Unexpected server-side error
0
OK
51
Invalid API key
54
60
Rate limited; too many events have been received in a short period of time
Score API Reference
The Score API is meant to get an up to date risk score when you don’t have new event data to pass. This is useful for when there is a time gap between when you send data for a user and are performing some action where you want to check risk and there is not a natural event to send at this point. Some examples of when you may want to check the score are before:
- Shipping out a package
- Finalizing a money transfer
- Giving access to a prearranged vacation rental
We do not recommend sending event data for a user and then very quickly attempting to get the score back with the Score API. If you need a score back quickly after an event, we can provide scores synchronously when events are sent. You can also synchronously get the status of a workflow and the score when you send an event.
Notes:
- You can only pull the score for
$user_id
values we've received Events API events or JavaScript activity for. - Use your Sandbox REST API key for accessing Sandbox users when testing. Switch to your Production API key for your live integration.
- Documentation for the previous version of the Score API can be found here.
Request all scores for a user:
curl -i "https://api.sift.com/v204/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(:api_key => "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(array('api_key' => 'YOUR_API_KEY')); $response = $client->score('USER_ID_HERE');
import com.siftscience.SiftClient; import com.siftscience.ScoreRequest; import com.siftscience.ScoreResponse; import com.siftscience.ScoreFieldSet; import com.siftscience.exception.SiftException; SiftClient client = new SiftClient("YOUR_API_KEY"); ScoreRequest request = client.buildRequest(new ScoreFieldSet() .setUserId("user_id_here")); ScoreResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; }
Request scores for specific abuse types using the abuse_types
query parameter:
curl -i "https://api.sift.com/v204/score/USER_ID_HERE/?api_key=YOUR_API_KEY&abuse_types=payment_abuse,promotion_abuse"
import sift client = sift.Client("YOUR_API_KEY") response = client.score("USER_ID_HERE", abuse_types=["payment_abuse", "promotion_abuse"])
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") response = client.score("USER_ID_HERE", :abuse_types => ["payment_abuse", "promotion_abuse"])
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); $response = $client->score('USER_ID_HERE', array('abuse_types' => array('payment_abuse', 'promotion_abuse')));
import com.siftscience.SiftClient; import com.siftscience.ScoreRequest; import com.siftscience.ScoreResponse; import com.siftscience.ScoreFieldSet; SiftClient client = new SiftClient("YOUR_API_KEY"); ScoreRequest request = client.buildRequest(new ScoreFieldSet() .setUserId("user_id_here") .setAbuseTypes(Arrays.asList("payment_abuse", "account_abuse"))); ScoreResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; }
Response
HTTP/1.1 200 OK Content-Type: text/json;charset=UTF-8 Connection: keep-alive { "status": 0, "error_message": "OK", "user_id": "billy_jones_301", "scores": { "payment_abuse": { "score": 0.898391231245, "reasons": [ { "name": "UsersPerDevice", "value": 4, "details": { "users": "a, b, c, d" } } ] }, "promotion_abuse": { "score": 0.472838192111, "reasons": [] }, }, "latest_labels": { "payment_abuse": { "is_fraud": true, "time": 1352201880, "description": "received a chargeback" }, "promotion_abuse": { "is_fraud": false, "time": 1362205000 } } }
response.is_ok() # false on failed score requests. response.http_status_code # 200 on successful score requests. response.api_status # see error codes and messages below response.api_error_message # check for a label for a specific abuse type bad_user = response.body['latest_labels']['payment_abuse']['is_fraud'] if 'latest_labels' in response.body else None # get Sift Score for a specific abuse type payment_abuse_score = round((response.body['scores']['payment_abuse']['score'] * 100), 1)
response.ok?() # false on failed score requests. response.http_status_code # 200 on successful score requests. response.api_status # see error codes and messages below response.api_error_message # check for a label for a specific abuse type bad_user = response.body.has_key?('latest_labels') ? response.body['latest_labels']['payment_abuse']['is_fraud'] : nil # get Sift Score for a specific abuse type payment_abuse_score = (response.body['scores']['payment_abuse']['score'] * 100).round(1)
response->isOk() # false on failed score requests. response->httpStatusCode # 200 on successful score requests. response->apiStatus # see error codes and messages below response->apiErrorMessage # To grab the payment_abuse score: $siftScore = round(($response->body['scores']['payment_abuse']['score'] * 100, 1);
response.isOk(); // false on failed score requests. response.getHttpStatusCode(); // 200 on successful score requests. response.getApiStatus(); // see error codes and messages below response.getApiErrorMessage(); // check for a label for a specific abuse type response.getBody().getLatestLabels().get("payment_abuse"); // get Sift Score for a specific abuse type Math.round(response.getScore("payment_abuse") * 100);
Response Fields
- statusInteger
The success or error code (see relevant error codes below).
- error_messageString
Description of error if applicable.
- scoresMap
The
scores
map contains all computed scores for all applicable abuse types for a given user. The map is keyed by abuse type, which could be one of:payment_abuse
,account_abuse
,content_abuse
,promotion_abuse
. The values in this map are objects which contain the following fields: - scoreFloat
Score for the user between 0.0 and 1.0. A score of 0.5 translates to a score a 50 in the console.
- reasonsArray
A list of the most significant reasons for the score and the values associated with the user. The included values will vary based on the user. Includes related users in the
details
object when applicable. - nameString
Name of the risk signal.
- valueString
Value of the risk signal.
- detailsObject
Additional details. Provided only when relevant. E.g., may contain a
details
field which contains the IDs of related users. - user_idString
The id of the user, matching what was passed in the Score API call.
- latest_labelsMap
NOTE: Latest Labels section is only intended for customers using the Labels API.
The
latest_labels
map contains entries for all abuse types for which the given user has been labeled. Note that the content of this map is not subject to the abuse types specified in the request; we always include all labels that have been applied to the given user. The map is keyed by abuse type, which could be one of:payment_abuse
,account_abuse
,content_abuse
,promotion_abuse
. The values in this map are objects which contain the following fields: - is_fraudBoolean
true
if the user is labeled Fraud,false
if the user is labeled Not Fraud. - timeLong
The time this label was applied to the user. It is a UNIX timestamp in seconds.
- descriptionString
Freeform text description of the user and/or incident triggering the label.
Error Codes
-4
Service currently unavailable. Please try again later.
-3
Server-side timeout processing request. Please try again later.
-2
Unexpected server-side error
-1
Unexpected server-side error
0
OK
51
Invalid API key
54
60
Rate limited; too many events have been received in a short period of time
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/529def32fe6b73f31300126e/devices/0ef840778p8q3j3jfs654q0vvk' \ -H 'Content-Type: application/json' \ -u {YOUR_API_KEY}:
Example Response
{ "id" : "0ef840778p8q3j3jfs654q0vvk", "label" : "fraud", "labeled_at" : 1241241214000, "first_seen" : 1412990802000, "users" : { "data" : [ { "id" : "bob123", "href" : "https://api.sift.com/v3/accounts/529def32fe6b73f31300126e/users/bob123" } ] }, "network" : { "first_seen" : 1412386033000, "score" : 0.8 }, "sessions" : { "has_more" : false, "total_results" : 1, "data" : [ { "time" : 1412990802000 } ] } }
Parameters
- accountIdrequired · string
Your Sift Account ID, which can be found in the Sift Console under the Developer Tab
- deviceIdrequired · string
Device Fingerprints are strings that are 26 characters in length, e.g. "0ef840778p8q3j3jfs654q0vvk"
Response
- idrequired · string
Device Fingerprints are strings that are 26 characters in length, e.g. '0ef840778p8q3j3jfs654q0vvk'
- first_seeninteger
The time (occurred POSIX time in milliseconds) when Sift first identified this device on your site
- usersobject
A list of references to external entities that this object is associated with
- datarequired · array
The list of data elements
- idrequired · string
id of the referenced resource
- has_moreboolean
True if there are more data elements available
- next_refstring
A link to the next set of data elements, if available
- total_resultsinteger
The total number of results, if known
- sessionsobject
A list of sessions in which this device has been seen
- datarequired · array
A list of data related to sessions in which this device has been seen
- timeinteger
The time at which this Session ID was first set in the Sift JavaScript snippet.
- has_moreboolean
True if there are more sessions available
- next_refstring
A link to the next set of sessions, if available
- total_resultsinteger
The total number of results, if known
- labelstring
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_atinteger
The time at which the latest label was applied to this device. If no label has been applied, this field is null
- networkobject
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_seeninteger
The time (occurred POSIX time in milliseconds) when Sift first identified this device within our network of customers.
- scorenumber
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.
- pervasivenessstring
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, when you find a user to be fraudulent, you should use this endpoint to flag the device the user originated from. You will prevent this device from interacting from your site using the /v3/accounts/{accountId}/session endpoint.
Example Request
$ curl -XPUT 'https://api.sift.com/v3/accounts/529def32fe6b73f31300126e/devices/0ef840778p8q3j3jfs654q0vvk/label' \ -H 'Content-Type: application/json' \ -u {YOUR_API_KEY}: \ -d '{ "label" : "fraud" }'
Example Response
{ "label" : "fraud" }
Parameters
- accountIdrequired · string
Your Sift Account ID, which can be found in the Sift Console under the Developer Tab
- deviceIdrequired · string
Device Fingerprints are strings that are 26 characters in length, e.g. "0ef840778p8q3j3jfs654q0vvk"
Entity
- labelstring
Allowed Values
- fruadThis device has exhibited behavior that is fraudulent or otherwise detrimental to your business
- not_fraudThis device is not fraudulent
Response
- labelstring
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/529def32fe6b73f31300126e/sessions/465733823' \ -H 'Content-Type: application/json' \ -u {YOUR_API_KEY}:
Example Response
{ "id" : 465733823, "time" : 1412990802000, "device" : { "id" : "0ef840778p8q3j3jfs654q0vvk", "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
- accountIdrequired · string
Your Sift Account ID, which can be found in the Sift Console under the Developer Tab
- sessionIdrequired · 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
- timeinteger
The time at which this Session ID was first set in the Sift JavaScript snippet.
- deviceobject
Data related to a Device Fingerprint
- idrequired · string
Device Fingerprints are strings that are 26 characters in length, e.g. '0ef840778p8q3j3jfs654q0vvk'
- first_seeninteger
The time (occurred POSIX time in milliseconds) when Sift first identified this device on your site
- usersobject
A list of references to external entities that this object is associated with
- datarequired · array
The list of data elements
- idrequired · string
id of the referenced resource
- has_moreboolean
True if there are more data elements available
- next_refstring
A link to the next set of data elements, if available
- total_resultsinteger
The total number of results, if known
- sessionsobject
A list of sessions in which this device has been seen
- datarequired · array
A list of data related to sessions in which this device has been seen
- timeinteger
The time at which this Session ID was first set in the Sift JavaScript snippet.
- has_moreboolean
True if there are more sessions available
- next_refstring
A link to the next set of sessions, if available
- total_resultsinteger
The total number of results, if known
- labelstring
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_atinteger
The time at which the latest label was applied to this device. If no label has been applied, this field is null
- networkobject
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_seeninteger
The time (occurred POSIX time in milliseconds) when Sift first identified this device within our network of customers.
- scorenumber
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.
- pervasivenessstring
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/529def32fe6b73f31300126e/users/465733823/devices' \ -H 'Content-Type: application/json' \ -u {YOUR_API_KEY}:
Example Response
{ "data" : [ { "id" : "0ef840778p8q3j3jfs654q0vvk", "href" : "https://api.sift.com/v3/accounts/529def32fe6b73f31300126e/devices/0ef840778p8q3j3jfs654q0vvk" }, { "id" : "043ef45323q33ks3kkd3q234df", "href" : "https://api.sift.com/v3/accounts/529def32fe6b73f31300126e/devices/043ef45323q33ks3kkd3q234df" } ] }
Parameters
- accountIdrequired · string
Your Sift Account ID, which can be found in the Sift Console under the Developer Tab
- userIdrequired · 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
- schemarequired · string
Reference to the json schema that the data in the array conforms to
- datarequired · array
A list of data items
- idrequired · string
id of the referenced resource
- has_moreboolean
Whether there are more results
- next_refstring
A link to the next set of data, if available
- total_resultsinteger
The total number of results, if known
Partner API Guide
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 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.
Account creation
POST /v3/partners/{id}/accounts
This endpoint allows you to create a new Sift account for one of your merchants. This will also create an associated analyst account.
Example Request
$ curl -XPOST 'https://api.sift.com/v3/partners/541752da89f0b8620624f17f/accounts' \ -H 'Content-Type: application/json' \ -u {YOUR_API_KEY}: \ -d '{ "site_url" : "merchant123.com", "site_email" : "owner@merchant123.com", "analyst_email" : "john.doe@merchant123.com", "password" : "s0mepA55word" }'
Example Response
{ "account_id" : "545d48e84d6963acf1000000", "production" : { "api_keys" : [ { "id" : "545d491c4d6963acf12d0000", "state" : "ACTIVE", "key" : "34fc67af86069804" } ], "beacon_keys" : [ { "id" : "545d491c4d6963acf12e0000", "state" : "ACTIVE", "key" : "735ea65235" } ] }, "sandbox" : { "api_keys" : [ { "id" : "545d491c4d6963acf1300000", "state" : "ACTIVE", "key" : "1f46f7f726607c1b" } ], "beacon_keys" : [ { "id" : "545d491c4d6963acf1310000", "state" : "ACTIVE", "key" : "63d0d7605c" } ] } }
Parameters
- idrequired · string
Your partner account id
Entity
- site_urlrequired · string
A URL for merchant's site
- site_emailrequired · string
An email for the merchant
- analyst_emailstring
An email to be used for as the username for the first analyst for this merchant.
- passwordstring
The initial password for the analyst account.
Response
- productionrequired · object
API keys for the production account
- api_keysarray
Keys used to access Sift's REST APIs
- idstring
Identifier for this API keys
- statestring
State of the API key. Only ACTIVE keys can make requests.
Allowed Values
- ACTIVEThis key is active, and may be used for API requests.
- DISABLEDThis key has been disabled, and will not be accepted unless reactivated.
- DELETED
- keystring
The actual key to be used for authenticated API requests
- beacon_keysarray
Keys used for the JavaScript integration
- idstring
Identifier for this API keys
- statestring
State of the API key. Only ACTIVE keys can make requests.
Allowed Values
- ACTIVEThis key is active, and may be used for API requests.
- DISABLEDThis key has been disabled, and will not be accepted unless reactivated.
- DELETED
- keystring
The actual key to be used for authenticated API requests
- sandboxrequired · object
API keys for the production account
- api_keysarray
Keys used to access Sift's REST APIs
- idstring
Identifier for this API keys
- statestring
State of the API key. Only ACTIVE keys can make requests.
Allowed Values
- ACTIVEThis key is active, and may be used for API requests.
- DISABLEDThis key has been disabled, and will not be accepted unless reactivated.
- DELETED
- keystring
The actual key to be used for authenticated API requests
- beacon_keysarray
Keys used for the JavaScript integration
- idstring
Identifier for this API keys
- statestring
State of the API key. Only ACTIVE keys can make requests.
Allowed Values
- ACTIVEThis key is active, and may be used for API requests.
- DISABLEDThis key has been disabled, and will not be accepted unless reactivated.
- DELETED
- keystring
The actual key to be used for authenticated API requests
- account_idrequired · string
Listing accounts
GET /v3/partners/{id}/accounts
This endpoint allows you to list all of the accounts you have created for your users.
Example Request
$ curl -XGET 'https://api.sift.com/v3/partners/541752da89f0b8620624f17f/accounts' \ -H 'Content-Type: application/json' \ -u {YOUR_API_KEY}:
Example Response
{ "schema" : "partner_account.json", "total_results" : 1, "data" : [ { "account_id" : "545d48e84d6963acf1000000", "production" : { "api_keys" : [ { "id" : "545d491c4d6963acf12d0000", "state" : "ACTIVE", "key" : "34fc67af86069804" } ], "beacon_keys" : [ { "id" : "545d491c4d6963acf12e0000", "state" : "ACTIVE", "key" : "735ea65235" } ] }, "sandbox" : { "api_keys" : [ { "id" : "545d491c4d6963acf1300000", "state" : "ACTIVE", "key" : "1f46f7f726607c1b" } ], "beacon_keys" : [ { "id" : "545d491c4d6963acf1310000", "state" : "ACTIVE", "key" : "63d0d7605c" } ] } } ] }
Parameters
- idrequired · string
Your partner account id
Response
- schemarequired · string
Reference to the json schema that the data in the array conforms to
- datarequired · array
A list of data items
- productionrequired · object
API keys for the production account
- api_keysarray
Keys used to access Sift's REST APIs
- idstring
Identifier for this API keys
- statestring
State of the API key. Only ACTIVE keys can make requests.
Allowed Values
- ACTIVEThis key is active, and may be used for API requests.
- DISABLEDThis key has been disabled, and will not be accepted unless reactivated.
- DELETED
- keystring
The actual key to be used for authenticated API requests
- beacon_keysarray
Keys used for the JavaScript integration
- idstring
Identifier for this API keys
- statestring
State of the API key. Only ACTIVE keys can make requests.
Allowed Values
- ACTIVEThis key is active, and may be used for API requests.
- DISABLEDThis key has been disabled, and will not be accepted unless reactivated.
- DELETED
- keystring
The actual key to be used for authenticated API requests
- sandboxrequired · object
API keys for the production account
- api_keysarray
Keys used to access Sift's REST APIs
- idstring
Identifier for this API keys
- statestring
State of the API key. Only ACTIVE keys can make requests.
Allowed Values
- ACTIVEThis key is active, and may be used for API requests.
- DISABLEDThis key has been disabled, and will not be accepted unless reactivated.
- DELETED
- keystring
The actual key to be used for authenticated API requests
- beacon_keysarray
Keys used for the JavaScript integration
- idstring
Identifier for this API keys
- statestring
State of the API key. Only ACTIVE keys can make requests.
Allowed Values
- ACTIVEThis key is active, and may be used for API requests.
- DISABLEDThis key has been disabled, and will not be accepted unless reactivated.
- DELETED
- keystring
The actual key to be used for authenticated API requests
- account_idrequired · string
- has_moreboolean
Whether there are more results
- next_refstring
A link to the next set of data, if available
- total_resultsinteger
The total number of results, if known
Labels API Reference
Note
The Labels API is not recommended for customers signing up after February 1st, 2017.
Overview
The Labels API is a way to tell Sift which transactions or events are fraudulent or legitimate. By telling us this information, Sift can identify abuse patterns unique to your business. Labels are used by the platform to generate the risk scores you within your application to automate your fraud fighting.
Labels API is no longer recommended for new customers. Decisions are now the recommended integration, they enable you to send more granular and powerful feedback to our machine learning system. Learn more about Decisions.
For customers already using Labels API, don't worry! It is still a supported integration method. If you are interested in migrating to Decisions, please contact your account manager or support@sift.com and we can help.
How it Works
- Labeling events as fraudulent helps us determine other events that are likely to be fraudulent.
- Labeling events as legitimate is useful for when a user has a high score but is known to be legitimate; it will help lower your false positive rate.
- If you want to change an existing label for a user ID - for example, from risky to valid - all you need to do is send a new label and we'll overwrite the existing value.
- If instead you want to remove labels, you can use our Unlabel API.
Note: You can find the documentation for the previous version of this API here.
Labeling a User
To label a user ID, send an HTTP POST to our Label API endpoint:
https://api.sift.com/v204/users/INSERT_USER_ID/labels
Be sure to replace INSERT_USER_ID with the ID of the user you are labeling. The response should have an HTTP status code of 200
and a status
of 0
. See our Error Codes for more information on non-zero statuses.
// Example curl request to label a user: curl -X POST https://api.sift.com/v204/users/INSERT_USER_ID/labels -d \ '{ "$api_key" : "YOUR_API_KEY", "$is_fraud" : true, "$abuse_type" : "payment_abuse", "$description" : "The user was testing cards repeatedly for a valid card", "$source" : "manual review", "$analyst" : "someone@your-site.com" }' // Example of returned response: { "time" : 1418757635 , "status" : 0 , "request" : "{ \n \"$api_key\" : \"YOUR_API_KEY\", \n \"$is_fraud\" : true, \n \"$abuse_type\" : \"payment_abuse\", \n \"$description\" : \"The user was testing cards repeatedly for a valid card\", \n \"$source\" : \"manual review\", \n \"$analyst\" : \"someone@your-site.com\" \n }" , "error_message" : "OK" }
import sift client = sift.Client("YOUR_API_KEY") properties = { "$is_fraud" : True, # ... or False; Required "$abuse_type" : "payment_abuse", # Required "$description" : "The user was testing cards repeatedly for a valid card", # Optional "$source" : "manual review", # Optional "$analyst" : "someone@your-site.com" # Optional } response = client.label("billy_jones_301", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") properties = { "$is_fraud" => true, # ... or false; Required "$abuse_type" => "payment_abuse", # Required "$description" => "The user was testing cards repeatedly for a valid card", # Optional "$source" => "manual review", # Optional "$analyst" => "someone@your-site.com" # Optional } response = client.label("billy_jones_301", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); $properties = array( '$is_fraud' => true, // ... or false; Required Field '$abuse_type' => 'payment_abuse', // Required '$description' => 'The user was testing cards repeatedly for a valid card', // Optional '$source' => 'manual review', // Optional '$analyst' => 'someone@your-site.com' // Optional ); $response = $client->label('billy_jones_301', $properties);
import com.siftscience.SiftClient; import com.siftscience.LabelRequest; import com.siftscience.LabelResponse; import com.siftscience.model.LabelFieldSet; SiftClient client = new SiftClient("YOUR_API_KEY"); LabelRequest request = client.buildRequest(new LabelFieldSet() .setUserId("billy_jones_301") .setIsBad(true) .setAbuseType("payment_abuse") .setDescription("The user was testing cards repeatedly for a valid card") .setSource("manual review") .setAnalyst("someone@your-site.com")); LabelResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
- $api_keyrequired · String
Your Sift API key.
- $is_fraudrequired · Boolean
Indicates whether a user is engaging in behavior deemed harmful to your business. Set to true if the user is engaging in abusive activity. Set to false if the user is engaging in valid activity.
- $abuse_typerequired · String
The type of abuse for which you want to send a label. It's important to send a label specific to the type of abuse the user is committing so that Sift can learn about specific patterns of behavior. You'll end up with more accurate results this way.
Allowed values
- payment_abuseA user using stolen payment information (e.g. a stolen credit card) to purchase goods or services.
- content_abuseA user creating content or sending messages on your site in an abusive manner. This includes spam posts that pollute your site, fake listings intended to scam other users, spammy messages to other users, and any other fraudulent or abusive content.
- promotion_abuseA user gaming the terms of a promotion in an excessive or abusive way. A promotion includes things like coupons, referral credits, limited offers, free trial periods, etc.
- account_abuseA user who uses your service in a manner you deem abusive. This behavior can include creating fake/duplicate accounts or any other abusive patterns specific to your business.
- $descriptionString
Freeform text description of the user and/or incident triggering the label. Useful as annotation on why the label was added.
- $sourceString
String describing the original source of the label information (e.g. payment gateway, manual review, etc.).
- $analystString
Unique identifier (e.g. email address) of the analyst who applied the label. Useful for tracking purposes after the fact.
Unlabeling a User ID
If you are unsure whether a user is fraudulent or legitimate, you can always remove labels and leave the user in a neutral
state. To unlabel a user for a particular abuse type, send an HTTP DELETE to our Labels API endpoint with the abuse_type
query parameter:
https://api.sift.com/v204/users/INSERT_USER_ID/labels?abuse_type=INSERT_ABUSE_TYPE
This API call should return an HTTP status code of 204
.
In the rare case that you want to remove all labels for all abuse types for a particular user, send an HTTP DELETE to our Labels API endpoint without the abuse_type
query parameter:
https://api.sift.com/v204/users/INSERT_USER_ID/labels
If you just want to change an existing label - for example, from fraudulent to legitimate - all you need to do is send a new label and we'll overwrite the existing value. Learn more about labeling a user.
Note: You can find the documentation for the previous version of this API here.
// Example curl request to remove a payment abuse label: curl -X DELETE "https://api.sift.com/v204/users/USER_ID/labels/?api_key=YOUR_API_KEY&abuse_type=payment_abuse"
import sift client = sift.Client("YOUR_API_KEY - production key if not testing") response = client.unlabel("billy_jones_301", abuse_type="payment_abuse")
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY - production key if not testing") response = client.unlabel("billy_jones_301", :abuse_type => "payment_abuse")
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY - production key if not testing')); $response = $client->unlabel('billy_jones_301', array('abuse_type' => 'payment_abuse'));
import com.siftscience.SiftClient; import com.siftscience.UnlabelRequest; import com.siftscience.UnlabelResponse; import com.siftscience.model.UnlabelFieldSet; SiftClient client = new SiftClient("YOUR_API_KEY"); UnlabelRequest request = client.buildRequest(new UnlabelFieldSet() .setUserId("billy_jones_301") .setAbuseType("payment_abuse")); UnlabelResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true