Sift API Overview

Sift is the leader in Digital Trust & Safety, empowering organizations of all sizes to unlock new revenue without risk using machine learning. Sift helps 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 across 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 many abuse use cases that Sift can stop:

  • Payment Protection - Reduce friction at checkout to increase revenue and stop chargebacks before they hurt your business.
  • Account Defense
    • Account Abuse - Stop fake accounts from polluting your service and block fraudulent users before they harm your business.
    • Account Takeover - Stop fraudulent actors from hijacking users accounts. Keep your users safe and ensure that they always trust your service.
  • Content Integrity - 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 the transactions and events on your website and/or mobile apps and what actions you take in response to them. This includes:

  • How your users are interacting on your website and/or mobile apps (e.g., 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 (e.g., 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 (e.g., approve an order, block and event 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’s actions are legitimate or fraudulent. Sift represents this risk with a score between 0 and 100, where risky events 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’s events 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 an event, 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 legitimate or risky patterns.

You’ll use Sift risk scores to help you make decisions about your users’ actions 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 ID.
  • 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 ID 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.

Overview

The Core Topics section covers items that are generally applicable across Sift’s APIs and answers questions common developers have about integrating and using Sift.

Client Libraries

Sift provides client libraries in Python, Ruby, PHP and Java. They provide a wrapper for Sift’s APIs and will help with sending events and decisions or receiving scores.

Installation instructions can be found in the Client Libraries Tutorial or in the respective Github repositories below:

Note

If you’re not seeing a client library in a language you use, please let us know what you’d like us to support via email: support@sift.com.

Authentication

Authentication is required for requests to Sift. Sift uses API Keys to authenticate REST API requests, and a separate Beacon Key to authenticate events from our SDKs. Keys are available in two classes: production for your live site once you’ve tested new parts of an integration, and sandbox for testing or getting started.

For greater security, you may also create a restricted API Key with specific permissions to your account data. A restricted key provides only permissions and access to data for an application that you permit, protecting the data that the application doesn’t need. For example, you may create a restricted key that grants only permission to retrieve Order data for the purposes of informing your Chargeback Management service. API Keys offer the ability to edit access to the following resources:

  • Events API
  • Scores - Score and Rescore
  • Feedback - Labels and Decisions
  • Device Fingerprinting
  • Verifications API
  • Webhooks API
  • Retrieve Orders

If a restricted key is no longer needed, or possibly compromised, access to the key may be disabled or revoked at any time. You also have the ability to edit the permissions of already existing keys.

Restricted keys are only intended to be used for applications which require partial access to your Sift data, and should not be used for the standard Sift integration.

Keys can found within the Sift Console under API Keys. Detailed guidance for each API or SDK can found within their reference sections.

  • Component
    Requirements
  • JS SDK, iOS SDK, and Android SDK
    Authenticate with a Beacon Key
  • Events API, Score API
    Authenticate with API Keys
  • Decisions API, Device Fingerprinting API
    Authenticate with API Keys and the Account ID

Note

When integrating Sift, it’s strongly recommended that you first test your changes by sending all data to the sandbox console with your sandbox API Keys prior to sending data with production API Keys.

For authenticating Decision Webhooks sent to your servers by Sift, you can configure a Webhook Signature Key.

Sandbox

Sift recommends that developers utilize the sandbox environment when testing new elements of Sift. This sandbox environment allows you to send test events or client data to Sift without impacting the scores Sift produces in production. To get access to your sandbox keys, visit the API Keys section of the console Developer center and make sure you’ve selected sandbox mode. Selecting sandbox mode will switch you to the sandbox view so you can see all your test data in the console (e.g. Explore, Queues, Workflows, etc.).

Error Reference

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. If Sift’s servers are dealing with unexpected problems, you’ll get a HTTP 500 response. A non-zero status indicates an error.

In the case that you’re using the return_score or return_workflow_status query parameter, you’ll also want to examine the score object within the response for failures.

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
  • 50
    Invalid Request
  • 51
    Invalid API Key
  • 52
    Invalid characters in field name
  • 53
    Invalid characters in field value
  • 54
    Specified user_id has no scoreable events
  • 55
    Missing required field
  • 56
    Invalid JSON in request
  • 57
    Invalid HTTP body
  • 58
    Invalid event: Event occurs in future
  • 59
    $user_id not URI encoded
  • 60
    Rate limited
  • 61
    Account disabled
  • 62
    Product not selected
  • 63
    Invalid Credentials
  • 100
    Required fields missing
  • 102
    Parameter encoding failure
  • 103
    No events for user found
  • 104
    Invalid API version
  • 105
    Not a valid reserved field
  • 106
    Missing event specific fields (could reference the event)
  • 107
    Score not ready for user
  • 108
    No events for session
  • 109
    Invalid parameter value
  • 110
    Incorrect event sent to $transaction only account
  • 111
    Feature disabled
  • 112
    Abuse product disabled
  • 113
    Conflicting fields selected
  • 114
    Invalid event type
  • 115
    Invalid abuse type requested
  • 116
    Event cannot be processed due to legal restrictions
  • 117
    List exceeds maximum size

Changelog

This changelog tracks updates to Sift's APIs since February 2018. Detailed changelogs can also be found for our client libraries and SDKs in Github.

  • Date
    Updates
  • April 2022

    API: Added $merchant_profile field to $create_account, $chargeback and $update_account events.

  • Oct 2021

    API: Added $merchant_profile complex field which should be used in $create_order, $update_order and $transaction events.


    API: Added allowed values $buy, $sell, $send, and $receive for $transaction_type field.


    API: Added allowed values $sepa_credit, $sepa_instant_credit, $sepa_direct_debit, $wire_credit, $wire_debit, $ach_credit, and $ach_debit for $payment_type field.


    API: Added fields $status_3ds, $triggered_3ds, $merchant_initiated_transaction, $sent_address, and $received_address to $transaction event.


    API: Added fields $shortened_iban_first6, $shortened_iban_last4, $sepa_direct_debit_mandate, $account_holder_name, $account_number_last5, $bank_name, and $bank_country to $payment_method field.

  • July 2021

    API: Added the $shipping_tracking_numbers field and marking $shipping_tracking_number as "Deprecated" (which will later be removed)

  • December 2020

    API: Changed the description of $user_email field for $login event

  • September 2020

    API: Added $shipping_carrier and $shipping_tracking_number fields to $create_order and $update_order events.

  • May 2020

    API: Added a new allowed value of $apple for $social_sign_on_type field.


    API: Added a new optional field $decline_category to $transaction to map common decline reason codes to a set of standardized decline categories.

  • April 2020

    API: Changed required fields on $chargeback event. The $user_id field is now recommended instead of required, and only one of $order_id or $transaction_id is required.

  • February 2020

    API: Added more allowed values $face, $fingerprint, push, security_key to field $verification_type in reserved event $verification.

  • January 2020

    API: Added $client_language field to $app complex field.


    API: Added $accept_language and $content_language fields to $browser complex field.


    API: Added $ordered_from complex field which should be used in $create_order, $update_order and $transaction events.


    API: Added $site_country, $site_domain and $brand_name fields to custom events and all reserved events except $chargeback, $link_session_to_user, and $flag_content.

  • August 2019

    API: Added $booking, $segment, and $guest complex fields to the following reserved events: $create_order and $update_order.

  • February 2019

    API: Added $app and $browser complex fields to the following reserved events: $content_status, $order_status, $security_notification, and $verification.


    API: Added $update_password event to capture user- and service- initiated password changes.


    API: Added $account_types field to $login, $create_account and $update_account events, to optimize for various types of user accounts.


    API: Added $verified_event and $verified_entity_id to the $verification event to track verifications triggered by most reserved events.


    API: Added $reason to $verification events to distinguish verifications that are always on from verifications triggered on risk.


    API: Added support for knowledge-based verifications through $shared_knowledge field in the $verification event.


    API: Added $social_sign_on_type to $login for use in ATO workflows; add reserved values for $microsoft and $amazon accounts.

  • January 2019

    API: Changed references to Sift API calls in the developer docs to api.sift.com. Previous requests to api3.siftscience.com will still function, this will simplify the experience for Sift developers.


    API: Added support for $failure_reason, $account_types, $username and $social_sign_on_type to $login event.

  • October 2018

    API: Added support for Rescore User and Get User Score APIs.


    API: Added $app and $browser complex fields to the following reserved events: $add_item_to_cart, $add_promotion, $create_account, $create_content, $create_order, $logout, $remove_item_from_cart, $transaction, $update_account, $update_content and custom events.

  • June 2018

    API: Added support for retrieving the decision status of a session to Decisions API.

  • March 2018

    API: Released Sift API Version 205, including major updates to $create_content and $update_content.


    API: Added support for content decisions to Decisions API.

  • February 2018

    API: Added support for $security_notification event.


    API: Added support for applying decisions to sessions and retrieve the list of session-level decisions in Decisions API.

Tracking User IDs and Sessions

Sift uses user ID and session ID to track user IDs and sessions respectively. Both are important for Sift to be able to understand the activity related to your user ID and it’s strongly recommended that these are sent whenever possible. A $user_id should be a field that the user cannot update (e.g. if they can change their email address, a different unique identifier is recommended).

Tracking Anonymous Actions

You may have some periods of time when the $user_id is not apparent for a user – either because they have not logged in, or because you’re doing something like guest checkout where the $user_id has not been assigned yet. In those cases:

  • In the Javascript Snippet, set _user_id to the empty string.
  • In the Mobile SDKs, call setUserId once the user has signed in.
  • In the REST API, for events that you do not need a score returned, set $user_id to an empty string and set $session_id to match the value provided in the JavaScript snippet, if applicable. Events sent without a user ID will not be scored, and will not trigger Workflows. Once the user has logged in or created an account, send a subsequent event, or a $link_session_to_user event with the user ID set, and the same session ID.
  • In the REST API, for events that need a score returned, pass a different unique identifier in the $user_id field (e.g. email address or transaction ID).

Reserved and Custom Events

When sending requests to the REST APIs, you can send both reserved and custom data. Reserved events and fields are events that Sift has defined, that Sift can do advanced analysis on. When possible, send the user actions taken on your site or app with reserved events or fields. Reserved events or fields are denoted by the $ character prior to the event or field name (e.g. $login event or $user_id field). Each event accepts required, reserved, and custom fields.

Custom Events and Fields

Custom events are events you create to capture actions unique to your application. If there are key actions or attributes your users take that are not captured by our reserved events, send these as custom event or custom field. Custom events still require $type, $api_key, and the presence of $user_id or $session_id.

To learn more, see examples in the Custom Events and Fields section.

Backfilling

When you’re first sending data to Sift, you may want to send critical historical data to Sift so there’s data available for our machine learning predictions. You’ll indicate an event is a historical event by sending with a $time in the past (using UNIX millis timestamp). You can then mark known fraudulent events through the Decisions API.

Event Backfill Guidelines

  • Send the event with $time in millis.
  • You should send 6-12 months of key events (e.g. account, order, content) for all user IDs (regardless of whether they’re known to be fraudulent or legitimate.)
  • Include as much historical data as you have available, including the user’s $ip if known.
  • Test in sandbox first before you send backfill data to production.
  • Be aware of rate limits and build in retry logic.

Note: While we use up to 12 months of historical data, users with activity older than 30 days will not show up in the console.

// Sample $create_account event
{
  // Required for backfilling
  // UNIX timestamp in milliseconds as an integer
  "$time" : 1456274104243, // Feb 24 2016 00:35:04 UTC

  "$type"             : "$create_account",
  "$api_key"          : "YOUR_API_KEY",
  "$user_id"          : "billy_jones_301",
  "$user_email"       : "bill@gmail.com",
  "$name"             : "Bill Jones",
  "$phone"            : "1-415-555-6040",
  "$ip"               : "54.208.214.78"
}

require "sift"

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

# Sample $create_account event
properties = {
  # Required for backfilling
  # UNIX timestamp in milliseconds as an integer
  "$time" => 1456274104243, # Feb 24 2016 00:35:04 UTC

  "$user_id"          => "billy_jones_301",
  "$user_email"       => "bill@gmail.com",
  "$name"             => "Bill Jones",
  "$phone"            => "1-415-555-6040",
  "$ip"               => "54.208.214.78"
}

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

import sift

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

# Sample $create_account event
properties = {
  # Required for backfilling
  # UNIX timestamp in milliseconds as an integer
  "$time" : 1456274104243, # Feb 24 2016 00:35:04 UTC

  "$user_id"          : "billy_jones_301",
  "$user_email"       : "bill@gmail.com",
  "$name"             : "Bill Jones",
  "$phone"            : "1-415-555-6040",
  "$ip"               : "54.208.214.78"
}

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 for backfilling
  // UNIX timestamp in milliseconds as an integer
  '$time' => 1456274104243, // Feb 24 2016 00:35:04 UTC

  '$user_id'          => 'billy_jones_301',
  '$user_email'       => 'bill@gmail.com',
  '$name'             => 'Bill Jones',
  '$phone'            => '1-415-555-6040',  
  '$ip'               => '54.208.214.78'
);

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

import com.siftscience.SiftClient;
import com.siftscience.EventRequest;

SiftClient client = new SiftClient("YOUR_API_KEY");
EventRequest request = client.buildRequest(new CreateAccountFieldSet()
        .setUserId("billy_jones_301")
        .setSessionId("gigtleqddo84l8cm15qe4il")
        .setUserEmail("bill@gmail.com")
        .setName("Bill Jones")
        .setIP("54.208.214.78")
        .setTime(1456274104243)

EventResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
    return;
}
response.isOk(); // true

Decision Backfill Guidelines

  • After you have backfilled historical data, use the DECISIONS API to send Block category decisions for previously identified fraudulent user IDs.
  • Decision Source should either be MANUAL_REVIEW, or CHARGEBACK depending on how you identified the user ID as fraudulent. If you don’t know how the user ID was identified as fraudulent originally, set the source to MANUAL_REVIEW.
// Sample Decision Event
// Requires that you configure a Decision with this ID first
// Decisions are configured in the Sift Console
// Decisions should be named based on your real business actions
{
  "decision_id"   : "ban_user_payment_abuse",
  "source"        : "MANUAL_REVIEW",
  "analyst"       : "analyst@example.com",
  "description"   : "backfill known fraud users",
  "time"          : 1456274104243, // Feb 24 2016 00:35:04 UTC
}

# Sample Decision Event
# Requires that you configure a Decision with this ID first
# Decisions are configured in the Sift Console
# Decisions should be named based on your real business actions

require "sift"

client = Sift::Client.new(api_key: "{YOUR_API_KEY}", account_id: "accountId")

response = client.apply_decision({
  "decision_id"       => "ban_user_payment_abuse",
  "description"       => "backfill known bad users",
  "source"            =>"MANUAL_REVIEW",
  "analyst"           => "analyst@example.com",
  "user_id"           => "userId",
  "time"              => 1456274104243, # Feb 24 2016 00:35:04 UTC
})

if (!response.ok?)
  puts "Unable to apply decision: " + response.api_error_message
end

# Sample Decision Event
# Requires that you configure a Decision with this ID first
# Decisions are configured in the Sift Console
# Decisions should be named based on your real business actions

import sift

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

applyDecisionRequest = {
    'decision_id'   : 'user_looks_ok_payment_abuse',
    'source'        : 'MANUAL_REVIEW',
    'analyst'       : 'analyst@example.com',
    'description'   : 'backfill known bad users',
    'time'          : 1456274104243, # Feb 24 2016 00:35:04 UTC
}

response = client.apply_user_decision(user_id, applyDecisionRequest)

// Sample Decision Event
// Requires that you configure a Decision with this ID first
// Decisions are configured in the Sift Console
// Decisions should be named based on your real business actions

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'   => 'backfill known bad users',
    'time'          =>  1456274104243
);

$response = $client->applyDecisionToUser('userId',
    'ban_user_payment_abuse',
    'MANUAL_REVIEW',
    'time',
    $options);

// Sample Decision Event
// Requires that you configure a Decision with this ID first
// Decisions are configured in the Sift Console
// Decisions should be named based on your real business actions

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("ban_user_payment_abuse")
        .setSource(DecisionSource.MANUAL_REVIEW)
        .setDescription("backfill known fraud users")
        .setAnalyst("analyst@example.com"))
        .setTime(1456274104243);

ApplyDecisionResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
}

DecisionLog decisionLog = response.getDecisionLog();

Rate Limits

Rate limit errors from Sift show up as HTTP 400 or HTTP 429 responses with status code 60. The default rate limits are below. If you need higher rate limits, please contact support for assistance on adjusting rate- limits to the right level.

  • Sift API
    Rate Limit (requests/second)
  • Events API
    180 requests/second (and a per $user_id rate limit of 3 requests/second)
  • Events API with synchronous score calls (return_score or return_workflow_status)
    20 requests/second
  • Decisions API
    40 requests/second
  • Decisions API w/ applying Block category Decisions
    20 requests/second
  • JavaScript Snippet
    1000 requests/second
  • Mobile SDKs
    180 requests/second
  • Score API
    6 requests/second

Installing the JavaScript Snippet

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

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

Install the JavaScript Snippet

  1. Insert this JavaScript snippet onto your webpage, just after the opening <body> tag:
    <script type="text/javascript">
  var _user_id = 'al_capone'; // Set to the user's ID, username, or email address, or '' if not yet known.
  var _session_id = 'unique_session_id'; // Set to a unique session ID for the visitor's current browsing session.

  var _sift = window._sift = window._sift || [];
  _sift.push(['_setAccount', 'INSERT_BEACON_KEY_HERE']);
  _sift.push(['_setUserId', _user_id]);
  _sift.push(['_setSessionId', _session_id]);
  _sift.push(['_trackPageview']);

 (function() {
   function ls() {
     var e = document.createElement('script');
     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>
  2. Change the parameter to _setAccount above to your JavaScript Snippet key.
  3. Set _session_id to a string that identifies a unique session ID for the visitor's current browsing session.
  4. Set _user_id to a string that identifies the user, e.g. a user ID, username, or email address. (Leave user_id blank if you do not yet know the ID of the user.). This user ID should be consistent with $user_id in your Events API requests.
  5. If you have a single-page app, see our help article.

Notes
  • To minimize download latency, we've hosted these files on Amazon Cloudfront. To minimize page load delay, this code executes as asynchronously as possible, yielding several times.
  • This code will set a long-lived cookie (four years) 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.

  1. 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"
  2. (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.
  3. If your app uses user location data but you do not want to send it to Sift, add the following to the configuration block above: [sift setDisallowCollectingLocationData:YES;].
  4. Set the user ID for the user, this allows us to associate mobile data with data sent via Sift’s Rest API and Javascript. When the user ID is available (for example, when user has just logged in), please set the user ID:
    [[Sift sharedInstance] setUserId:@"USER_ID"];
  5. (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.pause();
        }
        public void onActivityResumed(Activity activity) {
            Sift.resume(activity);
        }
        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.setUserId("SOME_USER_ID");

If the user logs out of your application or their session ends, you should unset the user ID:

Sift.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 onPause, onResume, and onDestroy 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.pause();
    }
    @Override
    protected void onResume() {
        super.onResume();
        Sift.resume(this);
    }
    @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, onResume, and onDestroy:

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.save();
    }
    @Override
    protected void onResume() {
        super.onResume();
        // For Fragments, use Sift.open(this.getActivity()) instead
        Sift.resume(this);
    }
    @Override
    protected void onDestroy() {
        super.onDestroy();
        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.setUserId("SOME_USER_ID");

If the user logs out of your application or their session ends, you should unset the user ID:

Sift.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 fraudulent and legitimate events. 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/v205/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.

$add_item_to_cart

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

  • $type
    required · String

    "$add_item_to_cart"

  • $api_key
    required · String

    Your Sift REST API key.

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

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

  • $user_id
    send if known · String

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

  • $item
    Item

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

  • $browser
    Browser

    The user agent of the browser that is used to add the item to cart. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to add the item to cart. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

  • $user_email
    String

    Email of the user logging in. 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.

  • $verification_phone_number
    String

    Phone number of the user. This phone number will be used to send One-Time Password (OTP) when required. The phone number should be in E.164 format including + and a country code.

// 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"            : "6786211451001",
    "$sku"            : "004834GQ",
    "$brand"          : "Slanket",
    "$manufacturer"   : "Slanket",
    "$category"       : "Blankets & Throws",
    "$tags"           : ["Awesome", "Wintertime specials"],
    "$color"          : "Texas Tea",
    "$quantity"       : 16
  },
  "$brand_name"                : "sift",
  "$site_domain"               : "sift.com",
  "$site_country"              : "US",
  "$user_email"                : "billjones1@example.com",
  "$verification_phone_number" : "+123456789012",

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

import sift

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

# 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"            : "6786211451001",
    "$sku"            : "004834GQ",
    "$brand"          : "Slanket",
    "$manufacturer"   : "Slanket",
    "$category"       : "Blankets & Throws",
    "$tags"           : ["Awesome", "Wintertime specials"],
    "$color"          : "Texas Tea",
    "$quantity"       : 16
  },
  "$brand_name"   : "sift",
  "$site_domain"  : "sift.com",
  "$site_country" : "US",
  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

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"            => "6786211451001",
    "$sku"            => "004834GQ",
    "$brand"          => "Slanket",
    "$manufacturer"   => "Slanket",
    "$category"       => "Blankets & Throws",
    "$tags"           => ["Awesome", "Wintertime specials"],
    "$color"          => "Texas Tea",
    "$quantity"       => 16
  },
  "$brand_name"   => "sift",
  "$site_domain"  => "sift.com",
  "$site_country" => "US",
  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

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'            => '6786211451001',
    '$sku'            => '004834GQ',
    '$brand'          => 'Slanket',
    '$manufacturer'   => 'Slanket',
    '$category'       => 'Blankets & Throws',
    '$tags'           => array('Awesome', 'Wintertime specials'),
    '$color'          => 'Texas Tea',
    '$quantity'       => 16
  ),
  '$brand_name'   => 'sift',
  '$site_domain'  => 'sift.com',
  '$site_country' => 'US',
  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$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("6786211451001")
                .setSku("004834GQ")
                .setBrand("Slanket")
                .setManufacturer("Slanket")
                .setCategory("Blankets & Throws")
                .setTags(Arrays.asList("Awesome", "Wintertime specials"))
                .setQuantity(16L)));
        .setBrandName("sift")
        .setSiteDomain("sift.com")
        .setSiteCountry("US")
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

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.

  • $type
    required · String

    "$add_promotion"

  • $user_id
    required · String

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

  • $promotions
    Array of Promotions

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

  • $browser
    Browser

    The user agent of the browser that is used to add the promotion. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to add the promotion. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

  • $user_email
    String

    Email of the user logging in. 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.

  • $verification_phone_number
    String

    Phone number of the user. This phone number will be used to send One-Time Password (OTP) when required. The phone number should be in E.164 format including + and a country code.

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

  // Supported fields.
  "$user_email"                : "billjones1@example.com",
  "$verification_phone_number" : "+123456789012",

  "$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"
      }
  }
  ],

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

import sift

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

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

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

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"
      }
  }
  ],

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

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

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$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))))
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

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.
  • It is recommended that you send both $order_id and $transaction_id to link the chargeback to the associated user and order. However, only one of those fields is required to be sent in the call (i.e. if $order_id is present, $transaction_id need not be sent and vice versa).

  • $type
    required · String

    "$chargeback"

  • $api_key
    required · String

    Your Sift REST API key.

  • $order_id
    required · String

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

    Note: Optional if the $transaction_id is present. This field is not required if this chargeback was filed against a transaction with no $order_id.

  • $transaction_id
    required · String

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

    Note: Optional if $order_id is present.

  • $user_id
    String

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

  • $chargeback_state
    String

    The current state of the chargeback.

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

    This field can be used to capture the reason given.

    Allowed Values
    • "$fraud" "$duplicate" "$product_not_received" "$product_unacceptable" "$other"
  • $merchant_profile
    Merchant Profile

    The details about the merchant or seller providing the goods or service.

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

  // Recommended Fields
  "$user_id"           : "billy_jones_301",
  "$chargeback_state"  : "$lost",
  "$chargeback_reason" : "$duplicate"
}

import sift

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

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

  # Recommended Fields
  "$user_id"           : "billy_jones_301",
  "$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
  "$order_id"          => "ORDER-123124124",
  "$transaction_id"    => "719637215",

  # Recommended Fields
  "$user_id"           => "billy_jones_301",
  "$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
  '$order_id'          => 'ORDER-123124124',
  '$transaction_id'    => '719637215',

  // Recommended Fields
  '$user_id'           => 'billy_jones_301',
  '$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
        .setOrderId("ORDER-123124124")
        .setTransactionId("719637215")
        // Recommended Fields
        .setUserId("billy_jones_301")
        .setChargebackState("$lost")
        .setChargebackReason("$duplicate"));

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.

  • $type
    required · String

    "$content_status"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $content_id
    required · String

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

  • $status
    required · String

    The status of the posting.

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

    The user agent of the browser that is used to add the item to cart. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to add the item to cart. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

  • $user_email
    String

    Email of the user logging in. 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.

  • $verification_phone_number
    String

    Phone number of the user. This phone number will be used to send One-Time Password (OTP) when required. The phone number should be in E.164 format including + and a country code.

// Sample $content_status event
{
  // Required Fields
  "$type"       : "$content_status",
  "$api_key"    : "YOUR_API_KEY",
  "$user_id"    : "billy_jones_301",
  "$content_id" : "9671500641",
  "$status"     : "$paused",

  // Supported Fields
  "$user_email"                : "billjones1@example.com",
  "$verification_phone_number" : "+123456789012",

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

import sift

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

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

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

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

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

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

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$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"));
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

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 or app. Examples of user-generated content include job listings, products for sale, apartment rentals, dating profiles, and blog posts.

With every $create_content request, you must specify the type of content you are sending. Sift supports the following types of content:

  1. Comment: The $comment field type represents comments created by users. Comments may be in response to an apartment listing, blog post, etc.
  2. Listing: The $listing field type represents information for a product or service offered by a user. This may include a marketplace listing, a classified ad, an auction, a job listing, etc.
  3. Message: The $message field type represents messages exchanged between users of your service.
  4. Post: The $post field type represents information that a user has shared with your community. Examples include social media posts like status updates, forum posts, blog articles etc.
  5. Profile: The $profile field type represents information related to a user's profile. Examples include social media, dating, or seller profiles.
  6. Review: The $review field type represents information related to a product or service reviewed by your users.

$create_content.comment

Use $create_content with a $comment type to tell Sift whenever a user posts into the comment section your site. Examples of comments include a comment on a social media or blog post, and discussion sections on news articles.

  • $type
    required · String

    "$create_content"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $content_id
    required · String

    The unique ID that you assign to an individual piece of content in your system. Note: content IDs are case sensitive and must be unique across all content types..

  • $session_id
    String

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

  • $status
    String

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

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

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

  • $browser
    Browser

    The user agent of the browser that is used to create the comment. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to create the comment. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $comment
    Object

    Contains information about the comment.

    • $body
      String

      The text content of the comment.

    • $contact_email
      String

      The email address provided with the listing for contacting the poster. When no email address is provided for the listing, use the email address of the user account instead.

    • $parent_comment_id
      String

      The $content_id of the immediate parent comment, i.e. the comment being replied to. Only use if it is a reply to a previous comment.

    • $root_content_id
      String

      The $content_id of the content being commented on. For example, this would be the id of the social media $post to which the comment applies.

    • $images
      Array of Images

      The list of images shared by the user with their comment. It includes images pasted inline or attached separately.

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

// Sample $create_content event for comments
{
  // Required fields
  "$type"                 : "$create_content",
  "$api_key"              : "YOUR_API_KEY",
  "$user_id"              : "fyw3989sjpqr71",
  "$content_id"           : "comment-23412",

  // Recommended fields
  "$session_id"           : "a234ksjfgn435sfg",
  "$status"               : "$active",
  "$ip"                   : "255.255.255.0",

  // Required $comment object
  "$comment"              : {
    "$body"               : "Congrats on the new role!",
    "$contact_email"      : "alex_301@domain.com",
    "$parent_comment_id"  : "comment-23407",
    "$root_content_id"    : "listing-12923213",
    "$images"             : [
      {
        "$md5_hash"           : "0cc175b9c0f1b6a831c399e269772661",
        "$link"               : "https://www.domain.com/file.png",
        "$description"        : "An old picture"
      }
    ]
  },

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

require "sift"

client = Sift::Client.new({api_key: "YOUR_API_KEY"})

# Sample $create_content event for comments
comment_properties = {
  # Required fields
  '$user_id'              => 'fyw3989sjpqr71',
  '$content_id'           => 'comment-23412',

  # Recommended fields
  '$session_id'           => 'a234ksjfgn435sfg',
  '$status'               => '$active',
  '$ip'                   => '255.255.255.0',

  # Required $comment object
  '$comment'              => {
    '$body'               => 'Congrats on the new role!',
    '$contact_email'      => 'alex_301@domain.com',
    '$parent_comment_id'  => 'comment-23407',
    '$root_content_id'    => 'listing-12923213',
    '$images'             => [
      {
        '$md5_hash'            => '0cc175b9c0f1b6a831c399e269772661',
        '$link'                => 'https://www.domain.com/file.png',
        '$description'         => 'An old picture'
      }
    ]
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

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

import sift

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

# Sample $create_content event for comments
comment_properties = {
  # Required fields
  "$user_id"                : "fyw3989sjpqr71",
  "$content_id"             : "comment-23412",

  # Recommended fields
  "$session_id"             : "a234ksjfgn435sfg",
  "$status"                 : "$active",
  "$ip"                     : "255.255.255.0",

  # Required $comment object
  "$comment"                : {
    "$body"               : "Congrats on the new role!",
    "$contact_email"      : "alex_301@domain.com",
    "$parent_comment_id"  : "comment-23407",
    "$root_content_id"    : "listing-12923213",
    "$images"             : [
      {
        "$md5_hash"       : "0cc175b9c0f1b6a831c399e269772661",
        "$link"           : "https://www.domain.com/file.png",
        "$description"    : "An old picture"
      }
    ]
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

response = client.track("$create_content", comment_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';

$event = '$create_content';
$client = new SiftClient(array('api_key' => YOUR_API_KEY));

// Sample $create_content event for comments
$comment_properties = array(
  // Required fields
  '$user_id' => 'fyw3989sjpqr71',
  '$content_id' => 'comment-23412',

  // Recommended fields
  '$session_id'           => 'a234ksjfgn435sfg',
  '$status'               => '$active',
  '$ip'                   => '255.255.255.0',

  // Required $comment object
  '$comment'              => array(
    '$body'               => 'Congrats on the new role!',
    '$contact_email'      => 'alex_301@domain.com',
    '$parent_comment_id'  => 'comment-23407',
    '$root_content_id'    => 'listing-12923213',
    '$images'             => array(
      array(
          '$md5_hash'            => '0cc175b9c0f1b6a831c399e269772661',
          '$link'                => 'https://www.domain.com/file.png',
          '$description'         => 'An old picture'
      )
    )
  ),

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$response = $client->track($event, $comment_properties);
import java.util.Arrays;

import com.siftscience.EventRequest;
import com.siftscience.EventResponse;
import com.siftscience.SiftClient;
import com.siftscience.exception.SiftException;
import com.siftscience.model.Comment;
import com.siftscience.model.CreateCommentFieldSet;
import com.siftscience.model.Image;

SiftClient client = new SiftClient("YOUR_API_KEY");

// Sample $create_content event for comments
EventRequest request = client.buildRequest(new CreateCommentFieldSet()
        // Required fields
        .setUserId("fyw3989sjpqr71")
        .setContentId("comment-23412")
        // Recommended fields
        .setSessionId("a234ksjfgn435sfg")
        .setStatus("$active")
        .setIp("255.255.255.0")
        // Required $comment object
        .setComment(new Comment()
                .setBody("Congrats on the new role!")
                .setContactEmail("alex_301@domain.com")
                .setParentCommentId("comment_23407")
                .setRootContentId("listing-12923213")
                .setImages(Arrays.asList(new Image()
                        .setMd5Hash("18E927C7E1229DC8F088643B7A65F978")
                        .setLink("https://www.domain.com/file.png")
                        .setDescription("An old picture")))));
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

EventResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
    return;
}
response.isOk(); // true

$create_content.listing

Use $create_content with a $listing type whenever a user creates a listing on your site. Examples of listings include job listing, product for sale, or an apartment for rent.

  • $type
    required · String

    "$create_content"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $content_id
    required · String

    The unique ID that you assign to an individual piece of content in your system. Note: content IDs are case sensitive and must be unique across all content types..

  • $session_id
    String

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

  • $status
    String

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

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

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

  • $browser
    Browser

    The user agent of the browser that is used to create the listing. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to create the listing. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $listing
    Object

    Contains information about the listing.

    • $subject
      String

      The subject of the listing.

    • $body
      String

      The text content of the listing.

    • $contact_email
      String

      The email address provided with the listing for contacting the poster. When no email address is provided for the listing, use the email address of the user account instead.

    • $contact_address
      Address

      The physical contact address provided with the listing. When no address is provided for the listing, use the physical address of the user account instead.

    • $locations
      Array of Addresses

      The locations associated with the listing. For example, this array would contain the location of the rental listing. You can pass one or more addresses that are associated with your listing. Pass as much information as you have. Partial addresses such as just the city and state are fine if that's all you have.

    • $listed_items
      Array of Items

      The items array represents physical or digital items listed by the user.

    • $images
      Array of Images

      The list of images shared by the user with their listing. It includes images pasted inline or attached separately.

    • $expiration_time
      Integer

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

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

// Sample $create_content event for listings
{
  // Required fields
  "$type"               : "$create_content",
  "$api_key"            : "YOUR_API_KEY",
  "$user_id"            : "fyw3989sjpqr71",
  "$content_id"         : "listing-23412",

  // Recommended fields
  "$session_id"         : "a234ksjfgn435sfg",
  "$status"             : "$active",
  "$ip"                 : "255.255.255.0",

  // Required $listing object
  "$listing"            : {
    "$subject"          : "2 Bedroom Apartment for Rent",
      "$body"           : "Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.",
      "$contact_email"  : "alex_301@domain.com",
      "$contact_address": {
        "$name"         : "Bill Jones",
        "$phone"        : "1-415-555-6041",
        "$city"         : "New London",
        "$region"       : "New Hampshire",
        "$country"      : "US",
        "$zipcode"      : "03257"
    },
    "$locations"        : [
      {
        "$city"             : "Seattle",
        "$region"           : "Washington",
        "$country"          : "US",
        "$zipcode"          : "98112"
      }
    ],
    "$listed_items"     : [
        {
          "$price"          : 2950000000, // $2950.00
          "$currency_code"  : "USD",
          "$tags"           : ["heat", "washer/dryer"]
        }
    ],
    "$images"           : [
        {
          "$md5_hash"       : "0cc175b9c0f1b6a831c399e269772661",
          "$link"           : "https://www.domain.com/file.png",
          "$description"    : "Billy's picture"
        }
    ],
    "$expiration_time"  : 1549063157000 // UNIX timestamp in milliseconds
  },

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

require "sift"

client = Sift::Client.new({api_key: "YOUR_API_KEY"})

# Sample $create_content event for listings
listing_properties = {
  # Required fields
  '$user_id'            => 'fyw3989sjpqr71',
  '$content_id'         => 'listing-23412',

  # Recommended fields
  '$session_id'         => 'a234ksjfgn435sfg',
  '$status'             => '$active',
  '$ip'                 => '255.255.255.0',

  # Required $listing object
  '$listing'            => {
    '$subject'          => '2 Bedroom Apartment for Rent',
    '$body'             => 'Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.',
    '$contact_email'    => 'alex_301@domain.com',
    '$contact_address'  => {
      '$name'           => 'Bill Jones',
      '$phone'          => '1-415-555-6041',
      '$city'           => 'New London',
      '$region'         => 'New Hampshire',
      '$country'        => 'US',
      '$zipcode'        => '03257'
    },
    '$locations'        => [
      {
        '$city'              => 'Seattle',
        '$region'            => 'Washington',
        '$country'           => 'US',
        '$zipcode'           => '98112'
      }
    ],
    '$listed_items'     => [
      {
        '$price'             => 2950000000, # $2950.00
        '$currency_code'     => 'USD',
        '$tags'              => ['heat', 'washer/dryer']
      }
    ],
    '$images'           => [
      {
        '$md5_hash'          => '0cc175b9c0f1b6a831c399e269772661',
        '$link'              => 'https =>//www.domain.com/file.png',
        '$description'       => 'Billy\'s picture'
      }
    ],
    '$expiration_time'       => 1549063157000 # UNIX timestamp in milliseconds
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

response = client.track("$create_content", listing_properties)
import sift

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

# Sample $create_content event for listings
listing_properties = {
  # Required fields
  "$user_id"                : "fyw3989sjpqr71",
  "$content_id"             : "listing-23412",

  # Recommended fields
  "$session_id"             : "a234ksjfgn435sfg",
  "$status"                 : "$active",
  "$ip"                     : "255.255.255.0",

  # Required $listing object
  "$listing"                : {
    "$subject"            : "2 Bedroom Apartment for Rent",
    "$body"               : "Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.",
    "$contact_email"      : "alex_301@domain.com",
    "$contact_address"    : {
      "$name"           : "Bill Jones",
      "$phone"          : "1-415-555-6041",
      "$city"           : "New London",
      "$region"         : "New Hampshire",
      "$country"        : "US",
      "$zipcode"        : "03257"
    },
    "$locations"          : [
      {
        "$city"           : "Seattle",
        "$region"         : "Washington",
        "$country"        : "US",
        "$zipcode"        : "98112"
      }
    ],
    "$listed_items"       : [
      {
        "$price"          : 2950000000, # $2950.00
        "$currency_code"  : "USD",
        "$tags"           : ["heat", "washer/dryer"]
      }
    ],
    "$images"             : [
      {
        "$md5_hash"       : "0cc175b9c0f1b6a831c399e269772661",
        "$link"           : "https://www.domain.com/file.png",
        "$description"    : "Billy's picture"
      }
    ],
    "$expiration_time"    : 1549063157000 # UNIX timestamp in milliseconds
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

response = client.track("$create_content", listing_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';

$event = '$create_content';
$client = new SiftClient(array('api_key' => YOUR_API_KEY));

// Sample $create_content event for listings
$listing_properties = array(
  // Required fields
  '$user_id'              => 'fyw3989sjpqr71',
  '$content_id'           => 'listing-23412',

  // Supported fields
  '$session_id'           => 'a234ksjfgn435sfg',
  '$status'               => '$active',
  '$ip'                   => '255.255.255.0',

  // Required $listing object
  '$listing'              => array(
    '$subject'            => '2 Bedroom Apartment for Rent',
      '$body'             => 'Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.',
      '$contact_email'    => 'alex_301@domain.com',
      '$contact_address'  => array(
        '$name'           => 'Bill Jones',
        '$phone'          => '1-415-555-6041',
        '$city'           => 'New London',
        '$region'         => 'New Hampshire',
        '$country'        => 'US',
        '$zipcode'        => '03257'
    ),
    '$locations'          => array(
      array(
        '$city'                => 'Seattle',
        '$region'              => 'Washington',
        '$country'             => 'US',
        '$zipcode'             => '98112'
      )
    ),
    '$listed_items'       => array(
      array(
        '$price'               => 2950000000, // $2950.00
        '$currency_code'       => 'USD',
        '$tags'                => array('heat', 'washer/dryer')
      )
    ),
    '$images'             => array(
      array(
        '$md5_hash'            => '0cc175b9c0f1b6a831c399e269772661',
        '$link'                => 'https://www.domain.com/file.png',
        '$description'         => 'Billy\'s picture'
      )
    ),
    '$expiration_time'    => 1549063157000 // UNIX timestamp in milliseconds
  ),

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$response = $client->track($event, $listing_properties);

import java.util.Arrays;

import com.siftscience.EventRequest;
import com.siftscience.EventResponse;
import com.siftscience.SiftClient;
import com.siftscience.exception.SiftException;
import com.siftscience.model.Address;
import com.siftscience.model.CreateListingFieldSet;
import com.siftscience.model.Image;
import com.siftscience.model.Item;
import com.siftscience.model.Listing;

SiftClient client = new SiftClient("YOUR_API_KEY");

// Sample $create_content event for listings
EventRequest request = client.buildRequest(new CreateListingFieldSet()
        // Required fields
        .setUserId("fyw3989sjpqr71")
        .setContentId("listing-23412")
        // Recommended fields
        .setSessionId("a234ksjfgn435sfg")
        .setStatus("$active")
        .setIp("255.255.255.0")
        // Required $listing object
        .setListing(new Listing()
                .setBody("Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.")
                .setContactAddress(new Address()
                        .setName("Bill Jones")
                        .setPhone("1-415-555-6041")
                        .setRegion("New Hampshire")
                        .setCity("New London")
                        .setCountry("US")
                        .setZipCode("03257"))
        .setLocations(Arrays.asList(new Address()
                .setCity("Seattle")
                .setRegion("Washington")
                .setCountry("US")
                .setZipCode("98112")))
                .setListedItems(Arrays.asList(new Item()
                        .setPrice(2950000000L) // $2950.00
                        .setCurrencyCode("USD")
                        .setTags(Arrays.asList("heat", "washer/dryer"))))
                .setImages(Arrays.asList(new Image()
                        .setMd5Hash("18E927C7E1229DC8F088643B7A65F978")
                        .setLink("https://www.domain.com/file.png")
                        .setDescription("An old picture")))
                .setExpirationTime(1471003200000L))); // UNIX timestamp in milliseconds
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

EventResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
    return;
}
response.isOk(); // true

$create_content.message

Use $create_content with a $message type to represent a message exchanged between users of your service.

  • $type
    required · String

    "$create_content"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $content_id
    required · String

    The unique ID that you assign to an individual piece of content in your system. Note: content IDs are case sensitive and must be unique across all content types..

  • $session_id
    String

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

  • $status
    String

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

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

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

  • $browser
    Browser

    The user agent of the browser that is used to create the message. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to create the message. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $message
    Object

    Contains information about the message.

    • $subject
      String

      The user-supplied subject of the message.

    • $body
      String

      The text content of the message.

    • $contact_email
      String

      The email address provided with the listing for contacting the poster. When no email address is provided for the listing, use the email address of the user account instead.

    • $root_content_id
      String

      The content_id in the context of which the messages is sent. For example, this would be the job listing being responded to.

    • $recipient_user_ids
      Array of Strings

      The user_ids of the recipients of the message.

    • $images
      Array of Images

      The list of images shared by the user with their message. It includes images pasted inline or attached separately.

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

// Sample $create_content event for messages
{
  // Required fields
  "$type"                  : "$create_content",
  "$api_key"               : "YOUR_API_KEY",
  "$user_id"               : "fyw3989sjpqr71",
  "$content_id"            : "message-23412",

  // Recommended fields
  "$session_id"            : "a234ksjfgn435sfg",
  "$status"                : "$active",
  "$ip"                    : "255.255.255.0",
  // Required $message object
  "$message"               : {
    "$body"                : "Let's meet at 5pm",
    "$contact_email"       : "alex_301@domain.com",
    "$recipient_user_ids"  : ["fy9h989sjphh71"],
    "$root_content_id"     : "listing-123",
    "$images"              : [
      {
        "$md5_hash"              : "0cc175b9c0f1b6a831c399e269772661",
        "$link"                  : "https://www.domain.com/file.png",
        "$description"           : "My hike today!"
      }
    ]
  },

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

require "sift"

client = Sift::Client.new({api_key: "YOUR_API_KEY"})

# Sample $create_content event for messages
message_properties = {
  # Required fields
  '$user_id'               => 'fyw3989sjpqr71',
  '$content_id'            => 'message-23412',

  # Recommended fields
  '$session_id'            => 'a234ksjfgn435sfg',
  '$status'                => '$active',
  '$ip'                    => '255.255.255.0',

  # Required $message object
  '$message'               => {
    '$body'                => 'Let\'s meet at 5pm',
    '$contact_email'       => 'alex_301@domain.com',
    '$recipient_user_ids'  => ['fy9h989sjphh71'],
    '$images'              => [
      {
        '$md5_hash'             => '0cc175b9c0f1b6a831c399e269772661',
        '$link'                 => 'https =>//www.domain.com/file.png',
        '$description'          => 'My hike today!'
      }
    ]
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

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

import sift

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

# Sample $create_content event for messages
message_properties = {
    # Required fields
    "$user_id"                 : "fyw3989sjpqr71",
    "$content_id"              : "message-23412",

    # Recommended fields
    "$session_id"              : "a234ksjfgn435sfg",
    "$status"                  : "$active",
    "$ip"                      : "255.255.255.0",

    # Required $message object
    "$message"                 : {
      "$body"                : "Let's meet at 5pm",
      "$contact_email"       : "alex_301@domain.com",
      "$recipient_user_ids"  : ["fy9h989sjphh71"],
      "$images"              : [
        {
          "$md5_hash"        : "0cc175b9c0f1b6a831c399e269772661",
          "$link"            : "https://www.domain.com/file.png",
          "$description"     : "My hike today!"
        }
      ]
    },

    # Send this information from a BROWSER client.
    "$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",
        "$accept_language"  : "en-US",
        "$content_language" : "en-GB"
    },

    # =========================================

    # Send this information from an APP client.
    "$app"        : {
      # 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",
      "$client_language"     : "en-US"
    }
}

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

require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$event = '$create_content';
$client = new SiftClient(array('api_key' => YOUR_API_KEY));

// Sample $create_content event for messages
$message_properties = array(
  // Required fields
  '$user_id'               => 'fyw3989sjpqr71',
  '$content_id'            => 'message-23412',

  // Recommended fields
  '$session_id'            => 'a234ksjfgn435sfg',
  '$status'                => '$active',
  '$ip'                    => '255.255.255.0',

  // Required $message object
  '$message'               => array(
    '$body'                => 'Let\'s meet at 5pm',
    '$contact_email'       => 'alex_301@domain.com',
    '$recipient_user_ids'  => array('fy9h989sjphh71'),
    '$images'              => array(
      array(
        '$md5_hash'             => '0cc175b9c0f1b6a831c399e269772661',
        '$link'                 => 'https://www.domain.com/file.png',
        '$description'          => 'My hike today!'
      )
    )
  ),

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$response = $client->track($event, $message_properties);

import java.util.Arrays;

import com.siftscience.EventRequest;
import com.siftscience.EventResponse;
import com.siftscience.SiftClient;
import com.siftscience.exception.SiftException;
import com.siftscience.model.Address;
import com.siftscience.model.CreateMessageFieldSet;
import com.siftscience.model.Image;
import com.siftscience.model.Message;

SiftClient client = new SiftClient("YOUR_API_KEY");

// Sample $create_content event for messages
EventRequest request = client.buildRequest(new CreateMessageFieldSet()
        // Required fields
        .setUserId("fyw3989sjpqr71")
        .setContentId("message-23412")
        // Recommended fields
        .setSessionId("a234ksjfgn435sfg")
        .setStatus("$active")
        .setIp("255.255.255.0")
        // Required $message object
        .setMessage(new Message()
                .setBody("Let's meet at 5pm")
                .setContactEmail("alex_301@domain.com")
                .setRecipientUserIds(Arrays.asList("fy9h989sjphh71"))
                .setImages(Arrays.asList(new Image()
                        .setMd5Hash("18E927C7E1229DC8F088643B7A65F978")
                        .setLink("https://www.domain.com/file.png")
                        .setDescription("An old picture")))));
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

EventResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
    return;
}
response.isOk(); // true

$create_content.post

Use $create_content with a $post type to represent information a user has shared with your community. Examples include social media posts like status updates, forum posts, blog articles, etc.

  • $type
    required · String

    "$create_content"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $content_id
    required · String

    The unique ID that you assign to an individual piece of content in your system. Note: content IDs are case sensitive and must be unique across all content types..

  • $session_id
    String

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

  • $status
    String

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

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

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

  • $browser
    Browser

    The user agent of the browser that is used to create the post. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to create the post. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $post
    Object

    Contains information about the post.

    • $subject
      String

      The user-supplied subject of the post.

    • $body
      String

      The text content of the post.

    • $contact_email
      String

      The email address provided with the post for contacting the poster. When no email address is provided for the listing, use the email address of the user account instead.

    • $contact_address
      Address

      The physical contact address provided with the post. When no address is provided for the post, use the physical address of the user account instead.

    • $locations
      Array of Addresses

      The locations associated with the post. In the example above, the locations array contains the check-in location of a social-media post. You can pass one or more addresses that are associated with your post. Pass as much information as you have. Partial addresses such as just the city and state are fine if that's all you have.

    • $categories
      Array of Strings

      The category or categories you associate with the posting. For example, a blog post might be categorized as ["Family", "Travel"].

    • $images
      Array of Images

      The list of images shared by the user with their post. It includes images pasted inline or attached separately.

    • $expiration_time
      Integer

      The UNIX timestamp in milliseconds of when the post will expire. Only set if the post is time bound in some way.

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

// Sample $create_content event for posts
{
  // Required fields
  "$type"               : "$create_content",
  "$api_key"            : "YOUR_API_KEY",
  "$user_id"            : "fyw3989sjpqr71",
  "$content_id"         : "post-23412",

  // Recommended fields
  "$session_id"         : "a234ksjfgn435sfg",
  "$status"             : "$active",
  "$ip"                 : "255.255.255.0",

  // Required $post object
  "$post"               : {
    "$subject"          : "My new apartment!",
    "$body"             : "Moved into my new apartment yesterday.",
    "$contact_email"    : "alex_301@domain.com",
    "$contact_address"  : {
      "$name"           : "Bill Jones",
      "$city"           : "New London",
      "$region"         : "New Hampshire",
      "$country"        : "US",
      "$zipcode"        : "03257"
    },
    "$locations"        : [
      {
        "$city"             : "Seattle",
        "$region"           : "Washington",
        "$country"          : "US",
        "$zipcode"          : "98112"
      }
    ],
    "$categories"       : ["Personal"],
    "$images"           : [
      {
        "$md5_hash"         : "0cc175b9c0f1b6a831c399e269772661",
        "$link"             : "https://www.domain.com/file.png",
        "$description"      : "View from the window!"
      }
    ],
    "$expiration_time"  : 1549063157000 // UNIX timestamp in milliseconds
  },

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

require "sift"

client = Sift::Client.new({api_key: "YOUR_API_KEY"})

# Sample $create_content event for posts
post_properties = {
  # Required fields
  '$user_id'            => 'fyw3989sjpqr71',
  '$content_id'         => 'post-23412',

  # Recommended fields
  '$session_id'         => 'a234ksjfgn435sfg',
  '$status'             => '$active',
  '$ip'                 => '255.255.255.0',

  # Required $post object
  '$post'               => {
    '$subject'          => 'My new apartment!',
    '$body'             => 'Moved into my new apartment yesterday.',
    '$contact_email'    => 'alex_301@domain.com',
    '$contact_address'  => {
      '$name'           => 'Bill Jones',
      '$city'           => 'New London',
      '$region'         => 'New Hampshire',
      '$country'        => 'US',
      '$zipcode'        => '03257'
    },
    '$locations'        => [
      {
        '$city'              => 'Seattle',
        '$region'            => 'Washington',
        '$country'           => 'US',
        '$zipcode'           => '98112'
      }
    ],
    '$categories'       => ['Personal'],
    '$images'           => [
      {
        '$md5_hash'          => '0cc175b9c0f1b6a831c399e269772661',
        '$link'              => 'https://www.domain.com/file.png',
        '$description'       => 'View from the window!'
      }
    ],
    '$expiration_time'  => 1549063157000 # UNIX timestamp in milliseconds
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

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

import sift

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

# Sample $create_content event for posts
post_properties = {
  # Required fields
  "$user_id"              : "fyw3989sjpqr71",
  "$content_id"           : "post-23412",

  # Recommended fields
  "$session_id"           : "a234ksjfgn435sfg",
  "$status"               : "$active",
  "$ip"                   : "255.255.255.0",

  # Required $post object
  "$post"                 : {
    "$subject"          : "My new apartment!",
    "$body"             : "Moved into my new apartment yesterday.",
    "$contact_email"    : "alex_301@domain.com",
    "$contact_address"  : {
      "$name"         : "Bill Jones",
      "$city"         : "New London",
      "$region"       : "New Hampshire",
      "$country"      : "US",
      "$zipcode"      : "03257"
    },
    "$locations"        : [
      {
        "$city"         : "Seattle",
        "$region"       : "Washington",
        "$country"      : "US",
        "$zipcode"      : "98112"
      }
    ],
    "$categories"       : ["Personal"],
    "$images"           : [
      {
        "$md5_hash"     : "0cc175b9c0f1b6a831c399e269772661",
        "$link"         : "https://www.domain.com/file.png",
        "$description"  : "View from the window!"
      }
    ],
    "$expiration_time"  : 1549063157000 # UNIX timestamp in milliseconds
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

response = client.track("$create_content", post_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';

$event = '$create_content';
$client = new SiftClient(array('api_key' => YOUR_API_KEY));

// Sample $create_content event for posts
$post_properties = array(
  // Required fields
  '$user_id' => 'fyw3989sjpqr71',
  '$content_id' => 'post-23412',

  // Recommended fields
  '$session_id'         => 'a234ksjfgn435sfg',
  '$status'             => '$active',
  '$ip'                 => '255.255.255.0',

  // Required $post object
  '$post'               => array(
    '$subject'          => 'My new apartment!',
    '$body'             => 'Moved into my new apartment yesterday.',
    '$contact_email'    => 'alex_301@domain.com',
    '$contact_address'  => array(
      '$name'                => 'Bill Jones',
      '$city'                => 'New London',
      '$region'              => 'New Hampshire',
      '$country'             => 'US',
      '$zipcode'             => '03257'
    ),
    '$locations'        => array(
      array(
        '$city'              => 'Seattle',
        '$region'            => 'Washington',
        '$country'           => 'US',
        '$zipcode'           => '98112'
      )
    ),
    '$categories'       => array('Personal'),
    '$images'           => array(
      array(
        '$md5_hash'          => '0cc175b9c0f1b6a831c399e269772661',
        '$link'              => 'https://www.domain.com/file.png',
        '$description'       => 'View from the window!'
      )
    ),
    '$expiration_time'  => 1549063157000
  ),

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$response = $client->track($event, $post_properties);

import java.util.Arrays;

import com.siftscience.EventRequest;
import com.siftscience.EventResponse;
import com.siftscience.SiftClient;
import com.siftscience.exception.SiftException;
import com.siftscience.model.Address;
import com.siftscience.model.CreatePostFieldSet;
import com.siftscience.model.Image;
import com.siftscience.model.Item;
import com.siftscience.model.Post;

SiftClient client = new SiftClient("YOUR_API_KEY");

// Sample $create_content event for posts
EventRequest request = client.buildRequest(new CreatePostFieldSet()
        // Required fields
        .setUserId("fyw3989sjpqr71")
        .setContentId("post-23412")
        // Recommended fields
        .setSessionId("a234ksjfgn435sfg")
        .setStatus("$active")
        .setIp("255.255.255.0")
        // Required $post object
        .setPost(new Post()
                .setSubject("My new apartment!")
                .setBody("Moved into my new apartment yesterday.")
                .setContactEmail("alex_301@domain.com")
                .setContactAddress(new Address()
                        .setName("Bill Jones")
                        .setPhone("1-415-555-6041")
                        .setRegion("New Hampshire")
                        .setCity("New London")
                        .setCountry("US")
                        .setZipCode("03257"))
                .setLocations(Arrays.asList(new Address()
                        .setCity("Seattle")
                        .setRegion("Washington")
                        .setCountry("US")
                        .setZipCode("98112")))
                .setCategories(Arrays.asList("Personal"))
                .setImages(Arrays.asList(new Image()
                        .setMd5Hash("18E927C7E1229DC8F088643B7A65F978")
                        .setLink("https://www.domain.com/file.png")
                        .setDescription("An old picture")))
                .setExpirationTime(1549063157000L))); // UNIX timestamp in milliseconds
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

EventResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
    return;
}
response.isOk(); // true

$create_content.profile

Use $create_content with a $profile type to represent information related to a user's profile. This may include a social media profile, dating profile, etc.

  • $type
    required · String

    "$create_content"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $content_id
    required · String

    The unique ID that you assign to an individual piece of content in your system. Note: content IDs are case sensitive and must be unique across all content types.

  • $session_id
    String

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

  • $status
    String

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

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

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

  • $browser
    Browser

    The user agent of the browser that is used to create the profile. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to create the profile. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $profile
    Object

    Contains information about the profile.

    • $body
      String

      The text content of the profile.

    • $contact_email
      String

      The email address provided with the profile for contacting the user. When no email address is provided for the listing, use the email address of the user account instead.

    • $contact_address
      Address

      The physical contact address provided with the profile. When no address is provided for the profile, use the physical address of the user account instead.

    • $images
      Array of Images

      The list of images shared by the user with their profile. It includes images pasted inline or attached separately.

    • $categories
      Array of Strings

      The category or categories you associate with the profile. For example, a profile on a services marketplace might be categorized as ["Photographer", "Weddings"].

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

// Sample $create_content event for profiles
{
  // Required fields
  "$type"               : "$create_content",
  "$api_key"            : "YOUR_API_KEY",
  "$user_id"            : "fyw3989sjpqr71",
  "$content_id"         : "profile-23412",

  // Recommended fields
  "$session_id"         : "a234ksjfgn435sfg",
  "$status"             : "active",
  "$ip"                 : "255.255.255.0",

  // Required $profile object
  "$profile"            : {
    "$body"             : "Hi! My name is Alex and I just moved to New London!",
    "$contact_email"    : "alex_301@domain.com",
    "$contact_address"  : {
    "$name"             : "Alex Smith",
    "$phone"            : "1-415-555-6041",
    "$city"             : "New London",
    "$region"           : "New Hampshire",
    "$country"          : "US",
    "$zipcode"          : "03257"
    },
    "$images"             : [
      {
        "$md5_hash"           : "0cc175b9c0f1b6a831c399e269772661",
        "$link"               : "https://www.domain.com/file.png",
        "$description"        : "Alex’s picture"
      }
    ],
    "$categories"         : ["Friends", "Long-term dating"]
  },

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

require "sift"

client = Sift::Client.new({api_key: "YOUR_API_KEY"})

# Sample $create_content event for profiles
profile_properties = {
  # Required fields
  '$user_id'            => 'fyw3989sjpqr71',
  '$content_id'         => 'profile-23412',

  # Recommended fields
  '$session_id'         => 'a234ksjfgn435sfg',
  '$status'             => '$active',
  '$ip'                 => '255.255.255.0',

  # Required $profile object
  '$profile'            => {
    '$body'             => 'Hi! My name is Alex and I just moved to New London!',
    '$contact_email'    => 'alex_301@domain.com',
    '$contact_address'  => {
      '$name'           => 'Alex Smith',
      '$phone'          => '1-415-555-6041',
      '$city'           => 'New London',
      '$region'         => 'New Hampshire',
      '$country'        => 'US',
      '$zipcode'        => '03257'
    },
    '$images'           => [
      {
        '$md5_hash'          => '0cc175b9c0f1b6a831c399e269772661',
        '$link'              => 'https://www.domain.com/file.png',
        '$description'       => 'Alex\'s picture'
      }
    ],
    '$categories'       => [
      'Friends',
      'Long-term dating'
    ]
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

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

import sift

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

# Sample $create_content event for reviews
profile_properties = {
  # Required fields
  "$user_id"              : "fyw3989sjpqr71",
  "$content_id"           : "profile-23412",

  # Recommended fields
  "$session_id"           : "a234ksjfgn435sfg",
  "$status"               : "$active",
  "$ip"                   : "255.255.255.0",

  # Required $profile object
  "$profile"              : {
    "$body"             : "Hi! My name is Alex and I just moved to New London!",
    "$contact_email"    : "alex_301@domain.com",
    "$contact_address"  : {
        "$name"         : "Alex Smith",
        "$phone"        : "1-415-555-6041",
        "$city"         : "New London",
        "$region"       : "New Hampshire",
        "$country"      : "US",
        "$zipcode"      : "03257"
    },
    "$images"           : [
      {
        "$md5_hash"     : "0cc175b9c0f1b6a831c399e269772661",
        "$link"         : "https://www.domain.com/file.png",
        "$description"  : "Alex's picture"
      }
    ],
    "$categories"       : [
      "Friends",
      "Long-term dating"
    ]
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

response = client.track("$create_content", profile_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';

$event = '$create_content';
$client = new SiftClient(array('api_key' => YOUR_API_KEY));

// Sample $create_content event for profiles
$profile_properties = array(
  // Required fields
  '$user_id'            => 'fyw3989sjpqr71',
  '$content_id'         => 'profile-23412',

  // Recommended fields
  '$session_id'         => 'a234ksjfgn435sfg',
  '$status'             => '$active',
  '$ip'                 => '255.255.255.0',

  // Required $profile object
  '$profile'            => array(
    '$body'             => 'Hi! My name is Alex and I just moved to New London!',
    '$contact_email'    => 'alex_301@domain.com',
    '$contact_address'  => array(
      '$name'           => 'Alex Smith',
      '$phone'          => '1-415-555-6041',
      '$city'           => 'New London',
      '$region'         => 'New Hampshire',
      '$country'        => 'US',
      '$zipcode'        => '03257'
    ),
    '$images'           => array(
      array(
        '$md5_hash'          => '0cc175b9c0f1b6a831c399e269772661',
        '$link'              => 'https://www.domain.com/file.png',
        '$description'       => 'Alex\'s picture'
      )
    ),
    '$categories'       => array(
      'Friends',
      'Long-term dating'
    )
  ),

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$response = $client->track($event, $profile_properties);

import java.util.Arrays;

import com.siftscience.EventRequest;
import com.siftscience.EventResponse;
import com.siftscience.SiftClient;
import com.siftscience.exception.SiftException;
import com.siftscience.model.Address;
import com.siftscience.model.CreateProfileFieldSet;
import com.siftscience.model.Image;
import com.siftscience.model.Profile;

SiftClient client = new SiftClient("YOUR_API_KEY");

// Sample $create_content event for profiles
EventRequest request = client.buildRequest(new CreateProfileFieldSet()
        // Required fields
        .setUserId("fyw3989sjpqr71")
        .setContentId("profile-23412")
        // Recommended fields
        .setSessionId("a234ksjfgn435sfg")
        .setStatus("$active")
        .setIp("255.255.255.0")
        // Required $profile object
        .setProfile(new Profile()
                .setBody("Hi! My name is Alex and I just moved to New London!")
                .setContactEmail("alex_301@domain.com")
                .setContactAddress(new Address()
                        .setName("Bill Jones")
                        .setPhone("1-415-555-6041")
                        .setRegion("New Hampshire")
                        .setCity("New London")
                        .setCountry("US")
                        .setZipCode("03257"))
                .setCategories(Arrays.asList("Friends", "Long-term dating"))
                .setImages(Arrays.asList(new Image()
                        .setMd5Hash("18E927C7E1229DC8F088643B7A65F978")
                        .setLink("https://www.domain.com/file.png")
                        .setDescription("An old picture")))));
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

EventResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
    return;
}
response.isOk(); // true

$create_content.review

Use $create_content with a $review type to represent information related to a product or service review submitted by your users.

  • $type
    required · String

    "$create_content"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $content_id
    required · String

    The unique ID that you assign to an individual piece of content in your system. Note: content IDs are case sensitive and must be unique across all content types.

  • $session_id
    String

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

  • $status
    String

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

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

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

  • $browser
    Browser

    The user agent of the browser that is used to create the review. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to create the review. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $review
    Object

    Contains information about the review.

    • $subject
      String

      The user-supplied title of the review.

    • $body
      String

      The text content of the review.

    • $contact_email
      String

      The email address provided with the review for contacting the reviewer. When no email address is provided for the listing, use the email address of the user account instead.

    • $locations
      Array of Addresses

      The locations associated with the review. In the example above, the location of the restaurant being reviewed. You can pass one or more addresses that are associated with your review. Pass as much information as you have. Partial addresses such as just the city and state are fine if that's all you have.

    • $item_reviewed
      Item

      An Item object representing the item being reviewed.

    • $reviewed_content_id
      String

      The $content_id of the item being reviewed. For example, this could be the id for the $listing or $profile being reviewed.

    • $rating
      Float

      A numeric rating supplied by the reviewer.

    • $images
      Array of Images

      The list of images shared by the user with their review. It includes images pasted inline or attached separately.

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

// Sample $create_content event for reviews
{
  // Required fields
  "$type"                   : "$create_content",
  "$api_key"                : "YOUR_API_KEY",
  "$user_id"                : "fyw3989sjpqr71",
  "$content_id"             : "review-23412",

  // Recommended fields
  "$session_id"             : "a234ksjfgn435sfg",
  "$status"                 : "$active",
  "$ip"                     : "255.255.255.0",

  // Required $review object
  "$review"                 : {
    "$subject"              : "Amazing Tacos!",
    "$body"                 : "I ate the tacos.",
    "$contact_email"        : "alex_301@domain.com",
    "$locations"            : [
      {
        "$city"                 : "Seattle",
        "$region"               : "Washington",
        "$country"              : "US",
        "$zipcode"              : "98112"
      }
    ],
    "$reviewed_content_id"  : "listing-234234",
    "$images"               : [
      {
        "$md5_hash"             : "0cc175b9c0f1b6a831c399e2697726618",
        "$link"                 : "https://www.domain.com/file.png",
        "$description"          : "Calamari tacos."
      }
    ],
    "$rating"               : 4.5
  },

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

require "sift"

client = Sift::Client.new({api_key: "YOUR_API_KEY"})

# Sample $create_content event for reviews
review_properties = {
  # Required fields
  '$user_id' => 'fyw3989sjpqr71',
  '$content_id' => 'review-23412',

  # Recommended fields
  '$session_id'             => 'a234ksjfgn435sfg',
  '$status'                 => '$active',
  '$ip'                     => '255.255.255.0',

  # Required $review object
  '$review'                 => {
    '$subject'              => 'Amazing Tacos!',
    '$body'                 => 'I ate the tacos.',
    '$contact_email'        => 'alex_301@domain.com',
    '$locations'            => [
      {
        '$city'                  => 'Seattle',
        '$region'                => 'Washington',
        '$country'               => 'US',
        '$zipcode'               => '98112'
      }
    ],
    '$reviewed_content_id'  => 'listing-234234',
    '$images'               => [
      {
        '$md5_hash'              => '0cc175b9c0f1b6a831c399e269772661',
        '$link'                  => 'https =>//www.domain.com/file.png',
        '$description'           => 'Calamari tacos.'
      }
    ],
    '$rating'               => 4.5
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

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

import sift

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

# Sample $create_content event for reviews
review_properties = {
  # Required fields
  "$user_id"                  : "fyw3989sjpqr71",
  "$content_id"               : "review-23412",

  # Recommended fields
  "$session_id"               : "a234ksjfgn435sfg",
  "$status"                   : "$active",
  "$ip"                       : "255.255.255.0",

  # Required $review object
  "$review"                   : {
    "$subject"              : "Amazing Tacos!",
    "$body"                 : "I ate the tacos.",
    "$contact_email"        : "alex_301@domain.com",
    "$locations"            : [
      {
        "$city"             : "Seattle",
        "$region"           : "Washington",
        "$country"          : "US",
        "$zipcode"          : "98112"
      }
    ],
    "$reviewed_content_id"  : "listing-234234",
    "$images"               : [
      {
        "$md5_hash"         : "0cc175b9c0f1b6a831c399e269772661",
        "$link"             : "https://www.domain.com/file.png",
        "$description"      : "Calamari tacos."
      }
    ],
    "$rating" : 4.5
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

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

$event = '$create_content';
$client = new SiftClient(array('api_key' => YOUR_API_KEY));

// Sample $create_content event for reviews
$review_properties = array(
  // Required fields
  '$user_id'                => 'fyw3989sjpqr71',
  '$content_id'             => 'review-23412',

  // Recommended fields
  '$session_id'             => 'a234ksjfgn435sfg',
  '$status'                 => '$active',
  '$ip'                     => '255.255.255.0',

  // Required $review object
  '$review'                 => array(
    '$subject'              => 'Amazing Tacos!',
    '$body'                 => 'I ate the tacos.',
    '$contact_email'        => 'alex_301@domain.com',
    '$locations'            => array(
      array(
        '$city'                 => 'Seattle',
        '$region'               => 'Washington',
        '$country'              => 'US',
        '$zipcode'              => '98112'
      )
    ),
    '$reviewed_content_id'  => 'listing-234234',
    '$images'               => array(
      array(
        '$md5_hash'             => '0cc175b9c0f1b6a831c399e269772661',
        '$link'                 => 'https://www.domain.com/file.png',
        '$description'          => 'Calamari tacos.'
      )
    ),
    '$rating'               => 4.5
  ),

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$response = $client->track($event, $review_properties);

import java.util.Arrays;

import com.siftscience.EventRequest;
import com.siftscience.EventResponse;
import com.siftscience.SiftClient;
import com.siftscience.exception.SiftException;
import com.siftscience.model.Address;
import com.siftscience.model.CreateReviewFieldSet;
import com.siftscience.model.Image;
import com.siftscience.model.Item;
import com.siftscience.model.Review;

SiftClient client = new SiftClient("YOUR_API_KEY");

// Sample $create_content event for reviews
EventRequest request = client.buildRequest(new CreateReviewFieldSet()
        // Required fields
        .setUserId("fyw3989sjpqr71")
        .setContentId("review-23412")
        // Recommended fields
        .setSessionId("a234ksjfgn435sfg")
        .setStatus("$active")
        .setIp("255.255.255.0")
        // Required $review object
        .setReview(new Review()
                .setSubject("Amazing Tacos!")
                .setBody("I ate the tacos.")
                .setContactEmail("alex_301@domain.com")
                .setLocations(Arrays.asList(new Address()
                        .setCity("Seattle")
                        .setRegion("Washington")
                        .setCountry("US")
                        .setZipCode("98112")))
                .setReviewedContentId("listing_234234")
                .setImages(Arrays.asList(new Image()
                        .setMd5Hash("18E927C7E1229DC8F088643B7A65F978")
                        .setLink("https://www.domain.com/file.png")
                        .setDescription("An old picture")))
                .setRating(4.5)));
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

EventResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
    return;
}
response.isOk(); // true

$create_order

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

  • $type
    required · String

    "$create_order"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $session_id
    String

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

  • $order_id
    String

    The ID for tracking this order in your system.

  • $user_email
    String

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

  • $verification_phone_number
    String

    Phone number of the user. This phone number will be used to send One-Time Password (OTP) when required. The phone number should be in E.164 format including + and a country code.

  • $amount
    Integer

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

  • $currency_code
    String

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

  • $billing_address
    Address

    The billing address as entered by the user.

  • $payment_methods
    Array of Payment Methods

    The payment information associated with this order.

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

  • $shipping_address
    Address

    The shipping address as entered by the user.

  • $expedited_shipping
    Boolean

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

  • $items
    Array of Items

    The list of items ordered. This may include physical products, gift cards, in-app purchases etc. Travel (Flights, Hotels, Rideshare, etc) and Event Ticketing customers should use $bookings instead of $items. $bookings supports specialized fields for modeling specific to Travel, Ticketing, and other cases where users make bookings. Note: cannot be used in conjunction with $bookings.

  • $bookings
    Array of Bookings

    The list of bookings made. This may include tickets and reservations like flights, hotels, rideshares etc. Note: cannot be used in conjunction with $items.

  • $seller_user_id
    String

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

  • $promotions
    Array of Promotions

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

  • $shipping_method
    String

    Indicates the method of delivery to the user.

    Allowed Values
    • "$electronic""$physical"
  • $shipping_carrier
    String

    Shipping carrier for the shipment of the product.

  • $shipping_tracking_number
    deprecated · String

    Shipping tracking number for the shipment of the product.

  • $shipping_tracking_numbers
    Array of Strings

    Shipping tracking number(s) for the shipment of the product(s).

  • $ordered_from
    Ordered From

    The details about the specific physical location providing the good or service. This can also be used to capture pickup, delivery locations, etc.

  • $browser
    Browser

    The user agent of the browser that is used to create the order. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to create the order. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

  • $merchant_profile
    Merchant Profile

    The details about the merchant or seller providing the goods or service.

// 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"                : "billjones1@example.com",
  "$verification_phone_number" : "+123456789012",
  "$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"
      }
  ],
  "$ordered_from" : {
    "$store_id"      : "123",
    "$store_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"
    }
  },
  "$brand_name"   : "sift",
  "$site_domain"  : "sift.com",
  "$site_country" : "US",
  "$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",
  "$shipping_carrier"         : "UPS",
  "$shipping_tracking_numbers": ["1Z204E380338943508", "1Z204E380338943509"],
  "$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"            : "6786211451001",
      "$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,

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

import sift

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

# Sample $create_order event
properties = {
  # Required Fields
  "$user_id"                   : "billy_jones_301",
  # Supported Fields
  "$session_id"                : "gigtleqddo84l8cm15qe4il",
  "$order_id"                  : "ORDER-28168441",
  "$user_email"                : "billjones1@example.com",
  "$verification_phone_number" : "+123456789012",
  "$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"
      }
  ],
  "$ordered_from" : {
    "$store_id"      : "123",
    "$store_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"
    }
  },
  "$brand_name"   : "sift",
  "$site_domain"  : "sift.com",
  "$site_country" : "US",
  "$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",
  "$shipping_carrier"         : "UPS",
  "$shipping_tracking_numbers": ["1Z204E380338943508", "1Z204E380338943509"],
  "$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"            : "6786211451001",
      "$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,

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

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"       => "billjones1@example.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"
    }
  ],
  "$ordered_from" => {
    "$store_id"      => "123",
    "$store_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"
    }
  },
  "$brand_name"   => "sift",
  "$site_domain"  => "sift.com",
  "$site_country" => "US",
  "$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",
  "$shipping_carrier"         => "UPS",
  "$shipping_tracking_numbers"=> ["1Z204E380338943508", "1Z204E380338943509"],
  "$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"            => "6786211451001",
      "$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,

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

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'
    )
  ),
  $ordered_from = array(
    '$store_id'      => '123',
    '$store_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'
    )
  ),
  '$brand_name'   => 'sift',
  '$site_domain'  => 'sift.com',
  '$site_country' => 'US',
  '$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',
  '$shipping_carrier'         => 'UPS',
  '$shipping_tracking_numbers'=> array('1Z204E380338943508', '1Z204E380338943509'),
  '$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'            => '6786211451001',
      '$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,

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$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("billjones1@example.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")))
        .setOrderedFrom(new OrderedFrom()
                .setStoreId("123")
                .setStoreAddress(new Address()
                        .setName("New London Stop")
                        .setAddress1("2100 Main Street")
                        .setCity("New London")
                        .setRegion("New Hampshire")
                        .setCountry("US")
                        .setZipCode("03257"))
        .setBrandName("sift")
        .setSiteDomain("sift.com")
        .setSiteCountry("US")
        .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")
        .setShippingCarrier("UPS")
        .setShippingTrackingNumbers(Arrays.asList("1Z204E380338943508", "1Z204E380338943509"))
        .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("6786211451001")
                        .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));
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

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 a user reports content that may violate your company’s policies. If you have a feature like "Report this post" or "Flag this profile", send that event to Sift using this reserved event.

  • $type
    required · String

    "$flag_content"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $content_id
    required · String

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

  • $flagged_by
    String

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

  • $reason
    String

    The reason provided by the flagger.

    Allowed Values
    • $toxicFoul language, harassment, hate speech or bullying. Example: Comments which contain hateful language.
    • $irrelevantThe content doesn't relate to the topic of discussion.
    • $commercialCommercial solicitations which are against your terms of service. For example, sending private messages to users to sell goods or services.
    • $phishingGenerally, taking user off your site to obtain sensitive information.
    • $privateThe content includes private information (like contact or identity information) that should not be shared.
    • $scamThe content is created to perpetrate a scam. For example, listings where the scammer will never ship the product. Or profiles for romance scammers.
    • $copyrightSharing any type of copyrighted content.
    • $otherAnything that doesn't fit in the above reasons.
  • $user_email
    String

    Email of the user logging in. 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.

  • $verification_phone_number
    String

    Phone number of the user. This phone number will be used to send One-Time Password (OTP) when required. The phone number should be in E.164 format including + and a country code.

// 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",
  "$reason"                    : "$toxic",
  "$user_email"                : "billjones1@example.com",
  "$verification_phone_number" : "+123456789012"
}

import sift

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

# 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

$link_session_to_user

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

  • $type
    required · String

    "$link_session_to_user"

  • $api_key
    required · String

    Your Sift REST API key.

  • $session_id
    required · String

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

  • $user_id
    required · String

    The user's account ID according to your systems. Note 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(api_key='{apiKey}', account_id='{accountId}')

# 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

$logout

Use $logout to record when a user logs out.

  • $type
    required · String

    "$logout"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $browser
    Browser

    The user agent of the browser that is used to logout. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to logout. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

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

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

import sift

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

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

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

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

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

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

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$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"))
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

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.

  • $type
    required · String

    "$order_status"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $order_id
    required · String

    The ID for tracking this order in your system.

  • $order_status
    required · String

    Indicates the high-level state of the order.

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

    The reason for a cancellation.

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

    The source of a decision.

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

    The analyst who made the decision, if manual.

  • $webhook_id
    String

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

  • $description
    String

    Any additional information about this order status change.

  • $browser
    Browser

    The user agent of the browser that is used to add the item to cart. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to add the item to cart. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

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

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}
import sift

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

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

  # Send this information from a BROWSER client.
  "$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"
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

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

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

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

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$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"));
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

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.

  • $type
    required · String

    "$remove_item_to_cart"

  • $api_key
    required · String

    Your Sift REST API key.

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

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

  • $user_id
    required · String

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

  • $item
    Item

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

  • $browser
    Browser

    The user agent of the browser that is used to remove the item from cart. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to remove the item from cart. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

  • $user_email
    String

    Email of the user logging in. 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.

  • $verification_phone_number
    String

    Phone number of the user. This phone number will be used to send One-Time Password (OTP) when required. The phone number should be in E.164 format including + and a country code.

// 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",
  "$user_email"                : "billjones1@example.com",
  "$verification_phone_number" : "+123456789012",
  "$item"                      : {
    "$item_id"        : "B004834GQO",
    "$product_title"  : "The Slanket Blanket-Texas Tea",
    "$price"          : 39990000, // $39.99
    "$currency_code"  : "USD",
    "$quantity"       : 2,
    "$upc"            : "6786211451001",
    "$sku"            : "004834GQ",
    "$brand"          : "Slanket",
    "$manufacturer"   : "Slanket",
    "$category"       : "Blankets & Throws",
    "$tags"           : ["Awesome", "Wintertime specials"],
    "$color"          : "Texas Tea"
  },

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

import sift

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

# 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"            : "6786211451001",
    "$sku"            : "004834GQ",
    "$brand"          : "Slanket",
    "$manufacturer"   : "Slanket",
    "$category"       : "Blankets & Throws",
    "$tags"           : ["Awesome", "Wintertime specials"],
    "$color"          : "Texas Tea"
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

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"            => "6786211451001",
    "$sku"            => "004834GQ",
    "$brand"          => "Slanket",
    "$manufacturer"   => "Slanket",
    "$category"       => "Blankets & Throws",
    "$tags"           => ["Awesome", "Wintertime specials"],
    "$color"          => "Texas Tea"
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

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'            => '6786211451001',
    '$sku'            => '004834GQ',
    '$brand'          => 'Slanket',
    '$manufacturer'   => 'Slanket',
    '$category'       => 'Blankets & Throws',
    '$tags'           => array('Awesome', 'Wintertime specials'),
    '$color'          => 'Texas Tea'
  ),

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$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("6786211451001")
                .setSku("004834GQ")
                .setBrand("Slanket")
                .setManufacturer("Slanket")
                .setCategory("Blankets & Throws")
                .setTags(Arrays.asList("Awesome", "Wintertime specials"))
                .setQuantity(16L)));
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

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.

  • $type
    required · String

    "$security_notification"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $session_id
    Required · String

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

  • $notification_type
    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_value
    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_status
    required · String/Enum

    The status of the notification event: records the follow-up action taken by the notified user.

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

    The user agent of the browser that is used to add the item to cart. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to add the item to cart. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

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

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

import sift

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

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

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

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

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

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

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$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"));
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

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.

  • $type
    required · String

    "$transaction"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $user_email
    String

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

  • $verification_phone_number
    String

    Phone number of the user. This phone number will be used to send One-Time Password (OTP) when required. The phone number should be in E.164 format including + and a country code.

  • $transaction_type
    String

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

    Allowed Values
    • $saleAuthorization and capture of a payment performed together in one step. This is the most commonly used transaction type. This is the default $transaction_type if the transaction type is not provided.
    • $authorizeAuthorizing a payment by reserving the payment amount from the buyer's account. Money does not change hands until capture.
    • $captureCapturing a payment reserved in the authorization step.
    • $voidCancelling a pending authorization or capture.
    • $refundReturning part or all of a captured payment to the buyer.
    • $depositDepositing money into an account.
    • $withdrawalWithdrawing money from an account.
    • $transferTransferring money from one account to another.
    • $buyAcquisition of an asset, for example the purchase of cryptocurrency.
    • $sellDisposal of an underlying asset, for example the sale of cryptocurrency.
    • $sendRepresents the movement of assets or funds between different wallets, exchanges, or accounts. For example, sending funds through remittance services.
    • $receiveRepresents the movement of assets or funds between different wallets, exchanges, or accounts. For example, receiving funds through remittance services.
  • $transaction_status
    String

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

  • $amount
    Required · Integer

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

  • $currency_code
    Required · String

    ISO-4217 currency code for the amount. e.g., USD, CAD, HKD, BTC.

  • $order_id
    String

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

  • $transaction_id
    String

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

  • $billing_address
    Address

    The billing address as entered by the user.

  • $payment_method
    Payment Method Object

    The payment information associated with this transaction.

  • $shipping_address
    Address

    The shipping address as entered by the user.

  • $session_id
    String

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

  • $seller_user_id
    String

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

  • $transfer_recipient_user_id
    String

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

  • $decline_category
    String

    Use $decline_category to indicate the category of a transaction decline sent by the PSP.


    Please note: Only send this field when $transaction_status is $failure. Sending for transactions with $transaction_status $success, $pending or empty will result in error.


    This field trains the model on decline reasons across PSPs, helping Sift catch card testing and traditional payments fraud.

    Allowed Values
    • $fraud $lost_or_stolen $risky $bank_decline $invalid $expired $insufficient_funds $limit_exceeded $additional_verification_required $invalid_verification $other

    For more explanation and a mapping for major PSPs, visit the $decline_category Guide.

  • $ordered_from
    Ordered From

    The details about the specific physical location providing the good or service. This can also be used to capture pickup, delivery locations, etc.

  • $browser
    Browser

    The user agent of the browser that is used to create the transaction. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to create the transaction. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

  • $status_3ds
    String

    Use the following allowed values to indicate the status of a 3DS request.

    Allowed Values
    • "$successful" "$attempted" "$failed" "$unavailable" "$rejected"
  • $triggered_3ds
    String

    Use $processor to reflect a challenge initiated by the processor. Use $merchant to indicate if the challenge was recommended by Sift via a workflow or a manual review.

  • $merchant_initiated_transaction
    Boolean

    Use true or false to indicate if this is a recurring payment for the same amount to the same merchant (recurring payments are considered out of scope for SCA).

  • $merchant_profile
    Merchant Profile

    The details about the merchant or seller providing the goods or service.

  • $sent_address
    Address

    The address to the specific physical location of the person sending a transaction.

  • $received_address
    Address

    The address to the specific physical location of the person receiving a transaction.

// 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"                : "billjones1@example.com",
  "$verification_phone_number" : "+123456789012",
  "$transaction_type"          : "$sale",
  "$transaction_status"        : "$failure",
  "$decline_category"          : "$bank_decline"
  "$order_id"                  : "ORDER-123124124",
  "$transaction_id"            : "719637215",

  "$billing_address"  : { // or "$sent_address" // or "$received_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"
  },
  "$brand_name"   : "sift",
  "$site_domain"  : "sift.com",
  "$site_country" : "US",
  "$ordered_from" : {
    "$store_id"      : "123",
    "$store_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"
    }
  },
  // 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 the field description

  // Supported fields for 3DS
  "$status_3ds"                     : "$attempted",
  "$triggered_3ds"                  : "$processor",
  "$merchant_initiated_transaction" : false,

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

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

import sift

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

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

  # Supported Fields
  "$user_email"                : "billjones1@example.com",
  "$verification_phone_number" : "+123456789012",
  "$transaction_type"          : "$sale",
  "$transaction_status"        : "$failure",
  "$decline_category"          : "$bank_decline",
  "$order_id"                  : "ORDER-123124124",
  "$transaction_id"            : "719637215",

  "$billing_address"  : { # or "$sent_address" # or "$received_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"
  },
  "$brand_name"   : "sift",
  "$site_domain"  : "sift.com",
  "$site_country" : "US",
  "$ordered_from" : {
    "$store_id"      : "123",
    "$store_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"
    }
  },
  # 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 the field description

  # Supported fields for 3DS
  "$status_3ds"                     : "$attempted",
  "$triggered_3ds"                  : "$processor",
  "$merchant_initiated_transaction" : false,

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

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

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"       => "billjones1@example.com",
  "$transaction_type" => "$sale",
  "$transaction_status" => "$failure",
  "$decline_category" => "$bank_decline",
  "$order_id"         => "ORDER-123124124",
  "$transaction_id"   => "719637215",

  "$billing_address"  => { # or "$sent_address" # or "$received_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"
  },
  "$brand_name"   => "sift",
  "$site_domain"  => "sift.com",
  "$site_country" => "US",
  "$ordered_from" => {
    "$store_id"      => "123",
    "$store_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"
    }
  },
  # 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 the field description

  # Supported fields for 3DS
  "$status_3ds"                     => "$attempted",
  "$triggered_3ds"                  => "$processor",
  "$merchant_initiated_transaction" => false,

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

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

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' => '$failure',
  '$decline_category' => '$bank_decline',
  '$order_id'         => 'ORDER-123124124',
  '$transaction_id'   => '719637215',

  '$billing_address'  => array( // or "$sent_address" // or "$received_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'
  ),
  '$brand_name'   => 'sift',
  '$site_domain'  => 'sift.com',
  '$site_country' => 'US',
  $ordered_from = array(
    '$store_id'      => '123',
    '$store_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'
    )
  ),
  // 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 the field description

  // Supported fields for 3DS
  '$status_3ds'                     => '$attempted',
  '$triggered_3ds'                  => '$processor',
  '$merchant_initiated_transaction' => false,

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

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$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("billjones1@example.com")
        .setTransactionType("$sale")
        .setTransactionStatus("$failure")
        .setDeclineCategory("$bank_decline")
        .setOrderId("ORDER-123124124")
        .setTransactionId("719637215")
        .setBillingAddress(new Address() // or setSentAddress // or setReceivedAddress
            .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"))
        .setBrandName("sift")
        .setSiteDomain("sift.com")
        .setSiteCountry("US")
        .setOrderedFrom(new OrderedFrom()
                .setStoreId("123")
                .setStoreAddress(new Address()
                        .setName("New London Stop")
                        .setAddress1("2100 Main Street")
                        .setCity("New London")
                        .setRegion("New Hampshire")
                        .setCountry("US")
                        .setZipCode("03257"))
        .setPaymentMethod(new PaymentMethod()
            .setPaymentType("$credit_card")
            .setPaymentGateway("$braintree")
            .setCardBin("542486")
            .setCardLast4("4444"))
        .setStatus3Ds("$attempted")
        .setTriggered3Ds("$processor")
        .setMerchantInitiatedTransaction(false)
        .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));
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

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 content created previously with a $create_content event.

  • 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 content 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 the content was created before your integration with Sift.

$update_content.comment

Use $update_content with a $comment type to tell Sift whenever a user posts into the comment section your site. Examples of comments include a comment on a social media or blog post, and discussion sections on news articles.

  • $type
    required · String

    "$update_content"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $content_id
    required · String

    The unique ID that you assign to an individual piece of content in your system. Note: content IDs are case sensitive and must be unique across all content types.

  • $session_id
    String

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

  • $status
    String

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

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

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

  • $browser
    Browser

    The user agent of the browser that is used to update the comment. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to update the comment. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $comment
    Object

    Contains information about the comment.

    • $body
      String

      The text content of the comment.

    • $contact_email
      String

      The email address provided with the listing for contacting the poster. When no email address is provided for the listing, use the email address of the user account instead.

    • $parent_comment_id
      String

      The $content_id of the immediate parent comment, i.e. the comment being replied to. Only use if it is a reply to a previous comment.

    • $root_content_id
      String

      The $content_id of the content being commented on. For example, this would be the id of the social media $post to which the comment applies.

    • $images
      Array of Images

      The list of images shared by the user with their comment. It includes images pasted inline or attached separately.

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

// Sample $update_content event for comments
{
  // Required fields
  "$type"                 : "$update_content",
  "$api_key"              : "YOUR_API_KEY",
  "$user_id"              : "fyw3989sjpqr71",
  "$content_id"           : "comment-23412",

  // Recommended fields
  "$session_id"           : "a234ksjfgn435sfg",
  "$status"               : "$active",
  "$ip"                   : "255.255.255.0",

  // Required $comment object
  "$comment"              : {
    "$body"               : "Congrats on the new role!",
    "$contact_email"      : "alex_301@domain.com",
    "$parent_comment_id"  : "comment-23407",
    "$root_content_id"    : "listing-12923213",
    "$images"             : [
      {
        "$md5_hash"           : "0cc175b9c0f1b6a831c399e269772661",
        "$link"               : "https://www.domain.com/file.png",
        "$description"        : "An old picture"
      }
    ]
  },

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

require "sift"

client = Sift::Client.new({api_key: "YOUR_API_KEY"})

# Sample $update_content event for comments
comment_properties = {
  # Required fields
  '$user_id'              => 'fyw3989sjpqr71',
  '$content_id'           => 'comment-23412',

  # Recommended fields
  '$session_id'           => 'a234ksjfgn435sfg',
  '$status'               => '$active',
  '$ip'                   => '255.255.255.0',

  # Required $comment object
  '$comment'              => {
    '$body'               => 'Congrats on the new role!',
    '$contact_email'      => 'alex_301@domain.com',
    '$parent_comment_id'  => 'comment-23407',
    '$root_content_id'    => 'listing-12923213',
    '$images'             => [
      {
        '$md5_hash'            => '0cc175b9c0f1b6a831c399e269772661',
        '$link'                => 'https://www.domain.com/file.png',
        '$description'         => 'An old picture'
      }
    ]
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

response = client.track("$update_content", comment_properties)

import sift

client = sift.Client(api_key="YOUR_API_KEY")

# Sample $update_content event for comments
comment_properties = {
  # Required fields
  "$user_id"                : "fyw3989sjpqr71",
  "$content_id"             : "comment-23412",

  # Recommended fields
  "$session_id"             : "a234ksjfgn435sfg",
  "$status"                 : "$active",
  "$ip"                     : "255.255.255.0",

  # Required $comment object
  "$comment"                : {
    "$body"               : "Congrats on the new role!",
    "$contact_email"      : "alex_301@domain.com",
    "$parent_comment_id"  : "comment-23407",
    "$root_content_id"    : "listing-12923213",
    "$images"             : [
      {
        "$md5_hash"       : "0cc175b9c0f1b6a831c399e269772661",
        "$link"           : "https://www.domain.com/file.png",
        "$description"    : "An old picture"
      }
    ]
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

response = client.track("$update_content", comment_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';

$event = '$update_content';
$client = new SiftClient(array('api_key' => YOUR_API_KEY));

// Sample $update_content event for comments
$comment_properties = array(
  // Required fields
  '$user_id' => 'fyw3989sjpqr71',
  '$content_id' => 'comment-23412',

  // Recommended fields
  '$session_id'           => 'a234ksjfgn435sfg',
  '$status'               => '$active',
  '$ip'                   => '255.255.255.0',

  // Required $comment object
  '$comment'              => array(
    '$body'               => 'Congrats on the new role!',
    '$contact_email'      => 'alex_301@domain.com',
    '$parent_comment_id'  => 'comment-23407',
    '$root_content_id'    => 'listing-12923213',
    '$images'             => array(
      array(
        '$md5_hash'            => '0cc175b9c0f1b6a831c399e269772661',
        '$link'                => 'https://www.domain.com/file.png',
        '$description'         => 'An old picture'
      )
    )
  ),

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$response = $client->track($event, $comment_properties);
import java.util.Arrays;

import com.siftscience.EventRequest;
import com.siftscience.EventResponse;
import com.siftscience.SiftClient;
import com.siftscience.exception.SiftException;
import com.siftscience.model.Comment;
import com.siftscience.model.CreateCommentFieldSet;
import com.siftscience.model.Image;

SiftClient client = new SiftClient("YOUR_API_KEY");

// Sample $update_content event for comments
EventRequest request = client.buildRequest(new CreateCommentFieldSet()
        // Required fields
        .setUserId("fyw3989sjpqr71")
        .setContentId("comment-23412")
        // Recommended fields
        .setSessionId("a234ksjfgn435sfg")
        .setStatus("$active")
        .setIp("255.255.255.0")
        // Required $commend object
        .setComment(new Comment()
                .setBody("Congrats on the new role!")
                .setContactEmail("alex_301@domain.com")
                .setParentCommentId("comment_23407")
                .setRootContentId("listing-12923213")
                .setImages(Arrays.asList(new Image()
                        .setMd5Hash("18E927C7E1229DC8F088643B7A65F978")
                        .setLink("https://www.domain.com/file.png")
                        .setDescription("An old picture")))));
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

EventResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
    return;
}
response.isOk(); // true

$update_content.listing

Use $update_content with a $listing type whenever a user updates a listing on your site. Examples of listings include job listing, product for sale, or an apartment for rent.

  • $type
    required · String

    "$update_content"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $content_id
    required · String

    The unique ID that you assign to an individual piece of content in your system. Note: content IDs are case sensitive and must be unique across all content types.

  • $session_id
    String

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

  • $status
    String

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

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

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

  • $browser
    Browser

    The user agent of the browser that is used to update the listing. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to update the listing. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $listing
    Object

    Contains information about the listing.

    • $subject
      String

      The subject of the listing.

    • $body
      String

      The text content of the listing.

    • $contact_email
      String

      The email address provided with the listing for contacting the poster. When no email address is provided for the listing, use the email address of the user account instead.

    • $contact_address
      Address

      The physical contact address provided with the listing. When no address is provided for the listing, use the physical address of the user account instead.

    • $locations
      Array of Addresses

      The locations associated with the listing. For example, this array would contain the location of the rental listing. You can pass one or more addresses that are associated with your listing. Pass as much information as you have. Partial addresses such as just the city and state are fine if that's all you have.

    • $listed_items
      Array of Items

      The items array represents physical or digital items listed by the user.

    • $images
      Array of Images

      The list of images shared by the user with their listing. It includes images pasted inline or attached separately.

    • $expiration_time
      Integer

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

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

// Sample $update_content event for listings
{
  // Required fields
  "$type"               : "$update_content",
  "$api_key"            : "YOUR_API_KEY",
  "$user_id"            : "fyw3989sjpqr71",
  "$content_id"         : "listing-23412",

  // Recommended fields
  "$session_id"         : "a234ksjfgn435sfg",
  "$status"             : "$active",
  "$ip"                 : "255.255.255.0",

  // Required $listing object
  "$listing"            : {
    "$subject"          : "2 Bedroom Apartment for Rent",
    "$body"             : "Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.",
    "$contact_email"    : "alex_301@domain.com",
    "$contact_address"  : {
      "$name"           : "Bill Jones",
      "$phone"          : "1-415-555-6041",
      "$city"           : "New London",
      "$region"         : "New Hampshire",
      "$country"        : "US",
      "$zipcode"        : "03257"
    },
    "$locations"        : [
      {
        "$city"             : "Seattle",
        "$region"           : "Washington",
        "$country"          : "US",
        "$zipcode"          : "98112"
      }
    ],
    "$listed_items"     : [
      {
        "$price"            : 2950000000, // $2950.00
        "$currency_code"    : "USD",
        "$tags"             : ["heat", "washer/dryer"]
      }
    ],
    "$images"           : [
      {
        "$md5_hash"         : "0cc175b9c0f1b6a831c399e269772661",
        "$link"             : "https://www.domain.com/file.png",
        "$description"      : "Billy's picture"
      }
    ],
    "$expiration_time"  : 1549063157000 // UNIX timestamp in milliseconds
  },

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

require "sift"

client = Sift::Client.new({api_key: "YOUR_API_KEY"})

# Sample $update_content event for listings
listing_properties = {
  # Required fields
  '$user_id'            => 'fyw3989sjpqr71',
  '$content_id'         => 'listing-23412',

  # Recommended fields
  '$session_id'         => 'a234ksjfgn435sfg',
  '$status'             => '$active',
  '$ip'                 => '255.255.255.0',

  # Required $listing object
  '$listing'            => {
    '$subject'          => '2 Bedroom Apartment for Rent',
    '$body'             => 'Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.',
    '$contact_email'    => 'alex_301@domain.com',
    '$contact_address'  => {
      '$name'           => 'Bill Jones',
      '$phone'          => '1-415-555-6041',
      '$city'           => 'New London',
      '$region'         => 'New Hampshire',
      '$country'        => 'US',
      '$zipcode'        => '03257'
    },
    '$locations'        => [
      {
        '$city'              => 'Seattle',
        '$region'            => 'Washington',
        '$country'           => 'US',
        '$zipcode'           => '98112'
      }
    ],
    '$listed_items'     => [
      {
        '$price'             => 2950000000, # $2950.00
        '$currency_code'     => 'USD',
        '$tags'              => ['heat', 'washer/dryer']
      }
    ],
    '$images'           => [
      {
        '$md5_hash'          => '0cc175b9c0f1b6a831c399e269772661',
        '$link'              => 'https =>//www.domain.com/file.png',
        '$description'       => 'Billy\'s picture'
      }
    ],
    '$expiration_time'       => 1549063157000 # UNIX timestamp in milliseconds
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

response = client.track("$update_content", listing_properties)
import sift

client = sift.Client(api_key="YOUR_API_KEY")

# Sample $update_content event for listings
listing_properties = {
  # Required fields
  "$user_id"                : "fyw3989sjpqr71",
  "$content_id"             : "listing-23412",

  # Recommended fields
  "$session_id"             : "a234ksjfgn435sfg",
  "$status"                 : "$active",
  "$ip"                     : "255.255.255.0",

  # Required $listing object
  "$listing"                : {
    "$subject"            : "2 Bedroom Apartment for Rent",
    "$body"               : "Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.",
    "$contact_email"      : "alex_301@domain.com",
    "$contact_address"    : {
      "$name"           : "Bill Jones",
      "$phone"          : "1-415-555-6041",
      "$city"           : "New London",
      "$region"         : "New Hampshire",
      "$country"        : "US",
      "$zipcode"        : "03257"
    },
    "$locations"          : [
      {
        "$city"           : "Seattle",
        "$region"         : "Washington",
        "$country"        : "US",
        "$zipcode"        : "98112"
      }
    ],
    "$listed_items"       : [
      {
        "$price"          : 2950000000, # $2950.00
        "$currency_code"  : "USD",
        "$tags"           : ["heat", "washer/dryer"]
      }
    ],
    "$images"             : [
      {
        "$md5_hash"       : "0cc175b9c0f1b6a831c399e269772661",
        "$link"           : "https://www.domain.com/file.png",
        "$description"    : "Billy's picture"
      }
    ],
    "$expiration_time"    : 1549063157000 # UNIX timestamp in milliseconds
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

response = client.track("$update_content", listing_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';

$event = '$update_content';
$client = new SiftClient(array('api_key' => YOUR_API_KEY));

// Sample $update_content event for listings
$listing_properties = array(
  // Required fields
  '$user_id'            => 'fyw3989sjpqr71',
  '$content_id'         => 'listing-23412',

  // Supported fields
  '$session_id'         => 'a234ksjfgn435sfg',
  '$status'             => '$active',
  '$ip'                 => '255.255.255.0',

  // Required $listing object
  '$listing'            => array(
    '$subject'          => '2 Bedroom Apartment for Rent',
    '$body'             => 'Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.',
    '$contact_email'    => 'alex_301@domain.com',
    '$contact_address'  => array(
      '$name'           => 'Bill Jones',
      '$phone'          => '1-415-555-6041',
      '$city'           => 'New London',
      '$region'         => 'New Hampshire',
      '$country'        => 'US',
      '$zipcode'        => '03257'
    ),
    '$locations'        => array(
      array(
        '$city'             => 'Seattle',
        '$region'           => 'Washington',
        '$country'          => 'US',
        '$zipcode'          => '98112'
      )
    ),
    '$listed_items'     => array(
      array(
        '$price'             => 2950000000, // $2950.00
        '$currency_code'     => 'USD',
        '$tags'              => array('heat', 'washer/dryer')
      )
    ),
    '$images'           => array(
      array(
        '$md5_hash'          => '0cc175b9c0f1b6a831c399e269772661',
        '$link'              => 'https://www.domain.com/file.png',
        '$description'       => 'Billy\'s picture'
      )
    ),
    '$expiration_time'  => 1549063157000 // UNIX timestamp in milliseconds
  ),

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$response = $client->track($event, $listing_properties);
import java.util.Arrays;

import com.siftscience.EventRequest;
import com.siftscience.EventResponse;
import com.siftscience.SiftClient;
import com.siftscience.exception.SiftException;
import com.siftscience.model.Address;
import com.siftscience.model.CreateListingFieldSet;
import com.siftscience.model.Image;
import com.siftscience.model.Item;
import com.siftscience.model.Listing;

SiftClient client = new SiftClient("YOUR_API_KEY");

// Sample $update_content event for listings
EventRequest request = client.buildRequest(new CreateListingFieldSet()
        // Required fields
        .setUserId("fyw3989sjpqr71")
        .setContentId("listing-23412")
        // Recommended fields
        .setSessionId("a234ksjfgn435sfg")
        .setStatus("$active")
        .setIp("255.255.255.0")
        // Required $listing object
        .setListing(new Listing()
                .setBody("Capitol Hill Seattle brand new condo. 2 bedrooms and 1 full bath.")
                .setContactAddress(new Address()
                        .setName("Bill Jones")
                        .setPhone("1-415-555-6041")
                        .setRegion("New Hampshire")
                        .setCity("New London")
                        .setCountry("US")
                        .setZipCode("03257"))
                .setLocations(Arrays.asList(new Address()
                        .setCity("Seattle")
                        .setRegion("Washington")
                        .setCountry("US")
                        .setZipCode("98112")))
                .setListedItems(Arrays.asList(new Item()
                        .setPrice(2950000000L) // $2950.00
                        .setCurrencyCode("USD")
                        .setTags(Arrays.asList("heat", "washer/dryer"))))
                .setImages(Arrays.asList(new Image()
                        .setMd5Hash("18E927C7E1229DC8F088643B7A65F978")
                        .setLink("https://www.domain.com/file.png")
                        .setDescription("An old picture")))
                .setExpirationTime(1471003200000L))); // UNIX timestamp in milliseconds
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

EventResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
    return;
}
response.isOk(); // true

$update_content.message

Use $update_content with a $message type to represent a message exchanged between users of your service.

  • $type
    required · String

    "$update_content"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $content_id
    required · String

    The unique ID that you assign to an individual piece of content in your system. Note: content IDs are case sensitive and must be unique across all content types..

  • $session_id
    String

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

  • $status
    String

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

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

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

  • $browser
    Browser

    The user agent of the browser that is used to update the message. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to update the message. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $message
    Object

    Contains information about the message.

    • $subject
      String

      The user-supplied subject of the message.

    • $body
      String

      The text content of the message.

    • $contact_email
      String

      The email address provided with the listing for contacting the poster. When no email address is provided for the listing, use the email address of the user account instead.

    • $root_content_id
      String

      The content_id in the context of which the messages is sent. For example, this would be the job listing being responded to.

    • $recipient_user_ids
      Array of Strings

      The user_ids of the recipients of the message.

    • $images
      Array of Images

      The list of images shared by the user with their message. It includes images pasted inline or attached separately.

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

// Sample $update_content event for messages
{
  // Required fields
  "$type"                  : "$update_content",
  "$api_key"               : "YOUR_API_KEY",
  "$user_id"               : "fyw3989sjpqr71",
  "$content_id"            : "message-23412",

  // Recommended fields
  "$session_id"            : "a234ksjfgn435sfg",
  "$status"                : "$active",
  "$ip"                    : "255.255.255.0",
  // Required $message object
  "$message"               : {
    "$body"                : "Let's meet at 5pm",
    "$contact_email"       : "alex_301@domain.com",
    "$recipient_user_ids"  : ["fy9h989sjphh71"],
    "$root_content_id"     : "listing-123",
    "$images"              : [
      {
        "$md5_hash"              : "0cc175b9c0f1b6a831c399e269772661",
        "$link"                  : "https://www.domain.com/file.png",
        "$description"           : "My hike today!"
      }
    ]
  },

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

require "sift"

client = Sift::Client.new({api_key: "YOUR_API_KEY"})

# Sample $update_content event for messages
message_properties = {
  # Required fields
  '$user_id'               => 'fyw3989sjpqr71',
  '$content_id'            => 'message-23412',

  # Recommended fields
  '$session_id'            => 'a234ksjfgn435sfg',
  '$status'                => '$active',
  '$ip'                    => '255.255.255.0',

  # Required $message object
  '$message'               => {
    '$body'                => 'Let\'s meet at 5pm',
    '$contact_email'       => 'alex_301@domain.com',
    '$recipient_user_ids'  => ['fy9h989sjphh71'],
    '$images'              => [
      {
        '$md5_hash'             => '0cc175b9c0f1b6a831c399e269772661',
        '$link'                 => 'https =>//www.domain.com/file.png',
        '$description'          => 'My hike today!'
      }
    ]
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

response = client.track("$update_content", message_properties)

import sift

client = sift.Client(api_key="YOUR_API_KEY")

# Sample $update_content event for messages
message_properties = {
  # Required fields
  "$user_id"                 : "fyw3989sjpqr71",
  "$content_id"              : "message-23412",

  # Recommended fields
  "$session_id"              : "a234ksjfgn435sfg",
  "$status"                  : "$active",
  "$ip"                      : "255.255.255.0",

  # Required $message object
  "$message"                 : {
    "$body"                : "Let's meet at 5pm",
    "$contact_email"       : "alex_301@domain.com",
    "$recipient_user_ids"  : ["fy9h989sjphh71"],
    "$images"              : [
      {
        "$md5_hash"        : "0cc175b9c0f1b6a831c399e269772661",
        "$link"            : "https://www.domain.com/file.png",
        "$description"     : "My hike today!"
      }
    ]
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

response = client.track("$update_content", message_properties)

require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$event = '$update_content';
$client = new SiftClient(array('api_key' => YOUR_API_KEY));

// Sample $update_content event for messages
$message_properties = array(
  // Required fields
  '$user_id'               => 'fyw3989sjpqr71',
  '$content_id'            => 'message-23412',

  // Recommended fields
  '$session_id'            => 'a234ksjfgn435sfg',
  '$status'                => '$active',
  '$ip'                    => '255.255.255.0',

  // Required $message object
  '$message'               => array(
    '$body'                => 'Let\'s meet at 5pm',
    '$contact_email'       => 'alex_301@domain.com',
    '$recipient_user_ids'  => array('fy9h989sjphh71'),
    '$images'              => array(
      array(
        '$md5_hash'             => '0cc175b9c0f1b6a831c399e269772661',
        '$link'                 => 'https://www.domain.com/file.png',
        '$description'          => 'My hike today!'
      )
    )
  ),

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$response = $client->track($event, $message_properties);

import java.util.Arrays;

import com.siftscience.EventRequest;
import com.siftscience.EventResponse;
import com.siftscience.SiftClient;
import com.siftscience.exception.SiftException;
import com.siftscience.model.Address;
import com.siftscience.model.CreateMessageFieldSet;
import com.siftscience.model.Image;
import com.siftscience.model.Message;

SiftClient client = new SiftClient("YOUR_API_KEY");

// Sample $update_content event for messages
EventRequest request = client.buildRequest(new CreateMessageFieldSet()
        // Required fields
        .setUserId("fyw3989sjpqr71")
        .setContentId("message-23412")
        // Recommended fields
        .setSessionId("a234ksjfgn435sfg")
        .setStatus("$active")
        .setIp("255.255.255.0")
        // Required $message object
        .setMessage(new Message()
                .setBody("Let's meet at 5pm")
                .setContactEmail("alex_301@domain.com")
                .setRecipientUserIds(Arrays.asList("fy9h989sjphh71"))
                .setImages(Arrays.asList(new Image()
                        .setMd5Hash("18E927C7E1229DC8F088643B7A65F978")
                        .setLink("https://www.domain.com/file.png")
                        .setDescription("An old picture")))));
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

EventResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
    return;
}
response.isOk(); // true

$update_content.post

Use $update_content with a $post type to represent information a user has shared with your community. Examples include social media posts like status updates, forum posts, blog articles, etc.

  • $type
    required · String

    "$update_content"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $content_id
    required · String

    The unique ID that you assign to an individual piece of content in your system. Note: content IDs are case sensitive and must be unique across all content types.

  • $session_id
    String

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

  • $status
    String

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

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

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

  • $browser
    Browser

    The user agent of the browser that is used to update the post. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to update the post. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $post
    Object

    Contains information about the post.

    • $subject
      String

      The user-supplied subject of the post.

    • $body
      String

      The text content of the post.

    • $contact_email
      String

      The email address provided with the post for contacting the poster. When no email address is provided for the listing, use the email address of the user account instead.

    • $contact_address
      Address

      The physical contact address provided with the post. When no address is provided for the post, use the physical address of the user account instead.

    • $locations
      Array of Addresses

      The locations associated with the post. In the example above, the locations array contains the check-in location of a social-media post. You can pass one or more addresses that are associated with your post. Pass as much information as you have. Partial addresses such as just the city and state are fine if that's all you have.

    • $categories
      Array of Strings

      The category or categories you associate with the posting. For example, a blog post might be categorized as ["Family", "Travel"].

    • $images
      Array of Images

      The list of images shared by the user with their post. It includes images pasted inline or attached separately.

    • $expiration_time
      Integer

      The UNIX timestamp in milliseconds of when the post will expire. Only set if the post is time bound in some way.

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

// Sample $update_content event for posts
{
  // Required fields
  "$type"               : "$update_content",
  "$api_key"            : "YOUR_API_KEY",
  "$user_id"            : "fyw3989sjpqr71",
  "$content_id"         : "post-23412",

  // Recommended fields
  "$session_id"         : "a234ksjfgn435sfg",
  "$status"             : "$active",
  "$ip"                 : "255.255.255.0",

  // Required $post object
  "$post"               : {
    "$subject"          : "My new apartment!",
    "$body"             : "Moved into my new apartment yesterday.",
    "$contact_email"    : "alex_301@domain.com",
    "$contact_address"  : {
      "$name"           : "Bill Jones",
      "$city"           : "New London",
      "$region"         : "New Hampshire",
      "$country"        : "US",
      "$zipcode"        : "03257"
    },
    "$locations"        : [
      {
        "$city"             : "Seattle",
        "$region"           : "Washington",
        "$country"          : "US",
        "$zipcode"          : "98112"
      }
    ],
    "$categories"       : ["Personal"],
    "$images"           : [
      {
        "$md5_hash"         : "0cc175b9c0f1b6a831c399e269772661",
        "$link"             : "https://www.domain.com/file.png",
        "$description"      : "View from the window!"
      }
    ],
    "$expiration_time"  : 1549063157000 // UNIX timestamp in milliseconds
  },

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

require "sift"

client = Sift::Client.new({api_key: "YOUR_API_KEY"})

# Sample $update_content event for posts
post_properties = {
  # Required fields
  '$user_id'            => 'fyw3989sjpqr71',
  '$content_id'         => 'post-23412',

  # Recommended fields
  '$session_id'         => 'a234ksjfgn435sfg',
  '$status'             => '$active',
  '$ip'                 => '255.255.255.0',

  # Required $post object
  '$post'               => {
    '$subject'          => 'My new apartment!',
    '$body'             => 'Moved into my new apartment yesterday.',
    '$contact_email'    => 'alex_301@domain.com',
    '$contact_address'  => {
      '$name'           => 'Bill Jones',
      '$city'           => 'New London',
      '$region'         => 'New Hampshire',
      '$country'        => 'US',
      '$zipcode'        => '03257'
    },
    '$locations'        => [
      {
        '$city'              => 'Seattle',
        '$region'            => 'Washington',
        '$country'           => 'US',
        '$zipcode'           => '98112'
      }
    ],
    '$categories'       => ['Personal'],
    '$images'           => [
      {
        '$md5_hash'          => '0cc175b9c0f1b6a831c399e269772661',
        '$link'              => 'https://www.domain.com/file.png',
        '$description'       => 'View from the window!'
      }
    ],
    '$expiration_time'  => 1549063157000 # UNIX timestamp in milliseconds
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

response = client.track("$update_content", post_properties)

import sift

client = sift.Client(api_key="YOUR_API_KEY")

# Sample $update_content event for posts
post_properties = {
  # Required fields
  "$user_id"              : "fyw3989sjpqr71",
  "$content_id"           : "post-23412",

  # Recommended fields
  "$session_id"           : "a234ksjfgn435sfg",
  "$status"               : "$active",
  "$ip"                   : "255.255.255.0",

  # Required $post object
  "$post"                 : {
    "$subject"          : "My new apartment!",
    "$body"             : "Moved into my new apartment yesterday.",
    "$contact_email"    : "alex_301@domain.com",
    "$contact_address"  : {
        "$name"         : "Bill Jones",
        "$city"         : "New London",
        "$region"       : "New Hampshire",
        "$country"      : "US",
        "$zipcode"      : "03257"
    },
    "$locations"        : [
      {
        "$city"         : "Seattle",
        "$region"       : "Washington",
        "$country"      : "US",
        "$zipcode"      : "98112"
      }
    ],
    "$categories"       : ["Personal"],
    "$images"           : [
      {
        "$md5_hash"     : "0cc175b9c0f1b6a831c399e269772661",
        "$link"         : "https://www.domain.com/file.png",
        "$description"  : "View from the window!"
      }
    ],
    "$expiration_time"  : 1549063157000 # UNIX timestamp in milliseconds
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

response = client.track("$update_content", post_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';

$event = '$update_content';
$client = new SiftClient(array('api_key' => YOUR_API_KEY));

// Sample $update_content event for posts
$post_properties = array(
  // Required fields
  '$user_id' => 'fyw3989sjpqr71',
  '$content_id' => 'post-23412',

  // Recommended fields
  '$session_id'         => 'a234ksjfgn435sfg',
  '$status'             => '$active',
  '$ip'                 => '255.255.255.0',

  // Required $post object
  '$post'               => array(
    '$subject'          => 'My new apartment!',
    '$body'             => 'Moved into my new apartment yesterday.',
    '$contact_email'    => 'alex_301@domain.com',
    '$contact_address'  => array(
      '$name'                => 'Bill Jones',
      '$city'                => 'New London',
      '$region'              => 'New Hampshire',
      '$country'             => 'US',
      '$zipcode'             => '03257'
    ),
    '$locations'        => array(
      array(
        '$city'              => 'Seattle',
        '$region'            => 'Washington',
        '$country'           => 'US',
        '$zipcode'           => '98112'
      )
    ),
    '$categories'       => array('Personal'),
    '$images'           => array(
      array(
        '$md5_hash'          => '0cc175b9c0f1b6a831c399e269772661',
        '$link'              => 'https://www.domain.com/file.png',
        '$description'       => 'View from the window!'
      )
    ),
    '$expiration_time'  => 1549063157000
  ),

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$response = $client->track($event, $post_properties);

import java.util.Arrays;

import com.siftscience.EventRequest;
import com.siftscience.EventResponse;
import com.siftscience.SiftClient;
import com.siftscience.exception.SiftException;
import com.siftscience.model.Address;
import com.siftscience.model.CreatePostFieldSet;
import com.siftscience.model.Image;
import com.siftscience.model.Item;
import com.siftscience.model.Post;

SiftClient client = new SiftClient("YOUR_API_KEY");

// Sample $update_content event for posts
EventRequest request = client.buildRequest(new CreatePostFieldSet()
        // Required fields
        .setUserId("fyw3989sjpqr71")
        .setContentId("post-23412")
        // Recommended fields
        .setSessionId("a234ksjfgn435sfg")
        .setStatus("$active")
        .setIp("255.255.255.0")
        // Required $post object
        .setPost(new Post()
                .setSubject("My new apartment!")
                .setBody("Moved into my new apartment yesterday.")
                .setContactEmail("alex_301@domain.com")
                .setContactAddress(new Address()
                        .setName("Bill Jones")
                        .setPhone("1-415-555-6041")
                        .setRegion("New Hampshire")
                        .setCity("New London")
                        .setCountry("US")
                        .setZipCode("03257"))
                .setLocations(Arrays.asList(new Address()
                        .setCity("Seattle")
                        .setRegion("Washington")
                        .setCountry("US")
                        .setZipCode("98112")))
                .setCategories(Arrays.asList("Personal"))
                .setImages(Arrays.asList(new Image()
                        .setMd5Hash("18E927C7E1229DC8F088643B7A65F978")
                        .setLink("https://www.domain.com/file.png")
                        .setDescription("An old picture")))
                .setExpirationTime(1549063157000L))); // UNIX timestamp in milliseconds
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

EventResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
    return;
}
response.isOk(); // true

$update_content.profile

Use $update_content with a $profile type to represent information related to a user's profile. This may include a social media profile, dating profile, etc.

  • $type
    required · String

    "$update_content"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $content_id
    required · String

    The unique ID that you assign to an individual piece of content in your system. Note: content IDs are case sensitive and must be unique across all content types.

  • $session_id
    String

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

  • $status
    String

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

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

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

  • $browser
    Browser

    The user agent of the browser that is used to update the profile. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to update the profile. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $profile
    Object

    Contains information about the profile.

    • $body
      String

      The text content of the profile.

    • $contact_email
      String

      The email address provided with the profile for contacting the user. When no email address is provided for the listing, use the email address of the user account instead.

    • $contact_address
      Address

      The physical contact address provided with the profile. When no address is provided for the profile, use the physical address of the user account instead.

    • $images
      Array of Images

      The list of images shared by the user with their profile. It includes images pasted inline or attached separately.

    • $categories
      Array of Strings

      The category or categories you associate with the profile. For example, a profile on a services marketplace might be categorized as ["Photographer", "Weddings"].

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

// Sample $update_content event for profiles
{
  // Required fields
  "$type"               : "$update_content",
  "$api_key"            : "YOUR_API_KEY",
  "$user_id"            : "fyw3989sjpqr71",
  "$content_id"         : "listing-23412",

  // Recommended fields
  "$session_id"         : "a234ksjfgn435sfg",
  "$status"             : "$active",
  "$ip"                 : "255.255.255.0",

  // Required $profile object
  "$profile"            : {
    "$body"             : "Hi! My name is Alex and I just moved to New London!",
    "$contact_email"    : "alex_301@domain.com",
    "$contact_address"  : {
    "$name"             : "Alex Smith",
    "$phone"            : "1-415-555-6041",
    "$city"             : "New London",
    "$region"           : "New Hampshire",
    "$country"          : "US",
    "$zipcode"          : "03257"
  },
  "$images"             : [
    {
      "$md5_hash"           : "0cc175b9c0f1b6a831c399e269772661",
      "$link"               : "https://www.domain.com/file.png",
      "$description"        : "Alex’s picture"
    }
  ],
  "$categories"         : ["Friends", "Long-term dating"]
  },

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

require "sift"

client = Sift::Client.new({api_key: "YOUR_API_KEY"})

# Sample $update_content event for profiles
profile_properties = {
  # Required fields
  '$user_id'            => 'fyw3989sjpqr71',
  '$content_id'         => 'profile-23412',

  # Recommended fields
  '$session_id'         => 'a234ksjfgn435sfg',
  '$status'             => '$active',
  '$ip'                 => '255.255.255.0',

  # Required $profile object
  '$profile'            => {
    '$body'             => 'Hi! My name is Alex and I just moved to New London!',
    '$contact_email'    => 'alex_301@domain.com',
    '$contact_address'  => {
      '$name'           => 'Alex Smith',
      '$phone'          => '1-415-555-6041',
      '$city'           => 'New London',
      '$region'         => 'New Hampshire',
      '$country'        => 'US',
      '$zipcode'        => '03257'
    },
    '$images'           => [
      {
        '$md5_hash'          => '0cc175b9c0f1b6a831c399e269772661',
        '$link'              => 'https://www.domain.com/file.png',
        '$description'       => 'Alex\'s picture'
      }
    ],
    '$categories'       => [
      'Friends',
      'Long-term dating'
    ]
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

response = client.track("$update_content", profile_properties)

import sift

client = sift.Client(api_key="YOUR_API_KEY")

# Sample $update_content event for reviews
profile_properties = {
  # Required fields
  "$user_id"              : "fyw3989sjpqr71",
  "$content_id"           : "profile-23412",

  # Recommended fields
  "$session_id"           : "a234ksjfgn435sfg",
  "$status"               : "$active",
  "$ip"                   : "255.255.255.0",

  # Required $profile object
  "$profile"              : {
    "$body"             : "Hi! My name is Alex and I just moved to New London!",
    "$contact_email"    : "alex_301@domain.com",
    "$contact_address"  : {
      "$name"         : "Alex Smith",
      "$phone"        : "1-415-555-6041",
      "$city"         : "New London",
      "$region"       : "New Hampshire",
      "$country"      : "US",
      "$zipcode"      : "03257"
    },
    "$images"           : [
      {
        "$md5_hash"     : "0cc175b9c0f1b6a831c399e269772661",
        "$link"         : "https://www.domain.com/file.png",
        "$description"  : "Alex's picture"
      }
    ],
    "$categories"       : [
      "Friends",
      "Long-term dating"
    ]
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

response = client.track("$update_content", profile_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';

$event = '$update_content';
$client = new SiftClient(array('api_key' => YOUR_API_KEY));

// Sample $update_content event for profiles
$profile_properties = array(
  // Required fields
  '$user_id'            => 'fyw3989sjpqr71',
  '$content_id'         => 'profile-23412',

  // Recommended fields
  '$session_id'         => 'a234ksjfgn435sfg',
  '$status'             => '$active',
  '$ip'                 => '255.255.255.0',

  // Required $profile object
  '$profile'            => array(
    '$body'             => 'Hi! My name is Alex and I just moved to New London!',
    '$contact_email'    => 'alex_301@domain.com',
    '$contact_address'  => array(
      '$name'           => 'Alex Smith',
      '$phone'          => '1-415-555-6041',
      '$city'           => 'New London',
      '$region'         => 'New Hampshire',
      '$country'        => 'US',
      '$zipcode'        => '03257'
    ),
    '$images'           => array(
      array(
        '$md5_hash'          => '0cc175b9c0f1b6a831c399e269772661',
        '$link'              => 'https://www.domain.com/file.png',
        '$description'       => 'Alex\'s picture'
      )
    ),
    '$categories'       => array(
      'Friends',
      'Long-term dating'
    )
  ),

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$response = $client->track($event, $profile_properties);

import java.util.Arrays;

import com.siftscience.EventRequest;
import com.siftscience.EventResponse;
import com.siftscience.SiftClient;
import com.siftscience.exception.SiftException;
import com.siftscience.model.Address;
import com.siftscience.model.CreateProfileFieldSet;
import com.siftscience.model.Image;
import com.siftscience.model.Profile;

SiftClient client = new SiftClient("YOUR_API_KEY");

// Sample $update_content event for profiles
EventRequest request = client.buildRequest(new CreateProfileFieldSet()
        // Required fields
        .setUserId("fyw3989sjpqr71")
        .setContentId("profile-23412")
        // Recommended fields
        .setSessionId("a234ksjfgn435sfg")
        .setStatus("$active")
        .setIp("255.255.255.0")
        // Required $profile object
        .setProfile(new Profile()
                .setBody("Hi! My name is Alex and I just moved to New London!")
                .setContactEmail("alex_301@domain.com")
                .setContactAddress(new Address()
                        .setName("Bill Jones")
                        .setPhone("1-415-555-6041")
                        .setRegion("New Hampshire")
                        .setCity("New London")
                        .setCountry("US")
                        .setZipCode("03257"))
                .setCategories(Arrays.asList("Friends", "Long-term dating"))
                .setImages(Arrays.asList(new Image()
                        .setMd5Hash("18E927C7E1229DC8F088643B7A65F978")
                        .setLink("https://www.domain.com/file.png")
                        .setDescription("An old picture")))));
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

EventResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
    return;
}
response.isOk(); // true

$update_content.review

Use $update_content with a $review type to represent information related to a product or service review submitted by your users.

  • $type
    required · String

    "$update_content"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $content_id
    required · String

    The unique ID that you assign to an individual piece of content in your system. Note: content IDs are case sensitive and must be unique across all content types.

  • $session_id
    String

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

  • $status
    String

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

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

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

  • $browser
    Browser

    The user agent of the browser that is used to update the review. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to update the review. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $review
    Object

    Contains information about the review.

    • $subject
      String

      The user-supplied title of the review.

    • $body
      String

      The text content of the review.

    • $contact_email
      String

      The email address provided with the review for contacting the reviewer. When no email address is provided for the listing, use the email address of the user account instead.

    • $locations
      Array of Addresses

      The locations associated with the review. In the example above, the location of the restaurant being reviewed. You can pass one or more addresses that are associated with your review. Pass as much information as you have. Partial addresses such as just the city and state are fine if that's all you have.

    • $item_reviewed
      Item

      An Item object representing the item being reviewed.

    • $reviewed_content_id
      String

      The $content_id of the item being reviewed. For example, this could be the id for the $listing or $profile being reviewed.

    • $rating
      Float

      A numeric rating supplied by the reviewer.

    • $images
      Array of Images

      The list of images shared by the user with their review. It includes images pasted inline or attached separately.

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

// Sample $update_content event for reviews
{
  // Required fields
  "$type"                   : "$update_content",
  "$api_key"                : "YOUR_API_KEY",
  "$user_id"                : "fyw3989sjpqr71",
  "$content_id"             : "review-23412",

  // Recommended fields
  "$session_id"             : "a234ksjfgn435sfg",
  "$status"                 : "$active",
  "$ip"                     : "255.255.255.0",

  // Required $review object
  "$review"                 : {
    "$subject"              : "Amazing Tacos!",
    "$body"                 : "I ate the tacos.",
    "$contact_email"        : "alex_301@domain.com",
    "$locations"            : [
      {
        "$city"                 : "Seattle",
        "$region"               : "Washington",
        "$country"              : "US",
        "$zipcode"              : "98112"
      }
    ],
    "$reviewed_content_id"  : "listing-234234",
    "$images"               : [
      {
        "$md5_hash"             : "0cc175b9c0f1b6a831c399e269772661",
        "$link"                 : "https://www.domain.com/file.png",
        "$description"          : "Calamari tacos."
      }
    ],
    "$rating"               : 4.5
  },

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

require "sift"

client = Sift::Client.new({api_key: "YOUR_API_KEY"})

# Sample $update_content event for reviews
review_properties = {
  # Required fields
  '$user_id' => 'fyw3989sjpqr71',
  '$content_id' => 'review-23412',

  # Recommended fields
  '$session_id'             => 'a234ksjfgn435sfg',
  '$status'                 => '$active',
  '$ip'                     => '255.255.255.0',

  # Required $review object
  '$review'                 => {
    '$subject'              => 'Amazing Tacos!',
    '$body'                 => 'I ate the tacos.',
    '$contact_email'        => 'alex_301@domain.com',
    '$locations'            => [
      {
        '$city'                  => 'Seattle',
        '$region'                => 'Washington',
        '$country'               => 'US',
        '$zipcode'               => '98112'
      }
    ],
    '$reviewed_content_id'  => 'listing-234234',
    '$images'               => [
      {
        '$md5_hash'              => '0cc175b9c0f1b6a831c399e269772661',
        '$link'                  => 'https =>//www.domain.com/file.png',
        '$description'           => 'Calamari tacos.'
      }
    ],
    '$rating'               => 4.5
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

response = client.track("$update_content", review_properties)

import sift

client = sift.Client(api_key="YOUR_API_KEY")

# Sample $update_content event for reviews
review_properties = {
  # Required fields
  "$user_id"                  : "fyw3989sjpqr71",
  "$content_id"               : "review-23412",

  # Recommended fields
  "$session_id"               : "a234ksjfgn435sfg",
  "$status"                   : "$active",
  "$ip"                       : "255.255.255.0",

  # Required $review object
  "$review"                   : {
    "$subject"              : "Amazing Tacos!",
    "$body"                 : "I ate the tacos.",
    "$contact_email"        : "alex_301@domain.com",
    "$locations"            : [
      {
        "$city"             : "Seattle",
        "$region"           : "Washington",
        "$country"          : "US",
        "$zipcode"          : "98112"
      }
    ],
    "$reviewed_content_id"  : "listing-234234",
    "$images"               : [
      {
        "$md5_hash"         : "0cc175b9c0f1b6a831c399e269772661",
        "$link"             : "https://www.domain.com/file.png",
        "$description"      : "Calamari tacos."
      }
    ],
    "$rating" : 4.5
  },

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

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

$event = '$update_content';
$client = new SiftClient(array('api_key' => YOUR_API_KEY));

// Sample $update_content event for reviews
$review_properties = array(
  // Required fields
  '$user_id'                => 'fyw3989sjpqr71',
  '$content_id'             => 'review-23412',

  // Recommended fields
  '$session_id'             => 'a234ksjfgn435sfg',
  '$status'                 => '$active',
  '$ip'                     => '255.255.255.0',

  // Required $review object
  '$review'                 => array(
    '$subject'              => 'Amazing Tacos!',
    '$body'                 => 'I ate the tacos.',
    '$contact_email'        => 'alex_301@domain.com',
    '$locations'            => array(
      array(
        '$city'                 => 'Seattle',
        '$region'               => 'Washington',
        '$country'              => 'US',
        '$zipcode'              => '98112'
      )
    ),
    '$reviewed_content_id'  => 'listing-234234',
    '$images'               => array(
      array(
        '$md5_hash'             => '0cc175b9c0f1b6a831c399e269772661',
        '$link'                 => 'https://www.domain.com/file.png',
        '$description'          => 'Calamari tacos.'
      )
    ),
    '$rating'               => 4.5
  ),

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$response = $client->track($event, $review_properties);

import java.util.Arrays;

import com.siftscience.EventRequest;
import com.siftscience.EventResponse;
import com.siftscience.SiftClient;
import com.siftscience.exception.SiftException;
import com.siftscience.model.Address;
import com.siftscience.model.CreateReviewFieldSet;
import com.siftscience.model.Image;
import com.siftscience.model.Item;
import com.siftscience.model.Review;

SiftClient client = new SiftClient("YOUR_API_KEY");

// Sample $update_content event for reviews
EventRequest request = client.buildRequest(new CreateReviewFieldSet()
        // Required fields
        .setUserId("fyw3989sjpqr71")
        .setContentId("review-23412")
        // Recommended fields
        .setSessionId("a234ksjfgn435sfg")
        .setStatus("$active")
        .setIp("255.255.255.0")
        // Required $review object
        .setReview(new Review()
                .setSubject("Amazing Tacos!")
                .setBody("I ate the tacos.")
                .setContactEmail("alex_301@domain.com")
                .setLocations(Arrays.asList(new Address()
                        .setCity("Seattle")
                        .setRegion("Washington")
                        .setCountry("US")
                        .setZipCode("98112")))
                .setReviewedContentId("listing_234234")
                .setImages(Arrays.asList(new Image()
                        .setMd5Hash("18E927C7E1229DC8F088643B7A65F978")
                        .setLink("https://www.domain.com/file.png")
                        .setDescription("An old picture")))
                .setRating(4.5)));
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

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

    "$update_order"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $session_id
    String

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

  • $order_id
    String

    The ID for tracking this order in your system.

  • $user_email
    String

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

  • $verification_phone_number
    String

    Phone number of the user. This phone number will be used to send One-Time Password (OTP) when required. The phone number should be in E.164 format including + and a country code.

  • $amount
    Integer

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

  • $currency_code
    String

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

  • $billing_address
    Address

    The billing address as entered by the user.

  • $payment_methods
    Array of Payment Methods

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

  • $shipping_address
    Address

    The shipping address as entered by the user.

  • $expedited_shipping
    Boolean

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

  • $items
    Array of Items

    The list of items ordered. This may include physical products, gift cards, in-app purchases etc. Travel (Flights, Hotels, Rideshare, etc) and Event Ticketing customers should use $bookings instead of $items. $bookings supports specialized fields for modeling specific to Travel, Ticketing, and other cases where users make bookings. Note: cannot be used in conjunction with $bookings.

  • $bookings
    Array of Bookings

    The list of bookings made. This may include tickets and reservations like flights, hotels, rideshares etc. Note: cannot be used in conjunction with $items.

  • $seller_user_id
    String

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

  • $promotions
    Array of Promotions

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

  • $shipping_method
    String

    Indicates the method of delivery to the user.

    Allowed Values
    • "$electronic""$physical"
  • $shipping_carrier
    String

    Shipping carrier for the shipment of the product.

  • $shipping_tracking_number
    deprecated · String

    Shipping tracking number for the shipment of the product.

  • $shipping_tracking_numbers
    Array of Strings

    Shipping tracking number(s) for the shipment of the product(s).

  • $ordered_from
    Ordered From

    The details about the specific physical location providing the good or service. This can also be used to capture pickup, delivery locations, etc.

  • $browser
    Browser

    The user agent of the browser that is used to update the order. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to update the order. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

  • $merchant_profile
    Merchant Profile

    The details about the merchant or seller providing the goods or service.

// 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"                : "billjones1@example.com",
  "$verification_phone_number" : "+123456789012",
  "$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"
      }
  ],
  "$brand_name"   : "sift",
  "$site_domain"  : "sift.com",
  "$site_country" : "US",
  "$ordered_from" : {
    "$store_id"      : "123",
    "$store_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"
  },
  "$expedited_shipping"       : true,
  "$shipping_method"          : "$physical",
  "$shipping_carrier"         : "UPS",
  "$shipping_tracking_numbers": ["1Z204E380338943508", "1Z204E380338943509"],
  "$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"            : "6786211451001",
      "$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,

  // Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  // =========================================

  // Send this information from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }
}

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"                : "billjones1@example.com",
  "$verification_phone_number" : "+123456789012",
  "$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"
      }
  ],
  "$brand_name"   : "sift",
  "$site_domain"  : "sift.com",
  "$site_country" : "US",
  "$ordered_from" : {
    "$store_id"      : "123",
    "$store_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"
  },
  "$expedited_shipping"       : True,
  "$shipping_method"          : "$physical",
  "$shipping_carrier"         : "UPS",
  "$shipping_tracking_numbers": ["1Z204E380338943508", "1Z204E380338943509"],
  "$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"            : "6786211451001",
      "$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,

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

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"       => "billjones1@example.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"
    }
  ],
  "$brand_name"   => "sift",
  "$site_domain"  => "sift.com",
  "$site_country" => "US",
  "$ordered_from" => {
    "$store_id"      => "123",
    "$store_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"
  },
  "$expedited_shipping"       => true,
  "$shipping_method"          => "$physical",
  "$shipping_carrier"         => "UPS",
  "$shipping_tracking_numbers"=> ["1Z204E380338943508", "1Z204E380338943509"],
  "$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"            => "6786211451001",
      "$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,

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

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'
    )
  ),
  '$brand_name'   => 'sift',
  '$site_domain'  => 'sift.com',
  '$site_country' => 'US',
  $ordered_from = array(
    '$store_id'      => '123',
    '$store_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'
  ),
  '$expedited_shipping'       => True,
  '$shipping_method'          => '$physical',
  '$shipping_carrier'         => 'UPS',
  '$shipping_tracking_numbers'=> array('1Z204E380338943508', '1Z204E380338943509'),
  '$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'            => '6786211451001',
      '$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,

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

$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("billjones1@example.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")))
        .setBrandName("sift")
        .setSiteDomain("sift.com")
        .setSiteCountry("US")
        .setOrderedFrom(new OrderedFrom()
                .setStoreId("123")
                .setStoreAddress(new Address()
                        .setName("New London Stop")
                        .setAddress1("2100 Main Street")
                        .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"))
        .setExpeditedShipping(true)
        .setShippingMethod("$physical")
        .setShippingCarrier("UPS")
        .setShippingTrackingNumbers(Arrays.asList("1Z204E380338943508", "1Z204E380338943509"))
        .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("6786211451001")
                        .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));
        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

EventResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
    return;
}
response.isOk(); // true

$update_password

Use $update_password to record all password changes, whether initiated by the user or the service.

  • $type
    required · String

    "$update_password"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $reason
    required · String

    The reason the password was updated or an update was attempted. The process may trigger a verification (with $verified_event = $update_password).

    Allowed Values
    • $user_updateThe user updates the password on their own while logged into the account. The update can be motivated by, e.g., desire to use a stronger password from a password manager or because the password expired after 90 days.
    • $forgot_passwordThe user forgot the password and initiates a self-service process to create a new password. The old password becomes invalid only once the process is complete ($status is $success).
    • $forced_resetThe service provider reset the password following suspicious account behavior or a support ticket. The old password becomes invalid once the process is initiated ($status is $pending).
  • $status
    required · String

    The status of the password update event.

    Allowed Values
    • $pendingPassword change initiated, waiting for user to act.
    • $successNew password was set. This is the only status needed for password updates from within the account ($reason is $user_update).
    • $failureUser clicks an expired password link.
  • $browser
    Browser

    The user agent of the browser that is used to update the password. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is used to update the password. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

  • $user_email
    String

    Email of the user logging in. 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.

  • $verification_phone_number
    String

    Phone number of the user. This phone number will be used to send One-Time Password (OTP) when required. The phone number should be in E.164 format including + and a country code.

// Sample $update_password event
{
  // Required Fields
  "$type"              : "$update_password",
  "$api_key"           : "YOUR_API_KEY",
  "$user_id"           : "billy_jones_301",
  "$session_id"        : "gigtleqddo84l8cm15qe4il",
  "$status"            : "$success",
  "$reason"            : "$forced_reset",
  "$ip"                : "128.148.1.135",    // IP of the user that entered the new password after the old password was reset

  // Supported Fields
  "$user_email"                : "billjones1@example.com",
  "$verification_phone_number" : "+123456789012",

  // Send this information with a login from a BROWSER client.
  "$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",
   "$accept_language"  : "en-US",
   "$content_language" : "en-GB"
  },
  // =========================================


  // Send this information with a login from an APP client.
  "$app"        : {
    // 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",
    "$client_language"     : "en-US"
  }

import sift

client = sift.Client("YOUR_API_KEY")

# Sample $update_password event
properties = {
  # Required Fields
  "$user_id"       : "billy_jones_301",
  "$session_id"    : "gigtleqddo84l8cm15qe4il",
  "$status"        : "$success",
  "$reason"        : "$forced_reset",
  "$ip"            : "128.148.1.135",     // IP of the user that entered the new password after the old password was reset

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  : "en-US",
    "$content_language" : "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        : {
    # 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",
    "$client_language"     : "en-US"
  }
}

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

require "sift"

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

# Sample $update_password event
properties = {
  # Required Fields
  "$user_id"    => "billy_jones_301",
  "$session_id" => "gigtleqddo84l8cm15qe4il",
  "$status"     => "$success",
  "$reason"     => "$forced_reset",
  "$ip"         => "128.148.1.135",     // IP of the user that entered the new password after the old password was reset

  # Send this information from a BROWSER client.
  "$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",
    "$accept_language"  => "en-US",
    "$content_language" => "en-GB"
  },

  # =========================================

  # Send this information from an APP client.
  "$app"        => {
    # 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",
    "$client_language"     => "en-US"
  }
}

response = client.track("$update_password", 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_password event
$properties = array(
  // Required Fields
  '$user_id'   => 'billy_jones_301',
  '$session_id' => 'gigtleqddo84l8cm15qe4il',
  '$status'     => '$success',
  '$reason'     => '$forced_reset',
  '$ip'         => '128.148.1.135',     // IP of the user that entered the new password after the old password was reset

  // Send this information from a BROWSER client.
  '$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',
    '$accept_language'  => 'en-US',
    '$content_language' => 'en-GB'
  ),

  // =========================================

  // Send this information an APP client.
  '$app'        => array(
    // 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',
    '$client_language'     => 'en-US'
  )
);

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

import com.siftscience.SiftClient;
import com.siftscience.EventRequest;
import com.siftscience.EventResponse;
import com.siftscience.model.UpdatePasswordFieldSet;

// Sample $update_password event
SiftClient client = new SiftClient("YOUR_API_KEY");
EventRequest request = client.buildRequest(new UpdatePasswordFieldSet()
        // Required Fields
        .setUserId("billy_jones_301")
        .setSessionId("gigtleqddo84l8cm15qe4il")
        .setStatus("$success")
        .setReason("$forced_reset")
        .setIp("128.148.1.135") // IP of the user that entered the new password after the old password was reset

        // Send this information from a BROWSER client.
        .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")
                .setAcceptLanguage("en-US")
                .setContentLanguage("en-GB"))

        // =========================================

        // Send this information from an APP client.
        .setApp(new App()
                // Example for the iOS Calculator 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")
                .setClientLanguage("en-US")));

EventResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
    return;
}
response.isOk(); // true

$verification

When a user attempts a high-value activity (e.g., login, view or change account information) that you deem risky, you may decide to verify whether the user is who they say they are. This is typically done by asking the user to enter a one-time passcode that is sent to their email, phone, or app. Other supported methods are detailed below. Sift models this interaction with the $verification event.

  • $type
    required · String

    "$verification"

  • $api_key
    required · String

    Your Sift REST API key.

  • $user_id
    required · String

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

  • $session_id
    required · String

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

  • $status
    required · 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.
  • $browser
    Browser

    The user agent of the browser that is verifying. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • $app
    App

    The details of the app, os, and device that is verifying. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • $verified_event
    String

    The type of the reserved event being verified, e.g., $login, $create_account, $update_account, $update_password, $create_content,

    $create_order, $transaction, $update_content, $update_order
  • $verified_entity_id
    String

    The ID of the entity impacted by the event being verified, e.g.,

    • Session ID

      for $login

    • Order ID

      for $create_order

    • Content ID

      for $create_content

    • No ID needed

      for $create_account, $update_account, or $update_password

  • $verification_type
    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).
    • $shared_knowledgeA shared secret (e.g., former address, mother’s maiden name, photo) is used to authenticate the user.
    • $faceA selfie processed via face recognition algorithms is used to authenticate the user.
    • $fingerprintA fingerprint is used to authenticate the user.
    • $pushA notification is sent to a known device, and the user needs to approve it to authenticate.
    • $security_keyA hardware token (e.g., USB stick) is used to authenticate the user.
  • $verified_value
    String

    The phone number (e.g. 14155551212, 442072193000), email address (e.g. bob@example.com) or the question (e.g., "what is your mother's maiden name?") used for verification. Do NOT send the answer to the security question! This value should be passed when the $verification_type is set to $sms, $phone_call, $email or $shared_knowledge.

  • $reason
    String

    The trigger for the verification

    Allowed Values
    • $user_settingThe user opted to require a verification with every login.
    • $manual_reviewA representative of the service provider (e.g., analyst, security engineer) forced a verification (e.g., upon noticing a suspicious behavior on the account).
    • $automated_ruleInput from Sift score, workflows or another system (in-house or third-party) triggered the verification.
  • $brand_name
    String

    Name of the brand of product or service being purchased.

  • $site_country
    String

    Country the company is providing service from. Use ISO-3166 country code.

  • $site_domain
    String

    Domain being interfaced with. Use fully qualified domain name.

// 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
  "$verified_event"     : "$login",
  "$reason"            : "$automated_rule", // Verification was triggered based on risk score
  "$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
  "$verified_event"     : "$login",
  "$reason"            : "$automated_rule", // Verification was triggered based on risk score
  "$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
  "$verified_event"     => "$login",
  "$reason"             => "$automated_rule", // Verification was triggered based on risk score
  "$verification_type"  => "$sms",
  "$verified_value"     => "14155551212"
}

response = client.track("$verification"$automated_rule"YOUR_API_KEY");

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
  '$verified_event'     => '$login',
  '$reason'             => '$automated_rule', // Verification was triggered based on risk score
  '$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
        .setVerifiedEvent("$login")
        .setReason("$automated_rule")
        .setVerificationType("$sms")
        .setVerifiedValue("14155551212"));

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_key
    String

    Your Sift REST API key.

  • $user_id
    String

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

  • $session_id
    required iF no User ID provided · String

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

  • $type
    String

    The name of the event, for example $create_order.

Optional

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

  • $ip
    String

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

  • $time
    Integer

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

Address

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

Fields of this type: $arrival_address, $billing_address, $departure_address, $location, $sent_address, $received_address, and $shipping_address

The values for a $sent_address or $received_address should only be sent with $transaction event. These values should be used in relation to the new transaction types buy/sell/send/receive.

  • $name
    String

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

  • $address_1
    String

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

  • $address_2
    String

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

  • $city
    String

    The city or town name.

  • $region
    String

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

  • $country
    String

    The ISO-3166 country code for the address.

  • $zipcode
    String

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

  • $phone
    String

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

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

App

The app field type represents the details of an application as well as the device and OS it's running on.

  • $os
    String

    The operating system on which application is running. (e.g. iOS, Android)

  • $os_version
    String

    The operating system version on which application is running. (e.g. 10.3.1, 7.1.1)

  • $device_manufacturer
    String

    The manufacturer of the device on which application is running. (e.g. Samsung, Apple, LG)

  • $device_model
    String

    The model of the device on which application is running. (e.g. SM-G920x, iPhone8,1)

  • $device_unique_id
    String

    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
    String

    The name of your application.

  • $app_version
    String

    The version of your application. Our accepted format is numbers separated by periods.

  • $client_language
    String

    The language the application content is being delivered in. Use ISO-3166 format for country codes. Examples: "en", "en-us, de", "fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5", etc.

// Send this information with a login from an APP client.
{
  "$session_id" : "gigtleqddo84l8cm15qe4il",
  "$ip"       : "128.148.1.135",
  "$app"      :
  {
    // 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",
    "$client_language"     : "en-us, de"
  }
}

# Send this information with a login from an APP client.
{
  "$session_id" : "gigtleqddo84l8cm15qe4il",
  "$ip"       : "128.148.1.135",
  "$app"      :
  {
    # 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",
    "$client_language"     : "en-us, de"
  }
}

# Send this information with a login from an APP client.
{
  "$session_id" => "gigtleqddo84l8cm15qe4il",
  "$ip"       => "128.148.1.135",
  "$app"      =>
  {
    # 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",
    "$client_language      => "en-us, de"
  }
}

// Send this information with a login from an APP client.
array(
  '$session_id' => 'gigtleqddo84l8cm15qe4il',
  '$ip'         => '128.148.1.135',
  '$app'        =>
   array(
    // 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',
    '$client_language'     => 'en-us, de'
  )
)

import com.siftscience.model.App;

// Send this information with a login from an APP client.
// 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")
        .setClientLanguage("en-us, de");

Booking

The $booking is a specialized field, analogous to $item, for travel and event ticketing use cases. A $booking represents a reservation purchased by a user.

$bookings should be used in a $create_order or $update_order event instead of $items - an event cannot have both.

$bookings support two additional complex types, $segments and $guests. $segments support more detailed fields for each part of a booking, for example, legs of a flight. $guests supports detailed fields for each guest on the booking. These fields are optional.

$booking requires a $booking_type. A single $create_order or $update_order event can have multiple types of bookings, such as sending both $flight and $accommodation bookings in one order.

Please not that $booking does not accept custom fields.

We support fields for integrations specific to the following booking types:

  1. $event_ticket: For tickets to sporting events, concerts, etc.
  2. $accommodation: For hotel reservations.
  3. $flight: For airline tickets.
  4. $bus: For bus, train or rail tickets.
  5. $rideshare: For booking rides in a ridesharing marketplace.
  6. $vehicle: For a reservation of a car or other vehicle.
  7. $cruise: For a cruise ticket.
  8. $other: For any reservation use case not covered above.

$booking.event_ticket

Tell Sift about a purchase of tickets to a concert, sporting event, or any other type of event.

A booking should be for a single event and seat type - e.g., a single order purchasing different seat classes to the same concert should get different booking objects.

  • $booking_type
    required · String

    $event_ticket

  • $title
    String

    A description of the event.

  • $start_time
    Integer

    The start time of the event. Send as a UNIX timestamp in milliseconds.

  • $end_time
    Integer

    The finish time of the event. Send as a UNIX timestamp in milliseconds.

  • $price
    String

    The price per ticket. Send this field in micros in the base unit of the $currency_code. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.

  • $currency_code
    String

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

  • $quantity
    Integer

    The count of reservations of the given type purchased by the user. e.g., 2 for a purchase of two tickets to the same event.

  • $guests
    Array of Guests

    Details of the guests using the tickets. Send as much information about each guest as you capture.

  • $event_id
    String

    For event ticket bookings, this field represents the internal identifier associated with the event.

  • $venue_id
    String

    This field represents the id of the venue.

  • $location
    Address

    This field represents the name and address of the venue.

  • $category
    String

    This field captures the genre of ticket.

  • $tags
    Array of Strings

    This field captures any descriptors of the event. For example, tags might be team names, region, etc.

{
  "$booking_type" : "$event_ticket",
  "$title"        : "Cotton Bowl Classic - Clemson vs. Notre Dame",
  "$start_time"   : 1564650701,
  "event-id"      : "event-123",
  "$location"     : {
    "$name"      : "Cotton Bowl Stadium",
    "$phone"     : "1-415-555-6041",
    "$address_1" : "3750 The Midway",
    "$city"      : "Dallas",
    "$region"    : "Texas",
    "$country"   : "US",
    "$zipcode"   : "75215"
  },
  "$price"          : 238278,
  "$currency_code"  : "USD",
  "$quantity"       : 2
}

{
  "$booking_type" : "$event_ticket",
  "$title"        : "Cotton Bowl Classic - Clemson vs. Notre Dame",
  "$start_time"   : 1564650701,
  "event_id"      : "event-123",
  "$location"     : {
    "$name"      : "Cotton Bowl Stadium",
    "$phone"     : "1-415-555-6041",
    "$address_1" : "3750 The Midway",
    "$city"      : "Dallas",
    "$region"    : "Texas",
    "$country"   : "US",
    "$zipcode"   : "75215"
  },
  "$price"         : 238278,
  "$currency_code" : "USD",
  "$quantity"      : 2
}

{
  "$booking_type" => "$event_ticket",
  "$title"        => "Cotton Bowl Classic - Clemson vs. Notre Dame",
  "$start_time"   => 1564650701,
  "$event_id"     => "event-123",
  "$location"     => {
    "$name"      => "Cotton Bowl Stadium",
    "$phone"     => "1-415-555-6041",
    "$address_1" => "3750 The Midway",
    "$city"      => "Dallas",
    "$region"    => "Texas",
    "$country"   => "US",
    "$zipcode"   => "75215"
  }
  "$price"         => 238278,
  "$currency_code" => "USD",
  "$quantity"      => 2
}

array(
  '$booking_type' => '$event_ticket',
  '$title'        => 'Cotton Bowl Classic - Clemson vs. Notre Dame',
  '$start_time'   => 1564650701,
  'event_id'      => 'event-123',
  '$location'     => {
    '$name'      => 'Cotton Bowl Stadium',
    '$phone'     => '1-415-555-6041',
    '$address_1' => '3750 The Midway',
    '$city'      => 'Dallas',
    '$region'    => 'Texas',
    '$country'   => 'US',
    '$zipcode'   => '75215'
  ),
  '$price'          => 238278,
  '$currency_code'  => 'USD',
  '$quantity'       => 2
)

import java.util.Arrays;

import com.siftscience.model.Address;
import com.siftscience.model.Booking;

Booking booking = new Booking()
        .setBookingType("$event_ticket")
        .setTitle("Cotton Bowl Classic - Clemson vs. Notre Dame")
        .setStartTime(1564650701L)
        .setEventId("event-123")
        .setLocation(new Address()
                .setName("Cotton Bowl Stadium")
                .setPhone("1-415-555-6041")
                .setAddress1("3750 The Midway")
                .setCity("Dallas")
                .setRegion("Texas")
                .setCountry("US")
                .setZipCode("75215"))
        .setPrice(238278L)
        .setCurrencyCode("USD")
        .setQuantity(2L);

$booking.accommodation

Tell Sift about a hotel reservation.

Each type of room should be its own booking - e.g., an order reserving both a single and double room should get two booking objects.

  • $booking_type
    required · String

    $accommodation

  • $title
    String

    A description of the reservation, e.g., "Deluxe King, Hotel Alpha".

  • $start_time
    Integer

    The check-in time for a hotel reservation. Send as a UNIX timestamp in milliseconds.

  • $end_time
    Integer

    The check-out time for a hotel reservation. Send as a UNIX timestamp in milliseconds.

  • $price
    String

    The price per room. Send this field in micros in the base unit of the $currency_code. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.

  • $currency_code
    String

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

  • $quantity
    Integer

    The count of reservations, e.g., 2 for two hotel rooms of the same type.

  • $guests
    Array of Guests

    Details of the guests on the reservation. Send as much information about each guest as you capture.

  • $room_type
    String

    This field represents the type of room. e.g., "Double Queen Deluxe"

  • $venue_id
    String

    This field represents the id of the hotel.

  • $location
    Address

    This field represents the address of the hotel.

  • $tags
    Array of Strings

    This field captures any descriptors of the booking. For example, tags might be "non-smoking", "wi-fi", etc.

{
  "$booking_type" : "$accommodation",
  "$start_time"   : 1564650701,
  "$end_time"     : 1564650701,
  "$location"     : {
    "$name"      : "Marriot New London",
    "$phone"     : "1-415-555-6041",
    "$address_1" : "2100 Main Street",
    "$city"      : "New London",
    "$region"    : "New Hampshire",
    "$country"   : "US",
    "$zipcode"   : "03257"
  },
  "$room_type"      : "Seaside View Queen",
  "$price"          : 103082000,
  "$currency_code"  : "USD",
  "$quantity"       : 2
}

{
  "$booking_type" : "$accommodation",
  "$start_time"   : 1564650701,
  "$end_time"     : 1564650701,
  "$location"     : {
    "$name"      : "Marriot New London",
    "$phone"     : "1-415-555-6041",
    "$address_1" : "2100 Main Street",
    "$city"      : "New London",
    "$region"    : "New Hampshire",
    "$country"   : "US",
    "$zipcode"   : "03257"
  },
  "$room_type"     : "Seaside View Queen",
  "$price"         : 103082000,
  "$currency_code" : "USD",
  "$quantity"      : 2
}

{
  "$booking_type" => "$accommodation",
  "$start_time"   => 1564650701,
  "$end_time"     => 1564650701,
  "$location"     => {
    "$name"      => "Marriot New London",
    "$phone"     => "1-415-555-6041",
    "$address_1" => "2100 Main Street",
    "$city"      => "New London",
    "$region"    => "New Hampshire",
    "$country"   => "US",
    "$zipcode"   => "03257"
  },
  "$room_type"     => "Seaside View Queen",
  "$price"         => 103082000,
  "$currency_code" => "USD",
  "$quantity"      => 2
}

array(
  '$booking_type' => '$accommodation',
  '$start_time'   => 1564650701,
  '$end_time'     => 1564650701,
  '$location'     => {
    '$name'      => 'Marriot New London',
    '$phone'     => '1-415-555-6041',
    '$address_1' => '2100 Main Street',
    '$city'      => 'New London',
    '$region'    => 'New Hampshire',
    '$country'   => 'US',
    '$zipcode'   => '03257'
  ),
  '$room_type'      => 'Seaside View Queen',
  '$price'          => 103082000,
  '$currency_code'  => 'USD',
  '$quantity'       => 2
)

import java.util.Arrays;

import com.siftscience.model.Address;
import com.siftscience.model.Booking;

Booking booking = new Booking()
        .setBookingType("$accommodation")
        .setStartTime(1564650701L)
        .setEndTime(1564650701L)
        .setLocation(new Address()
                .setName("Marriot New London")
                .setPhone("1-415-555-6041")
                .setAddress1("2100 Main Street")
                .setCity("New London")
                .setRegion("New Hampshire")
                .setCountry("US")
                .setZipCode("03257"))
        .setRoomType("Seaside View Queen")
        .setPrice(103082000L)
        .setCurrencyCode("USD")
        .setQuantity(2L);

$booking.flight

Tell Sift about the purchase of an airline ticket.

Each type of ticket should be its own booking - e.g., an order reserving both business class and economy seats on the same flight should get two booking objects.

A flight booking should also be for one trip, i.e., a round trip should be split into two bookings.

  • $booking_type
    required · String

    $flight

  • $title
    String

    A description of the flight reservation.

  • $start_time
    Integer

    The departure time for the first flight leg in the booking. Send as a UNIX timestamp in milliseconds.

  • $end_time
    Integer

    The arrival time for the last flight leg in the booking etc. Send as a UNIX timestamp in milliseconds.

  • $price
    String

    The price per flight ticket (including all legs of the flight). Send this field in micros in the base unit of the $currency_code. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.

  • $currency_code
    String

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

  • $quantity
    Integer

    The count of tickets of the given type purchased by the user.

  • $guests
    Array of Guests

    Details of the guests on the flight. Send as much information about each guest as you capture.

  • $segments
    Array of Segments

    Use this field to send information about each leg of the flight (even if there’s only one).

  • $tags
    Array of Strings

    This field captures any descriptors of the booking. For example, tags might be "premium economy", "summer sale", etc.

{
  "$booking_type" : "$flight",
  "$title"        : "SFO - CDG, 2 Adults",
  "$start_time"   : 2038412903,
  "$end_time"     : 2048412903,
  "$guests"       : [
    {
      "$name"               : "John Doe",
      "$birth_date"         : "1985-01-19",
      "$loyalty_program"    : "skymiles",
      "$loyalty_program_id" : "PSOV34DF",
      "$phone"              : "1-415-555-6041",
      "$email"              : "jdoe@domain.com"
    },
    {
      "$name" : "Jane Doe"
    }
  ],
  "$segments" : [
    {
      "$start_time"             : 15638412903,
      "$end_time"               : 15638463711,
      "$vessel_number"          : "LH454",
      "$fare_class"             : "Premium Economy",
      "$departure_airport_code" : "SFO",
      "$arrival_airport_code"   : "JFK"
    },
    {
      "$start_time"             : 15638473491,
      "$end_time"               : 15638822146,
      "$vessel_number"          : "LH388",
      "$fare_class"             : "Premium Economy",
      "$departure_airport_code" : "JFK",
      "$arrival_airport_code"   : "CDG"
    },
  ],
  "$price"          : 49900000,
  "$currency_code"  : "USD",
  "$quantity"       : 2
}

{
  "$booking_type" : "$flight",
  "$title"        : "SFO - CDG, 2 Adults",
  "$start_time"   : 2038412903,
  "$end_time"     : 2048412903,
  "$guests"       : [
    {
      "$name"               : "John Doe",
      "$birth_date"         : "1985-01-19",
      "$loyalty_program"    : "skymiles",
      "$loyalty_program_id" : "PSOV34DF",
      "$phone"              : "1-415-555-6041",
      "$email"              : "jdoe@domain.com"
    },
    {
      "$name" : "Jane Doe"
    }
  ],
  "$segments" : [
    {
    "$start_time"             : 15638412903,
    "$end_time"               : 15638463711,
    "$vessel_number"          : "LH454",
    "$fare_class"             : "Premium Economy",
    "$departure_airport_code" : "SFO",
    "$arrival_airport_code"   : "JFK"
    },
    {
      "$start_time"             : 15638473491,
      "$end_time"               : 15638822146,
      "$vessel_number"          : "LH388",
      "$fare_class"             : "Premium Economy",
      "$departure_airport_code" : "JFK",
      "$arrival_airport_code"   : "CDG"
    }
  ],
  "$price"          : 49900000,
  "$currency_code"  : "USD",
  "$quantity"       : 2
}

{
  "$booking_type" => "$flight",
  "$title"        => "SFO - CDG, 2 Adults",
  "$start_time"   => 2038412903,
  "$end_time"     => 2048412903,
  "$guests"       => [
    {
      "$name"               => "John Doe",
      "$birth_date"         => "1985-01-19",
      "$loyalty_program"    => "skymiles",
      "$loyalty_program_id" => "PSOV34DF",
      "$phone"              => "1-415-555-6041",
      "$email"              => "jdoe@domain.com"
    },
    {
      "$name" => "Jane Doe"
    }
  ],
  "$segments" => [
    {
      "$start_time"             => 15638412903,
      "$end_time"               => 15638463711,
      "$vessel_number"          => "LH454",
      "$fare_class"             => "Premium Economy",
      "$departure_airport_code" => "SFO",
      "$arrival_airport_code"   => "JFK"
    },
    {
      "$start_time"             => 15638473491,
      "$end_time"               => 15638822146,
      "$vessel_number"          => "LH388",
      "$fare_class"             => "Premium Economy",
      "$departure_airport_code" => "JFK",
      "$arrival_airport_code"   => "CDG"
    }
  ],
  "$price"          => 49900000,
  "$currency_code"  => "USD",
  "$quantity"       => 2
}

array(
  '$booking_type' => '$flight',
  '$title'        => 'SFO - CDG, 2 Adults',
  '$start_time'   => 2038412903,
  '$end_time'     => 2048412903,
  '$guests'       => array(
    array(
      '$name'               => 'John Doe',
      '$birth_date'         => '1985-01-19',
      '$loyalty_program'    => 'skymiles',
      '$loyalty_program_id' => 'PSOV34DF',
      '$phone'              => '1-415-555-6041',
      '$email'              => 'jdoe@domain.com'
    ),
    array(
      '$name' => 'Jane Doe'
    )
  ),
  '$segments' => array(
    array(
      '$start_time'             => 15638412903,
      '$end_time'               => 15638463711,
      '$vessel_number'          => 'LH454',
      '$fare_class'             => 'Premium Economy',
      '$departure_airport_code' => 'SFO',
      '$arrival_airport_code'   => 'JFK'
    ),
    array(
      '$start_time'             => 15638473491,
      '$end_time'               => 15638822146,
      '$vessel_number'          => 'LH388',
      '$fare_class'             => 'Premium Economy',
      '$departure_airport_code' => 'JFK',
      '$arrival_airport_code'   => 'CDG'
    ),
  ),
  '$price'          => 49900000,
  '$currency_code'  => 'USD',
  '$quantity'       => 2
)

import java.util.Arrays;

import com.siftscience.model.Booking;
import com.siftscience.model.Segment;

Booking booking = new Booking()
        .setBookingType("$flight")
        .setTitle("SFO - CDG, 2 Adults")
        .setStartTime(2038412903L)
        .setEndTime(2048412903L)
        .setGuests(Arrays.asList(
                new Guest()
                        .setName("John Doe")
                        .setBirthDate("1985-01-19")
                        .setPhone("1-415-555-6041")
                        .setEmail("jdoe@domain.com")
                        .setLoyaltyProgram("skymiles")
                        .setLoyaltyProgramId("PSOV34DF"),
                new Guest()
                        .setName("Jane Doe")))
        .setSegments(Arrays.asList(
                new Segment()
                      .setStartTime(15638412903L)
                      .setEndTime(15638463711L)
                      .setVesselNumber("LH454")
                      .setFareClass("Premium Economy")
                      .setDepartureAirportCode("SFO")
                      .setArrivalAirportCode("JFK"),
                new Segment()
                      .setStartTime(15638473491L)
                      .setEndTime(15638822146L)
                      .setVesselNumber("LH388")
                      .setFareClass("Premium Economy")
                      .setDepartureAirportCode("JFK")
                      .setArrivalAirportCode("CDG")))
        .setPrice(49900000L)
        .setCurrencyCode("USD")
        .setQuantity(2L);

$booking.bus

Tell Sift about bus, train, or rail tickets.

Each type of ticket should get its own booking - e.g., an order reserving both business class and economy seats on the same ride should get two booking objects. However, an order booking two economy seats on the same flight would be one booking with quantity 2.

A booking should also be for one trip - ie, a round trip should be split into two bookings.

  • $booking_type
    required · String

    $bus

  • $title
    String

    A description of the trip.

  • $start_time
    Integer

    The departure time for a trip. Send as a UNIX timestamp in milliseconds.

  • $end_time
    Integer

    The arrival time of the trip. Send as a UNIX timestamp in milliseconds.

  • $price
    String

    The price per ticket. Send this field in micros in the base unit of the $currency_code. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.

  • $currency_code
    String

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

  • $quantity
    Integer

    The count of tickets of the given type purchased by the user.

  • $guests
    Array of Guests

    Details of the guests on the trip. The number of guests and the quantity of tickets do not need to match. Send as much information about each guest as you capture.

  • $segments
    Array of Segments

    Use this field to send information about each ride of the trip (even if there’s only one).

  • $tags
    Array of Strings

    This field captures any descriptors of the trip. For example, tags might be "sleeper", "summer sale", etc.

{
  "$booking_type" : "$bus",
  "$title"        : "Ride 2a34029, 2 seats",
  "$start_time"   : 2038412903,
  "$end_time"     : 2048412903,
  "$guests"       : [
    {
      "$name"  : "John Doe",
      "$email" : "jdoe@domain.com"
    }
  ],
  "$segments" : [
    {
      "$departure_address"  : {
          "$name"       : "New London Stop",
          "$address_1"  : "2100 Main Street",
          "$city"       : "New London",
          "$region"     : "New Hampshire",
          "$country"    : "US",
          "$zipcode"    : "03257"
        },
      "$arrival_address"  : {
          "$name"       : "Concord Stop",
          "$address_1"  : "213 Elm Street",
          "$city"       : "Concord",
          "$region"     : "New Hampshire",
          "$country"    : "US",
          "$zipcode"    : "03301"
        },
      "$start_time"       : 2190121220,
      "$end_time"         : 2290122129,
      "$vessel_number"    : "F Line",
      "$fare_class"       : "Economy",
    }
  ],
  "$price"          : 300000,
  "$currency_code"  : "USD",
  "$quantity"       : 1,
  "$tags"           : ["Holiday Schedule"]
}

{
  "$booking_type" : "$bus",
  "$title"        : "Ride 2a34029, 2 seats",
  "$start_time"   : 2038412903,
  "$end_time"     : 2048412903,
  "$guests"       : [
    {
      "$name"  : "John Doe",
      "$email" : "jdoe@domain.com"
    }
  ],
  "$segments" : [
    {
      "$departure_address"  : {
        "$name"      : "New London Stop",
        "$address_1" : "2100 Main Street",
        "$city"      : "New London",
        "$region"    : "New Hampshire",
        "$country"   : "US",
        "$zipcode"   : "03257"
    },
      "$arrival_address"  : {
        "$name"      : "Concord Stop",
        "$address_1" : "213 Elm Street",
        "$city"      : "Concord",
        "$region"    : "New Hampshire",
        "$country"   : "US",
        "$zipcode"   : "03301"
    },
    "$start_time"        : 2190121220,
    "$end_time"          : 2290122129,
    "$vessel_number"     : "F Line",
    "$fare_class"        : "Economy",
    }
  ],
  "$price"          : 300000,
  "$currency_code"  : "USD",
  "$quantity"       : 1,
  "$tags"           : ["Holiday Schedule"]
}

{
  "$booking_type" => "$bus",
  "$title"        => "Ride 2a34029, 2 seats",
  "$start_time"   => 2038412903,
  "$end_time"     => 2048412903,
  "$guests"       => [
    {
      "$name"  => "John Doe",
      "$email" => "jdoe@domain.com"
    }
  ],
  "$segments" => [
    {
      "$departure_address"  => {
        "$name"      => "New London Stop",
        "$address_1" => "2100 Main Street",
        "$city"      => "New London",
        "$region"    => "New Hampshire",
        "$country"   => "US",
        "$zipcode"   => "03257"
      },
      "$arrival_address"  => {
        "$name"      => "Concord Stop",
        "$address_1" => "213 Elm Street",
        "$city"      => "Concord",
        "$region"       => "New Hampshire",
        "$country"      => "US",
        "$zipcode"      => "03301"
      },
      "$start_time"       => 2190121220,
      "$end_time"         => 2290122129,
      "$vessel_number"    => "F Line",
      "$fare_class"       => "Economy",
    }
  ],
  "$price"          => 49900000,
  "$currency_code"  => "USD",
  "$quantity"       => 1,
  "$tags"           => ["Holiday Schedule"]
}

array(
  '$booking_type' => '$bus',
  '$title'        => 'Ride 2a34029, 2 seats',
  '$start_time'   => 2038412903,
  '$end_time'     => 2048412903,
  '$guests'       => array(
    array(
      '$name'  => 'John Doe',
      '$email' => 'jdoe@domain.com'
    )
  ),
  '$segments' => array(
    array(
    '$departure_address'  => {
      '$name'      => 'New London Stop',
      '$address_1' => '2100 Main Street',
      '$city'      => 'New London',
      '$region'    => 'New Hampshire',
      '$country'   => 'US',
      '$zipcode'   => '03257'
    ),
    '$arrival_address'  => array(
      '$name'      => 'Concord Stop',
      '$address_1' => '213 Elm Street',
      '$city'      => 'Concord',
      '$region'    => 'New Hampshire',
      '$country'   => 'US',
      '$zipcode'   => '03301'
    ),
    '$start_time'       => 2190121220,
    '$end_time'         => 2290122129,
    '$vessel_number'    => 'F Line',
    '$fare_class'       => 'Economy',
  ),
  '$price'          => 49900000,
  '$currency_code'  => 'USD',
  '$quantity'       => 1,
  '$tags'           => array('Holiday Schedule')
)

import java.util.Arrays;

import com.siftscience.model.Address;
import com.siftscience.model.Booking;
import com.siftscience.model.Segment;

Booking booking = new Booking()
        .setBookingType("$bus")
        .setTitle("Ride 2a34029, 2 seats")
        .setStartTime(2038412903L)
        .setEndTime(2048412903L)
        .setGuests(Arrays.asList(
                new Guest()
                        .setName("John Doe")
                        .setEmail("jdoe@domain.com")
        .setSegments(Arrays.asList(
                new Segment()
                        .setDepartureAddress(new Address()
                                .setName("New London Stop")
                                .setAddress1("2100 Main Street")
                                .setCity("New London")
                                .setRegion("New Hampshire")
                                .setCountry("US")
                                .setZipCode("03257"))
                        .setArrivalAddress(new Address()
                                .setName("Concord Stop")
                                .setAddress1("213 Elm Street")
                                .setCity("Concord")
                                .setRegion("New Hampshire")
                                .setCountry("US")
                                .setZipCode("03301"))
                .setStartTime(2190121220L)
                .setEndTime(2290122129L)
                .setVesselNumber("F Line")
                .setFareClass("Economy")
        .setPrice(49900000L)
        .setCurrencyCode("USD")
        .setQuantity(1L)
        .setTags(Arrays.asList("Holiday Schedule"));

$booking.rideshare

Tell Sift about a booking of a ride in a ridesharing marketplace.

  • $booking_type
    required · String

    $rideshare

  • $title
    String

    A description of the ride.

  • $start_time
    Integer

    The pickup time of the ride. Send as a UNIX timestamp in milliseconds.

  • $end_time
    Integer

    The estimated drop-off time of the ride. Send as a UNIX timestamp in milliseconds.

  • $price
    String

    The price per ride of the booking. Send this field in micros in the base unit of the $currency_code. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.

  • $currency_code
    String

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

  • $quantity
    Integer

    The count of reservations of the given type purchased by the user. This does not necessarily reflect the number of guests (eg, a single ride may be booked for two guests).

  • $guests
    Array of Guests

    Details of the guests on the booking. Send as much information about each guest as you capture.

  • $segments
    Array of Segments

    Add more specific information about the ride (even if there is only one segment).

  • $tags
    Array of Strings

    This field captures any descriptors of the ride. For example, tags might be "sale", "first ride", etc.

{
  "$booking_type" : "$rideshare",
  "$title"        : "Ride 2a34029, 1 seat",
  "$start_time"   : 2038412903, // pickup time
  "$end_time"     : 2048412903, // estimated drop-off time
  "$guests"       : [
    {
      "$name"  : "John Doe",
      "$email" : "jdoe@domain.com"
    }
  ],
  "$segments" : [
    {
      "$departure_address"  : {
          "$name"       : "Mason Theater",
          "$address_1"  : "2100 Main Street",
          "$city"       : "New London",
          "$region"     : "New Hampshire",
          "$country"    : "US",
          "$zipcode"    : "03257"
        },
      "$arrival_address"  : {
          "$address_1"  : "213 Elm Street",
          "$city"       : "Concord",
          "$region"     : "New Hampshire",
          "$country"    : "US",
          "$zipcode"    : "03301"
        },
      "$start_time"    : 2190121220, // pickup time
      "$end_time"      : 2290122129, // estimated drop-off time
      "$vessel_number" : "Toyota Camry 5ABC580",
      "$fare_class"    : "Pool"
    }
  ],
  "$price"          : 3200000,
  "$currency_code"  : "USD",
  "$quantity"       : 1
}

{
  "$booking_type" : "$rideshare",
  "$title"        : "Ride 2a34029, 1 seat",
  "$start_time"   : 2038412903, # pickup time
  "$end_time"     : 2048412903, # estimated drop-off time
  "$guests"       : [
    {
      "$name"  : "John Doe",
      "$email" : "jdoe@domain.com"
    }
  ],
  "$segments" : [
    {
      "$departure_address"  : {
        "$name"      : "Mason Theater",
        "$address_1" : "2100 Main Street",
        "$city"      : "New London",
        "$region"    : "New Hampshire",
        "$country"   : "US",
        "$zipcode"   : "03257"
    },
      "$arrival_address"  : {
        "$address_1" : "213 Elm Street",
        "$city"      : "Concord",
        "$region"    : "New Hampshire",
        "$country"   : "US",
        "$zipcode"   : "03301"
    },
    "$start_time"    : 2190121220, # pickup time
    "$end_time"      : 2290122129, # estimated drop-off time
    "$vessel_number" : "Toyota Camry 5ABC580",
    "$fare_class"    : "Pool"
    }
  ],
  "$price"          : 3200000,
  "$currency_code"  : "USD",
  "$quantity"       : 1
}

{
  "$booking_type" => "$rideshare",
  "$title"        => "Ride 2a34029, 1 seat",
  "$start_time"   => 2038412903, # pickup time
  "$end_time"     => 2048412903, # estimated drop-off time
  "$guests"       => [
    {
      "$name"   => "John Doe",
      "$email"  => "jdoe@domain.com"
    }
  ],
  "$segments" => [
    {
      "$departure_address"  => {
        "$name"      => "Mason Theater",
        "$address_1" => "2100 Main Street",
        "$city"      => "New London",
        "$region"    => "New Hampshire",
        "$country"   => "US",
        "$zipcode"   => "03257"
      },
      "$arrival_address"  => {
        "$address_1" => "213 Elm Street",
        "$city"      => "Concord",
        "$region"    => "New Hampshire",
        "$country"   => "US",
        "$zipcode"   => "03301"
      },
      "$start_time"    => 2190121220, # pickup time
      "$end_time"      => 2290122129, # estimated drop-off time
      "$vessel_number" => "Toyota Camry 5ABC580",
      "$fare_class"    => "Pool"
    }
  ],
  "$price"          => 3200000,
  "$currency_code"  => "USD",
  "$quantity"       => 1
}

array(
  '$booking_type' => '$rideshare',
  '$title'        => 'Ride 2a34029, 1 seat',
  '$start_time'   => 2038412903, // pickup time
  '$end_time'     => 2048412903, // estimated drop-off time
  '$guests'       => array(
    array(
      '$name'  => 'John Doe',
      '$email' => 'jdoe@domain.com'
    )
  ),
  '$segments' => array(
    array(
      '$departure_address'  => {
        '$name'      => 'Mason Theater',
        '$address_1' => '2100 Main Street',
        '$city'      => 'New London',
        '$region'    => 'New Hampshire',
        '$country'   => 'US',
        '$zipcode'   => '03257'
      ),
      '$arrival_address'  => array(
        '$address_1' => '213 Elm Street',
        '$city'      => 'Concord',
        '$region'    => 'New Hampshire',
        '$country'   => 'US',
        '$zipcode'   => '03301'
      ),
      '$start_time'    => 2190121220, // pickup time
      '$end_time'      => 2290122129, // estimated drop-off time
      '$vessel_number' => 'Toyota Camry 5ABC580',
      '$fare_class'    => 'Pool'
  ),
  '$price'          => 3200000,
  '$currency_code'  => 'USD',
  '$quantity'       => 1
)

import java.util.Arrays;

import com.siftscience.model.Address;
import com.siftscience.model.Booking;
import com.siftscience.model.Segment;

Booking booking = new Booking()
        .setBookingType("$rideshare")
        .setTitle("Ride 2a34029, 1 seat")
        .setStartTime(2038412903L) // pickup time
        .setEndTime(2048412903L) // estimated drop-off time
        .setGuests(Arrays.asList(
                new Guest()
                        .setName("John Doe")
                        .setEmail("jdoe@domain.com")
        .setSegments(Arrays.asList(
                new Segment()
                        .setDepartureAddress(new Address()
                                .setName("Mason Theater")
                                .setAddress1("2100 Main Street")
                                .setCity("New London")
                                .setRegion("New Hampshire")
                                .setCountry("US")
                                .setZipCode("03257"))
                        .setArrivalAddress(new Address()
                                .setAddress1("213 Elm Street")
                                .setCity("Concord")
                                .setRegion("New Hampshire")
                                .setCountry("US")
                                .setZipCode("03301"))
                .setStartTime(2190121220L) // pickup time
                .setEndTime(2290122129L) // estimated drop-off time
                .setVesselNumber("Toyota Camry 5ABC580")
                .setFareClass("Pool")
        .setPrice(3200000L)
        .setCurrencyCode("USD")
        .setQuantity(1L);

$booking.vehicle

Tell Sift about a reservation of a car or other vehicle.

A reservation should be for a single type of vehicle (i.e, two different types of vehicles should be in two bookings. However, two of the same vehicle types should be in the same booking with quantity 2).

  • $booking_type
    required · String

    $vehicle

  • $title
    String

    A description of the reservation.

  • $start_time
    Integer

    The pickup time for the reservation. Send as a UNIX timestamp in milliseconds.

  • $end_time
    Integer

    The drop-off time of the reservation. Send as a UNIX timestamp in milliseconds.

  • $price
    String

    The price per vehicle of the reservation. Send this field in micros in the base unit of the $currency_code. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.

  • $currency_code
    String

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

  • $quantity
    Integer

    The count of reservations of the given type purchased by the user. This does not reflect the number of guests (eg, a single vehicle may be booked for two guests), but would reflect the number of vehicles of the same type.

  • $guests
    Array of Guests

    Details of the guests on the reservation. Send as much information about each guest as you capture.

  • $segments
    Array of Segments

    Add more specific information about the reservation.

  • $tags
    Array of Strings

    This field captures any descriptors of the reservation. For example, tags might be "sale", "first ride", etc.

{
  "$booking_type" : "$vehicle",
  "$title"        : "2 Day Rental, New Hampshire",
  "$start_time"   : 2038412903, // pickup time
  "$end_time"     : 2048412903, // estimated drop-off time
  "$guests"       : [
    {
      "$name"  : "John Doe",
      "$email" : "jdoe1985@domain.com"
    },
    {
      "$name"  : "Jane Doe",
      "$email" : "jdoe1983@domain.com"
    }
  ],
  "$segments" : [
    {
      "$departure_address"  : {
          "$name"       : "New London Branch",
          "$phone"      : "1-415-555-6041",
          "$address_1"  : "2100 Main Street",
          "$city"       : "New London",
          "$region"     : "New Hampshire",
          "$country"    : "US",
          "$zipcode"    : "03257"
        },
      "$arrival_address"  : {
          "$name"       : "Concord Branch",
          "$phone"      : "1-415-555-6032",
          "$address_1"  : "213 Elm Street",
          "$city"       : "Concord",
          "$region"     : "New Hampshire",
          "$country"    : "US",
          "$zipcode"    : "03301"
        },
      "$start_time"    : 2190121220, // pickup time
      "$end_time"      : 2290122129, // estimated drop-off time
      "$vessel_number" : "Toyota Camry 5ABC580",
      "$fare_class"    : "Compact"
    }
  ],
  "$price"          : 3200000,
  "$currency_code"  : "USD",
  "$quantity"       : 2
}

{
  "$booking_type" : "$vehicle",
  "$title"        : "2 Day Rental, New Hampshire",
  "$start_time"   : 2038412903, # pickup time
  "$end_time"     : 2048412903, # estimated drop-off time
  "$guests"       : [
    {
      "$name"  : "John Doe",
      "$email" : "jdoe@domain.com"
    },
    {
      "$name"  : "Jane Doe",
      "$email" : "jdoe1983@domain.com"
    }
  ],
  "$segments" : [
    {
      "$departure_address"  : {
        "$name"      : "New London Branch",
        "$phone"      : "1-415-555-6041",
        "$address_1" : "2100 Main Street",
        "$city"      : "New London",
        "$region"    : "New Hampshire",
        "$country"   : "US",
        "$zipcode"   : "03257"
    },
      "$arrival_address"  : {
        "$name"       : "Concord Branch",
        "$phone"      : "1-415-555-6032",
        "$address_1" : "213 Elm Street",
        "$city"      : "Concord",
        "$region"    : "New Hampshire",
        "$country"   : "US",
        "$zipcode"   : "03301"
    },
    "$start_time"    : 2190121220, # pickup time
    "$end_time"      : 2290122129, # estimated drop-off time
    "$vessel_number" : "Toyota Camry 5ABC580",
    "$fare_class"    : "Compact"
    }
  ],
  "$price"          : 3200000,
  "$currency_code"  : "USD",
  "$quantity"       : 2
}

{
  "$booking_type" => "$vehicle",
  "$title"        => "2 Day Rental, New Hampshire",
  "$start_time"   => 2038412903, # pickup time
  "$end_time"     => 2048412903, # estimated drop-off time
  "$guests"       => [
    {
      "$name"   => "John Doe",
      "$email"  => "jdoe1985@domain.com"
    },
    {
      "$name"   => "Jane Doe",
      "$email"  => "jdoe1983@domain.com"
    }
  ],
  "$segments" => [
    {
      "$departure_address"  => {
        "$name"      => "New London Branch",
        "$phone"     => "1-415-555-6041",
        "$address_1" => "2100 Main Street",
        "$city"      => "New London",
        "$region"    => "New Hampshire",
        "$country"   => "US",
        "$zipcode"   => "03257"
      },
      "$arrival_address"  => {
        "$name"     => "Concord Branch",
        "$phone"    => "1-415-555-6032",
        "$address_1" => "213 Elm Street",
        "$city"      => "Concord",
        "$region"    => "New Hampshire",
        "$country"   => "US",
        "$zipcode"   => "03301"
      },
      "$start_time"    => 2190121220, # pickup time
      "$end_time"      => 2290122129, # estimated drop-off time
      "$vessel_number" => "Toyota Camry 5ABC580",
      "$fare_class"    => "Compact"
    }
  ],
  "$price"          => 3200000,
  "$currency_code"  => "USD",
  "$quantity"       => 2
}

array(
  '$booking_type' => '$vehicle',
  '$title'        => '2 Day Rental, New Hampshire',
  '$start_time'   => 2038412903, // pickup time
  '$end_time'     => 2048412903, // estimated drop-off time
  '$guests'       => array(
    array(
      '$name'  => 'John Doe',
      '$email' => 'jdoe1985@domain.com'
    ),
    array(
      '$name'  => 'Jane Doe',
      '$email' => 'jdoe1983@domain.com'
    )
  ),
  '$segments' => array(
    array(
      '$departure_address'  => {
        '$name'      => 'New London Branch',
        '$phone'     => '1-415-555-6041',
        '$address_1' => '2100 Main Street',
        '$city'      => 'New London',
        '$region'    => 'New Hampshire',
        '$country'   => 'US',
        '$zipcode'   => '03257'
      ),
      '$arrival_address'  => array(
        '$name'     =>  'Concord Branch',
        '$phone'     => '1-415-555-6032',
        '$address_1' => '213 Elm Street',
        '$city'      => 'Concord',
        '$region'    => 'New Hampshire',
        '$country'   => 'US',
        '$zipcode'   => '03301'
      ),
      '$start_time'    => 2190121220, // pickup time
      '$end_time'      => 2290122129, // estimated drop-off time
      '$vessel_number' => 'Toyota Camry 5ABC580',
      '$fare_class'    => 'Compact'
  ),
  '$price'          => 3200000,
  '$currency_code'  => 'USD',
  '$quantity'       => 2
)

import java.util.Arrays;

import com.siftscience.model.Address;
import com.siftscience.model.Booking;
import com.siftscience.model.Segment;

Booking booking = new Booking()
        .setBookingType("$vehicle")
        .setTitle("2 Day Rental, New Hampshire")
        .setStartTime(2038412903L) // pickup time
        .setEndTime(2048412903L) // estimated drop-off time
        .setGuests(Arrays.asList(
                new Guest()
                        .setName("John Doe")
                        .setEmail("jdoe1985@domain.com"),
                new Guest()
                        .setName("Jane Doe")
                        .setEmail("jdoe1983@domain.com")
        .setSegments(Arrays.asList(
                new Segment()
                        .setDepartureAddress(new Address()
                                .setName("New London Branch")
                                .setPhone("1-415-555-6041)
                                .setAddress1("2100 Main Street")
                                .setCity("New London")
                                .setRegion("New Hampshire")
                                .setCountry("US")
                                .setZipCode("03257"))
                        .setArrivalAddress(new Address()
                                .setName("Concord Branch)
                                .setAddress1("213 Elm Street")
                                .setCity("Concord")
                                .setRegion("New Hampshire")
                                .setCountry("US")
                                .setZipCode("03301"))
                .setStartTime(2190121220L) // pickup time
                .setEndTime(2290122129L) // estimated drop-off time
                .setVesselNumber("Toyota Camry 5ABC580")
                .setFareClass("Compact")
        .setPrice(3200000L)
        .setCurrencyCode("USD")
        .setQuantity(2L);

$booking.cruise

Tell Sift about the booking of a cruise ticket.

Each type of ticket should be its own booking - for example, an order reserving both premium and standard rooms on the same cruise should get two booking objects.

A booking should also be for one trip - ie, a round trip should be split into two bookings.

  • $booking_type
    required · String

    $cruise

  • $title
    String

    A description of the trip.

  • $start_time
    Integer

    The departure time of the cruise. Send as a UNIX timestamp in milliseconds.

  • $end_time
    Integer

    The arrival time of the cruise. Send as a UNIX timestamp in milliseconds.

  • $price
    String

    The price per ticket of the cruise. Send this field in micros in the base unit of the $currency_code. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.

  • $currency_code
    String

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

  • $quantity
    Integer

    The count of tickets of the given type purchased by the user.

  • $guests
    Array of Guests

    Details of the guests on the cruise. Send as much information about each guest as you capture.

  • $segments
    Array of Segments

    For travel bookings, use this field to send information about the travel segments. Eg. each item in this array would represent a flight segment, a rideshare ride etc

  • $tags
    Array of Strings

    This field captures any descriptors of the reservation. For example, tags might be "last minute deal", "abcd cruise line", "contest winner" etc.

{
  "$booking_type" : "$cruise",
  "$title"        : "Luxury Pacific",
  "$start_time"   : 2038412903, // departure time
  "$end_time"     : 2048412903, // estimated arrival time
  "$guests"       : [
    {
      "$name"  : "John Doe",
      "$email" : "jdoe@domain.com"
    }
  ],
  "$segments" : [
    {
      "$departure_address"  : {
          "$name"       : "Luxury Cruise Pier 21",
          "$address_1"  : "Pier 21",
          "$city"       : "San Francisco",
          "$region"     : "California",
          "$country"    : "US",
          "$zipcode"    : "94401"
        },
      "$arrival_address"  : {
          "$name"       : "Luxury Cruise Pier 09",
          "$address_1"  : "213 Elm Street",
          "$city"       : "Honolulu",
          "$region"     : "Hawaii",
          "$country"    : "US",
          "$zipcode"    : "96795"
        },
      "$start_time"    : 2190121220,
      "$end_time"      : 2290122129,
      "$vessel_number" : "F312",
      "$fare_class"    : "Private Suite"
    }
  ],
  "$price"          : 300000,
  "$currency_code"  : "USD",
  "$quantity"       : 3,
  "$tags"           : ["Contest Winner"]
}

{
  "$booking_type" : "$cruise",
  "$title"        : "Luxury Pacific"",
  "$start_time"   : 2038412903, # departure time
  "$end_time"     : 2048412903, # estimated arrival time
  "$guests"       : [
    {
      "$name"  : "John Doe",
      "$email" : "jdoe@domain.com"
    }
  ],
  "$segments" : [
    {
      "$departure_address"  : {
        "$name"      : "Luxury Cruise Pier 21",
        "$address_1" : "Pier 21",
        "$city"      : "San Francisco",
        "$region"    : "California",
        "$country"   : "US",
        "$zipcode"   : "94401"
    },
      "$arrival_address"  : {
        "$name"      : "Luxury Cruise Pier 09",
        "$address_1" : "213 Elm Street",
        "$city"      : "Honolulu",
        "$region"    : "Hawaii",
        "$country"   : "US",
        "$zipcode"   : "96795"
    },
    "$start_time"    : 2190121220,
    "$end_time"      : 2290122129,
    "$vessel_number" : "F312",
    "$fare_class"    : "Private Suite"
    }
  ],
  "$price"          : 300000,
  "$currency_code"  : "USD",
  "$quantity"       : 3,
  "$tags"           : ["Contest Winner"]
}

{
  "$booking_type" => "$cruise",
  "$title"        => "Luxury Pacific",
  "$start_time"   => 2038412903, # departure time
  "$end_time"     => 2048412903, # estimated arrival time
  "$guests"       => [
    {
      "$name"   => "John Doe",
      "$email"  => "jdoe@domain.com"
    }
  ],
  "$segments" => [
    {
      "$departure_address"  => {
        "$name"      => "Luxury Cruise Pier 21",
        "$address_1" => "Pier 21",
        "$city"      => "San Francisco",
        "$region"    => "California",
        "$country"   => "US",
        "$zipcode"   => "94401"
      },
      "$arrival_address"  => {
      "$name"      => "Luxury Cruise Pier 09",
        "$address_1" => "213 Elm Street",
        "$city"      => "Honolulu",
        "$region"    => "Hawaii",
        "$country"   => "US",
        "$zipcode"   => "96795"
      },
      "$start_time"    => 2190121220,
      "$end_time"      => 2290122129,
      "$vessel_number" => "F312",
      "$fare_class"    => "Private Suite"
    }
  ],
  "$price"          => 300000,
  "$currency_code"  => "USD",
  "$quantity"       => 3,
  "$tags"           => ["Contest Winner"]
}

array(
  '$booking_type' => '$cruise',
  '$title'        => 'Luxury Pacific',
  '$start_time'   => 2038412903, // departure time
  '$end_time'     => 2048412903, // estimated arrival time
  '$guests'       => array(
    array(
      '$name'  => 'John Doe',
      '$email' => 'jdoe@domain.com'
    )
  ),
  '$segments' => array(
    array(
      '$departure_address'  => {
        '$name'      => 'Luxury Cruise Pier 21',
        '$address_1' => 'Pier 21',
        '$city'      => 'San Francisco',
        '$region'    => 'California',
        '$country'   => 'US',
        '$zipcode'   => '94401'
      ),
      '$arrival_address'  => array(
        '$name'      => 'Luxury Cruise Pier 09',
        '$address_1' => '213 Elm Street',
        '$city'      => 'Honolulu',
        '$region'    => 'Hawaii',
        '$country'   => 'US',
        '$zipcode'   => '96795'
      ),
      '$start_time'    => 2190121220,
      '$end_time'      => 2290122129,
      '$vessel_number' => 'F312',
      '$fare_class'    => 'Private Suite'
  ),
  '$price'          => 3200000,
  '$currency_code'  => 'USD',
  '$quantity'       => 3,
  '$tags'           => array('Contest Winner')
)

import java.util.Arrays;

import com.siftscience.model.Address;
import com.siftscience.model.Booking;
import com.siftscience.model.Segment;

Booking booking = new Booking()
        .setBookingType("$cruise")
        .setTitle("Luxury Pacific")
        .setStartTime(2038412903L) // departure time
        .setEndTime(2048412903L) // estimated arrival time
        .setGuests(Arrays.asList(
                new Guest()
                        .setName("John Doe")
                        .setEmail("jdoe@domain.com")
        .setSegments(Arrays.asList(
                new Segment()
                        .setDepartureAddress(new Address()
                                .setName("Luxury Cruise Pier 21")
                                .setAddress1("Pier 21")
                                .setCity("San Francisco")
                                .setRegion("California")
                                .setCountry("US")
                                .setZipCode("94401"))
                        .setArrivalAddress(new Address()
                                .setName("Luxury Cruise Pier 09")
                                .setAddress1("213 Elm Street")
                                .setCity("Honolulu")
                                .setRegion("Hawaii")
                                .setCountry("US")
                                .setZipCode("96795"))
                .setStartTime(2190121220L)
                .setEndTime(2290122129L)
                .setVesselNumber("F312")
                .setFareClass("Private Suite")
        .setPrice(300000L)
        .setCurrencyCode("USD")
        .setQuantity(3L)
        setTags(Arrays.asList("Contest Winner"));

$booking.other

For any reservation use case not covered above, leverage whichever of the following fields are appropriate:

  • $booking_type
    required · String

    $other

  • $title
    String

    A description of the booking.

  • $start_time
    Integer

    The start time of the reservation. Send as a UNIX timestamp in milliseconds.

  • $end_time
    Integer

    The finish time of the reservation. Send as a UNIX timestamp in milliseconds.

  • $price
    String

    The price per unit of the booking. Send this field in micros in the base unit of the $currency_code. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. For currencies without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.

  • $currency_code
    String

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

  • $quantity
    Integer

    The count of reservations of the given type purchased by the user.

  • $guests
    Array of Guests

    Details of the guests on the booking. Send as much information about each guest as you capture.

  • $segments
    Array of Segments

    For bookings with multiple segments, use this field to send information about the travel segments. e.g., each item in this array would represent a flight leg.

  • $room_type
    String

    For hotels or other accommodation bookings, this field represents the type of room. Eg. "Double Queen Deluxe"

  • $event_id
    String

    For event ticket bookings, this field represents the internal identifier associated with the event.

  • $venue_id
    String

    For event ticket bookings, this field represents the name of the venue.

  • $location
    Address

    For event ticket and accommodation bookings, this field represents the address of venue or hotel respectively.

  • $category
    String

    This field can be used to send the category of booking. For event tickets, this field captures the genre of a ticket.

  • $tags
    Array of Strings

    This field captures any descriptors of the events. For event tickets, for example, tags might be team names, region, etc.

Browser

The $browser field type contains information about the browser.

  • $user_agent
    Required · String

    The user agent of the browser that is interacting with your website.

  • $accept_language

    The language(s) that the client is requesting the site content be delivered in. Use ISO-3166 format for country codes. Examples: "en", "en-us, de", "fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5", etc.

  • $content_language

    The language(s) of the user that the delivered site content is intended for. Use ISO-3166 format for country codes. Examples: "en", "en-us, de", "fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5", etc.

{
  "$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",
  "$content_language" : "en-US",
  "$accept_language"  : "en-GB"
}

{
  "$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",
  "$content_language" : "en-US",
  "$accept_language"  : "en-GB"
}

{
  "$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"
  "$content_language" => "en-US",
  "$accept_language"  => "en-GB"
}

// 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',
  '$content_language' => 'en-US',
  '$accept_language'  => 'en-GB'
)

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")
        .setContentLanguage("en-US")
        .setAcceptLanguage("en-GB");

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.

  • $amount
    Required · Integer

    The amount of credits the promotion is worth.

  • $credit_point_type
    Required · String

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

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

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_off
    Float

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

  • $amount
    Integer

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

  • $currency_code
    String

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

  • $minimum_purchase_amount
    Integer

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

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

Guest

The Guest field type represents a person using a booking. The value must be a nested object with the appropriate subfields.

$guest is used as an array item in the $guests subfield of $booking.

  • $name
    String

    Name of the individual on the booking.

  • $email
    String

    The email address provided for the guest.

  • $phone
    String

    The phone number provided for the guest. 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.

  • $loyalty_program
    String

    The name of the loyalty program used for this guest.

  • $loyalty_program_id
    String

    The membership id for the loyalty program used for this guest.

  • $birth_date
    String

    The date of birth of the guest. Use ISO 8601 format, e.g. "1985-03-20" or "19850320"

{
  "$name"                : "John Doe",
  "$birth_date"          : "1985-01-19",
  "$loyalty_program"     : "skymiles",
  "$loyalty_program_id"  : "PSOV34DF",
  "$phone"               : "1-415-555-6040",
  "$email"               : "jdeo@domain.com"
}

{
  "$name"                : "John Doe",
  "$birth_date"          : "1985-01-19",
  "$loyalty_program"     : "skymiles",
  "$loyalty_program_id"  : "PSOV34DF",
  "$phone"               : "1-415-555-6040",
  "$email"               : "jdeo@domain.com"
}

{
  "$name"                => "John Doe",
  "$birth_date"          => "1985-01-19",
  "$loyalty_program"     => "skymiles",
  "$loyalty_program_id"  => "PSOV34DF",
  "$phone"               => "1-415-555-6040",
  "$email"               => "jdeo@domain.com"
}

array(
  '$name'                 => 'John Doe',
  '$birth_date'           => '1985-01-19',
  '$loyalty_program'      => 'skymiles'
  '$loyalty_program_id'   => 'PSOV34DF',
  '$phone'                => '1-415-555-6040',
  '$email'                => 'jdeo@domain.com'
);

import com.siftscience.model.Guest;

Guest guest1 = new Guest()
        .setName("John Doe")
        .setBirthDate("1985-01-19")
        .setLoyaltyProgram("skymiles")
        .setLoyaltyProgramId("PSOV34DF")
        .setPhone("1-415-555-6040")
        .setEmail("jdeo@domain.com");

Image

The Image complex type represents an image hosted on your website or app, typically uploaded by a user. Used in the in one of the $create_content or $update_content events.

  • $md5_hash
    String

    The MD5 hash of the image file. A hexadecimal hash for a single file could look like this: 0cc175b9c0f1b6a831c399e269772661.

  • $link
    String

    A hyperlink to the image file.

  • $description
    String

    The user-supplied caption with the image.

// Example $image field value
{
  "$md5_hash"     : "0cc175b9c0f1b6a831c399e269772661",
  "$link"         : "https://www.example.com/file.png",
  "$description"  : "Example picture"
}
# Example $image field value
{
  '$md5_hash'     => '0cc175b9c0f1b6a831c399e269772661',
  '$link'         => 'https://www.example.com/file.png',
  '$description'  => 'Example picture'
}
# Example $image field value
{
  "$md5_hash"     : "0cc175b9c0f1b6a831c399e269772661",
  "$link"         : "https://www.example.com/file.png",
  "$description"  : "Example picture"
}
// Example $image field value
array(
  '$md5_hash'     => '0cc175b9c0f1b6a831c399e269772661',
  '$link'         => 'https://www.example.com/file.png',
  '$description'  => 'Example picture'
)
// Example $image field value
Image image = new Image()
        .setMd5Hash("0cc175b9c0f1b6a831c399e269772661")
        .setLink("https://www.example.com/file.png")
        .setDescription("Example picture");

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 represented as a nested JSON object.

Please note that $item cannot be used with $booking. Customers in event ticketing or travel (such as OTAs, Rideshare, Vehicle rentals, Hotels, etc) should use $booking instead to leverage Sift’s specialization in Travel and Ticketing use cases.

  • $item_id
    String

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

  • $product_title
    String

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

  • $price
    Integer

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

  • $currency_code
    String

    ISO-4217 currency code for the price.

  • $quantity
    Integer

    Quantity of the item.

  • $upc
    String

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

  • $sku
    String

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

  • $isbn
    String

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

  • $brand
    String

    The brand name of the item.

  • $manufacturer
    String

    Name of the item's manufacturer.

  • $category
    String

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

  • $tags
    Array of Strings

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

  • $color
    String

    The color of the item.

  • $size
    String

    The size of the item.

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

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

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

# Example 2
item = {
  "$item_id"        : "10101042",
  "$product_title"  : "Delivering Happiness [eBook edition]",
  "$price"          : 6990000, # $6.99
  "$currency_code"  : "CDN",
  "$isbn"           : "0446576220",
  "$sku"            : "10101042",
  "$brand"          : "Writers of the Round Table Press",
  "$manufacturer"   : "eBook Digital Services, Inc.",
  "$category"       : "Business books",
  "$tags"           : ["reprint", "paperback", "Tony Hsieh"],
  "$quantity"       : 1
}

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

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

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

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

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

Merchant Profile

The $merchant_profile field type contains information about the merchant or seller providing the goods or service.

  • $merchant_id
    required · String

    The internal identifier for the merchant or seller providing the good or service.

  • $merchant_category_code
    String

    The merchant category code follows the 4-digit ISO code. Use ISO-18245 MCC ISO Merchant Category Code.

  • $merchant_name
    required · String

    The name of the merchant or seller providing the good or service.

  • $merchant_address
    Address

    The address associated with the merchant of record.

"$merchant_profile" : {
  "$merchant_id"            : "AX527123",
  "$merchant_category_code" : "1234",
  "$merchant_name"          : "Dream Company",
  "$merchant_address" : {
    "$phone"      : "1-415-555-6040",
    "$address_1"  : "2100 Main Street",
    "$address_2"  : "Apt 3B",
    "$city"       : "New London",
    "$region"     : "New Hampshire",
    "$country"    : "US",
    "$zipcode"    : "03257"
  }
}

"$merchant_profile" : {
  "$merchant_id"            : "AX527123",
  "$merchant_category_code" : "1234",
  "$merchant_name"          : "Dream Company",
  "$merchant_address" : {
    "$phone"      : "1-415-555-6040",
    "$address_1"  : "2100 Main Street",
    "$address_2"  : "Apt 3B",
    "$city"       : "New London",
    "$region"     : "New Hampshire",
    "$country"    : "US",
    "$zipcode"    : "03257"
  }
}

"$merchant_profile" => {
  "$merchant_id"            => "AX527123",
  "$merchant_category_code" => "1234",
  "$merchant_name"          => "Dream Company",
  "$merchant_address" => {
    "$phone"      => "1-415-555-6040",
    "$address_1"  => "2100 Main Street",
    "$address_2"  => "Apt 3B",
    "$city"       => "New London",
    "$region"     => "New Hampshire",
    "$country"    => "US",
    "$zipcode"    => "03257"
  }
}

$merchant_profile = array(
  '$merchant_id'            => 'AX527123',
  '$merchant_category_code' => '1234',
  '$merchant_name'          => 'Dream Company',
  '$merchant_address' => array(
    '$phone'      => '1-415-555-6040',
    '$address_1'  => '2100 Main Street',
    '$address_2'  => 'Apt 3B',
    '$city'       => 'New London',
    '$region'     => 'New Hampshire',
    '$country'    => 'US',
    '$zipcode'    => '03257'
  )
)

import com.siftscience.model.MerchantProfile;

MerchantProfile merchantProfile = new MerchantProfile()
        .setMerchantId("AX527123")
        .setMerchantCategoryCode("1234")
        .setMerchantName("Dream Company)
        .setMerchantAddress(new Address()
                .setPhone("1-415-555-6040")
                .setAddress1("2100 Main Street")
                .setAddress2("Apt 3B)
                .setCity("New London")
                .setRegion("New Hampshire")
                .setCountry("US")
                .setZipCode("03257"));

Ordered From

The $ordered_from field type contains information about the specific physical location providing the good or service. This can also be used to capture pickup, delivery locations, etc.

We use the values of the latest version of the $ordered_from object for each $order_id for reporting in your console. If you send all other fields except $zipcodein a $create_order and then send only $zipcode in a later, associated $transaction for the same $order_id, we will only use $zipcode for this order in reporting and forget the initial $ordered_from fields sent. So, we recommend that you send this object in either the $create_order/$update_order events OR in $transaction events, but not in both. Choose the time where you have the most information to send or where it is easiest to include.

  • $store_id
    String

    The customer’s internal identifier for the specific physical location providing the good or service.

  • $store_address
    Address

    The address of the specific physical location providing the good or service.

"$ordered_from" : {
  "$store_id"      : "123",
  "$store_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"
  }
}

"$ordered_from" : {
  "$store_id"      : "123",
  "$store_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"
  }
}

"$ordered_from" => {
  "$store_id"      => "123",
  "$store_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"
  }
}

$ordered_from = array(
  '$store_id'      => '123',
  '$store_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'
  )
)

import com.siftscience.model.OrderedFrom;

OrderedFrom orderedFrom = new OrderedFrom()
        .setStoreId("123")
        .setStoreAddress(new Address()
                .setName("New London Stop")
                .setAddress1("2100 Main Street")
                .setCity("New London")
                .setRegion("New Hampshire")
                .setCountry("US")
                .setZipCode("03257"));

Payment Method

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

  • $payment_type
    String

    The general type of payment being used.

    Allowed Values
    • $cash$check$credit_card$crypto_currency$debit_card$digital_wallet$electronic_fund_transfer $financing$gift_card$invoice$in_app_purchase$money_order $points$prepaid_card$store_credit$third_party_processor$voucher$sepa_credit$sepa_instant_credit $sepa_direct_debit$ach_credit$ach_debit$wire_credit$wire_debit

    If your payment system is not covered by one of the values above please contact support.

  • $payment_gateway
    String

    The specific gateway, company, product, etc. being used to process payment.

    Allowed Values
    • $abra$acapture$adyen$aeropay$afex$affinipay $affipay$affirm$afrivoucher$afterpay$alipay$allpago $altapay$amazon_payments$ambank_fpx$amex_checkout$android_iap $android_pay$apg$apple_iap$apple_pay$argus$astropay $atrium$authorizenet$avangate $balanced$bancodobrasil$bancontact$bancoplural$banorte $banwire$barclays$bayanpay$bbcn$bcb$beanstream $belfius$best_inc$billdesk$billpocket$bitgo$bitpay $bizum$blackhawk$blockchain$bluepay$bluesnap $bnpparibas$boacompra$bob$boku$bold$boletobancario $boltpay$bpay$bradesco$braintree$bread$bridgepay $buckaroo $cadc$cardconnect$cardknox$cashlib$catchball$ccbill $ccavenue$ceevo$cepbank$chain_commerce$chase_paymentech $checkalt$checkoutcom$cielo$circle$citrus_pay $clear_junction$clearbridge$clearsettle$clearcommerce $cleverbridge$close_brothers$cloudpayments$cofinoga$coinbase $coindirect$coinpayments$collector$community_bank_transfer $commweb$compropago$concardis$conekta$credit_union_atlantic $credorax$credsystem$cross_river$cuentadigital$culqi $cybersource$cryptocapital$cryptopay$currencycloud $daopay$datacash$dbs_paylah$dcbank$debitway$deltec $democracy_engine$deutsche_bank$dibs$digital_river$digitalpay $dlocal$dotpay$dragonpay$dwolla $ebanx$ecommpay$ecopayz$edenred$edgil_payway$efecty $eft$elavon$empcorp$enets$epay$epayeu$epoch $eprocessing_network$eps$esitef$etana$euteller$everypay $eway$e_xact $fastnetwork$fat_zebra$fidor$finix$fiserv $first_atlantic_commerce$first_data$flexepin$flexiti$fluidpay $flutterwave$fpx$frick$fxpaygate $g2apay$galileo$gcash$geoswift$getnet$giropay $globalcollect$global_payments$global_payways$gmo$gmopg $gocardless$gocoin$google_pay$google_wallet $hanmi$hdfc_fssnet$heidelpay$hipay$humm$hyperpay $i2c$ibok$ideal$ikajo$incore$ingenico $inghomepay$inovapay$inovio$instamojo$interac $internetsecure$intuit_quickbooks_payments$ipay$isignthis$itau $itelebill$iugu$ixopay$iyzico$izettle $jabong$jatis$jeton$jnfx$juspay $kash$kbc$kddi$klarna$knet$konbini$kushki $latamgateway$latampass$laybuy$lemonway$lifemiles $limelight$link4pay$logon $mada$mangopay$mastercard_payment_gateway$masterpass $maxipago$maxpay$maybank$mcb$meikopay$mercadopago $merchant_esolutions$midtrans$minerva$mirjeh$mobile_money $moip$mollie$momopay$moneris_solutions$moneygram $monoova$moyasar$mpesa$muchbetter$multibanco $multicaja$multiplus$mvb$mybank$myfatoorah $naranja$neosurf$netbilling$netregistry$neteller $network_for_good$nhn_kcp$nicepay$ngenius$nmcryptgate $nmi$noble$noon_payments $ogone$okpay$omcp$omise$onebip$openpaymx $optile$optimal_payments$oxxo $paddle$pagar_me$pagoefectivo$pagofacil$pagseguro $papara$paxum$pay_garden$pay_zone$pay4fun$paybright $paycase$paycash$paydoo$payease$payeer$payeezy $payfast$payfix$payflow$payfort$paygarden$paygate $paygent$payix$payjp$payjunction$paykwik$paylike $paymaya$paymentez$paymentos$paymentwall$payment_express $paymill$paynl$payone$payoneer$payop$paypal $paypal_express$paysafe$paysafecard$paysera$paysimple $payssion$paystack$paystation$paytabs$paytm$paytrace $paytrail$payture$payway$payu$payulatam$payvector $payza$payzen$peach_payments$perfect_money$pinpayments $pivotal_payments$pix$plaid$planet_payment$plugandplay $poli$posconnect$primetrust$princeton_payment_solutions $prismpay$processing$przelewy24$psigate$pulse$pwmb $qiwi$qr_code_bt$quadpay$quaife$quickpay$quickstream $raberil$radial$railsbank$rakuten_checkout$rapipago $rappipay$ratepay$ravepay$razorpay$rbkmoney$reach $recurly$red_dot_payment$rede$redpagos$redsys $rewardspay$rietumu$ripple$rocketgate $safecharge$safetypay$sagepay$samsung_pay$santander$sbi $secure_trading$securepay$securionpay$sentbe$sepa $sermepa$servipag$sezzle$shopify_payments$signature $silvergate$simplify_commerce$skrill$smart2pay$smartcoin $smartpayments$smbc$snapscan$sofort$splash_payments $splitit$spotii$sps_decidir$square$stcpay$stone $stripe$swedbank$synapsepay $tabapay$tabby$tamara$tapcompany$tdcanada$telerecargas $tfm$tipalti$tnspay$todopago$towah$tpaga $transact_pro$transactive$transfirst$transpay$truelayer $trustcommerce$trustly$trustpay$tsys_sierra$tsys_transit $tu_compra$twoc2p$twocheckout $undostres$unionpay$upay$usa_epay$usafill$utrust $vantiv$vapulus$venmo$veritrans$versapay$vesta $viabaloto$vindicia$virtual_card_services$visa$vme $vogogo$vpos $watchman$webbilling$webmoney$webpay$webpay_oneclick $wechat$wepay$western_union$wirecard$worldpay $worldspan$wp_cnpapi$wyre $xfers$xipay $yandex_money$yapily$yapstone $zapper$zeus$zip$zipmoney$zoop$zooz_paymentsos

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

  • $card_bin
    String

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

  • $card_last4
    String

    The last four digits of the credit card number.

  • $avs_result_code
    String

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

  • $cvv_result_code
    String

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

  • $verification_status
    String

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

  • $routing_number
    String

    This is the ABA routing number, BIC or SWIFT code used.

  • $shortened_iban_first6
    String

    This is the first 6 characters of the IBAN structure as defined in ISO 13616-1.

  • $shortened_iban_last4
    String

    This is the last 4 characters of the IBAN structure as defined in ISO 13616-1.

  • $sepa_direct_debit_mandate
    Boolean

    Use true or false to indicate if a end-user/customer has provided authorization to collect future payments via Sepa Direct Debit.

  • $decline_reason_code
    String

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

  • $paypal_payer_id
    String

    Payer ID returned by Paypal.

  • $paypal_payer_email
    String

    Payer email address returned by Paypal.

  • $paypal_payer_status
    String

    Payer status returned by Paypal.

  • $paypal_address_status
    String

    Payer address status returned by Paypal.

  • $paypal_protection_eligibility
    String

    Seller protection eligibility returned by Paypal.

  • $paypal_payment_status
    String

    Payment status returned by Paypal.

  • $stripe_cvc_check
    String

    CVC verification result returned by Stripe.

  • $stripe_address_line1_check
    String

    Address line 1 verification result returned by Stripe.

  • $stripe_address_line2_check
    String

    Address line 2 verification result returned by Stripe.

  • $stripe_address_zip_check
    String

    Address zip code verification result returned by Stripe.

  • $stripe_funding
    String

    Funding source returned by Stripe.

  • $stripe_brand
    String

    Card brand returned by Stripe.

  • $account_holder_name
    String

    Full name of the user associated with the account.

  • $account_number_last5
    String

    The last 5 digits of the account number associated with an ACH or a Wire transaction.

  • $bank_name
    String

    Name of the financial institution used.

  • $bank_country
    String

    Two-digit ISO-3166 code for the bank country of origin.

// 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",
  }
]

// An ACH Credit Payment, as it would appear
// in a $create_order event.
"$payment_methods"  :  [
  {
       "$payment_type"  :  "$ach_credit",
       "$routing_number"  : "4444333333",
       "$account_number_last5"  : "44144",
       "$account_holder_name"  : "John Smith",
  }
]

// 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",
  }
]

# An ACH Credit Payment, as it would appear
# in a $create_order event.
"payment_methods"  :  [
  {
    "$payment_type"  :  "$ach_credit",
    "$routing_number"  : "4444333333",
    "$account_number_last5"  : "44144",
    "$account_holder_name"  : "John Smith",
  }
]

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

# An ACH Credit Payment, as it would appear
# in a $create_order event.
"payment_methods"  =>  [
  {
    "$payment_type"  =>  "$ach_credit",
    "$routing_number"  => "4444333333",
    "$account_number_last5"  => "44144",
    "$account_holder_name"  => "John Smith",
  }
]

# 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.
$paymentMethods = array(
  array(
    '$payment_type'  => '$third_party_processor',
    '$payment_gateway'  => '$paypal',
    '$paypal_payer_id'  => '7E7MGXCWKTKK2',
    '$paypal_payer_email'  => 'bill@gmail.com'
  )
);

// An ACH Credit Payment, as it would appear
// in a $create_order event.
$paymentMethods = array(
  array(
    '$payment_type'  => '$ach_credit',
    '$routing_number'  => '4444333333',
    '$account_number_last5'  => '44144',
    '$account_holder_name'  => 'John Smith'
  )
);

// 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.
List paymentMethods = 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")
);

// An ACH Credit Payment, as it would appear
// in a $create_order event.
paymentMethods = Arrays.asList(
    new PaymentMethod()
                .setPaymentType("$ach_credit")
                .setRoutingNumber("4444333333")
                .setAccountNumberLast5("44144")
                .setAccountHolderName("John Smith")
);

// 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_id
    String

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

  • $status
    String

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

    Allowed Values
    • $success $failure
  • $failure_reason
    String

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

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

    Freeform text to describe the promotion.

  • $referrer_user_id
    String

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

  • $discount
    Discount

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

  • $credit_point
    Credit Point

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

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

Segment

The Segment field type supports more detailed information about the components of a travel$booking. The value must be a nested object with the appropriate subfields.

We recommend sending at least one segment for the following booking_types:

  1. $flight
  2. $bus
  3. $rideshare
  4. $vehicle
  5. $cruise

Even if there’s only a single segment associated with the booking, use segment to send valuable information about the trip.

  • $departure_address
    Address

    The address of the start of the journey. This could be the pickup address for rideshare or the train station address for a rail journey. For flights, you can use the $departure_airport_code in lieu of this field.

  • $arrival_address
    Address

    The address of the end of the journey. This could be the drop-off address for rideshare or the train station address for a rail journey. For flights, you can use the $arrival_airport_code in lieu of this field.

  • $start_time
    Integer

    The start time of this segment of the journey. This may be departure time for a flight, the expected pickup time for a rideshare, etc. Send as a UNIX timestamp in milliseconds.

  • $end_time
    Integer

    The finish time of this segment of the journey. This may be departure time for a flight, the expected pickup time for a rideshare, etc. Send as a UNIX timestamp in milliseconds.

  • $vessel_number
    String

    An identifier for the journey: this could be the flight number ("UA 454"), the car license plate number ("6XYZ123"), etc.

  • $departure_airport_code
    String

    The IATA code for the departure airport. For example: "SFO"

  • $arrival_airport_code
    String

    The IATA code for the arrival airport. For example: "SEA"

  • $fare_class
    String

    A description of the class of travel. Eg. "Premium Economy", "Pool", "E3".

{
  "$departure_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"
  },
  "$arrival_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"
  },
  "$start_time"             : 2190121220,
  "$end_time"               : 2290122129,
  "$vessel_number"          : "LH454",
  "$fare_class"             : "Premium Economy",
  "$departure_airport_code" : "SFO",
  "$arrival_airport_code"   : "LAS"
}

{
  "$departure_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"
  },
  "$arrival_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"
  },
  "$start_time"             : 2190121220,
  "$end_time"               : 2290122129,
  "$vessel_number"          : "LH454",
  "$fare_class"             : "Premium Economy",
  "$departure_airport_code" : "SFO",
  "$arrival_airport_code"   : "LAS"
}

{
  "$departure_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"
  },
  "$arrival_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"
  },
  "$start_time"             => 2190121220,
  "$end_time"               => 2290122129,
  "$vessel_number"          => "LH454",
  "$fare_class"             => "Premium Economy",
  "$departure_airport_code" => "SFO",
  "$arrival_airport_code"   => "LAS"
}

array(
  '$departure_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'
  ),
  '$arrival_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'
  ),
  '$start_time'             => 2190121220,
  '$end_time'               => 2290122129,
  '$vessel_number'          => 'LH454',
  '$fare_class'             => 'Premium Economy',
  '$departure_airport_code' => 'SFO',
  '$arrival_airport_code'   => 'LAS'
);

import com.siftscience.model.Address;
import com.siftscience.model.Segment;

Segment segment1 = new Segment()
        .setDepartureAddress(new Address()
                .setName("Bill Jones")
                .setPhone("1-415-555-6040")
                .setAddress1("2100 Main Street")
                .setAddress2("Apt 3B")
                .setCity("New London")
                .setRegion("New Hampshire")
                .setCountry("US")
                .setZipCode("03257"))
        .setArrivalAddress(new Address()
                .setName("Bill Jones")
                .setPhone("1-415-555-6040")
                .setAddress1("2100 Main Street")
                .setAddress2("Apt 3B")
                .setCity("New London")
                .setRegion("New Hampshire")
                .setCountry("US")
                .setZipCode("03257"))
        .setStartTime(2190121220L)
        .setEndTime(2290122129L)
        .setVesselNumber("LH454")
        .setFareClass("Premium Economy")
        .setDepartureAirportCode("SFO")
        .setArrivalAirportCode("LAS");

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(api_key='{apiKey}', account_id='{accountId}')

# 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 include alphanumeric characters and _.
  • the $api_key field where you provide your REST API key.
  • the $user_id or, if not available, the $session_id which identifies the user taking this action.

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

Custom Field Suffixes

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

  • Email
    _email · String

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


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

  • Phone
    _phone · String

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


    Send phone numbers in field names like secondary_phone and mobile_phone.

  • Latitude
    _lat · Float

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


    Send latitudes in field names like dropoff_location_lat.

  • Longitude
    _lng · Float

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


    Send longitudes in field names like dropoff_location_lng.

  • ID
    _id · String

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


    Send IDs in field names like buyer_user_id or store_id.

  • Status
    _status · String

    Status of an event.

    Allowed Values
    • $success
    • $failure
    • $pending

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

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

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


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

Error Codes

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

Any non-zero status indicates an error.

{
    "status" : 51,         // Non-zero status indicates an error!
    "error_message" : "Invalid API Key. Please check your credentials and try again.",
    "time" : 1327604222,   // When we received the original request (as seconds since the epoch)
    "request" : "{ \"$api_key\": \"XXXXXXXXXXX\", \"$type\": \"$capture_payment\"... }"
}

# To check if the call was successful:
response.is_ok() # returns true on successful calls, false on failed score requests.

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

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

# To check if the call was successful:
response.ok? # returns true on successful calls, false on failed score requests.

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

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

// To check if the call was successful:
response->isOk() // returns true on successful calls, false on failed score requests.

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

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

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

  • 114

    Invalid event type

  • 116

    Event cannot be processed due to legal restrictions

  • 117

    List exceeds maximum size


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, content 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 Post”, “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 the creation of a post (eg Content Abuse Score > 95), Sift generates the Decision on that content, and sends a Webhook to your system so you can block the post 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, session or content.
  • 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 account_takeover
  • 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 entity. (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.
  • 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, content 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.

Request

Arguments
  • decision_id
    required · 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 with entity_type=user can only be applied to a user. Similarly, a Decision configured with entity_type=order can only be applied to an order.

  • source
    required · String

    The source of this Decision.

    Allowed Values
    • MANUAL_REVIEW
      This Decision was applied by an analyst during review of a user/order.
    • AUTOMATED_RULE
      This 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.
    • CHARGEBACK
      This 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.
  • analyst
    String

    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.

  • time
    optional · Long

    The time the Decision was applied, as a UNIX timestamp in milliseconds. This is only necessary to send for historical backfill.

  • description
    optional · String

    A description of the Decision that will be applied.

Apply User Decision
$ 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='{apiKey}', 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);
Order Decision
$ 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='{apiKey}', 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);
Session Decision
$ 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_fraud_account_takeover",
          "source"        : "MANUAL_REVIEW",
          "analyst"       : "analyst@example.com",
          "description"   : "compromised account reported to customer service"
        }'

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' => 'my_account_id'));

$options = array(
    'analyst' => 'analyst@example.com',
    'description' => 'compromised account reported to customer service
');

$response = $client->applyDecisionToSession('userId','sessionId','session_looks_fraud_account_takeover','MANUAL_REVIEW',$options);
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("sessionId")
            .setDecisionId("session_looks_fraud_account_takover")
            .setSource(DecisionSource.MANUAL_REVIEW)
           .setAnalyst("analyst@example.com")
            .setDescription("compromised account reported to customer service")
);

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: "session_looks_fraud_account_takover",
  description: "compromised account reported to customer service",
  source: "MANUAL_REVIEW",
  analyst: "analyst@example.com",
  user_id: "userId",
  session_id: "sessionId"
})

if (!response.ok?)
  puts "Unable to apply decision: " + response.api_error_message
end
import sift



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

applyDecisionRequest = {
    'decision_id': "session_looks_fraud_account_takover",
    'source': "MANUAL_REVIEW",
    'analyst': 'analyst@example.com'
    'description': 'compromised account reported to customer service'
}

response = self.client.apply_order_decision(user_id, session_id, apply_session)
Content Decision
$ curl -XPOST https://api.sift.com/v3/accounts/{accountId}/users/{userId}/content/{contentId}/decisions
-H 'Content-Type: application/json' \
-u {YOUR_API_KEY}:
-d \
        '{
          "decision_id"   : "content_looks_fraud_content_abuse",
          "source"        : "MANUAL_REVIEW",
          "analyst"       : "analyst@example.com",
          "description"   : "fraudulent listing"
        }'
require "sift"
client = Sift::Client.new({api_key: "{YOUR_API_KEY}", account_id: "{accountId}"})

response = client.apply_decision({
  decision_id: "content_looks_fraud_content_abuse",
  description: "fraudulent listing",
  source: "AUTOMATED_RULE",
  analyst: "analyst@example.com",
  user_id: "userId",
  content_id: "contentId"
})

if (!response.ok?)
  puts "Unable to apply decision: " + response.api_error_message
end
import sift

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

applyDecisionRequest = {
    'decision_id'    : 'content_looks_fraud_content_abuse',
    'source'         : 'MANUAL_REVIEW',
    'analyst'.       : 'analyst@example.com',
    'description'    : 'fraudulent listing'

}

response = self.client.apply_content_decision(user_id, content_id, applyDecisionRequest)
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' => 'frauulent listing'
);

$response = $client->applyDecisionToContent('userId',
    'contentId',
    'content_looks_fraud_content_abuse',
    'MANUAL_REVIEW',
    $options);
import com.siftscience.ApplyDecisionRequest;
import com.siftscience.ApplyDecisionResponse;
import com.siftscience.SiftClient;
import com.siftscience.model.ApplyDecisionFieldSet;

SiftClient client = new SiftScience("{YOUR_API_KEY}");
ApplyDecisionRequest request;
ApplyDecisionRequest request = client.buildRequest(
        new ApplyDecisionFieldSet()
            .setAccountId("accountId")
            .setUserId("userId")
            .setContentId("contentId")
            .setDecisionId("content_looks_fraud_content_abuse")
            .setAnalyst("analyst@example.com")
            .setDescription("fraudulent listing")
            .setSource(ApplyDecisionFieldSet.DecisionSource.MANUAL_REVIEW));

ApplyDecisionResponse response;

try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
}

DecisionLog decisionLog = response.getDecisionLog();

Response

For successful requests, the response will have an HTTP status code of 200.

Attributes
  • entity
    Object

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

    • id
      String

      The id of the entity on which the Decision was applied.

    • type
      String

      Type of entity, (user or order), to which Decision was applied.

  • decision
    String

    The Decision object containing information on the Decision that was applied.

    • id
      String

      The id of the Decision that was applied.

  • time
    Long

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

{
    "entity": {
        "id" : {entity_id}
        "type" : "{entity_type}"
    },
    "decision": {
        "id": "{decision_id}"
    },
    "time": "1461963439151"
    }
}

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
# or
curl -XGET https://api.sift.com/v3/accounts/{accountId}/users/{userId}/content/{contentId}/decisions
-H 'Content-Type: application/json' \
-u {YOUR_API_KEY}:

import sift

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

response = client.get_user_decisions('the_user_id')
# or
response = client.get_order_decisions('the_order_id')
# or
response = client.get_content_decisions('the_user_id', 'the_content_id')
# or
response = client.get_session_decisions('the_user_id', 'the_session_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')
# or
response = client.get_content_decisions('the_user_id', 'the_content_id')
# or 
response = client.get_session_decisions('the_user_id', 'the_session_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');
// or
$response = $client->getContentDecisions('the_user_id', 'the_content_id');
// or
$response = $client->getSessionDecisions('the_user_id', 'the_session_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"));
// or
request = client.buildRequest(new DecisionStatusFieldSet()
.setAccountId("4e1a50e172beb95cf1e4ae54")
.setEntity(DecisionStatusFieldSet.ENTITY_CONTENT)
.setUserId("the_user_id")
.setEntityId("the_content_id"));

// or
request = client.buildRequest(new DecisionStatusFieldSet()
.setAccountId("4e1a50e172beb95cf1e4ae54")
.setEntity(DecisionStatusFieldSet.ENTITY_SESSION)
.setUserId("the_user_id")
.setEntityId("the_session_id"));

DecisionStatusResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
}
Map 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 (users, orders, sessions, or content) 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
    },
    "account_takeover": {
      "decision": {
        "id": "block_session_account_takeover"
      },
      "time": 1461966441151,
      "webhook_succeeded": true
    }
  }
}

Response Fields

  • decisions
    Object

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

    Possible Key Values
    • payment_abuse
      The associated JSON object is the latest Decision for the Payment Abuse abuse type.
    • promo_abuse
      The associated JSON object is the latest Decision for the Promo Abuse abuse type.
    • content_abuse
      The associated JSON object is the latest Decision for the Content Abuse abuse type.
    • account_abuse
      The associated JSON object is the latest Decision for the Account Abuse abuse type.
    • legacy
      The associated JSON object is the latest Decision for the Legacy abuse type.
    • account_takeover
      The 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 object
      Object

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

      • decision
        Object

        The Decision object containing information on the Decision taken.

        • id
          String

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


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

      • time
        Long

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

      • webhook_succeeded
        Boolean

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

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,account_takeover&entity_type=user&from=5&limit=10
-u {YOUR_API_KEY}:

import sift

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

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_type
    optional · String

    Return only decisions applicable to the specified entity_type.

    Allowed Values
    • USER
      This Decision should be applied to users.
    • ORDER
      This Decision should be applied to orders.
    • SESSION
      This Decision should be applied to sessions.
    • CONTENT
      This Decision should be applied to content.
  • abuse_types
    optional · Comma-separated strings

    Return only decisions applicable to specified abuse_types.

    Allowed Values
    • LEGACY
      Return Decisions associated with the Legacy product.
    • PAYMENT_ABUSE
      Return Decisions associated with the Payment Abuse product.
    • ACCOUNT_ABUSE
      Return Decisions associated with the Account Abuse product.
    • CONTENT_ABUSE
      Return Decisions associated with the Content Abuse product.
    • PROMO_ABUSE
      Return Decisions associated with the Promotion Abuse product.
    • ACCOUNT_TAKEOVER
      Return Decisions associated with the Account Takeover product.
  • limit
    optional · 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.

  • from
    optional · integer

    Used in conjunction with limit parameter to page through the result set. By default, result set is sorted by id. The field from specifies the index of the first entry in a collection to return. The default value for from is 0. For example if from 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"
    },
    {
      "id": "session_looks_fraud_account_takeover",
      "name": "Session looks fraud",
      "description": "Manually reviewed, looks fraud (suspected ATO)",
      "category": "block",
      "entity_type": "session",
      "abuse_type": "account_takeover",
      "created_at": 1511204532332,
      "created_by": "billy@example.com",
      "updated_at": 1511204539924,
      "updated_by": "billy@example.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

  • data
    Array

    An array of decisions.

    • id
      String

      The id of the decision. This is auto generated when the Decision is created based on the initial display name of the Decision.

    • name
      String

      Display name of the decision.

    • description
      String

      A description of the Decision. This field is intended as a way to describe the business action(s) associated with the Decision.

    • entity_type
      String

      Entity type to which this Decision is applicable.

      Possible Values
      • USER
        This Decision should be applied to users.
      • ORDER
        This Decision should be applied to orders.
      • SESSION
        The Decision should be applied to sessions.
      • CONTENT
        The Decision should be applied to content.
    • abuse_type
      String

      Abuse type which this Decision describes.

      Possible Values
      • LEGACY
        Return Decisions associated with the Legacy product.
      • PAYMENT_ABUSE
        Return Decisions associated with the Payment Abuse product.
      • ACCOUNT_ABUSE
        Return Decisions associated with the Account Abuse product.
      • CONTENT_ABUSE
        Return Decisions associated with the Content Abuse product.
      • PROMO_ABUSE
        Return Decisions associated with the Promotion Abuse product.
    • category
      String

      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
      • ACCEPT
        Accept entity
      • WATCH
        Watch entity
      • BLOCK
        Block entity
    • webhook_url
      String

      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_at
      integer

      Time at which the Decision was created, as a UNIX timestamp in milliseconds.

    • created_by
      String

      User who created decision.

    • updated_at
      integer

      Time at which the Decision was last updated, as a UNIX timestamp in milliseconds.

    • updated_by
      String

      User who last updated the Decision.

  • has_more
    boolean

    For result sets that span multiple requests, the has_more field indicates whether more results may be retrieved. Used in conjunction with next_ref to paginate result sets.

  • next_ref
    boolean

    For paginated results, next_ref contains a URL where the next set of results can be retrieved

Decision Webhooks

Decision Webhooks can be set up when you create or edit a Decision in the Sift Console. If you haven't yet configured webhooks on your Decisions, read our Connecting Decisions to Business Actions tutorial to learn how. Once you've configured webhooks for a Decision, we'll start sending webhooks to the URL you've specified whenever a Decision is applied by a user or automatically by a Workflow. Webhooks will be sent with the following body:

Response

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

Response Fields

  • entity
    Object

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

    • type
      String

      The type of entity on which the Decision was taken.

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

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

  • decision
    Object

    The Decision object containing information on the Decision taken.

    • id
      String

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


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

  • time
    Long

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

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

Authentication

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

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
}

Workflows API Overview

The final, and most important step to integrating with Sift is to write business logic that makes Decisions based on the Sift Risk Score. Workflows allow you to write and evaluate this logic in Sift. For example, you can setup a Workflow that evaluates whenever a user creates an account. You can specify criteria (e.g. country = "Canada" and 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 in the console.

Please read our Creating a Workflow tutorial, which will walk you through the process of creating Workflows and attaching Decisions/Review Queues to them.

Workflows Integration

To successfully integrate with Workflows, you need to send the trigger event to Sift , and ingest the Workflow Decision. There are two ways to consume Workflow Decisions:

  • Synchronously when you send Sift any REST API event using the return_workflow_status=true 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 if you send the trigger event to Sift without any parameters, the Workflow will run asynchronously. This is best for when you don't need to take action immediately after the triggering event occurs. In this scenario you will need to set up your Workflow Decisions with webhooks to successfully consume the output of the Workflow. Additionally note that if you have set up your Workflow to only run with API request, you must send the Workflow trigger event with the force_workflow_run=true parameter to ensure that the workflow executes asynchronously.
Note

If your workflow includes Review Queues, you will need to configure Webhooks on the queue Decisions. Also note that you can both run a Workflow synchronously, and receive Webhooks. This is a common case for Workflows that both auto block some users and queue medium risk users in the review queue.

Synchronous Workflows

Request

If you want to receive the Workflow 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.

Query Parameters
  • return_workflow_status
    Boolean

    Set to true to get the Workflow Decision Synchronously. If a Workflow is not running on the event you send this with, it will just return a score synchronously with an empty workflow_statuses block.

  • abuse_types
    optional · String

    the abuse type of the scores that you want to return. If you are a customer that has not upgraded to abuse specific scores, and are just using "Sift Score", you must set to legacy to get a score.

curl -X POST "https://api.sift.com/v205/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(api_key='{apiKey}', account_id='{accountId}')

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;
}

Response

Attributes
  • status
    Integer

    Success or Error Code of the event ingestion.

  • error_message
    String
  • request
    String

    The event you sent

  • time
    Integer

    Time event was processed

  • score_response
    Object
    • status
      Integer

      Success or Error Code of the re-score.

    • error_message
      String
    • user_id
      String
    • scores
      Scores Map
    • latest_labels
      Latest Labels Map
    • 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. If the Workflow has a fatal error, or there is no running Workflow configured for this event, the object will be empty.

      • id
        String

        The run ID of this specific Workflow run. Pass to the Workflow Status API to view the latest Workflow Status for this ID.

      • state
        String

        The state of this Workflow run. When you request a status synchronously, the workflow will either be running or failed. If it is running, but the history includes a Decision, there will be no further updates.

      • config
        Object

        Details about the Workflow ID and version.

        • id
          String

          The static, unique identifier ID of the Workflow

        • version
          String

          The version of this Workflow. This updates each time the Workflow logic is updated

      • config_display_name
        String

        The Workflow's current display name

      • abuse_types
        String

        A list of abuse types of the Decisions this Workflow can apply. Possible Values are payment_abuse, promotion_abuse, content_abuse, account_abuse, account_takeover, and legacy.

      • entity
        Object

        Information about the entity that this Workflow is Deciding on.

        • type
          String

          The type of entity on which the Decision was taken. Possible Values are user, order, content, or session

        • id
          String

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

      • history
        Object

        A list of apps/stages that have occurred in the Workflow run.

        • app
          String

          The type of app which was run. Values include decision, review queue, order, user, content, session, and event.

          Decision is the final stage in a Workflow so a Workflow is complete when the Decision app is reached. review_queue means the item is queued in the Sift Console waiting for an analyst decision.
          The other options are internal apps, indicating the event was processed, and the apps indicate the entity was scored by our Machine Learning system.

        • name
          String

          The display name of the app which was run.

        • state
          String

          The state of this app. Options are either running, finished, or failed.

        • config
          Object

          The configuration information of the app.

          • decision_id
            String

            The unique identifier of the Decision taken in this app. This will only be returned if the app is a decision app.

          • buttons
            Object

            A list of Decision buttons currently configured in the Review Queue.

            • id
              String

              The unique Decision ID for this button.

            • name
              String

              The display name for this button.

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

Asynchronous Workflows

If you have a running Workflow configured in the Sift Console, and you send the Workflow trigger event without setting return_workflow_status=true, the Workflow will run asynchronously. See Events API to see how to send events to Sift. Workflows that are ran asynchronously, and Workflows that use Review Queues require Webhooks to receive the final Decision.

To receive Decision Webhooks, just add a Webhook URL to the Decisions used in your Workflow, and see Decision Webhooks documentation.

If your Workflow is configured to only run on API Request, you will need to include force_workflow_run=true to run the Workflow asynchronously.

Force Asynchronous Run Request

Query Parameters
  • force_workflow_run
    Boolean

    Set to true to run the Workflow Asynchronously if your Workflow is set to only run on API Request. If a Workflow is not running on the event you send this with, there will be no error or score response, and no workflow will run.

  • abuse_types
    optional · String

    the abuse type of the scores that you want to return. If you are a customer that has not upgraded to abuse specific scores, and are just using "Sift Score", you must set to legacy to get a score.

curl -X POST "https://api.sift.com/v205/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(api_key='{apiKey}', account_id='{accountId}')

properties = {
  '$user_id'    : 'test_user',
  '$user_email' : 'sample_user@gmail.com'
} 
response = client.track('$create_order', properties, force_workflow_run=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, :force_workflow_run => 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(
          'force_workflow_run' => 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"))
        .withForceWorkflowRun()
        .withScores("promo_abuse", "payment_abuse");

EventResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
    return;
}

Workflow Status API

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 Run ID. You can get this by using the Synchronous Workflow Status API when you send the initial Workflow event. This API is useful for gathering information on previously executed Workflows.

Request

Arguments
  • api_key
    string

    Your rest api key, located in the API Keys section in the Console.

  • account_id
    string

    Your Account ID, found in the Profile section of the Account Settings Page in the Console.

  • workflow_run_id
    string

    Obtained in the response of synchronous workflow 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='{apiKey}', account_id='{accountId}')

workflow_run_id = '123' 
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'
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' 
$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("123")
        .setAccountId("4e1a50e172beb95cf1e4ae54"));

WorkflowStatusResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
    return;
}
response.getBody().getState(); // "running", "finished", or "failed"

Response

Attributes
  • id
    String

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

  • state
    String

    The state of this Workflow instance.

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

    An object containing the configuration information for this Workflow.

    • id
      String

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

    • version
      String

      The version of this Workflow.

  • config_display_name
    String

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

  • abuse_types
    String

    A list of abuse types of the Decisions this Workflow can apply. Possible Values are payment_abuse, promotion_abuse, content_abuse, account_abuse, account_takeover, and legacy.

  • entity
    Object

    Information about the entity that this Workflow is Deciding on.

    • type
      String

      The type of entity on which the Decision was taken. Possible Values are user, order, content, or session

    • id
      String

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

  • history
    Object

    A list of apps objects that have occurred in the Workflow run. You can think of these as Workflow stages.

    • app
      String

      The type of app which was run. The type of app which was run. Values include decision, review queue, order, user, content, session, and event.


      Decision is the final stage in a Workflow so a Workflow is complete when the Decision app is reached. review queue means the item is queued in the Sift Console waiting for an analyst decision.
      The other options are internal apps, indicating the event was processed, and the apps indicate the entity was scored by our Machine Learning system.

    • name
      String

      The app display name.

    • state
      String

      The state of this app. The possible values are running, finished, or failed

    • config
      Object

      The configuration information of the app.

      • decision_id
        String

        The unique identifier of the Decision taken in this app. This field only exists if the app type is decision.

      • buttons
        Object

        A list of button objects associated with the review queue.

        • id
          String

          The unique Decision ID for this button.

        • name
          String

          The display name for this button.

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

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 six 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).
  • Account Takeover - the risk that an account is accessed through stolen credentials
  • Legacy - this is a legacy version of the Sift Score that scored users for custom fraud types, similar to the Account Abuse score.

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 four different ways to get scores from Sift:

  1. Get a score synchronously when you send an event
  2. Get a score and workflows status synchronously when you send an event
  3. Get the latest score without sending an event
  4. Get a score by forcing the re-scoring of a user

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.

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.

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.

curl -X POST "https://api.sift.com/v205/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(api_key='{apiKey}', account_id='{accountId}')

# 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;
}

Response

Fields
  • status
    Integer

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

  • error_message
    String

    Description of status code.

  • request
    String

    The content of the event you sent.

  • time
    Integer

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

  • score_response
    Object

    The requested scoring information for the given user.

    • status
      Integer

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

    • error_message
      String

      Description of error if applicable.

    • scores
      Map

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

      • score
        Float

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

      • reasons
        Array

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

        • name
          String

          Name of the risk signal.

        • value
          String

          Value of the risk signal.

        • details
          Object

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

    • user_id
      String

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

    • latest_labels
      Map

      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 event 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 ID. 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_fraud
        Boolean

        true if the user is labeled Fraud, false if the user is labeled Not Fraud.
      • time
        Long

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

        Freeform text description of the user and/or incident triggering the label.
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");

Error Codes

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

    OK

  • 51

    Invalid API key

  • 54

    Specified user_id has no scoreable events

  • 60

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

Note: This API is deprecated. To get scores without sending an event, we recommend using the Get Scores API.

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/v205/score/USER_ID_HERE/?api_key=YOUR_API_KEY"

import sift

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

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/v205/score/USER_ID_HERE/?api_key=YOUR_API_KEY&abuse_types=payment_abuse,promotion_abuse"

import sift

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

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

  • status
    Integer

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

  • error_message
    String

    Description of error if applicable.

  • scores
    Map

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

    • score
      Float

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

    • reasons
      Array

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

      • name
        String

        Name of the risk signal.

      • value
        String

        Value of the risk signal.

      • details
        Object

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

  • user_id
    String

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

  • latest_labels
    Map

    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 event 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 ID. 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_fraud
      Boolean

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

    • time
      Long

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

    • description
      String

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

Error Codes

  • -4

    Service currently unavailable. Please try again later.

  • -3

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

  • -2

    Unexpected server-side error

  • -1

    Unexpected server-side error

  • 0

    OK

  • 51

    Invalid API key

  • 54

    Specified user_id has no scoreable events

  • 60

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

Get Scores API Reference

The Get Scores API is meant to retrieve the latest risk score Sift has computed. This is useful for when there is not a natural user event to send, but you would like to see the risk score before making a decision. 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
  • Approving an order in your review tool

If you need a score back quickly after a user 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 a user 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.

Request

Request scores for a user and abuse types using the (optional) abuse_types query parameter.

curl -XGET https://api.sift.com/v205/users/{UserId}/score?api_key={apiKey}&abuse_types=payment_abuse,promotion_abuse

import sift

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

response = client.get_user_score(user_id = "USER_ID_HERE", abuse_types=["payment_abuse", "promotion_abuse"])

import "sift"

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

response = client.get_user_score("USER_ID_HERE", :abuse_types => ["payment_abuse", "promotion_abuse"])


require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';
 
$client = new SiftClient(array('api_key' => 'REST_API_KEY_HERE'));
 
$response = $client->get_user_score('USER_ID_HERE', array('abuse_types' => array('payment_abuse', 'promotion_abuse')));

import com.siftscience.SiftClient;
import com.siftscience.UserScoreRequest;
import com.siftscience.EntityScoreResponse;
import com.siftscience.UserScoreFieldSet;
 
SiftClient client = new SiftClient("your_api_key_here");
UserScoreRequest request = client.buildRequest(new UserScoreFieldSet()
        .setUserId("user_id_here")
        .setAbuseTypes(Arrays.asList("payment_abuse", "account_abuse")));
 
EntityScoreResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
    return;
}

Response

Fields
  • status
    Integer

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

  • error_message
    String

    Description of error if applicable.

  • scores
    Map

    The scores map contains the computed scores for all applicable abuse types. 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:

    • score
      Float

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

    • time
      Long

      The time at which the score was generated, as a UNIX timestamp.

    • reasons
      Array

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

      • name
        String

        Name of the risk signal.

      • value
        String

        Value of the risk signal.

      • details
        Object

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

  • entity_type
    String

    What type of entity is the score in reference to. This defaults to user.

  • entity_id
    String

    The id for which the score was requested.

  • latest_decisions
    Map

    The latest_decisions map contains entries for all abuse types for which Decisions have been applied on the given entity. Note that the content of this map is not subject to the abuse types specified in the request; we always include all Decisions that have been applied to the given entity. 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:

    • id
      String

      The id of the Decision that was applied.

    • type
      String

      One of the following: BLOCK, WATCH, ACCEPT

    • source
      String

      The source of this Decision. One of the following: AUTOMATED_RULE, MANUAL_REVIEW, CHARGEBACK

    • time
      Long

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

    • description
      String

      The description of the Decision, if available.

  • latest_labels
    Map

    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 event 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 ID. 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_fraud
      Boolean

      true if the user is labeled Fraud, false if the user is labeled Not Fraud.
    • time
      Long

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

      Freeform text description of the user and/or incident triggering the label.
{
  "status": 0, 
  "error_message": "OK",
  "user_id": "billy_jones_301",
  "scores": {
    "payment_abuse": {
      "status": 0, 
      "error_message": "OK",      
      "score": 0.898391231245,
      "time": 84710383103092309,
      "reasons": [
        {
          "name": "UsersPerDevice",
          "value": 4,
          "details": {
            "users": "a, b, c, d"
          }
        }
      ]
    },
    "promotion_abuse": {
      "status": 0, 
      "error_message": "OK",
      "score": 0.472838192111,
      "reasons": []
    },
    "account_takeover": {
      "status": -1, 
      "error_message": "Unexpected server-side error",
    },
  },
  "latest_decisions": {
    "payment_abuse": {
      "id": "user_looks_bad_payment_abuse",
      "type": "block",
      "source": "AUTOMATED_RULE",
      "time": 1352201880,
      "description": "Bad Fraudster",
    }            
  },
  "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 decision for a specific abuse type
decision = response.body['latest_decisions']['payment_abuse']['id'] if 'latest_decisions' 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 decision for a specific abuse type
decision = response.body.has_key?('latest_decisions') ? response.body['latest_decisions']['payment_abuse']['id'] : 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 decision for a specific abuse type
response.getBody().getLatestDecisions().get("payment_abuse");

// get Sift Score for a specific abuse type
Math.round(response.getScore("payment_abuse") * 100);

Error Codes

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

    OK

  • 51

    Invalid API key

  • 54

    Specified user_id has no scoreable events

  • 60

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

  • 64

    Specified user does not have a previously computed score.

Re-score API Reference

The Re-score API is meant to force the computation of a new Sift score. This is useful for when there is not a natural user event to send, but you would like to update and retrieve the risk score based on user activity that you know to have occurred since the last time the score was computed. If you do not believe that the user has had any activity since the last score computation, we recommend using the Get Scores API.

We do not recommend sending event data for a user and then very quickly attempting to get the score back with the Re-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 a user 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.

Request

Request scores for a user and abuse types using the (optional) abuse_types query parameter

curl -X POST https://api.sift.com/v205/users/{UserId}/score?api_key={apiKey}&abuse_types=payment_abuse,promotion_abuse

import sift

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

response = client.rescore_user(user_id = "USER_ID_HERE", abuse_types=["payment_abuse", "promotion_abuse"])


import "sift"

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

response = client.rescore_user("USER_ID_HERE", :abuse_types => ["payment_abuse", "promotion_abuse"])


require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';
 
$client = new SiftClient(array('api_key' => 'REST_API_KEY_HERE'));
 
$response = $client->rescore_user('USER_ID_HERE', array('abuse_types' => array('payment_abuse', 'promotion_abuse')));

import com.siftscience.SiftClient;
import com.siftscience.UserScoreRequest;
import com.siftscience.EntityScoreResponse;
import com.siftscience.UserScoreFieldSet;
 
SiftClient client = new SiftClient("your_api_key_here");
UserScoreRequest request = client.buildRequest(new UserScoreFieldSet()
        .setUserId("user_id_here")
        .setRescoreUser(true)
        .setAbuseTypes(Arrays.asList("payment_abuse", "account_abuse")));
 
EntityScoreResponse response;
try {
    response = request.send();
} catch (SiftException e) {
    System.out.println(e.getApiErrorMessage());
    return;
}

Response

Fields
  • status
    Integer

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

  • error_message
    String

    Description of error if applicable.

  • scores
    Map

    The scores map contains the computed scores for all applicable abuse types. 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:

    • score
      Float

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

    • time
      Long

      The time at which the score was generated, as a UNIX timestamp.

    • reasons
      Array

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

      • name
        String

        Name of the risk signal.

      • value
        String

        Value of the risk signal.

      • details
        Object

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

  • entity_type
    String

    What type of entity is the score in reference to. This defaults to user.

  • entity_id
    String

    The id for which the score was requested.

  • latest_decisions
    Map

    The latest_decisions map contains entries for all abuse types for which Decisions have been applied on the given entity. Note that the content of this map is not subject to the abuse types specified in the request; we always include all Decisions that have been applied to the given entity. 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:

    • id
      String

      The id of the Decision that was applied.

    • type
      String

      One of the following: BLOCK, WATCH, ACCEPT

    • source
      String

      The source of this Decision. One of the following: AUTOMATED_RULE, MANUAL_REVIEW, CHARGEBACK

    • time
      Long

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

    • description
      String

      The description of the Decision, if available.

  • latest_labels
    Map

    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 event 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 ID. 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_fraud
      Boolean

      true if the user is labeled Fraud, false if the user is labeled Not Fraud.
    • time
      Long

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

      Freeform text description of the user and/or incident triggering the label.
{
  "status": 0, 
  "error_message": "OK",
  "user_id": "billy_jones_301",
  "scores": {
    "payment_abuse": {
      "status": 0, 
      "error_message": "OK",      
      "score": 0.898391231245,
      "time": 84710383103092309,
      "reasons": [
        {
          "name": "UsersPerDevice",
          "value": 4,
          "details": {
            "users": "a, b, c, d"
          }
        }
      ]
    },
    "promotion_abuse": {
      "status": 0, 
      "error_message": "OK",
      "score": 0.472838192111,
      "reasons": []
    },
    "account_takeover": {
      "status": -1, 
      "error_message": "Unexpected server-side error",
    },
  },
  "latest_decisions": {
    "payment_abuse": {
      "id": "user_looks_bad_payment_abuse",
      "type": "block",
      "source": "AUTOMATED_RULE",
      "time": 1352201880,
      "description": "Bad Fraudster",
    }
  },
  "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 decision for a specific abuse type
decision = response.body['latest_decisions']['payment_abuse']['id'] if 'latest_decisions' 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 decision for a specific abuse type
decision = response.body.has_key?('latest_decisions') ? response.body['latest_decisions']['payment_abuse']['id'] : 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().getLatestDecisions().get("payment_abuse");

// get Sift Score for a specific abuse type
Math.round(response.getScore("payment_abuse") * 100);

Error Codes

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

    OK

  • 51

    Invalid API key

  • 54

    Specified user_id has no scoreable events

  • 60

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

  • 64

    Specified user does not have a previously computed score.

  • 100
    Required fields missing
  • 111
    Feature disabled
  • 112
    Abuse product disabled

Verification API Guide

Verification is a two-factor authentication solution built into Sift. Verification enables the triggering of one-time passwords for risky login attempts based on our ATO risk score. Configuration includes integrating with our Verification API as well as an in-console setup. The in-console setup involves creating TFA email templates and generating CNAMEs to update your DNS records so we can send emails on your behalf.

This service is designed for sending emails to the already-confirmed emails of account owners. It is not designed as a tool to confirm whether an email address is real or is owned by a user. Therefore, it works best when you use email addresses that you have already validated are real and owned by the user account the 2FA code is being sent for.

Check

The /check call is used for sending the OTP provided by the end user to Sift. Sift then checks the validity of the OTP, checks rate limits, and responds with a decision whether the user should be able to proceed or not.

Use Sift's response to determine what action to take:

  • If the user was successfully verified, then let the user log in to the site.
  • If the user failed to verify (wrong code, too many attempts, etc.), then present an error message to the user. The message should inform the user what to do next ("click resend and try again" or "wait for minutes and try again")

Authenticate your requests using the Basic HTTP Authorization scheme with your production API key as the user_id: Authorization: Basic base_64_encode(production_api_key)

Request

Fields
  • user_id
    required · String

    User ID of user being verified, e.g. johndoe123.

  • code
    required · Integer

    The code the user sent to the customer for validation.

  • verified_event
    String (enum)

    This will be the event type that triggered the verification. Possible values are $add_item_to_cart, $add_promotion, $content_status, $create_account, $create_content, $create_order, $flag_content, $login, $order_status, $remove_item_from_cart, $transaction, $transaction, $update_account, $update_content, $update_order and $update_password.

  • verified_entity_id
    String

    The ID of the entity impacted by the event being verified.

curl -X POST "http://api.sift.com/v1/verification/check"
  -H "Content-Type: application/json"
  -d '{
    "$user_id" : "billy_jones_301",
    "$code": 123456,
    "$verified_event": "$login",
    "$verified_entity_id": "SOME_SESSION_ID"
  }'

curl -X POST "http://api.sift.com/v1/verification/check"
  -H "Content-Type: application/json"
  -d '{
    "$user_id" : "billy_jones_301",
    "$code": 123456,
    "$verified_event": "$login",
    "$verified_entity_id": "SOME_SESSION_ID"
  }'

curl -X POST "http://api.sift.com/v1/verification/check"
  -H "Content-Type: application/json"
  -d '{
    "$user_id" : "billy_jones_301",
    "$code": 123456,
    "$verified_event": "$login",
    "$verified_entity_id": "SOME_SESSION_ID"
  }'

curl -X POST "http://api.sift.com/v1/verification/check"
  -H "Content-Type: application/json"
  -d '{
    "$user_id" : "billy_jones_301",
    "$code": 123456,
    "$verified_event": "$login",
    "$verified_entity_id": "SOME_SESSION_ID"
  }'

curl -X POST "http://api.sift.com/v1/verification/check"
  -H "Content-Type: application/json"
  -d '{
    "$user_id" : "billy_jones_301",
    "$code": 123456,
    "$verified_event": "$login",
    "$verified_entity_id": "SOME_SESSION_ID"
  }'

Response

Fields
  • status
    Integer

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

  • error_message
    String

    Human readable description of the error.

  • checked_at
    Integer

    The time the OTP verified, as a UNIX timestamp in milliseconds.

{
    '$status': 0,
    '$error_message': 'OK',
    '$checked_at': 1566324368002
}

{
    '$status': 0,
    '$error_message': 'OK',
    '$checked_at': 1566324368002
}

{
    '$status': 0,
    '$error_message': 'OK',
    '$checked_at': 1566324368002
}

{
    '$status': 0,
    '$error_message': 'OK',
    '$checked_at': 1566324368002
}

{
    '$status': 0,
    '$error_message': 'OK',
    '$checked_at': 1566324368002
}

Resend

A user can ask for a new OTP (one-time password) if they haven’t received the previous one, or in case the previous OTP expired. The /resend call generates a new OTP and sends it to the original recipient with the same settings (template, verified event info).

Authenticate your requests using the Basic HTTP Authorization scheme with your production API key as the user_id: Authorization: Basic base_64_encode(production_api_key)

Request

Fields
  • user_id
    required · String

    User ID of user being verified, e.g. johndoe123.

  • verified_event
    String (enum)

    This will be the event type that triggered the verification. Possible values are $add_item_to_cart, $add_promotion, $content_status, $create_account, $create_content, $create_order, $flag_content, $login, $order_status, $remove_item_from_cart, $transaction, $transaction, $update_account, $update_content, $update_order and $update_password.
  • verified_entity_id
    String

    The ID of the entity impacted by the event being verified.

curl -X POST "http://api.sift.com/v1/verification/resend"
  -H "Content-Type: application/json"
  -d '{
    "$user_id" : "billy_jones_301",
    "$verified_event": "$login",
    "$verified_entity_id": "SOME_SESSION_ID"
  }'

curl -X POST "http://api.sift.com/v1/verification/resend"
  -H "Content-Type: application/json"
  -d '{
    "$user_id" : "billy_jones_301",
    "$verified_event": "$login",
    "$verified_entity_id": "SOME_SESSION_ID"
  }'

curl -X POST "http://api.sift.com/v1/verification/resend"
  -H "Content-Type: application/json"
  -d '{
    "$user_id" : "billy_jones_301",
    "$verified_event": "$login",
    "$verified_entity_id": "SOME_SESSION_ID"
  }'

curl -X POST "http://api.sift.com/v1/verification/resend"
  -H "Content-Type: application/json"
  -d '{
    "$user_id" : "billy_jones_301",
    "$verified_event": "$login",
    "$verified_entity_id": "SOME_SESSION_ID"
  }'

curl -X POST "http://api.sift.com/v1/verification/resend"
  -H "Content-Type: application/json"
  -d '{
    "$user_id" : "billy_jones_301",
    "$verified_event": "$login",
    "$verified_entity_id": "SOME_SESSION_ID"
  }'

Response

Fields
  • status
    Integer

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

  • error_message
    String

    Human readable description of the error.

  • send_at
    Integer

    The time the OTP was sent, as a UNIX timestamp in milliseconds.

{
    '$status': 0,
    '$error_message': 'OK',
    '$sent_at': 1566324368002
}

{
    '$status': 0,
    '$error_message': 'OK',
    '$sent_at': 1566324368002
}

{
    '$status': 0,
    '$error_message': 'OK',
    '$sent_at': 1566324368002
}

{
    '$status': 0,
    '$error_message': 'OK',
    '$sent_at': 1566324368002
}

{
    '$status': 0,
    '$error_message': 'OK',
    '$sent_at': 1566324368002
}

Send

Sift strongly recommends using Verification with Workflows. However, you may want to use the /send endpoint for testing purposes. The /send endpoint initiates a user’s 2FA flow: it triggers the generation of a OTP code that is stored by Sift and emails the code to the user. It will also produce a pending $verification event in the user’s activity log.

Authenticate your requests using the Basic HTTP Authorization scheme with your production API key as the user_id: Authorization: Basic base_64_encode(production_api_key)

Request

Fields
  • user_id
    required · String

    User ID of user being verified, e.g. johndoe123

  • send_to
    required · String

    The phone / email to send the OTP to.

  • event.$session_id
    required · String

    The session being verified. See $verification in the Sift Events API documentation.

  • verification_type
    required · String

    The channel used for verification

  • verified_entity_id
    String

    The ID of the entity impacted by the event being verified.

  • event.$verified_event
    required · String

    The type of the reserved event being verified.

  • brand_name
    String

    Name of the brand of product or service the user interacts with.

  • site_country
    String

    Country of the content of the site.

  • (FOR APP) event.$app.$client_language
    String (Locale: enum of ISO 639-1 language codes)

    Language the application content is being delivered in.

  • (FOR BROWSER) event.$browser.$content_language
    String (Locale: enum of ISO 639-1 language codes)

    Language of the content of the web site.

  • event.$ip
    String

    The user’s IP address

  • event.$browser
    Sift Browser object

    The user agent of the browser that is verifying. Represented by the $browser object. Use this field if the client is a browser. Note: cannot be used in conjunction with $app.

  • event.app
    Sift App object

    The details of the app, OS, and device that is verifying. Represented by the $app object. Use this field if the client is an app. Note: cannot be used in conjunction with $browser.

  • event.$reason
    String

    The trigger for the verification. See $verification in the Sift Events API documentation.

curl -X POST "http://api.sift.com/v1/verification/send"
  -H "Content-Type: application/json"
  -d '{
     "$user_id" : "billy_jones_301",
     "$send_to":	"billy_jones_301@gmail.com",
     "$verification_type": "$email",
     "$brand_name": "MyTopBrand",
     "$language": "en",
     "$event": {
          "$session_id": "SOME_SESSION_ID"
          "$verified_event": "$login",
          "$reason": "$automated_rule",
          "$ip": "192.168.1.1",
          "$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"
          }
     }
   }'

curl -X POST "http://api.sift.com/v1/verification/send"
  -H "Content-Type: application/json"
  -d '{
     "$user_id" : "billy_jones_301",
     "$send_to":	"billy_jones_301@gmail.com",
     "$verification_type": "$email",
     "$brand_name": "MyTopBrand",
     "$language": "en",
     "$event": {
          "$session_id": "SOME_SESSION_ID"
          "$verified_event": "$login",
          "$reason": "$automated_rule",
          "$ip": "192.168.1.1",
          "$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"
          }
     }
   }'

curl -X POST "http://api.sift.com/v1/verification/send"
  -H "Content-Type: application/json"
  -d '{
     "$user_id" : "billy_jones_301",
     "$send_to":	"billy_jones_301@gmail.com",
     "$verification_type": "$email",
     "$brand_name": "MyTopBrand",
     "$language": "en",
     "$event": {
          "$session_id": "SOME_SESSION_ID"
          "$verified_event": "$login",
          "$reason": "$automated_rule",
          "$ip": "192.168.1.1",
          "$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"
          }
     }
   }'


curl -X POST "http://api.sift.com/v1/verification/send"
  -H "Content-Type: application/json"
  -d '{
     "$user_id" : "billy_jones_301",
     "$send_to":	"billy_jones_301@gmail.com",
     "$verification_type": "$email",
     "$brand_name": "MyTopBrand",
     "$language": "en",
     "$event": {
          "$session_id": "SOME_SESSION_ID"
          "$verified_event": "$login",
          "$reason": "$automated_rule",
          "$ip": "192.168.1.1",
          "$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"
          }
     }
   }'

curl -X POST "http://api.sift.com/v1/verification/send"
  -H "Content-Type: application/json"
  -d '{
     "$user_id" : "billy_jones_301",
     "$send_to":	"billy_jones_301@gmail.com",
     "$verification_type": "$email",
     "$brand_name": "MyTopBrand",
     "$language": "en",
     "$event": {
          "$session_id": "SOME_SESSION_ID"
          "$verified_event": "$login",
          "$reason": "$automated_rule",
          "$ip": "192.168.1.1",
          "$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

Fields
  • status
    Integer

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

  • error_message
    String

    Human readable description of the error.

  • send_at
    Integer

    The time the OTP was sent, as a UNIX timestamp in milliseconds.

{
    '$status': 0,
    '$error_message': 'OK',
    '$sent_at': 1566324368002
}

{
    '$status': 0,
    '$error_message': 'OK',
    '$sent_at': 1566324368002
}

{
    '$status': 0,
    '$error_message': 'OK',
    '$sent_at': 1566324368002
}

{
    '$status': 0,
    '$error_message': 'OK',
    '$sent_at': 1566324368002
}

{
    '$status': 0,
    '$error_message': 'OK',
    '$sent_at': 1566324368002
}

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

  • accountId
    required · string

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

  • deviceId
    required · string

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

Response

  • id
    required · string

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

  • first_seen
    integer

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

  • users
    object

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

    • data
      required · array

      The list of data elements

      • id
        required · string

        id of the referenced resource

    • has_more
      boolean

      True if there are more data elements available

    • next_ref
      string

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

    • total_results
      integer

      The total number of results, if known

  • sessions
    object

    A list of sessions in which this device has been seen

    • data
      required · array

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

      • time
        integer

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

    • has_more
      boolean

      True if there are more sessions available

    • next_ref
      string

      A link to the next set of sessions, if available

    • total_results
      integer

      The total number of results, if known

  • label
    string

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

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

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

  • network
    object

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

    • first_seen
      integer

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

    • score
      number

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

    • pervasiveness
      string

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

      Allowed Values
      • low
      • medium
      • high

Label a Device

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

Use this endpoint to flag devices as either "fraud" or "not_fraud". Most likely you will need to link some concept of a user (e.g. email address or user id) to a Device Fingerprint at some point in your product flow. Then, 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 {API_KEY}: \
  -d '{
  "label" : "fraud"
}'
Example Response
{
  "label" : "fraud"
}

Parameters

  • accountId
    required · string

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

  • deviceId
    required · string

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

Entity

  • label
    string

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

Response

  • label
    string

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

Session Information

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

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

Example Request
$ curl -XGET 'https://api.sift.com/v3/accounts/529def32fe6b73f31300126e/sessions/465733823' \
  -H 'Content-Type: application/json' \
  -u {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

  • accountId
    required · string

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

  • sessionId
    required · string

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

Response

  • time
    integer

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

  • device
    object

    Data related to a Device Fingerprint

    • id
      required · string

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

    • first_seen
      integer

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

    • users
      object

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

      • data
        required · array

        The list of data elements

        • id
          required · string

          id of the referenced resource

      • has_more
        boolean

        True if there are more data elements available

      • next_ref
        string

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

      • total_results
        integer

        The total number of results, if known

    • sessions
      object

      A list of sessions in which this device has been seen

      • data
        required · array

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

        • time
          integer

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

      • has_more
        boolean

        True if there are more sessions available

      • next_ref
        string

        A link to the next set of sessions, if available

      • total_results
        integer

        The total number of results, if known

    • label
      string

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

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

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

    • network
      object

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

      • first_seen
        integer

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

      • score
        number

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

      • pervasiveness
        string

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

        Allowed Values
        • low
        • medium
        • high

Device Information for Users

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

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

Example Request
$ curl -XGET 'https://api.sift.com/v3/accounts/529def32fe6b73f31300126e/users/465733823/devices' \
  -H 'Content-Type: application/json' \
  -u {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

  • accountId
    required · string

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

  • userId
    required · string

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

Response

  • schema
    required · string

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

  • data
    required · array

    A list of data items

    • id
      required · string

      id of the referenced resource

  • has_more
    boolean

    Whether there are more results

  • next_ref
    string

    A link to the next set of data, if available

  • total_results
    integer

    The total number of results, if known

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

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 {API_KEY}:
Example Response
{
  "schema" : "partner_account.json",
  "total_results" : 1,
  "data" : [ {
    "account_id" : "545d48e84d6963acf1000000",
    "production" : {
      "api_keys" : [ {
        "id" : "545d491c4d6963acf12d0000",
        "name" : "Merchant API Key",
        "description" : "For merchant integration",
        "state" : "ACTIVE",
        "key" : "34fc67af86069804",
        "permissions" : []
      } ],
      "beacon_keys" : [ {
        "id" : "545d491c4d6963acf12e0000",
        "name" : "Merchant Beacon Key",
        "description" : "Description of Beacon Key",
        "state" : "ACTIVE",
        "key" : "735ea65235",
        "permissions" : []
      } ]
    },
    "sandbox" : {
      "api_keys" : [ {
        "id" : "545d491c4d6963acf1300000",
        "name" : "Merchant Sandbox API Key",
        "description" : "For merchant sandbox integration",
        "state" : "ACTIVE",
        "key" : "1f46f7f726607c1b",
        "permissions" : ["EVENTS_API", "FEEDBACK"]
      } ],
      "beacon_keys" : [ {
        "id" : "545d491c4d6963acf1310000",
        "name" : "Merchant Sandbox Beacon Key",
        "description" : "Description of Sandbox Beacon Key",
        "state" : "ACTIVE",
        "key" : "63d0d7605c",
        "permissions" : []
      } ]
    }
  } ]
}

Parameters

  • id
    required · string

    Your partner account id

Response

  • schema
    required · string

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

  • data
    required · array

    A list of data items

    • production
      required · object

      API keys for the production account

      • api_keys
        array

        Keys used to access Sift's REST APIs

        • id
          string

          Identifier for this API keys

        • name
          string

          The name of the API Key

        • description
          string

          The description of the API Key

        • state
          string

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

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

          The actual key to be used for authenticated API requests

        • permissions
          string

          The permissions that this key has access to. An empty array indicates full access.

          Allowed Values
          • EVENTS_APISpecifies access to the Events API
          • GET_SCORE_APISpecifies access to the Get Score API
          • SCORE_APISpecifies access to the Score API
          • FEEDBACKSpecifies access to the Labels and Decisions API
          • DEVICE_FINGERPRINTINGSpecifies access to the Device Fingerprinting API
          • VERIFICATIONSSpecifies access to the Verifications API
          • MANAGE_WEBHOOKSSpecifies access to the Webhooks API
          • RETRIEVE_ORDERSSpecifies access to the Order API
      • beacon_keys
        array

        Keys used for the JavaScript integration

        • id
          string

          Identifier for this API keys

        • name
          string

          The name of the API Key

        • description
          string

          The description of the API Key

        • state
          string

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

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

          The actual key to be used for authenticated API requests

        • permissions
          string

          This would indicate the permissions that this beacon key has access to. This field will always be empty at this time.

          Allowed Values
      • sandbox
        required · object

        API keys for the production account

        • api_keys
          array

          Keys used to access Sift's REST APIs

          • id
            string

            Identifier for this API keys

          • name
            string

            The name of the API Key

          • description
            string

            The description of the API Key

          • state
            string

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

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

            The actual key to be used for authenticated API requests

          • permissions
            string

            The permissions that this key has access to. An empty array indicates full access.

            Allowed Values
            • EVENTS_APISpecifies access to the Events API
            • GET_SCORE_APISpecifies access to the Get Score API
            • SCORE_APISpecifies access to the Score API
            • FEEDBACKSpecifies access to the Labels and Decisions API
            • DEVICE_FINGERPRINTINGSpecifies access to the Device Fingerprinting API
            • VERIFICATIONSSpecifies access to the Verifications API
            • MANAGE_WEBHOOKSSpecifies access to the Webhooks API
            • RETRIEVE_ORDERSSpecifies access to the Order API
        • beacon_keys
          array

          Keys used for the JavaScript integration

          • id
            string

            Identifier for this API keys

          • name
            string

            The name of the API Key

          • description
            string

            The description of the API Key

          • state
            string

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

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

            The actual key to be used for authenticated API requests

          • permissions
            string

            This would indicate the permissions that this beacon key has access to. This field will always be empty at this time.

            Allowed Values
        • account_id
          required · string

      • has_more
        boolean

        Whether there are more results

      • next_ref
        string

        A link to the next set of data, if available

      • total_results
        integer

        The total number of results, if known

      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/v205/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/v205/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(api_key='{apiKey}', account_id='{accountId}')

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_key
        required · String

        Your Sift API key.

      • $is_fraud
        required · Boolean

        Indicates whether a user is engaging in behavior deemed harmful to your business. Set to true if the user is engaging in abusive activity. Set to false if the user is engaging in valid activity.

      • $abuse_type
        required · String

        The type of abuse for which you want to send a label. It's important to send a label specific to the type of abuse the user is committing so that Sift can learn about specific patterns of behavior. You'll end up with more accurate results this way.

        Allowed values
        • payment_abuse
          A user using stolen payment information (e.g. a stolen credit card) to purchase goods or services.
        • content_abuse
          A user creating content or sending messages on your site in an abusive manner. This includes spam posts that pollute your site, fake listings intended to scam other users, spammy messages to other users, and any other fraudulent or abusive content.
        • promotion_abuse
          A user gaming the terms of a promotion in an excessive or abusive way. A promotion includes things like coupons, referral credits, limited offers, free trial periods, etc.
        • account_abuse
          A user who uses your service in a manner you deem abusive. This behavior can include creating fake/duplicate accounts or any other abusive patterns specific to your business.
      • $description
        String

        Freeform text description of the user and/or incident triggering the label. Useful as annotation on why the label was added.

      • $source
        String

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

      • $analyst
        String

        Unique identifier (e.g. email address) of the analyst who applied the label. Useful for tracking purposes after the fact.

      Unlabeling a User ID

      If you are unsure whether a user ID 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/v205/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/v205/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/v205/users/USER_ID/labels/?api_key=YOUR_API_KEY&abuse_type=payment_abuse'
      import sift

client = sift.Client(api_key='{apiKey}', account_id='{accountId}')
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

      Webhooks API

      Overview

      You may use webhooks to receive notifications about particular events in Sift. When one of the events is triggered, Sift will send a JSON payload to the webhook’s specified URL. Webhooks can be used to update your own support tool, data warehouses, and more.

      Authentication

      Our webhook APIs are accessible using your API Keys. If you are a Sift product partner, API keys must be provided by a customer.

      All API requests should be made over HTTPS. Any call using HTTP or without authentication will fail.

      Create a webhook

      Creates a new webhook with a specified URL.

      Request

      Arguments
      • payload_type
        REQUIRED · String

        The type of payload.

        Allowed Values
      • status
        REQUIRED · String

        The status of the webhook.

        Allowed Values
        • draft
          Indicates the webhook is in a draft state. No webhooks are sent.
        • active
          Indicates the webhook is active. The webhook is live.
      • url
        REQUIRED · String

        The URL of the webhook endpoint. This must be HTTPS.

      • enabled_events
        REQUIRED · String

        The list of events to enable for this endpoint. These correspond to our Reserved Events in our Events API.

        Possible enabled events
        • $create_order
          Occurs whenever a $create_order API call is received.
        • $update_order
          Occurs whenever a $update_order API call is received.
        • order_status
          Occurs whenever a $order_status API call is received.
        • $transaction
          Occurs whenever a $transaction API call is received.
        • $chargeback
          Occurs whenever a $chargeback API call is received.
      • name
        OPTIONAL · String

        An optional name you specify for this webhook

      • description
        OPTIONAL · String

        An optional description about what the webhook is used for.

      curl -X POST https://api.sift.com/v3/accounts/{accountId}/webhooks \
-H 'Content-Type: application/json' \
-u {YOUR_API_KEY}: \
-d \
    '{
    "payload_type": "ORDER_V1_0",
    "status": "draft",
    "url": "https://example.com/",
    "enabled_events": ["$create_order"],
    "name": "My webhook name",
    "description": "This is a webhook!"
    }'

      Response

      Attributes
      • id
        String

        The id of the webhook.

      • created
        Integer

        The time at which the webhook was created as a UNIX timestamp.

      • last_updated
        Integer

        The time at which the webhook endpoint was last updated as a UNIX timestamp.

      • name
        String

        The specified name of the webhook.

      • description
        String

        The specified description of the webhook

      • payload_type
        String

        The type of payload.

        Possible Values
      • enabled_events
        String

        The list of events to enable for this endpoint. These correspond to our Reserved Events in our Events API.

        Possible enabled events
        • $create_order
          Occurs whenever a $create_order API call is received.
        • $update_order
          Occurs whenever a $update_order API call is received.
        • order_status
          Occurs whenever a $order_status API call is received.
        • $transaction
          Occurs whenever a $transaction API call is received.
        • $chargeback
          Occurs whenever a $chargeback API call is received.
      • status
        String

        The status of the webhook.

        Possible Values
        • draft
          Indicates the webhook is in a draft state. No webhooks are sent.
        • active
          Indicates the webhook is active. The webhook is live.
      • url
        String

        The URL of the webhook endpoint. This must be HTTPS. 

      {
    "id":512,
    "created":1607731610614,
    "last_updated":1607731610614,
    "name":"My webhook name",
    "description":"This is a webhook!",
    "payload_type":"ORDER_V1_0",
    "enabled_events":[
        "$create_order"
    ],
    "status":"DRAFT",
    "url":"https://example.com/"
}

      Retrieve a Webhook

      Retrieves a webhook when given an ID.

      Request

      Arguments

      No arguments. 

      curl -X GET https://api.sift.com/v3/accounts/{accountId}/webhooks/{id} \
    -H 'Content-Type: application/json' \
    -u {YOUR_API_KEY}:

      Response

      Attributes
      • id
        String

        The id of the webhook.

      • created
        Integer

        The time at which the webhook was created as a UNIX timestamp.

      • last_updated
        Integer

        The time at which the webhook endpoint was last updated as a UNIX timestamp.

      • name
        String

        The specified name of the webhook.

      • description
        String

        The specified description of the webhook

      • payload_type
        String

        The type of payload.

        Possible Values
      • enabled_events
        String

        The list of events to enable for this endpoint. These correspond to our Reserved Events in our Events API.

        Possible enabled events
        • $create_order
          Occurs whenever a $create_order API call is received.
        • $update_order
          Occurs whenever a $update_order API call is received.
        • order_status
          Occurs whenever a $order_status API call is received.
        • $transaction
          Occurs whenever a $transaction API call is received.
        • $chargeback
          Occurs whenever a $chargeback API call is received.
      • status
        String

        The status of the webhook.

        Possible Values
        • draft
          Indicates the webhook is in a draft state. No webhooks are sent.
        • active
          Indicates the webhook is active. The webhook is live.
      • url
        String

        The URL of the webhook endpoint. This must be HTTPS. 

      {
    "id":534,
    "created":1607731610614,
    "last_updated":1607731610614,
    "name":"My webhook name",
    "description":"This is a webhook!",
    "payload_type":"ORDER_V1_0",
    "enabled_events":[
        "$create_order"
    ],
    "status":"DRAFT",
    "url":"https://example.com/"
}

      List All Webhooks

      Returns a list of all webhooks.

      Request

      Arguments

      No arguments. 

      curl -X GET https://api.sift.com/v3/accounts/{accountId}/webhooks \
    -H 'Content-Type: application/json' \
    -u {YOUR_API_KEY}:

      Response

      Attributes
      • data
        Array

        A list of all webhooks.

        • id
          String

          The id of the webhook.

        • created
          Integer

          The time at which the webhook was created as a UNIX timestamp.

        • last_updated
          Integer

          The time at which the webhook endpoint was last updated as a UNIX timestamp.

        • name
          String

          The specified name of the webhook.

        • description
          String

          The specified description of the webhook

        • payload_type
          String

          The type of payload.

          Possible Values
        • enabled_events
          String

          The list of events to enable for this endpoint. These correspond to our Reserved Events in our Events API.

          Possible enabled events
          • $create_order
            Occurs whenever a $create_order API call is received.
          • $update_order
            Occurs whenever a $update_order API call is received.
          • order_status
            Occurs whenever a $order_status API call is received.
          • $transaction
            Occurs whenever a $transaction API call is received.
          • $chargeback
            Occurs whenever a $chargeback API call is received.
        • status
          String

          The status of the webhook.

          Possible Values
          • draft
            Indicates the webhook is in a draft state. No webhooks are sent.
          • active
            Indicates the webhook is active. The webhook is live.
        • url
          String

          The URL of the webhook endpoint. This must be HTTPS.

      {
    "data": [
        {
        "id":573,
        "created":1607731610614,
        "last_updated":1607731610614,
        "name":"My webhook name",
        "description":"This is a webhook!",
        "payload_type":"ORDER_V1_0",
        "enabled_events":[
            "$create_order"
        ],
        "status":"DRAFT",
        "url":"https://example.com/"
        },
        {...},
        {...}
    ]
    "has_more": false,
    "total_results": 3
}

      Update a Webhook

      Updates a webhook when given an ID. This will overwrite the entire existing webhook object.

      Request

      Arguments
      • payload_type
        REQUIRED · String

        The type of payload.

        Allowed Values
      • status
        REQUIRED · String

        The status of the webhook.

        Allowed Values
        • draft
          Indicates the webhook is in a draft state. No webhooks are sent.
        • active
          Indicates the webhook is active. The webhook is live.
      • url
        REQUIRED · String

        The URL of the webhook endpoint. This must be HTTPS.

      • enabled_events
        REQUIRED · String

        The list of events to enable for this endpoint. These correspond to our Reserved Events in our Events API.

        Possible enabled events
        • $create_order
          Occurs whenever a $create_order API call is received.
        • $update_order
          Occurs whenever a $update_order API call is received.
        • order_status
          Occurs whenever a $order_status API call is received.
        • $transaction
          Occurs whenever a $transaction API call is received.
        • $chargeback
          Occurs whenever a $chargeback API call is received.
      • name
        OPTIONAL · String

        An optional name you specify for this webhook

      • description
        OPTIONAL · String

        An optional description about what the webhook is used for.

      curl -X PUT https://api.sift.com/v3/accounts/{accountId}/webhooks/{id} \
-H 'Content-Type: application/json' \
-u {YOUR_API_KEY}: \
-d \
    '{
    "payload_type": "ORDER_V1_0", 
    "status": "active", 
    "url": "https://example.com/updated", 
    "enabled_events": ["$update_order"], 
    "name": "My updated webhook name",
    "description": "This is an updated webhook!"
    }'

      Response

      Attributes
      • id
        String

        The id of the webhook.

      • created
        Integer

        The time at which the webhook was created as a UNIX timestamp.

      • last_updated
        Integer

        The time at which the webhook endpoint was last updated as a UNIX timestamp.

      • name
        String

        The specified name of the webhook.

      • description
        String

        The specified description of the webhook

      • payload_type
        String

        The type of payload.

        Possible Values
      • enabled_events
        String

        The list of events to enable for this endpoint. These correspond to our Reserved Events in our Events API.

        Possible enabled events
        • $create_order
          Occurs whenever a $create_order API call is received.
        • $update_order
          Occurs whenever a $update_order API call is received.
        • order_status
          Occurs whenever a $order_status API call is received.
        • $transaction
          Occurs whenever a $transaction API call is received.
        • $chargeback
          Occurs whenever a $chargeback API call is received.
      • status
        String

        The status of the webhook.

        Possible Values
        • draft
          Indicates the webhook is in a draft state. No webhooks are sent.
        • active
          Indicates the webhook is active. The webhook is live.
      • url
        String

        The URL of the webhook endpoint. This must be HTTPS. 

      {
    "id":573,
    "created":1607731610614,
    "last_updated":1607731610614,
    "name":"My updated webhook name",
    "description":"This is an updated webhook!",
    "payload_type":"ORDER_V1_0",
    "enabled_events":[
        "$update_order"
    ],
    "status":"ACTIVE",
    "url":"https://example.com/updated"
}

      Delete a Webhook

      Deletes a webhook when given an ID.

      Request

      Arguments

      No arguments. 

      curl -X DELETE https://api.sift.com/v3/accounts/{accountId}/webhooks/{id}
    -u {YOUR_API_KEY}:

      Response

      Response will contain no content and have an HTTP status of 204.

      Orders

      Overview

      The Sift order is a collection of data sent by $create_order, $update_order, $order_status, $transaction, and $chargeback. Orders can be identified by a unique $order_id or $transaction_id.

      The Order Object

      Attributes

      • accountId
        String

        The order's Sift Account ID, which can be found in the Sift Console under the Developer Tab.

      • event
        String

        If triggered via webhook, indicates the triggering webhook event. One of $create_order, $update_order, $order_status, $transaction, or $update_order.

      • created
        Integer

        The UNIX timestamp in milliseconds at which the order was created.

      • updated_at
        Integer

        The UNIX timestamp in milliseconds at which the order was last updated.

      • order_id
        String

        The ID for tracking this order in your system.

      • user_id
        String

        The user's account ID according to your systems. Note that user IDs are case sensitive.

      • user_email
        String

        Email of the user who has created this order.

      • ip
        String

        The ip address of the user that created the order.

      • order_status
        String

        Indicates the state of the order. One of $approved, $canceled, $held, $fulfilled, or $returned.

      • amount
        Integer

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

      • currency_code
        String

        ISO-4217 currency code for the amount.

      • payment_methods
        Array of Payment Methods

        The payment information associated with the order. Contains the following attributes:

        • payment_type
          String

          The general type of payment being used.

        • card_bin
          String

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

        • card_last_4
          String

          The last four digits of the credit card number.

        • payment_gateway
          String

          The specific gateway, company, product, etc. being used to process payment.

        • avs_result_code
          String

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

        • cvv_result_code
          String

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

        • billing_address
          Billing Address Object

          The billing address entered by the user. See Address.

      • ordered_from
        Ordered From Object

        The details about the specific location providing the good or service. This can be used to capture pickup, delivery locations, etc. See Ordered From.

      • shipping_address
        Shipping Address Object

        The shipping address entered by the user. See Address.

      • expedited_shipping
        Boolean

        Whether the user requested priority/expedited shipping on their order

      • shipping_method
        String

        Indicates the method of delivery to the user.

      • shipping_carrier
        String

        Shipping carrier for the shipment of the product.

      • shipping_tracking_number
        deprecated · String

        Shipping tracking number of the product

      • shipping_tracking_numbers
        Array of Strings

        Shipping tracking number(s) for the shipment of the product(s).

      • items
        Array of Items

        The list of items ordered. Each item contains:

        • item_id
          String

          The item’s unique identifier.

        • product_title
          String

          The item’s name.

        • price
          Integer

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

        • currency_code
          String

          ISO-4217 currency code for the price.

      • bookings
        Array of Bookings

        The list of bookings made. This may include tickets and reservations like flights, hotels, rideshares etc. Note: cannot be used in conjunction with $items.

      • transactions
        Array of Transactions

        The list of transactions associated with the order. Each transaction contains:

        • id
          String

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

        • transaction_type
          String

          The type of transaction being recorded. One of sale, authorize, capture, void, refund, deposit, withdrawal, or transfer.

        • transaction_time
          Integer

          The UNIX timestamp in milliseconds at which the transaction occurred.

        • amount
          Integer

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

        • currency_code
          String

          ISO-4217 currency code for the amount.

      • chargebacks
        Array of Chargebacks

        The list of chargebacks associated with the order. Each chargeback contains:

        • transaction_id
          String

          The transaction_id that this chargeback is linked to.

        • time
          Integer

          The UNIX timestamp in milliseconds at which the transaction occurred.

        • status
          String

          The current state of the chargeback.

        • reason
          String

          The reason for why the chargeback occurred. One of fraud, duplicate, product_not_received, product_unacceptable, other.

      • latest_decisions
        Map

        The decisions map contains the most recent decision on the order. The map is keyed by abuse type, which could be one of: payment_abuse, account_abuse, content_abuse, promotion abuse, and legacy. Contains:

        • id
          String

          The ID of the decision. This is derived from the decision name in the Console.

        • type
          String

          The type of the decision taken on the entity. One of Red, Yellow, or Green

        • time
          Integer

          The UNIX timestamp of when the decision was made.

        • description
          String

          A description of the decision.

      • scores
        Map

        The scores map contains the computed scores for all applicable abuse types. The map is keyed by abuse type, which could be one of: payment_abuse, account_abuse, content_abuse, promotion abuse, and legacy. Contains:

        • score
          Float

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

        • time
          Long

          The time at which the score was generated, as a UNIX timestamp.

      Orders
      "body": {
    "accountId": "YOUR_ACCOUNT_ID"
    "event": "$create_order",
    "created": 1607650820366,
    "updated_at": 1607650820056,
    "order_id": "ORDER-28168441",
    "user_id": "billy_jones_301",
    "user_email": "bill@gmail.com",
    "ip": "11.11.11.11",
    "order_status": "$approved",
    "amount": 200000,
    "currency_code": "USD",
    "payment_methods": [{
        "payment_type": "$credit_card",
        "card_bin": "54248612",
        "card_last4": "4444",
        "payment_gateway": "$braintree",
        "avs_result_code": "Y",
        "cvv_result_code": "M",
        "billing_address": {
            "name": "Jake Joseph",
            "address_1": "1111 Oak St",
            "address_2": "Unit 111",
            "city": "New Orleans",
            "region": "Louisiana",
            "country": "US",
            "zipcode": "03254"
        }
    }],
    "ordered_from": {
        "store_id": "123",
        "store_address": {
            "name": "Alice Green",
            "address_1": "18 Market Street",
            "address_2": "Suite 100",
            "city": "New London",
            "region": "New Hampshire",
            "country": "US",
            "zipcode": "03257",
            "phone": "1-415-532-6892"
        }
    },
    "shipping_address": {
        "name": "Bill Jones",
        "address_1": "2100 Main Street",
        "address_2": "Apt 3B",
        "city": "New London",
        "region": "New Hampshire",
        "country": "US",
        "zipcode": "03257",
        "phone": "1-415-555-6041"
    },
    "expedited_shipping": true,
    "shipping_method": "$physical",
    "shipping_carrier": "UPS",
    "shipping_tracking_numbers": ["1Z204E380338943508", "1Z204E380338943509"],
    "items": [{
            "item_id": "12344321",
            "product_title": "Microwavable Kettle Corn: Original Flavor",
            "price": 4990000,
            "currency_code": "USD"
        },
        {
            "item_id": "B004834GQO",
            "product_title": "The Slanket Blanket-Texas Tea",
            "price": 39990000,
            "currency_code": "USD"
        }
    ],
    "transactions": [{
            "id": "123",
            "transaction_type": "auth",
            "time": 1592433168230,
            "amount": 0,
            "currency_code": "USD"
        },
        {
            "id": "123",
            "transaction_type": "capture",
            "time": 1592433168230,
            "amount": 300000,
            "currency_code": "USD"
        },
        {
            "id": "124",
            "transaction_type": "sale",
            "time": 1592433168230,
            "amount": 100000,
            "currency_code": "USD"
        }
    ],
    "chargebacks": [{
            "transaction_id": 123,
            "time": 1592433277044,
            "status": "disputed",
            "reason": "fraud"
        },
        {
            "transaction_id": 124,
            "time": 1592433277044,
            "status": "disputed",
            "reason": "fraud"
        }
    ],
    "latest_decisions": {
        "payment_abuse": {
            "id": "Accept Order",
            "type": "ACCEPT",
            "time": 1571420853046,
            "description": ""
        }
    },
    "scores": {
        "content_abuse": {
            "score": 0.021003901194838703,
            "time": 1607650820056
        },
        "payment_abuse": {
            "score": 0.25462552602582395,
            "time": 1607650820056
        }
    }
}