Secure your business from login to chargeback
Stop fraud, break down data silos, and lower friction with Sift.
- Achieve up to 285% ROI
- Increase user acceptance rates up to 99%
- Drop time spent on manual review up to 80%
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:
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.
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:
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.
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.
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:
To build this business logic, there are two different approaches that you can take. You should choose your approach based on your business needs.
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.
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.
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.
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:
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 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:
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.
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.
Prefer SHA-256 over SHA-1 as the encryption type when creating a webhook signature key in the Console.
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.).
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.
-4
-3
-2
-1
0
50
51
52
53
54
55
56
57
58
59
60
61
62
63
100
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
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.
API: Added new payment gateways: $bosspay
, $devonrex
,
$liquido
, $moozimi
, $jpay
, $onerway
, $lapay
,
$bexs
, $geepay
, $onewallet
, $shareit
, $klicklpay
,
$gopay
, $mbway
, $rabbitlinepay
, $boost
to the $payment_gateway
field description
belonging to the Payment Method field type
API: Added a new Events API reserved event type $wager
API: Added new deposit and withdrawal fields added to
the $transaction
event
Updated versions of sift-java
and sift-dotnet
libraries.
API: Added info about setting beacon request priority in JavaScript Snippet
API: Added new payment gateways: $revolut
, $januar
and $oneio
to the $payment_gateway
field description
belonging to the Payment Method field type
API: Added field $iata_carrier_code
to the Booking
field type.
API: Added new payment gateways: $atome
, $cashapp
,
$nupay
and $zuora
to the $payment_gateway
field description
belonging to the Payment Method field type
API: Removed Orders API section and instead added Webhooks API Order Object.
API: Added a note about $start_time
and $end_time
fields
belonging to the Booking field type
API: Added description of the fields=warnings
request parameter
to the Events API Overview.
Also added example of a response with warnings
API: Update the descriptions of $account_holder_name
,
$account_number_last5
, $bank_name
and $bank_country
fields belonging to the
Payment Method field type
API: Added fields $guest_booking_reference_id
and $guest_user_id
to the Guest field type.
API: Added $ip
field to the events: $add_item_to_cart
, $add_promotion
,
$chargeback
, $content_status
, $create_account
, $create_content
, $create_order
,
$flag_content
, $link_session_to_user
, $logout
, $order_status
, $remove_item_from_cart
,
$security_notification
, $transaction
, $update_account
, $update_content
, $update_order
,
$update_password
, $verification
API: Added description of the fields=score_percentiles
request parameter
to the Score API Sync Scores Overview
API: Added Verification API section
API: Added $user_email
field to $add_item_to_cart
, $add_promotion
,
$content_status
, $flag_content
, $remove_item_from_cart
and $update_password
events
API: Added $shipping_carrier
and $shipping_tracking_numbers
fields
to $create_order
and $update_order
events
API: Added $reason
field to $flag_content
event
API: Removed $keyless_user_id
field from Events API
API: Added $ach_return_code
field to $chargeback
event
API: Added fields $wallet_address
and $wallet_type
to $payment_method
field.
API: Added $digital_order
complex field which should be used in $create_order
,
$update_order
and $transaction
events.
API: Added fields $receiver_wallet_address
and $receiver_external_address
to $transaction
event.
API: Added PSP Merchant Management API
to manage PSP Merchant summaries.
API: Added $merchant_profile
field to $create_account
, $chargeback
and $update_account
events.
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.
API: Added the $shipping_tracking_numbers
field and marking
$shipping_tracking_number
as "Deprecated" (which will later be removed)
API: Changed the description of $user_email
field for $login
event
API: Added $shipping_carrier
and $shipping_tracking_number
fields
to $create_order
and $update_order
events.
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.
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.
API: Added more allowed values $face
, $fingerprint
, push
, security_key
to field
$verification_type
in reserved event $verification
.
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
.
API: Added $booking
, $segment
, and $guest
complex fields to the following reserved events:
$create_order
and $update_order
.
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.
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.
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.
API: Added support for retrieving the decision status of a session to Decisions API.
API: Released Sift API Version 205, including major updates to
$create_content
and $update_content
.
API: Added support for content decisions to Decisions API.
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.
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).
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:
_user_id
to the empty string.setUserId
once the user has signed in.$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.$user_id
field (e.g. email address or transaction ID).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 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.
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.
$time
in millis.$ip
if known. 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
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 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.
$user_id
rate limit of 3 requests/second)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.
<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>
_setAccount
above to your JavaScript Snippet key._session_id
to a string that identifies a unique session ID for the visitor's current
browsing session._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.__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']);
_setPriority
JavaScript parameter.
Each subsequent _trackPageview
will use it._sift.push(['_setPriority','highPriority']);
_sift.push(['_setPriority','normalPriority']);
_trackPageview
will use a global priority._sift.push(['_trackPageview', { priority: ‘highPriority' }]);
_sift.push(['_trackPageview', { priority: ‘normalPriority' }]);
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.
The SDK can be installed through either CocoaPods or Carthage.
pod 'Sift'
(this uses the latest version).pod install
.github "SiftScience/sift-ios"
(this uses
the latest version)carthage update
.At a bare minimum, configuring your use of the Sift iOS SDK requires passing in your account id and beacon key. Your account id is retrievable by your account's admin in your profile section. The beacon key is the same key that is used in your Sift JS Snippet, and can be found in the developer section. Note in particular that this key is not considered secret; a sophisticated bad actor could recover this key from your app, or from the JS beacon, and use it to submit mobile events.
The 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"];
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"
[sift setAllowUsingMotionSensors:YES
;]. This enables the SDK to collect
motion data in the background.[sift setDisallowCollectingLocationData:YES
;].[[Sift sharedInstance] setUserId:@"USER_ID"];
<key>LSApplicationQueriesSchemes</key> <array> <string>cydia</string> </array>
Add the
latest version
of the Sift SDK to your application's build.gradle
file:
dependencies { ... implementation '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' } ... }
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.
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();
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();
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:
Each event has fields that provide details.
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.
fields
parameterUse $add_item_to_cart
to record when a user adds an item to their shopping cart or list.
"$add_item_to_cart"
Your Sift REST API key.
The user's current session ID, used to tie a user's action before and after log in or account creation.
The user's account ID according to your systems. Note: User IDs are case sensitive.
Find valid $user_id
values here.
The product item added to cart.
Required subfields are $item_id
, $product_title
, and
$price
. The $quantity
is specified as a subfield.
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
.
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
.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
Domain being interfaced with. Use fully qualified domain name.
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.
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.
IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
// Sample $add_item_to_cart event { // Required Fields "$type" : "$add_item_to_cart", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", // Supported Fields "$session_id" : "gigtleqddo84l8cm15qe4il", "$item" : { "$item_id" : "B004834GQO", "$product_title" : "The Slanket Blanket-Texas Tea", "$price" : 39990000, // $39.99 "$currency_code" : "USD", "$upc" : "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", "$ip" : "54.208.214.78", // 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", "$ip" : "54.208.214.78", # 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", "$ip" => "54.208.214.78", # 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', '$ip' => '54.208.214.78', // 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") .setUserEmail("billjones1@example.com") .setVerificationPhoneNumber("+123456789012") .setIp("54.208.214.78") // 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
Use $add_promotion
to record when a user adds one or more promotions to their account.
"$add_promotion"
The user's account ID according to your systems. Note: User IDs are case sensitive.
Find valid $user_id
values here.
Contains all promotions that have been newly applied to the referenced user.
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
.
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
.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
Domain being interfaced with. Use fully qualified domain name.
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.
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.
IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
// 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" } } ], "$ip" : "54.208.214.78", // 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" } } ], "$ip" : "54.208.214.78", # 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" } } ], "$ip" => "54.208.214.78", # 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' ) ) ), '$ip' => '54.208.214.78', // 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)))) .setBrandName("sift") .setSiteDomain("sift.com") .setSiteCountry("US") .setUserEmail("billjones1@example.com") .setVerificationPhoneNumber("+123456789012") .setIp("54.208.214.78") // 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
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:
$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.$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)."$chargeback"
Your Sift REST API key.
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
.
The ID for the transaction that this chargeback is filed against.
Note: Optional if $order_id
is present.
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.
The current state of the chargeback.
"$received"
"$accepted"
"$disputed"
"$won"
"$lost"
This field can be used to capture the reason given.
"$fraud"
"$duplicate"
"$product_not_received"
"$product_unacceptable"
"$other"
"$authorization"
"$consumer_disputes"
"$processing_errors"
"$cancel_subscription"
"$friendly_fraud"
"$ach_return"
"$ach_reversal"
The details about the merchant or seller providing the goods or service.
The code returned, as defined by NACHA, which identifies the reason for return. Standard format begins with 'R' followed by a two digit number.
IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
// Sample $chargeback event { // Required Fields "$type" : "$chargeback", "$api_key" : "YOUR_API_KEY", "$order_id" : "ORDER-123124124", "$transaction_id" : "719637215", // Recommended Fields "$user_id" : "billy_jones_301", "$chargeback_state" : "$lost", "$chargeback_reason" : "$duplicate", // Supported Fields "$ip" : "54.208.214.78" }
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", # Supported Fields "$ip" : "54.208.214.78" } 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", # Supported Fields "$ip" => "54.208.214.78" } response = client.track("$chargeback", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(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', // Supported Fields '$ip' => '54.208.214.78' ); $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") // Supported Fields .setIp("54.208.214.78")); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
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
.
"$content_status"
Your Sift REST API key.
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.
The unique ID for the piece of content that you’re updating the status of. Note: content IDs are case sensitive.
The status of the posting.
$active
at a later date.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
.
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
.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
Domain being interfaced with. Use fully qualified domain name.
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.
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.
IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
// 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", "$ip" : "54.208.214.78", // 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", # Supported Fields "$ip" : "54.208.214.78", # 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", # Supported Fields "$ip" => "54.208.214.78", # 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', // Supported Fields '$ip' => '54.208.214.78', // 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") // Supported Fields .setBrandName("sift") .setSiteDomain("sift.com") .setSiteCountry("US") .setUserEmail("billjones1@example.com") .setVerificationPhoneNumber("+123456789012") .setIp("54.208.214.78") // 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
Use $create_account
to capture user details at account creation. To capture updates to
an account after it is initially created, use $update_account.
"$create_account"
Your Sift REST API key.
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.
The user's current session ID, used to tie a user's action before and after log in or account creation.
Email of the user creating the account. 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.
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.
The full name of the user.
The primary phone number of the user associated with this account. Provide the phone number as a string
starting with the country code. Use E.164 format or send
in the standard national format of number's origin. For example: "+14155556041" or "1-415-555-6041" for a
U.S. number. If you collect other phone numbers for the account, provide them as additional custom fields,
e.g work_phone
The ID of the user that referred the current user to your business. This field is
required for detecting referral fraud. Note: User IDs are case sensitive. You
may need to normalize the capitalization of your user IDs. Follow our
guidelines for $user_id
values.
The payment method(s) associated with this account.
The billing address associated with this user.
The shipping address associated with this user.
The list of promotions that apply to this account. You can add one or more promotions when creating
or updating the account. It is particularly useful to add the promotion with this event if the
account is receiving some referral incentive.
You can also separately add promotions to the account via the $add_promotion
event.
If the user logged in with a social identify provider, give the name here.
$facebook
$google
$linkedin
$twitter
$yahoo
$microsoft
$amazon
$apple
$wechat
$github
$other
The user agent of the browser that is used to create the account. Represented by the $browser
object.
Use this field if the client is a browser. Note: cannot be used in conjunction with $app
.
The details of the app, os, and device that is used to create the account. Represented by the $app
object.
Use this field if the client is an app. Note: cannot be used in conjunction with $browser
.
Capture the type(s) of the account: "merchant"
or "shopper"
, "regular"
or "premium"
, etc.
The array supports multiple types for a single account, e.g. ["merchant", "premium"]
.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
Domain being interfaced with. Use fully qualified domain name.
The details about the merchant or seller providing the goods or service.
IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
// Sample $create_account event { // Required Fields "$type" : "$create_account", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", // Supported Fields "$session_id" : "gigtleqddo84l8cm15qe4il", "$user_email" : "billjones1@example.com", "$verification_phone_number" : "+123456789012", "$name" : "Bill Jones", "$phone" : "1-415-555-6040", "$referrer_user_id" : "janejane101", "$payment_methods" : [ { "$payment_type" : "$credit_card", "$card_bin" : "542486", "$card_last4" : "4444" } ], "$billing_address" : { "$name" : "Bill Jones", "$phone" : "1-415-555-6040", "$address_1" : "2100 Main Street", "$address_2" : "Apt 3B", "$city" : "New London", "$region" : "New Hampshire", "$country" : "US", "$zipcode" : "03257" }, "$shipping_address" : { "$name" : "Bill Jones", "$phone" : "1-415-555-6041", "$address_1" : "2100 Main Street", "$address_2" : "Apt 3B", "$city" : "New London", "$region" : "New Hampshire", "$country" : "US", "$zipcode" : "03257" }, "$promotions" : [ { "$promotion_id" : "FriendReferral", "$status" : "$success", "$referrer_user_id" : "janejane102", "$credit_point" : { "$amount" : 100, "$credit_point_type" : "account karma" } } ], "$social_sign_on_type" : "$twitter", "$account_types" : ["merchant", "premium"], "$ip" : "54.208.214.78", // Suggested Custom Fields "twitter_handle" : "billyjones", "work_phone" : "1-347-555-5921", "location" : "New London, NH", "referral_code" : "MIKEFRIENDS", "email_confirmed_status" : "$pending", "phone_confirmed_status" : "$pending", // 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_account event properties = { # Required Fields "$user_id" : "billy_jones_301", # Supported Fields "$session_id" : "gigtleqddo84l8cm15qe4il", "$user_email" : "billjones1@example.com", "$verification_phone_number" : "+123456789012", "$name" : "Bill Jones", "$phone" : "1-415-555-6040", "$referrer_user_id" : "janejane101", "$payment_methods" : [ { "$payment_type" : "$credit_card", "$card_bin" : "542486", "$card_last4" : "4444" } ], "$billing_address" : { "$name" : "Bill Jones", "$phone" : "1-415-555-6040", "$address_1" : "2100 Main Street", "$address_2" : "Apt 3B", "$city" : "New London", "$region" : "New Hampshire", "$country" : "US", "$zipcode" : "03257" }, "$shipping_address" : { "$name" : "Bill Jones", "$phone" : "1-415-555-6041", "$address_1" : "2100 Main Street", "$address_2" : "Apt 3B", "$city" : "New London", "$region" : "New Hampshire", "$country" : "US", "$zipcode" : "03257" }, "$promotions" : [ { "$promotion_id" : "FriendReferral", "$status" : "$success", "$referrer_user_id" : "janejane102", "$credit_point" : { "$amount" : 100, "$credit_point_type" : "account karma" } } ], "$social_sign_on_type" : "$twitter", "$account_types" : ["merchant", "premium"], "$ip" : "54.208.214.78", # Suggested Custom Fields "twitter_handle" : "billyjones", "work_phone" : "1-347-555-5921", "location" : "New London, NH", "referral_code" : "MIKEFRIENDS", "email_confirmed_status" : "$pending", "phone_confirmed_status" : "$pending", # 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_account", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $create_account event properties = { # Required Fields "$user_id" => "billy_jones_301", # Supported Fields "$session_id" => "gigtleqddo84l8cm15qe4il", "$user_email" => "billjones1@example.com", "$name" => "Bill Jones", "$phone" => "1-415-555-6040", "$referrer_user_id" => "janejane101", "$payment_methods" => [ { "$payment_type" => "$credit_card", "$card_bin" => "542486", "$card_last4" => "4444" } ], "$billing_address" => { "$name" => "Bill Jones", "$phone" => "1-415-555-6040", "$address_1" => "2100 Main Street", "$address_2" => "Apt 3B", "$city" => "New London", "$region" => "New Hampshire", "$country" => "US", "$zipcode" => "03257" }, "$shipping_address" => { "$name" => "Bill Jones", "$phone" => "1-415-555-6041", "$address_1" => "2100 Main Street", "$address_2" => "Apt 3B", "$city" => "New London", "$region" => "New Hampshire", "$country" => "US", "$zipcode" => "03257" }, "$promotions" => [ { "$promotion_id" => "FriendReferral", "$status" => "$success", "$referrer_user_id" => "janejane102", "$credit_point" => { "$amount" => 100, "$credit_point_type" => "account karma" } } ], "$social_sign_on_type" => "$twitter", "$account_types" => ["merchant", "premium"], "$ip" => "54.208.214.78", # Suggested Custom Fields "twitter_handle" => "billyjones", "work_phone" => "1-347-555-5921", "location" => "New London, NH", "referral_code" => "MIKEFRIENDS", "email_confirmed_status" => "$pending", "phone_confirmed_status" => "$pending", # 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_account", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $create_account event $properties = array( // Required Fields '$user_id' => 'billy_jones_301', // Supported Fields '$session_id' => 'gigtleqddo84l8cm15qe4il', '$user_email' => 'bill@gmail.com', '$name' => 'Bill Jones', '$phone' => '1-415-555-6040', '$referrer_user_id' => 'janejane101', '$payment_methods' => array( array( '$payment_type' => '$credit_card', '$card_bin' => '542486', '$card_last4' => '4444' ) ), '$billing_address' => array( '$name' => 'Bill Jones', '$phone' => '1-415-555-6040', '$address_1' => '2100 Main Street', '$address_2' => 'Apt 3B', '$city' => 'New London', '$region' => 'New Hampshire', '$country' => 'US', '$zipcode' => '03257' ), '$shipping_address' => array( '$name' => 'Bill Jones', '$phone' => '1-415-555-6041', '$address_1' => '2100 Main Street', '$address_2' => 'Apt 3B', '$city' => 'New London', '$region' => 'New Hampshire', '$country' => 'US', '$zipcode' => '03257' ), '$promotions' => array( array( '$promotion_id' => 'FriendReferral', '$status' => '$success', '$referrer_user_id' => 'janejane102', '$credit_point' => array( '$amount' => 100, '$credit_point_type' => 'account karma' ) ) ), '$social_sign_on_type' => '$twitter', '$account_types' => ['merchant', 'premium'], '$ip' => '54.208.214.78', // Suggested Custom Fields 'twitter_handle' => 'billyjones', 'work_phone' => '1-347-555-5921', 'location' => 'New London, NH', 'referral_code' => 'MIKEFRIENDS', 'email_confirmed_status' => "$pending", 'phone_confirmed_status' => "$pending", // 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_account', $properties);
import java.util.Arrays; import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.model.CreateAccountFieldSet; import com.siftscience.model.Address; import com.siftscience.model.Discount; import com.siftscience.model.Promotion; import com.siftscience.model.PaymentMethod; SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new CreateAccountFieldSet() // Required Fields .setUserId("billy_jones_301") // Supported Fields .setSessionId("gigtleqddo84l8cm15qe4il") .setUserEmail("billjones1@example.com") .setName("Bill Jones") .setPhone("1-415-555-6040") .setReferrerUserId("janejane101") .setPaymentMethods(Arrays.asList(new PaymentMethod() .setPaymentType("$credit_card") .setPaymentGateway("$braintree") .setCardBin("542486") .setCardLast4("4444"))) .setBillingAddress(new Address() .setName("Bill Jones") .setPhone("1-415-555-6041") .setAddress1("2100 Main Street") .setAddress2("Apt 3B") .setCity("New London") .setRegion("New Hampshire") .setCountry("US") .setZipCode("03257")) .setShippingAddress(new Address() .setName("Bill Jones") .setPhone("1-415-555-6041") .setAddress1("2100 Main Street") .setAddress2("Apt 3B") .setCity("New London") .setRegion("New Hampshire") .setCountry("US") .setZipCode("03257")) .setPromotions(Arrays.asList(new Promotion() .setPromotionId("FirstTimeBuyer") .setStatus("$success") .setDescription("$5 off") .setDiscount(new Discount() .setAmount(5000000L) .setCurrencyCode("USD") .setMinimumPurchaseAmount(25000000L)))) .setSocialSignOnType("$twitter") .setAccountTypes(Arrays.asList(new String[]{"merchant","premium"})) .setIp("54.208.214.78") // Suggested Custom Fields .setCustomField("twitter_handle", "billyjones") .setCustomField("work_phone", "1-347-555-5921") .setCustomField("location", "New London, NH") .setCustomField("referral_code", "MIKEFRIENDS") .setCustomField("email_confirmed_status", "$pending") .setCustomField("phone_confirmed_status", "$pending")); // 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
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:
$comment
field type represents comments created by users. Comments may be in response
to an apartment listing, blog post, etc.$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.$message
field type represents messages exchanged between users of your service.$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.$profile
field type represents information related to a user's profile.
Examples include social media, dating, or seller profiles.$review
field type represents information related to a product or
service reviewed by your users.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.
"$create_content"
Your Sift REST API key.
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.
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..
The user's current session ID, used to tie a user's action before and after login or account creation.
The status of the listing. After you update a listing, you can also update its status via the
$content_status
event.
$active
at a later date.IP address of the request made by the user. Recommended for historical backfills and customers with with mobile apps.
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
.
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
.
Contains information about the listing.
The subject of the listing.
The text content of the listing.
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.
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.
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.
The items array represents physical or digital items listed by the user.
The list of images shared by the user with their listing. It includes images pasted inline or attached separately.
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).
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
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
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.
"$create_content"
Your Sift REST API key.
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.
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..
The user's current session ID, used to tie a user's action before and after login or account creation.
The status of the posting. After you create a posting, you can also update its status via the
$content_status
event.
$active
at a later date.IP address of the request made by the user. Recommended for historical backfills and customers with with mobile apps.
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
.
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
.
Contains information about the post.
The user-supplied subject of the post.
The text content of the post.
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.
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.
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.
The category or categories you associate with the posting. For example, a blog post might be
categorized as ["Family", "Travel"]
.
The list of images shared by the user with their post. It includes images pasted inline or attached separately.
The UNIX timestamp in milliseconds of when the post will expire. Only set if the post is time bound in some way.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
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
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.
"$create_content"
Your Sift REST API key.
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.
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.
The user's current session ID, used to tie a user's action before and after login or account creation.
The status of the profile. After you create a profile, you can also update its status via the
$content_status
event.
$active
at a later date.IP address of the request made by the user. Recommended for historical backfills and customers with with mobile apps.
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
.
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
.
Contains information about the profile.
The text content of the profile.
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.
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.
The list of images shared by the user with their profile. It includes images pasted inline or attached separately.
The category or categories you associate with the profile. For example, a profile on a services
marketplace might be categorized as ["Photographer", "Weddings"]
.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
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
Use $create_content
with a $review
type to represent information related to a product or service review
submitted by your users.
"$create_content"
Your Sift REST API key.
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.
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.
The user's current session ID, used to tie a user's action before and after login or account creation.
The status of the review. After you create a review, you can also update its status via the
$content_status
event.
$active
at a later date.IP address of the request made by the user. Recommended for historical backfills and customers with with mobile apps.
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
.
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
.
Contains information about the review.
The user-supplied title of the review.
The text content of the review.
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.
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.
An Item object representing the item being reviewed.
The $content_id
of the item being reviewed. For example, this could be the id for the
$listing
or $profile
being reviewed.
A numeric rating supplied by the reviewer.
The list of images shared by the user with their review. It includes images pasted inline or attached separately.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
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
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.
"$create_order"
Your Sift REST API key.
The user's account ID according to your systems. Note that user IDs are case sensitive.
Find valid $user_id
values here.
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.
The ID for tracking this order in your system.
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.
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.
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.
ISO-4217 currency code for the amount. If your site uses alternative currencies, specify them here.
The billing address as entered by the user.
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.
The shipping address as entered by the user.
Whether the user requested priority/expedited shipping on their order.
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: can be used in conjunction with $bookings
or $digital_orders
.
The list of bookings made. This may include tickets and reservations like flights, hotels, rideshares etc.
Note: can be used in conjunction with $items
or $digital_orders
.
For marketplace businesses, this is the seller's user ID, typically a database primary key.
Follow our guidelines for $user_id
values.
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.
Indicates the method of delivery to the user.
"$electronic"
"$physical"
Shipping carrier for the shipment of the product.
Shipping tracking number for the shipment of the product.
Shipping tracking number(s) for the shipment of the product(s).
The details about the specific physical location providing the good or service. This can also be used to capture pickup, delivery locations, etc.
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
.
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
.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
Domain being interfaced with. Use fully qualified domain name.
The details about the merchant or seller providing the goods or service.
The list of digital orders made. A digital order represents a digital asset which can be part of
a cryptocurrency or digital asset transaction. Note: can be used in conjunction with $items
or
$bookings
.
IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
// Sample $create_order event { // Required Fields "$type" : "$create_order", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", // Supported Fields "$session_id" : "gigtleqddo84l8cm15qe4il", "$order_id" : "ORDER-28168441", "$user_email" : "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 } ], "$ip" : "54.208.214.78", // 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 } ], "$ip" : "54.208.214.78", # 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 } ], "$ip" => "54.208.214.78", # 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 ) ), '$ip' => '54.208.214.78', // 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)))) .setIp("54.208.214.78") // 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
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.
"$flag_content"
Your Sift REST API key.
The content creator's account ID according to your systems. Note: User IDs are case sensitive.
Find valid $user_id
values here.
The unique ID for the piece of content that is being flagged. Note: content IDs are case sensitive.
The account ID of the user who is flagging the content. Note: User IDs are case sensitive.
The reason provided by the flagger.
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.
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.
IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
// 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", "$ip" : "54.208.214.78" }
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", "$ip" : "54.208.214.78" } 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", "$ip" => "54.208.214.78" } 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', '$ip' => '54.208.214.78' ); $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") .setReason(FlagContentFieldSet.FlagContentReason.TOXIC) .setUserEmail("billjones1@example.com") .setVerificationPhoneNumber("+123456789012") .setIp("54.208.214.78")); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
Use $link_session_to_user
to associate data from a specific session to a user. Generally used only in
anonymous checkout workflows.
"$link_session_to_user"
Your Sift REST API key.
The user's current session ID, used to associate Javascript page events with their REST API counterparts.
The user's account ID according to your systems. Note that user IDs are case sensitive.
Find valid $user_id
values here.
IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
// Sample $link_session_to_user event { // Required Fields "$type" : "$link_session_to_user", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", "$session_id" : "gigtleqddo84l8cm15qe4il", // Supported Fields "$ip" : "54.208.214.78" }
import sift client = sift.Client(api_key='{apiKey}', account_id='{accountId}') # Sample $link_session_to_user event properties = { # Required Fields "$user_id" : "billy_jones_301", "$session_id" : "gigtleqddo84l8cm15qe4il", # Supported Fields "$ip" : "54.208.214.78" } response = client.track("$link_session_to_user", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $link_session_to_user event properties = { # Required Fields "$user_id" => "billy_jones_301", "$session_id" => "gigtleqddo84l8cm15qe4il", # Supported Fields "$ip" => "54.208.214.78" } response = client.track("$link_session_to_user", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $link_session_to_user event $properties = array( // Required Fields '$user_id' => 'billy_jones_301', '$session_id' => 'gigtleqddo84l8cm15qe4il', // Supported Fields '$ip' => '54.208.214.78' ); $response = $client->track('$link_session_to_user', $properties);
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") // Supported Fields .setIp("54.208.214.78")); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
Use $login
to record when a user attempts to log in.
"$login"
Your Sift REST API key.
The user's account ID according to your systems. Note that user IDs are case sensitive.
Find valid $user_id
values here.
The user's current session ID, used to tie a user's action before and after log in or account creation.
NOTE: this is required if no $user_id
is provided.
Use $login_status
to represent the success or failure of the login attempt.
"$success"
"$failure"
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.
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.
IP address of the user that is logging in.
The user agent of the browser that is logging in. Represented by the $browser
object.
Use this field if the client is a browser. Note: cannot be used in conjunction with $app
.
The details of the app, os, and device that is logging in. Represented by the $app
object.
Use this field if the client is an app. Note: cannot be used in conjunction with $browser
.
Capture the reason for the failure of the login.
The username entered at the login prompt.
If the user logged in with a social identify provider, give the name here.
$facebook
$google
$linkedin
$twitter
$yahoo
$microsoft
$amazon
$apple
$github
$other
Capture the type(s) of the account: "merchant"
or "shopper"
, "regular"
or "premium"
, etc.
The array supports multiple types for a single account, e.g. ["merchant", "premium"]
.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
Domain being interfaced with. Use fully qualified domain name.
// Sample $login event { // Required Fields "$type" : "$login", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", "$login_status" : "$success", "$session_id" : "gigtleqddo84l8cm15qe4il", "$ip" : "128.148.1.135", // Optional Fields "$user_email" : "billjones1@example.com", "$verification_phone_number" : "+123456789012", "$failure_reason" : "$account_unknown", "$username" : "billjones1@example.com", "$account_types" : ["merchant", "premium"], "$social_sign_on" : "$linkedin", "$brand_name" : "sift", "$site_domain" : "sift.com", "$site_country" : "US", // 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(api_key='{apiKey}', account_id='{accountId}') # Sample $login event properties = { # Required Fields "$user_id" : "billy_jones_301", "$login_status" : "$success", "$session_id" : "gigtleqddo84l8cm15qe4il", "$ip" : "128.148.1.135", # Optional Fields "$user_email" : "billjones1@example.com", "$verification_phone_number" : "+123456789012", "$failure_reason" : "$account_unknown", "$username" : "billjones1@example.com", "$account_types" : ["merchant", "premium"], "$social_sign_on" : "$linkedin", "$brand_name" : "sift", "$site_domain" : "sift.com", "$site_country" : "US", # 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" } } response = client.track("$login", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $login event properties = { # Required Fields "$user_id" => "billy_jones_301", "$login_status" => "$success", "$session_id" => "gigtleqddo84l8cm15qe4il", "$ip" => "128.148.1.135", # Optional Fields "$user_email" => "billjones1@example.com", "$failure_reason" => "$account_unknown", "$username" => "billjones1@example.com", "$account_types" => ["merchant", "premium"], "$social_sign_on" => "$linkedin", "$brand_name" => "sift", "$site_domain" => "sift.com", "$site_country" => "US", # 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 a 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("$login", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $login event $properties = array( // Required Fields '$user_id' => 'billy_jones_301', '$login_status' => '$success', '$session_id' => 'gigtleqddo84l8cm15qe4il', '$ip' => '128.148.1.135', // Optional Fields '$user_email' => 'billjones1@example.com', '$failure_reason' => '$account_unknown', '$username' => 'billjones1@example.com', '$account_types' => ['merchant','premium'], '$social_sign_on' => '$linkedin', '$brand_name' => 'sift', '$site_domain' => 'sift.com', '$site_country' => 'US', // Send this information with a login 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 with a login from a 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('$login', $properties);
import java.util.Arrays; import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.EventResponse; import com.siftscience.model.LoginFieldSet; // Sample $login event SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new LoginFieldSet() // Required Fields .setUserId("billy_jones_301") .setLoginStatus("$success") // Optional Fields .setUserEmail("billjones1@example.com") .setFailureReason("$account_unknown") .setUsername("billjones1@example.com") .setAccountTypes(Arrays.asList(new String[]{"merchant","premium"})) .setSocialSignOn("$linkedin") .setBrandName("sift") .setSiteDomain("sift.com") .setSiteCountry("US") // Send this information with a login from a BROWSER client. .setSessionId("gigtleqddo84l8cm15qe4il") .setIp("128.148.1.135") .setBrowser(new Browser() .setUserAgent("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36") .setAcceptLanguage("en-US") .setContentLanguage("en-GB")) // ========================================= // Send this information with a login from a APP client. .setSessionId("gigtleqddo84l8cm15qe4il") .setIp("128.148.1.135") .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
Use $logout
to record when a user logs out.
"$logout"
Your Sift REST API key.
The user's account ID according to your systems. Note that user IDs are case sensitive.
Find valid $user_id
values here.
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
.
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
.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
Domain being interfaced with. Use fully qualified domain name.
IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
// Sample $logout event { // Required Fields "$type" : "$logout", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", // Supported Fields "$ip" : "54.208.214.78", // 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", # Supported Fields "$ip" : "54.208.214.78", # 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", # Supported Fields "$ip" => "54.208.214.78", # 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', // Supported Fields '$ip' => '54.208.214.78', // 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") //Supported Fields .setIp("54.208.214.78") // 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
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.
"$order_status"
Your Sift REST API key.
The user's account ID according to your systems. Note that user IDs are case sensitive.
Find valid $user_id
values here.
The ID for tracking this order in your system.
Indicates the high-level state of the order.
"$approved"
"$canceled"
"$held"
"$fulfilled"
"$returned"
The reason for a cancellation.
"$payment_risk"
"$abuse"
"$policy"
"$other"
The source of a decision.
"$automated"
"$manual_review"
The analyst who made the decision, if manual.
An alternative to using $source
and $analyst
, this is the ID of the Sift
Action webhook that triggered the status change.
Any additional information about this order status change.
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
.
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
.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
Domain being interfaced with. Use fully qualified domain name.
IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
// Sample $order_status event { // Required Fields "$type" : "$order_status", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", "$order_id" : "ORDER-28168441", "$order_status" : "$canceled", // Optional Fields "$reason" : "$payment_risk", "$source" : "$manual_review", "$analyst" : "someone@your-site.com", "$webhook_id" : "3ff1082a4aea8d0c58e3643ddb7a5bb87ffffeb2492dca33", "$description" : "Canceling because multiple fraudulent users on device", "$ip" : "54.208.214.78", // 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", "$ip" : "54.208.214.78", # 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", "$ip" => "54.208.214.78", # 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', '$ip' => '54.208.214.78', // 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") .setIp("54.208.214.78") // 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
Use $remove_item_from_cart
to record when a user removes an item from their shopping cart or list.
"$remove_item_to_cart"
Your Sift REST API key.
The user's current session ID, used to tie a user's action before and after log in or account creation.
The user's account ID according to your systems. Note that user IDs are case sensitive.
Find valid $user_id
values here.
The product item removed from cart.
Strongly recommended subfields are $item_id
, $product_title
, and
$price
. The $quantity
is specified as a subfield.
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
.
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
.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
Domain being interfaced with. Use fully qualified domain name.
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.
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.
IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
// Sample $remove_item_from_cart event { // Required Fields "$type" : "$remove_item_from_cart", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", // Supported Fields "$session_id" : "gigtleqddo84l8cm15qe4il", "$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" }, "$ip" : "54.208.214.78", // 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" }, "$ip" : "54.208.214.78", # 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" }, "$ip" => "54.208.214.78", # 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' ), '$ip' => '54.208.214.78', // 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)) .setBrandName("sift") .setSiteDomain("sift.com") .setSiteCountry("US") .setUserEmail("billjones1@example.com") .setVerificationPhoneNumber("+123456789012") .setIp("54.208.214.78") // 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
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.
"$security_notification"
Your Sift REST API key.
The user's account ID according to your systems. Note that user IDs are case sensitive.
Find valid $user_id
values here.
The user's current session ID, used to tie a user's action before and after log in or account creation.
The type of notification issued.
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
.
The status of the notification event: records the follow-up action taken by the notified user.
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
.
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
.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
Domain being interfaced with. Use fully qualified domain name.
IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
// 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", "$ip" : "54.208.214.78", // 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", "$ip" : "54.208.214.78", # 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", "$ip" => "54.208.214.78", # 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', '$ip' => '54.208.214.78', // 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") .setIp("54.208.214.78") // 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
Use $transaction
to record attempts to exchange money, credit or other tokens of value.
"$transaction"
Your Sift REST API key.
The user's account ID according to your systems. Note that user IDs are case sensitive.
Find valid $user_id
values here.
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.
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.
The type of transaction being recorded. There are eight types:
$transaction_type
if the transaction type is not provided.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"
.
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.
ISO-4217 currency code for the amount. e.g., USD, CAD, HKD, BTC.
The ID for this order in your system. Used for cross referencing an order in your internal systems.
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.
The billing address as entered by the user.
The payment information associated with this transaction.
The shipping address as entered by the user.
The user's current session ID, used to tie a user's action before and after log in or account creation.
For marketplace businesses, this is the seller's user ID, typically a database primary key.
Follow our guidelines for $user_id
values.
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.
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.
$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.
The details about the specific physical location providing the good or service. This can also be used to capture pickup, delivery locations, etc.
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
.
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
.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
Domain being interfaced with. Use fully qualified domain name.
Use the following allowed values to indicate the status of a 3DS request.
"$successful"
"$attempted"
"$failed"
"$unavailable"
"$rejected"
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.
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).
The details about the merchant or seller providing the goods or service.
The address to the specific physical location of the person sending a transaction.
The address to the specific physical location of the person receiving a transaction.
The list of digital orders made. A digital order represents a digital asset which can be part of a cryptocurrency or digital asset transaction.
The wallet ID or address of the person receiving a crypto payment.
Use true
or false
to indicate if the recipient is on an external platform.
IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
Minimum deposit 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. Compatible only with
transactions sent with a $transaction_status = $deposit
. For currencies without
cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.
Use 1 for 1 microBitcoin.
Maximum deposit 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. Compatible only with
transactions sent with a $transaction_status = $deposit
. For currencies without
cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.
Use 1 for 1 microBitcoin.
Minimum withdrawal 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. Compatible only with
transactions sent with a $transaction_status = $withdrawal
. For currencies without
cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.
Use 1 for 1 microBitcoin.
Maximum withdrawal 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. Compatible only with
transactions sent with a $transaction_status = $withdrawal
. For currencies without
cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.
Use 1 for 1 microBitcoin.
The current balance of the account prior to this transaction being processed. For the
updated balance after this transaction is processed, use the $new_balance
field.
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. Compatible only with transactions sent with a
$transaction_status
$withdrawal
or $deposit
. For currencies
without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.
Use 1 for 1 microBitcoin.
The new balance of the account after this transaction is processed. For the updated
balance before this transaction is processed, use the $current_balance
field.
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. Compatible only with transactions sent with
a $transaction_status
$withdrawal
or $deposit
. For currencies
without cents of fractional denominations, like the Japanese Yen, use 1 JPY = 1000000 micros.
Use 1 for 1 microBitcoin.
// 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", "$ip" : "54.208.214.78", "$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", "$ip" : "54.208.214.78", "$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", "$ip" => "54.208.214.78", "$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', '$ip' => '54.208.214.78', '$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") .setIp("54.208.214.78") .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
Use $update_account
to record changes to the user's account
information. For user accounts created prior to integrating with Sift, it's
recommended that $create_account
is called before $update_account
to enable Sift to track the account's age. Otherwise, call $update_account
and
we'll infer that account was created before integration.
"$update_account"
Your Sift REST API key.
The user's account ID according to your systems. Note that user IDs are case sensitive.
Find valid $user_id
values here.
Track password changes via $update_password.
If the user changed their password, set this field and mark as true
. Additionally,
Sift's recommended approach is to send the $update_password
reserved event.
Updated value of the user's email address. Note: If the user's email is also their account ID in your
system, set both the $user_id
and $user_email
fields to their
email address.
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.
The full name of the user.
The primary phone number of the user associated with this account. Provide the phone number as a string
starting with the country code. Use E.164 format or send
in the standard national format of number's origin. For example: "+14155556041" or "1-415-555-6041" for a
U.S. number. If you collect other phone numbers for the account, provide them as additional custom fields,
e.g work_phone
The ID of the user that referred the current user to your business. This field is required for
detecting referral fraud. Note: User IDs are case sensitive. You may need to normalize the
capitalization of your user IDs. Follow our guidelines
for $user_id
values.
The payment method(s) associated with this account. If possible, please send all payment methods associated with the account each time payment methods are updated.
The updated billing address.
The shipping address associated with this user.
If the user logged in with a social identify provider, give the name here.
$facebook
$google
$linkedin
$twitter
$yahoo
$microsoft
$amazon
$apple
$github
$other
The user agent of the browser that is used to update the account. Represented by the $browser
object.
Use this field if the client is a browser. Note: cannot be used in conjunction with $app
.
The details of the app, os, and device that is used to update the account. Represented by the $app
object.
Use this field if the client is an app. Note: cannot be used in conjunction with $browser
.
Capture the type(s) of the account: "merchant"
or "shopper"
, "regular"
or "premium"
, etc.
The array supports multiple types for a single account, e.g.["merchant", "premium"]
.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
Domain being interfaced with. Use fully qualified domain name.
The details about the merchant or seller providing the goods or service.
IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
// Sample $update_account event { // Required Fields "$type" : "$update_account", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", // Supported Fields "$changed_password" : true, "$user_email" : "billjones1@example.com", "$verification_phone_number" : "+123456789012", "$name" : "Bill Jones", "$phone" : "1-415-555-6040", "$referrer_user_id" : "janejane102", "$payment_methods" : [ { "$payment_type" : "$credit_card", "$card_bin" : "542486", "$card_last4" : "4444" } ], "$billing_address" : { "$name" : "Bill Jones", "$phone" : "1-415-555-6041", "$address_1" : "2100 Main Street", "$address_2" : "Apt 3B", "$city" : "New London", "$region" : "New Hampshire", "$country" : "US", "$zipcode" : "03257" }, "$shipping_address" : { "$name" : "Bill Jones", "$phone" : "1-415-555-6041", "$address_1" : "2100 Main Street", "$address_2" : "Apt 3B", "$city" : "New London", "$region" : "New Hampshire", "$country" : "US", "$zipcode" : "03257" }, "$social_sign_on_type" : "$twitter", "$account_types" : ["merchant", "premium"], "$ip" : "54.208.214.78", // 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_account event properties = { # Required Fields "$user_id" : "billy_jones_301", # Supported Fields "$changed_password" : True, "$user_email" : "billjones1@example.com", "$verification_phone_number" : "+123456789012", "$name" : "Bill Jones", "$phone" : "1-415-555-6040", "$referrer_user_id" : "janejane102", "$payment_methods" : [ { "$payment_type" : "$credit_card", "$card_bin" : "542486", "$card_last4" : "4444" } ], "$billing_address" : { "$name" : "Bill Jones", "$phone" : "1-415-555-6041", "$address_1" : "2100 Main Street", "$address_2" : "Apt 3B", "$city" : "New London", "$region" : "New Hampshire", "$country" : "US", "$zipcode" : "03257" }, "$shipping_address" : { "$name" : "Bill Jones", "$phone" : "1-415-555-6041", "$address_1" : "2100 Main Street", "$address_2" : "Apt 3B", "$city" : "New London", "$region" : "New Hampshire", "$country" : "US", "$zipcode" : "03257" }, "$social_sign_on_type" : "$twitter", "$account_types" : ["merchant", "premium"], "$ip" : "54.208.214.78", # 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_account", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $update_account event properties = { # Required Fields "$user_id" => "billy_jones_301", # Supported Fields "$changed_password" => true, "$user_email" => "billjones1@example.com", "$name" => "Bill Jones", "$phone" => "1-415-555-6040", "$referrer_user_id" => "janejane102", "$payment_methods" => [ { "$payment_type" => "$credit_card", "$card_bin" => "542486", "$card_last4" => "4444" } ], "$billing_address" => { "$name" => "Bill Jones", "$phone" => "1-415-555-6041", "$address_1" => "2100 Main Street", "$address_2" => "Apt 3B", "$city" => "New London", "$region" => "New Hampshire", "$country" => "US", "$zipcode" => "03257" }, "$shipping_address" => { "$name" => "Bill Jones", "$phone" => "1-415-555-6041", "$address_1" => "2100 Main Street", "$address_2" => "Apt 3B", "$city" => "New London", "$region" => "New Hampshire", "$country" => "US", "$zipcode" => "03257" }, "$social_sign_on_type" => "$twitter", "$account_types" => ["merchant", "premium"], "$ip" => "54.208.214.78", # 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_account", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); // Sample $update_account event $properties = array( // Required Fields '$user_id' => 'billy_jones_301', // Supported Fields '$changed_password' => True, '$user_email' => 'bill@gmail.com', '$name' => 'Bill Jones', '$phone' => '1-415-555-6040', '$referrer_user_id' => 'janejane102', '$payment_methods' => array( array( '$payment_type' => '$credit_card', '$card_bin' => '542486', '$card_last4' => '4444' ) ), '$billing_address' => array( '$name' => 'Bill Jones', '$phone' => '1-415-555-6041', '$address_1' => '2100 Main Street', '$address_2' => 'Apt 3B', '$city' => 'New London', '$region' => 'New Hampshire', '$country' => 'US', '$zipcode' => '03257' ), '$shipping_address' => array( '$name' => 'Bill Jones', '$phone' => '1-415-555-6041', '$address_1' => '2100 Main Street', '$address_2' => 'Apt 3B', '$city' => 'New London', '$region' => 'New Hampshire', '$country' => 'US', '$zipcode' => '03257' ), '$social_sign_on_type' => '$twitter', '$account_types' => ['merchant', 'premium'], '$ip' => '54.208.214.78', // 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_account', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.model.UpdateAccountFieldSet; import com.siftscience.model.Address; import com.siftscience.model.PaymentMethod; SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new UpdateAccountFieldSet() // Required Fields .setUserId("billy_jones_301") .setSessionId("gigtleqddo84l8cm15qe4il") .setChangedPassword(true) .setUserEmail("billjones1@example.com") .setName("Bill Jones") .setPhone("1-415-555-6040") .setReferrerUserId("janejane102") .setPaymentMethods(Arrays.asList(new PaymentMethod() .setPaymentType("$credit_card") .setPaymentGateway("$braintree") .setCardBin("542486") .setCardLast4("4444"))) .setBillingAddress(new Address() .setName("Bill Jones") .setPhone("1-415-555-6041") .setAddress1("2100 Main Street") .setAddress2("Apt 3B") .setCity("New London") .setRegion("New Hampshire") .setCountry("US") .setZipCode("03257")) .setShippingAddress(new Address() .setName("Bill Jones") .setPhone("1-415-555-6041") .setAddress1("2100 Main Street") .setAddress2("Apt 3B") .setCity("New London") .setRegion("New Hampshire") .setCountry("US") .setZipCode("03257")) .setSocialSignOnType("$twitter") .setAccountTypes(Arrays.asList(new String[]{"merchant","premium"})) .setIp("54.208.214.78") // 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
Use $update_content
to record changes to a content created previously with a $create_content
event.
$create_content
.$update_content
. Be sure
to specify all values for the content, not just those that changed.$create_content
before
$update_content
. Simply call $update_content
and we'll infer that the content was created before
your integration with Sift.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.
"$update_content"
Your Sift REST API key.
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.
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.
The user's current session ID, used to tie a user's action before and after login or account creation.
The status of the comment. After you update a posting, you can also update its status via the
$content_status
event.
$active
at a later date.IP address of the request made by the user. Recommended for historical backfills and customers with with mobile apps.
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
.
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
.
Contains information about the comment.
The text content of the comment.
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.
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.
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.
The list of images shared by the user with their comment. It includes images pasted inline or attached separately.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
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
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.
"$update_content"
Your Sift REST API key.
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.
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.
The user's current session ID, used to tie a user's action before and after login or account creation.
The status of the listing. After you update a listing, you can also update its status via the
$content_status
event.
$active
at a later date.IP address of the request made by the user. Recommended for historical backfills and customers with with mobile apps.
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
.
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
.
Contains information about the listing.
The subject of the listing.
The text content of the listing.
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.
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.
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.
The items array represents physical or digital items listed by the user.
The list of images shared by the user with their listing. It includes images pasted inline or attached separately.
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).
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
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
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.
"$update_content"
Your Sift REST API key.
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.
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.
The user's current session ID, used to tie a user's action before and after login or account creation.
The status of the posting. After you update a posting, you can also update its status via the
$content_status
event.
$active
at a later date.IP address of the request made by the user. Recommended for historical backfills and customers with with mobile apps.
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
.
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
.
Contains information about the post.
The user-supplied subject of the post.
The text content of the post.
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.
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.
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.
The category or categories you associate with the posting. For example, a blog post might be
categorized as ["Family", "Travel"]
.
The list of images shared by the user with their post. It includes images pasted inline or attached separately.
The UNIX timestamp in milliseconds of when the post will expire. Only set if the post is time bound in some way.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
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
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.
"$update_content"
Your Sift REST API key.
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.
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.
The user's current session ID, used to tie a user's action before and after login or account creation.
The status of the profile. After you update a profile, you can also update its status via the
$content_status
event.
$active
at a later date.IP address of the request made by the user. Recommended for historical backfills and customers with with mobile apps.
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
.
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
.
Contains information about the profile.
The text content of the profile.
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.
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.
The list of images shared by the user with their profile. It includes images pasted inline or attached separately.
The category or categories you associate with the profile. For example, a profile on a services
marketplace might be categorized as ["Photographer", "Weddings"]
.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
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
Use $update_content
with a $review
type to represent information related to a product or service review
submitted by your users.
"$update_content"
Your Sift REST API key.
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.
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.
The user's current session ID, used to tie a user's action before and after login or account creation.
The status of the review. After you create a posting, you can also update its status via the
$content_status
event.
$active
at a later date.IP address of the request made by the user. Recommended for historical backfills and customers with with mobile apps.
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
.
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
.
Contains information about the review.
The user-supplied title of the review.
The text content of the review.
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.
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.
An Item object representing the item being reviewed.
The $content_id
of the item being reviewed. For example, this could be the id for the
$listing
or $profile
being reviewed.
A numeric rating supplied by the reviewer.
The list of images shared by the user with their review. It includes images pasted inline or attached separately.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
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
Use $update_order
to record when a user updates an order for products or services they intend to
purchase.
$create_order
.$update_order
. Be sure to specify
all values for the order, not just those that changed.$order_id
found, a new order will be created."$update_order"
Your Sift REST API key.
The user's account ID according to your systems. Note that user IDs are case sensitive.
Find valid $user_id
values here.
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.
The ID for tracking this order in your system.
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.
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.
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.
ISO-4217 currency code for the amount. If your site uses alternative currencies, specify them here.
The billing address as entered by the user.
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.
The shipping address as entered by the user.
Whether the user requested priority/expedited shipping on their order.
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: can be used in conjunction with $bookings
or $digital_orders
.
The list of bookings made. This may include tickets and reservations like flights, hotels, rideshares etc.
Note: can be used in conjunction with $items
or $digital_orders
.
For marketplace businesses, this is the seller's user ID, typically a database primary key.
Follow our guidelines for $user_id
values.
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.
Indicates the method of delivery to the user.
"$electronic"
"$physical"
Shipping carrier for the shipment of the product.
Shipping tracking number for the shipment of the product.
Shipping tracking number(s) for the shipment of the product(s).
The details about the specific physical location providing the good or service. This can also be used to capture pickup, delivery locations, etc.
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
.
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
.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
Domain being interfaced with. Use fully qualified domain name.
The details about the merchant or seller providing the goods or service.
The list of digital orders made. A digital order represents a digital asset which can be part of
a cryptocurrency or digital asset transaction. Note: can be used in conjunction with $items
or
$bookings
.
IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
// Sample $update_order event { // Required Fields "$type" : "$update_order", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", // Supported Fields "$session_id" : "gigtleqddo84l8cm15qe4il", "$order_id" : "ORDER-28168441", "$user_email" : "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 } ], "$ip" : "54.208.214.78", // 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 } ], "$ip" : "54.208.214.78", # 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 } ], "$ip" => "54.208.214.78", # 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 ) ), '$ip' => '54.208.214.78', // 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)))) .setIp("54.208.214.78") // 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
Use $update_password
to record all password changes, whether initiated by the user or the service.
"$update_password"
Your Sift REST API key.
The user's account ID according to your systems. Note that user IDs are case sensitive.
Find valid $user_id
values here.
The reason the password was updated or an update was attempted. The process may trigger a verification
(with $verified_event = $update_password
).
$status
is $success
).$status
is $pending
).The status of the password update event.
$reason
is $user_update
).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
.
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
.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
Domain being interfaced with. Use fully qualified domain name.
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.
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.
IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
// 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", // Supported Fields "$user_email" : "billjones1@example.com", "$verification_phone_number" : "+123456789012", "$ip" : "128.148.1.135", // IP of the user that entered the new password after the old password was reset // 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", # Supported Fields "$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", # Supported Fields "$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', // Supported Fields '$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") // Supported Fields .setIp("128.148.1.135") // IP of the user that entered the new password after the old password was reset .setBrandName("sift") .setSiteDomain("sift.com") .setSiteCountry("US") .setUserEmail("billjones1@example.com") .setVerificationPhoneNumber("+123456789012") // 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
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.
"$verification"
Your Sift REST API key.
The user's account ID according to your systems. Note that user IDs are case sensitive.
Find valid $user_id
values here.
The user's current session ID, used to tie a user's action before and after log in or account creation.
The status of the verification event.
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.
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.
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
The ID of the entity impacted by the event being verified, e.g.,
for $login
for $create_order
for $create_content
for $create_account
, $update_account
, or $update_password
The type of verification being performed.
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
.
The trigger for the verification
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
Domain being interfaced with. Use fully qualified domain name.
IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
// 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", "$ip" : "54.208.214.78" }
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", "$ip" : "54.208.214.78" } 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", "$ip" => "54.208.214.78" } 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', '$ip' => '54.208.214.78' ); $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") .setIp("54.208.214.78")); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
Represents a user-initiated wager on iGaming platforms, used to track individual bets, game entries, or other forms of wagering.
"$wager"
Your Sift REST API key.
The user's account ID according to your systems. Note that user IDs are case sensitive.
Find valid $user_id
values here.
The ID for identifying this wager on a platform.
Specifies the type of wager placed, such as “Moneyline," “Spread,” or other types relevant to the event.
Represents the status of a wager.
Total wager 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.
ISO-4217 currency code for the amount. e.g., USD, CAD, HKD.
Specifies the type of event the wager is associated with, such as “Sportsbook,” “Casino,” or other relevant categories.
Indicates the specific name of the event on which the user is wagering, such as a sports match or game title.
A unique identifier for the event on which the wager is placed. This ID is used for tracking and reference purposes within the system.
Minimum wager 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.
// Sample $wager event { // Required Fields "$type" : "$wager", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", "$wager_id" : "ID000001", "$wager_type" : "spread", "$wager_status" : "$accept", "$amount" : 506790000, "$currency_code" : "USD", // Optional fields if applicable "$wager_event_type" : "Sportsbook", "$wager_event_name" : "NFL", "$wager_event_id" : "KHG23423093", "$minimum_wager_amount" : 3000000 }
import sift client = sift.Client("YOUR_API_KEY") # Sample $wager event properties = { # Required Fields "$type" : "$wager", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", "$wager_id" : "ID000001", "$wager_type" : "spread", "$wager_status" : "$accept", "$amount" : 506790000, "$currency_code" : "USD", # Optional fields if applicable "$wager_event_type" : "Sportsbook", "$wager_event_name" : "NFL", "$wager_event_id" : "KHG23423093", "$minimum_wager_amount" : 3000000 } response = client.track("$wager", properties)
require "sift" client = Sift::Client.new(:api_key => "YOUR_API_KEY") # Sample $wager event properties = { # Required Fields "$type" : "$wager", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", "$wager_id" : "ID000001", "$wager_type" : "spread", "$wager_status" : "$accept", "$amount" : 506790000, "$currency_code" : "USD", # Optional fields if applicable "$wager_event_type" : "Sportsbook", "$wager_event_name" : "NFL", "$wager_event_id" : "KHG23423093", "$minimum_wager_amount" : 3000000 } response = client.track("$wager", 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 $wager event properties = array( // Required Fields "$type" : "$wager", "$api_key" : "YOUR_API_KEY", "$user_id" : "billy_jones_301", "$wager_id" : "ID000001", "$wager_type" : "spread", "$wager_status" : "$accept", "$amount" : 506790000, "$currency_code" : "USD", // Optional fields if applicable "$wager_event_type" : "Sportsbook", "$wager_event_name" : "NFL", "$wager_event_id" : "KHG23423093", "$minimum_wager_amount" : 3000000 ); $response = $client->track('$wager', $properties);
import com.siftscience.SiftClient; import com.siftscience.EventRequest; import com.siftscience.EventResponse; import com.siftscience.model.VerificationFieldSet; // Sample $wager event SiftClient client = new SiftClient("YOUR_API_KEY"); EventRequest request = client.buildRequest(new WagerFieldSet() // Required Fields .setUserId("billy_jones_301") .setWagerId("ID000001") .setWagerType("spread") .setWagerStatus("$accept") .setAmount(506790000L) .setCurrencyCode("USD") // Optional Fields .setWagerEventType("Sportsbook") .setWagerEventName("NFL") .setWagerEventId("KHG23423093") .setMinimumWagerAmount(3000000L)); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; } response.isOk(); // true
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.
The following reserved fields are required in every event.
Your Sift REST API key.
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,=, ., -, _, +, @, :, &, ^, %, !, $
The user's current session ID, used to tie a user's action before and after log in or account creation.
The name of the event, for example $create_order
.
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 address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
Represents the time the event occurred in your system. Send as a UNIX timestamp in milliseconds as shown in the historical backfill tutorial.
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
.
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 first line, e.g., "2100 Main Street".
Address second line, e.g., "Apt 3B".
The city or town name.
The region portion of the address. In the USA, this corresponds to the state.
The ISO-3166 country code for the address.
The postal code associated with the address, e.g., "90210". Send +4 postal codes with a '-', e.g. "90210-3344"
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");
The app field type represents the details of an application as well as the device and OS it's running on.
The operating system on which application is running. (e.g. iOS, Android)
The operating system version on which application is running. (e.g. 10.3.1, 7.1.1)
The manufacturer of the device on which application is running. (e.g. Samsung, Apple, LG)
The model of the device on which application is running. (e.g. SM-G920x, iPhone8,1)
The unique ID of the device on which application is running. For iOS, send the IFV identifier. For Android, send the Android ID.
The name of your application.
The version of your application. Our accepted format is numbers separated by periods.
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");
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 can 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.
Note: If the $start_time
and $end_time
fields are present for all $segments
,
and the $start_time
and $end_time
fields of a $booking
are omitted,
then they will be automatically set to the earliest $start_time
and latest $end_time
contained within the $segments
defined in the $booking
.
$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:
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.
$event_ticket
A description of the event.
The start time of the event. Send as a UNIX timestamp in milliseconds.
The finish time of the event. Send as a UNIX timestamp in milliseconds.
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.
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.
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.
Details of the guests using the tickets. Send as much information about each guest as you capture.
For event ticket bookings, this field represents the internal identifier associated with the event.
This field represents the id of the venue.
This field represents the name and address of the venue.
This field captures the genre of ticket.
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" : 1679062720000, "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" : 1679062720000, "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" => 1679062720000, "$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' => 1679062720000, '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);
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.
$accommodation
A description of the reservation, e.g., "Deluxe King, Hotel Alpha".
The check-in time for a hotel reservation. Send as a UNIX timestamp in milliseconds.
The check-out time for a hotel reservation. Send as a UNIX timestamp in milliseconds.
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.
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.
The count of reservations, e.g., 2 for two hotel rooms of the same type.
Details of the guests on the reservation. Send as much information about each guest as you capture.
This field represents the type of room. e.g., "Double Queen Deluxe"
This field represents the id of the hotel.
This field represents the address of the hotel.
This field captures any descriptors of the booking. For example, tags might be "non-smoking", "wi-fi", etc.
{ "$booking_type" : "$accommodation", "$start_time" : 1678062720000, "$end_time" : 1679062720000, "$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" : 1678062720000, "$end_time" : 1679062720000, "$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" => 1678062720000, "$end_time" => 1679062720000, "$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' => 1678062720000, '$end_time' => 1679062720000, '$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);
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.
$flight
A description of the flight reservation.
The departure time for the first flight leg in the booking. Send as a UNIX timestamp in milliseconds.
The arrival time for the last flight leg in the booking etc. Send as a UNIX timestamp in milliseconds.
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.
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.
The count of tickets of the given type purchased by the user.
The two-character IATA airline designator code associated with the booking.
Details of the guests on the flight. Send as much information about each guest as you capture.
Use this field to send information about each leg of the flight (even if there’s only one).
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" : 1678062720000, "$end_time" : 1679062720000, "$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", "$guest_booking_reference_id" : "987612345", "$guest_user_id" : "joe-doe_1985-03-20" }, { "$name" : "Jane Doe" } ], "$segments" : [ { "$start_time" : 1678062720000, "$end_time" : 1679062720000, "$vessel_number" : "LH454", "$fare_class" : "Premium Economy", "$departure_airport_code" : "SFO", "$arrival_airport_code" : "JFK" }, { "$start_time" : 1678062720000, "$end_time" : 1679062720000, "$vessel_number" : "LH388", "$fare_class" : "Premium Economy", "$departure_airport_code" : "JFK", "$arrival_airport_code" : "CDG" }, ], "$price" : 49900000, "$currency_code" : "USD", "$quantity" : 2, "$iata_carrier_code" : "AS" }
{ "$booking_type" : "$flight", "$title" : "SFO - CDG, 2 Adults", "$start_time" : 1678062720000, "$end_time" : 1679062720000, "$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", "$guest_booking_reference_id" : "987612345", "$guest_user_id" : "joe-doe_1985-03-20" }, { "$name" : "Jane Doe" } ], "$segments" : [ { "$start_time" : 1678062720000, "$end_time" : 1679062720000, "$vessel_number" : "LH454", "$fare_class" : "Premium Economy", "$departure_airport_code" : "SFO", "$arrival_airport_code" : "JFK" }, { "$start_time" : 1678062720000, "$end_time" : 1679062720000, "$vessel_number" : "LH388", "$fare_class" : "Premium Economy", "$departure_airport_code" : "JFK", "$arrival_airport_code" : "CDG" } ], "$price" : 49900000, "$currency_code" : "USD", "$quantity" : 2, "$iata_carrier_code" : "AS" }
{ "$booking_type" => "$flight", "$title" => "SFO - CDG, 2 Adults", "$start_time" => 1678062720000, "$end_time" => 1679062720000, "$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", "$guest_booking_reference_id" => "987612345", "$guest_user_id" => "joe-doe_1985-03-20" }, { "$name" => "Jane Doe" } ], "$segments" => [ { "$start_time" => 1678062720000, "$end_time" => 1679062720000, "$vessel_number" => "LH454", "$fare_class" => "Premium Economy", "$departure_airport_code" => "SFO", "$arrival_airport_code" => "JFK" }, { "$start_time" => 1678062720000, "$end_time" => 1679062720000, "$vessel_number" => "LH388", "$fare_class" => "Premium Economy", "$departure_airport_code" => "JFK", "$arrival_airport_code" => "CDG" } ], "$price" => 49900000, "$currency_code" => "USD", "$quantity" => 2, "$iata_carrier_code" => "AS" }
array( '$booking_type' => '$flight', '$title' => 'SFO - CDG, 2 Adults', '$start_time' => 1678062720000, '$end_time' => 1679062720000, '$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', '$guest_booking_reference_id' => '987612345', '$guest_user_id' => 'joe-doe_1985-03-20' ), array( '$name' => 'Jane Doe' ) ), '$segments' => array( array( '$start_time' => 1678062720000, '$end_time' => 1679062720000, '$vessel_number' => 'LH454', '$fare_class' => 'Premium Economy', '$departure_airport_code' => 'SFO', '$arrival_airport_code' => 'JFK' ), array( '$start_time' => 1678062720000, '$end_time' => 1679062720000, '$vessel_number' => 'LH388', '$fare_class' => 'Premium Economy', '$departure_airport_code' => 'JFK', '$arrival_airport_code' => 'CDG' ), ), '$price' => 49900000, '$currency_code' => 'USD', '$quantity' => 2, '$iata_carrier_code' => "AS" )
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") .setGuestBookingReferenceId("987612345") .setGuestUserId("joe-doe_1985-03-20"), 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) .setIataCarrierCode("AS");
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.
$bus
A description of the trip.
The departure time for a trip. Send as a UNIX timestamp in milliseconds.
The arrival time of the trip. Send as a UNIX timestamp in milliseconds.
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.
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.
The count of tickets of the given type purchased by the user.
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.
Use this field to send information about each ride of the trip (even if there’s only one).
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" : 1678062720000, "$end_time" : 1679062720000, "$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" : 1678062720000, "$end_time" : 1679062720000, "$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" : 1678062720000, "$end_time" : 1679062720000, "$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" : 1678062720000, "$end_time" : 1679062720000, "$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" => 1678062720000, "$end_time" => 1679062720000, "$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" => 1678062720000, "$end_time" => 1679062720000, "$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' => 1678062720000, '$end_time' => 1679062720000, '$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' => 1678062720000, '$end_time' => 1679062720000, '$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"));
Tell Sift about a booking of a ride in a ridesharing marketplace.
$rideshare
A description of the ride.
The pickup time of the ride. Send as a UNIX timestamp in milliseconds.
The estimated drop-off time of the ride. Send as a UNIX timestamp in milliseconds.
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.
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.
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).
Details of the guests on the booking. Send as much information about each guest as you capture.
Add more specific information about the ride (even if there is only one segment).
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" : 1678062720000, // pickup time "$end_time" : 1679062720000, // 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" : 1678062720000, // pickup time "$end_time" : 1679062720000, // 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" : 1678062720000, # pickup time "$end_time" : 1679062720000, # 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" : 1678062720000, # pickup time "$end_time" : 1679062720000, # 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" => 1678062720000, # pickup time "$end_time" => 1679062720000, # 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" => 1678062720000, # pickup time "$end_time" => 1679062720000, # 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' => 1678062720000, // pickup time '$end_time' => 1679062720000, // 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' => 1678062720000, // pickup time '$end_time' => 1679062720000, // 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);
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).
$vehicle
A description of the reservation.
The pickup time for the reservation. Send as a UNIX timestamp in milliseconds.
The drop-off time of the reservation. Send as a UNIX timestamp in milliseconds.
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.
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.
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.
Details of the guests on the reservation. Send as much information about each guest as you capture.
Add more specific information about the reservation.
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" : 1678062720000, // pickup time "$end_time" : 1679062720000, // 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" : 1678062720000, // pickup time "$end_time" : 1679062720000, // 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" : 1678062720000, # pickup time "$end_time" : 1679062720000, # 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" => 1678062720000, # pickup time "$end_time" => 1679062720000, # 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" => 1678062720000, # pickup time "$end_time" => 1679062720000, # 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' => 1678062720000, // pickup time '$end_time' => 1679062720000, // 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' => 1678062720000, // pickup time '$end_time' => 1679062720000, // 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);
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.
$cruise
A description of the trip.
The departure time of the cruise. Send as a UNIX timestamp in milliseconds.
The arrival time of the cruise. Send as a UNIX timestamp in milliseconds.
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.
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.
The count of tickets of the given type purchased by the user.
Details of the guests on the cruise. Send as much information about each guest as you capture.
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
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" : 1678062720000, // departure time "$end_time" : 1679062720000, // 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" : 1678062720000, "$end_time" : 1679062720000, "$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" : 1678062720000, # departure time "$end_time" : 1679062720000, # 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" : 1678062720000, "$end_time" : 1679062720000, "$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" => 1678062720000, # departure time "$end_time" => 1679062720000, # 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" => 1678062720000, "$end_time" => 1679062720000, "$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' => 1678062720000, // departure time '$end_time' => 1679062720000, // 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' => 1678062720000, '$end_time' => 1679062720000, '$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"));
For any reservation use case not covered above, leverage whichever of the following fields are appropriate:
$other
A description of the booking.
The start time of the reservation. Send as a UNIX timestamp in milliseconds.
The finish time of the reservation. Send as a UNIX timestamp in milliseconds.
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.
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.
The count of reservations of the given type purchased by the user.
Details of the guests on the booking. Send as much information about each guest as you capture.
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.
For hotels or other accommodation bookings, this field represents the type of room. Eg. "Double Queen Deluxe"
For event ticket bookings, this field represents the internal identifier associated with the event.
For event ticket bookings, this field represents the name of the venue.
For event ticket and accommodation bookings, this field represents the address of venue or hotel respectively.
This field can be used to send the category of booking. For event tickets, this field captures the genre of a ticket.
This field captures any descriptors of the events. For event tickets, for example, tags might be team names, region, etc.
The $browser
field type contains information about the browser.
The user agent of the browser that is interacting with your website.
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.
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");
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.
The amount of credits the promotion is worth.
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");
The $digital_order
field type represents a digital asset which can be part of a cryptocurrency or
digital asset transaction. The value must be a nested object with the appropriate asset subfields.
Generally used in the $create_order
, $update_order
, or $transaction
events. Please note
that $digital_order
can be used with $item
or $booking
.
The trading name of the asset.
Trading pair symbol representing the conversion of one currency to another. For example, BTC_USD represents moving bitcoin to US dollars.
Any digital asset that has value or established ownership.
$coin
$commodity
$crypto
$fiat
$token
$stock
$bond
The type of trade or exchange being made.
$limit
$market
$stop_limit
$stop_loss
$take_profit
$take_profit_limit
The amount or quantity of the digital asset. This should be a string representation of a double value.
"$digital_orders" : [ { "$digital_asset" : "BTC", "$pair" : "BTC_USD", "$asset_type" : "$crypto", "$order_type" : "$market", "$volume" : "6.0" } ]
"$digital_orders" : [ { "$digital_asset" : "BTC", "$pair" : "BTC_USD", "$asset_type" : "$crypto", "$order_type" : "$market", "$volume" : "6.0" } ]
"$digital_orders" => [ { "$digital_asset" => "BTC", "$pair" => "BTC_USD", "$asset_type" => "$crypto", "$order_type" => "$market", "$volume" => "6.0" } ]
$digital_orders = array( array( '$digital_asset' => 'BTC', '$pair' => 'BTC_USD', '$asset_type' => '$crypto', '$order_type' => '$market', '$volume' => '6.0' ) )
import com.siftscience.model.DigitalOrder; List<DigitalOrder> digitalOrders = Arrays.asList( new DigitalOrder() .setDigitalAsset("BTC") .setPair("BTC_USD") .setAssetType("$crypto") .setOrderType("$market") .setVolume("6.0") );
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.
The percentage discount. If the discount is 10% off, you would send "0.1".
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.
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.
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
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 of the individual on the booking.
The email address provided for the guest.
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.
The name of the loyalty program used for this guest.
The membership id for the loyalty program used for this guest.
The date of birth of the guest. Use ISO 8601 format, e.g. "1985-03-20" or "19850320"
The unique booking identifier for an individual guest. This field could be used to represent values like ticket numbers, booking confirmation codes, or seat assignments that are specific to a each guest. If there is just a single booking reference number for all guests on a booking, or there is just a single guest on a booking, consider using the $order_id or $transaction_id fields instead.
The unique identifier for the guest on the booking.
{ "$name" : "John Doe", "$birth_date" : "1985-01-19", "$loyalty_program" : "skymiles", "$loyalty_program_id" : "PSOV34DF", "$phone" : "1-415-555-6040", "$email" : "jdoe@domain.com", "$guest_booking_reference_id" : "987612345", "$guest_user_id" : "joe-doe_1985-03-20" }
{ "$name" : "John Doe", "$birth_date" : "1985-01-19", "$loyalty_program" : "skymiles", "$loyalty_program_id" : "PSOV34DF", "$phone" : "1-415-555-6040", "$email" : "jdoe@domain.com", "$guest_booking_reference_id" : "987612345", "$guest_user_id" : "joe-doe_1985-03-20" }
{ "$name" => "John Doe", "$birth_date" => "1985-01-19", "$loyalty_program" => "skymiles", "$loyalty_program_id" => "PSOV34DF", "$phone" => "1-415-555-6040", "$email" => "jdoe@domain.com", "$guest_booking_reference_id" => "987612345", "$guest_user_id" => "joe-doe_1985-03-20" }
array( '$name' => 'John Doe', '$birth_date' => '1985-01-19', '$loyalty_program' => 'skymiles' '$loyalty_program_id' => 'PSOV34DF', '$phone' => '1-415-555-6040', '$email' => 'jdoe@domain.com', '$guest_booking_reference_id' => '987612345', '$guest_user_id' => 'joe-doe_1985-03-20' );
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("jdoe@domain.com") .setGuestBookingReferenceId("987612345") .setGuestUserId("joe-doe_1985-03-20");
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.
The MD5 hash of the image file. A hexadecimal hash for a single file could look like this:
0cc175b9c0f1b6a831c399e269772661
.
A hyperlink to the image file.
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");
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
can 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.
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.
The item's name, e.g., "Men's Running Springblade Drive Shoes, US10".
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.
ISO-4217 currency code for the price.
Quantity of the item.
If the item has a Universal Product Code (UPC), provide it here.
If the item has a Stock-keeping Unit ID (SKU), provide it here.
If the item is a book with anInternational Standard Book Number (ISBN), provide it here.
The brand name of the item.
Name of the item's manufacturer.
The category this item is listed under in your business. e.g., "kitchen appliance", "menswear > pants".
The tags used to describe this item in your business. e.g., "funny", "halloween".
The color of the item.
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);
The $merchant_profile
field type contains information about the merchant or seller providing the goods or service.
The internal identifier for the merchant or seller providing the good or service.
The merchant category code follows the 4-digit ISO code. Use ISO-18245 MCC ISO Merchant Category Code.
The name of the merchant or seller providing the good or service.
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"));
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 $zipcode
in 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.
The customer’s internal identifier for the specific physical location providing the good or service.
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"));
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.
The general type of payment being used.
$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.
The specific gateway, company, product, etc. being used to process payment.
$abra
$acapture
$accpet_blue
$adyen
$aeropay
$afex
$affinipay
$affipay
$affirm
$afrivoucher
$afterpay
$airpay
$airwallex
$alipay
$alipay_hk
$allpago
$altapay
$amazon_payments
$ambank_fpx
$amex_checkout
$android_iap
$android_pay
$apg
$aplazo
$apple_iap
$apple_pay
$argus
$asiabill
$astropay
$atome
$atrium
$au_kantan
$authorizenet
$avangate
$balanced
$bancodobrasil
$bancontact
$bancoplural
$banorte
$banrisul
$banwire
$barclays
$bayanpay
$bbcn
$bcb
$beanstream
$belfius
$best_inc
$bexs
$billdesk
$billpocket
$bitcash
$bitgo
$bitpay
$bizum
$blackhawk
$blik
$blinc
$blockchain
$bluepay
$bluesnap
$bnpparibas
$boacompra
$bob
$boku
$bold
$boletobancario
$boltpay
$boost
$bosspay
$bpay
$bradesco
$braintree
$bread
$bridgepay
$brite
$buckaroo
$buckzy
$cadc
$cardconnect
$cardknox
$cashapp
$cashfree
$cashlesso
$cashlib
$catchball
$ccbill
$ccavenue
$ceevo
$cellulant
$cepbank
$chain_commerce
$chase_paymentech
$checkalt
$checkoutcom
$cielo
$circle
$citi
$citizen
$citrus_pay
$clear_junction
$clearbridge
$clearsettle
$clearcommerce
$cleverbridge
$close_brothers
$cloudpayments
$codi
$cofinoga
$coinbase
$coindirect
$coinpayments
$collector
$community_bank_transfer
$commweb
$compropago
$concardis
$conekta
$copo
$credit_union_atlantic
$credorax
$credsystem
$cross_river
$cuentadigital
$culqi
$cybersource
$cryptocapital
$cryptopay
$currencycloud
$customers_bank
$d_barai
$dana
$daopay
$datacash
$dbs_paylah
$dcbank
$decta
$debitway
$deltec
$democracy_engine
$deutsche_bank
$devonrex
$dibs
$digital_river
$digitalpay
$dinero_services
$directa24
$dlocal
$docomo
$doku
$dospara
$dotpay
$dragonpay
$dreftorpay
$dwarkesh
$dwolla
$ebanx
$ecommpay
$ecopayz
$edenred
$edgil_payway
$efecty
$eft
$elavon
$elipa
$emerchantpay
$empcorp
$enets
$epay
$epayeu
$epoch
$epospay
$eprocessing_network
$eps
$esitef
$etana
$euteller
$everypay
$eway
$e_xact
$fastnetwork
$fat_zebra
$fidor
$finix
$finmo
$fintola
$fiserv
$first_atlantic_commerce
$first_data
$flexepin
$flexiti
$fluidpay
$flutterwave
$fpx
$frick
$fxpaygate
$g2apay
$galileo
$gcash
$geepay
$geoswift
$getnet
$gigadat
$giropay
$globalcollect
$global_payments
$global_payways
$gmo
$gmopg
$gocardless
$gocoin
$google_pay
$google_wallet
$gopay
$grabpay
$hanmi
$happy_money
$hayhay
$hdfc_fssnet
$heidelpay
$hipay
$humm
$hyperpay
$i2c
$ibok
$ideal
$ifthenpay
$ikajo
$incomm
$incore
$ingenico
$inghomepay
$inovapay
$inovio
$instamojo
$interac
$internetsecure
$interswitch
$intuit_quickbooks_payments
$ipay
$ipay88
$isignthis
$itau
$itelebill
$iugu
$ixopay
$iyzico
$izettle
$jabong
$januar
$jatis
$jeton
$jnfx
$jpay
$juspay
$kakaopay
$kash
$kbc
$kddi
$kevin
$khipu
$klarna
$klicklpay
$knet
$komoju
$konbini
$kopay
$korapay
$kushki
$lapay
$latamgateway
$latampass
$laybuy
$lean
$lemonway
$letzpay
$lifemiles
$limelight
$linepay
$link4pay
$liquido
$logon
$mada
$mangopay
$mastercard_payment_gateway
$masterpass
$matera
$maxipago
$maxpay
$maybank
$mbway
$mcb
$meikopay
$mercadopago
$merchant_esolutions
$merpay
$mfs
$midtrans
$minerva
$mirjeh
$mobile_money
$mockpay
$modo
$moip
$mollie
$momopay
$moneris_solutions
$moneygram
$monoova
$moozimi
$moyasar
$mpesa
$muchbetter
$multibanco
$multicaja
$multiplus
$mvb
$mybank
$myfatoorah
$nanaco
$nanoplazo
$naranja
$naverpay
$neosurf
$net_cash
$netbilling
$netregistry
$neteller
$network_for_good
$nhn_kcp
$nicepay
$ngenius
$nmcryptgate
$nmi
$noble
$noon_payments
$nupay
$ocean
$ogone
$okpay
$omcp
$omise
$onebip
$oneio
$onerway
$onewallet
$opay
$openpay
$openpaymx
$optile
$optimal_payments
$ovo
$oxxo
$pacypay
$paddle
$pagar_me
$pago_efectivo
$pagoefectivo
$pagofacil
$pagseguro
$paidy
$papara
$paxum
$pay_garden
$pay_zone
$pay4fun
$paybright
$paycase
$paycash
$payco
$paycell
$paydo
$paydoo
$payease
$payeasy
$payeer
$payeezy
$payfast
$payfix
$payflow
$payfort
$paygarden
$paygate
$paygent
$pago24
$pagsmile
$pay2
$payaid
$payfun
$payix
$payjp
$payjunction
$paykun
$paykwik
$paylike
$paymaya
$paymee
$paymentez
$paymentos
$paymentwall
$payment_express
$paymill
$paynl
$payone
$payoneer
$payop
$paypal
$paypal_express
$paypay
$payper
$paypost
$paysafe
$paysafecard
$paysera
$paysimple
$payssion
$paystack
$paystation
$paystrax
$paytabs
$paytm
$paytrace
$paytrail
$paystrust
$paytrust
$payture
$payway
$payu
$payulatam
$payvalida
$payvector
$payza
$payzen
$peach_payments
pep
$perfect_money
$perla_terminals
$picpay
$pinpayments
$pivotal_payments
$pix
$plaid
$planet_payment
$plugandplay
$poli
$posconnect
$ppro
$primetrust
$princeton_payment_solutions
$prisma
$prismpay
$processing
$przelewy24
$psigate
$pubali_bank
$pulse
$pwmb
$qiwi
$qr_code_bt
$quadpay
$quaife
$quickpay
$quickstream
$quikipay
$rabbitlinepay
$raberil
$radial
$railsbank
$rakbank
$rakuten_checkout
$rapid_payments
$rapipago
$rappipay
$rapyd
$ratepay
$ravepay
$razorpay
$rbkmoney
$reach
$recurly
$red_dot_payment
$rede
$redpagos
$redsys
$revolut
$rewardspay
$rietumu
$ripple
$rocketgate
$safecharge
$safetypay
$safexpay
$sagepay
$saltedge
$samsung_pay
$santander
$sbi
$sbpayments
$secure_trading
$securepay
$securionpay
$sentbe
$sepa
$sermepa
$servipag
$sezzle
$shareit
$shopify_payments
$sightline
$signature
$signet
$silvergate
$simpaisa
$simplify_commerce
$skrill
$smart2pay
$smartcoin
$smartpayments
$smbc
$snapscan
$sofort
$softbank_matomete
$solanapay
$splash_payments
$splitit
$spotii
$sps_decidir
$square
$starkbank
$starpayment
$stcpay
$sticpay
$stitch
$stone
$stp
$stripe
$surepay
$swedbank
$synapsepay
$tabapay
$tabby
$tamara
$tapcompany
$tdcanada
$telerecargas
$tfm
$tink
$tipalti
$tnspay
$todopago
$toss
$touchngo
$towah
$tpaga
$transact_pro
$transactive
$transactworld
$transfirst
$transpay
$truelayer
$truemoney
$trust
$trustcommerce
$trustly
$trustpay
$tsys_sierra
$tsys_transit
$tu_compra
$twoc2p
$twocheckout
$undostres
$unlimint
$unionpay
$upay
$usa_epay
$usafill
$utrust
$vantiv
$vapulus
$venmo
$veritrans
$versapay
$verve
$vesta
$viabaloto
$vindicia
$vip_preferred
$virtual_card_services
$virtualpay
$visa
$vme
$vogogo
$volt
$vpos
$watchman
$web_money
$webbilling
$webmoney
$webpay
$webpay_oneclick
$wechat
$wepay
$western_union
$wirecard
$worldpay
$worldspan
$wompi
$wp_cnpapi
$wyre
$xendit
$xfers
$xipay
$yandex_money
$yapily
$yapstone
$zapper
$zenrise
$zer0pay
$zeus
$zgold
$zimpler
$zip
$zipmoney
$zoop
$zotapay
$zooz_paymentsos
$zuora
$2c2p
If the payment gateway you use is not supported, contact support and we'll add it.
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.
The last four digits of the credit card number.
Response code from the AVS address verification system. Used in payments involving credit cards.
Response code from the credit card company indicating if the CVV number entered matches the number on record. Used in payments involving credit cards.
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
.
This is the ABA routing number, BIC or SWIFT code used.
This is the first 6 characters of the IBAN structure as defined in ISO 13616-1.
This is the last 4 characters of the IBAN structure as defined in ISO 13616-1.
Use true
or false
to indicate if a end-user/customer has provided authorization to collect future payments via Sepa Direct Debit.
In case of a declined payment, response code received from the payment processor indicating the reason for the decline.
The value entered to identify the Wallet used for the payment.
The type of wallet used in the payment.
$crypto
$digital
$fiat
Payer ID returned by Paypal.
Payer email address returned by Paypal.
Payer status returned by Paypal.
Payer address status returned by Paypal.
Seller protection eligibility returned by Paypal.
Payment status returned by Paypal.
CVC verification result returned by Stripe.
Address line 1 verification result returned by Stripe.
Address line 2 verification result returned by Stripe.
Address zip code verification result returned by Stripe.
Funding source returned by Stripe.
Card brand returned by Stripe.
Full name of the user associated with the account. Use this field for payment types $electronic_fund_transfer
, $sepa_credit
, $sepa_instant_credit
, $sepa_debit
, $ach_credit
, $ach_debit
, $wire_credit
, and $wire_debit
.
The last 5 digits of the account number. Use this field for payment types $electronic_fund_transfer
, $sepa_credit
, $sepa_instant_credit
, $sepa_debit
, $ach_credit
, $ach_debit
, $wire_credit
, and $wire_debit
.
Name of the financial institution used for the transaction. Use this field for payment types $electronic_fund_transfer
, $sepa_credit
, $sepa_instant_credit
, $sepa_debit
, $ach_credit
, $ach_debit
, $wire_credit
, and $wire_debit
.
Two-digit ISO-3166 code for the bank country of origin. Use this field for payment types $electronic_fund_transfer
, $sepa_credit
, $sepa_instant_credit
, $sepa_debit
, $ach_credit
, $ach_debit
, $wire_credit
, and $wire_debit
.
// 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<PaymentMethod> 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") );
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").
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").
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.
$success
$failure
When adding a promotion fails, use this to describe why it failed.
$already_used
$invalid_code
$not_applicable
$expired
Freeform text to describe the promotion.
The unique account ID of the user who referred the user to this promotion. Note: User IDs are case sensitive.
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.
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"));
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:
Even if there’s only a single segment associated with the booking, use segment to send valuable information about the trip.
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.
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.
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.
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.
An identifier for the journey: this could be the flight number ("UA 454"), the car license plate number ("6XYZ123"), etc.
The IATA code for the departure airport. For example: "SFO"
The IATA code for the arrival airport. For example: "SEA"
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" : 1678062720000, "$end_time" : 1679062720000, "$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" : 1678062720000, "$end_time" : 1679062720000, "$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" => 1678062720000, "$end_time" => 1679062720000, "$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' => 1678062720000, '$end_time' => 1679062720000, '$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 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:
$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 _
.$api_key
field where you provide your REST API key.$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.
The following the suffixes should be used for custom fields when relevant:
_email
· StringSift performs a number of fraud detection algorithms on emails, including matching against throwaway email domains, and looking for similarity to known fraudsters in the past.
Send any other emails associated with the user in field names like secondary_email
.
_phone
· StringSift can perform lookups to identify country and region of phone numbers if the data is well formed. 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.
Send phone numbers in field names like secondary_phone
and mobile_phone
.
_lat
· FloatSent as a floating point number with at least two significant figures. Sift uses this data to calculate location and movement, which are particularly useful for businesses where location is an important part of the transaction and for mobile transactions. Typically used along with longitude.
Send latitudes in field names like dropoff_location_lat
.
_lng
· FloatSent as a floating point number with at least two significant figures. Sift uses this data to calculate location and movement, which are particularly useful for businesses where location is an important part of the transaction and for mobile transactions. Typically used along with latitude.
Send longitudes in field names like dropoff_location_lng
.
_id
· StringID of a user or other entity. Valid characters in IDs are alphanumeric characters (without space) and:
=
, .
, -
, _
, +
, @
, :
, &
, ^
,
%
, !
, $
.
Send IDs in field names like buyer_user_id
or store_id
.
_status
· StringStatus of an event.
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.
_title
, _desc
, _message
, _name
, · StringWhen users enter text in a form, send with one of the supported suffixes to take advantage of additional machine learning features.
Send user-entered text in field names like post_title
, job_desc
,
profile_message
, or user_name
.
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.
-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.
There is an ability to request a list of validation warnings in the API response
so that it can be automatically tracked.
They are not critical enough to reject the whole request, but important enough to be fixed.
To receive them in the response
the following param should be passed in the request: &fields=warnings
{ "status": 0, "error_message": "OK", ..., "warnings": { "count": 2, "items": [ { "message": "Required json fields not specified at $.$items[0].$currency_code" }, { "message": "Invalid field value at $.$items[0].$price" } ] } }
Anonymous events are events that do not have a $user_id
.
This can happen when a user visits a website for the first time,
when a customer user has not logged in, or during a guest checkout flow.
Anonymous events are not allowed to be scored synchronously because there is no user associated with the event. Anonymous event promotion is not supported for synchronous events.
When an anonymous event is sent to Sift we will try to fill in the $user_id
based on past
or future non-anonymous events. When we find an event that can promote the anonymous event to a
non-anonymous event then we promote this event asynchronously. When the event is promoted the event
is scored, workflows are not run on the event, and the event can be seen in the user’s activity log.
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.
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:
{ "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.
The Decisions APIs allow you to:
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.
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.
The source of this Decision.
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.
The time the Decision was applied, as a UNIX timestamp in milliseconds. This is only necessary to send for historical backfill.
A description of the Decision that will be applied.
curl -X POST 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 = 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);
curl -X POST 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 = 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);
$ curl -X POST 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 = client.apply_session_decision(user_id, session_id, applyDecisionRequest)
curl -X POST 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 = 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();
For successful requests, the response will have an
HTTP status code of
200
.
The entity object containing information on the entity on which the Decision was applied.
The id of the entity on which the Decision was applied.
Type of entity, (user or order), to which Decision was applied.
The Decision object containing information on the Decision that was applied.
The id of the Decision that was applied.
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" } }
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' \n-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()); } MapdecisionStatuses = 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:
{ "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 }, "bot_management": { "decision": { "id": "suspicious_bot_user" }, "time": 1677040435564, "webhook_succeeded": true } } }
A map of abuse types to the associated latest Decisions for the entity.
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.
The information associated with the latest Decision for a specific abuse type key (read above).
The Decision object containing information on the Decision taken.
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.
The time the Decision was applied, as a UNIX timestamp in milliseconds.
true
if the webhook was successfully sent, false
if the webhook failed
to send, null
if no webhook is configured.
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.
$ 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);
Return only decisions applicable to the specified entity_type
.
Return only decisions applicable to specified abuse_types.
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.
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
.
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" }
An array of decisions.
The id of the decision. This is auto generated when the Decision is created based on the initial display name of the Decision.
Display name of the decision.
A description of the Decision. This field is intended as a way to describe the business action(s) associated with the Decision.
Entity type to which this Decision is applicable.
Abuse type which this Decision describes.
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.
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.
Time at which the Decision was created, as a UNIX timestamp in milliseconds.
User who created decision.
Time at which the Decision was last updated, as a UNIX timestamp in milliseconds.
User who last updated the Decision.
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.
For paginated results, next_ref
contains a URL where the next set of results can
be retrieved
Take advantage of webhook authentication to ensure that the request you receive is coming from Sift.
Notes:
Switch to one of the programming language tabs for the specific language implementation of webhook signature verification.
import json from hashlib import sha256 import hmac from flask import request SIFT_WEBHOOK_SECRET_KEY = "#####" @app.route("/webhook") def webhook(): # Let's check whether this webhook actually came from Sift! # First let's grab the signature from the postback's headers postback_signature = request.get("X-Sift-Science-Signature") # Next, let's try to assemble the signature on our side to verify postback_body = json.dumps(request.json) h = hmac.new(SIFT_WEBHOOK_SECRET_KEY, postback_body, sha256) verification_signature = "sha256={}".format(h.hexdigest()) if verification_signature == postback_signature: process_webhook() else: raise SomeException()
require 'json' require 'openssl' require 'sinatra' SIFT_WEBHOOK_SECRET_KEY = "#####" post '/webhook' do # Let's check whether this webhook actually came from Sift! # First let's grab the signature from the postback's headers postback_signature = request.env['X-Sift-Science-Signature'] # Next, let's try to assemble the signature on our side to verify digest = OpenSSL::Digest.new('sha256') calculated_hmac = OpenSSL::HMAC.hexdigest(digest, SIFT_WEBHOOK_SECRET_KEY, request.body) verification_signature = "sha256=#{calculated_hmac}" if verification_signature == postback_signature puts "success" else raise Exception end end
SIFT_WEBHOOK_SECRET_KEY = "#####"; BLOCK_ACTION = 'block'; #name of the Action you set up in the console # Let's check whether this webhook actually came from Sift! # First let's grab the signature from the postback's headers $webhookSignature = $headers['X-Sift-Science-Signature']; # Next, let's try to assemble the signature on our side to verify $verificationSignature = "sha256=" . hash_hmac('sha256', $requestBody, $SIFT_WEBHOOK_SECRET_KEY); if ($webhookSignature == $verificationSignature) { $siftRequest = json_decode($requestBody); if ($siftRequest->action->id == BLOCK_ACTION) { ... } }
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 = "sha256=" + HmacUtils.hmacSha256Hex( SIFT_WEBHOOK_SECRET_KEY.getBytes(), requestBody); if (!webhookSignature.equals(verificationSignature)) { // Handle unauthenticated webhook }
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:
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.force_workflow_run=true
parameter to ensure that the workflow executes asynchronously. 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.
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.
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.
Set to true
to get the route information from the Workflow Decision. This parameter must be used with the return_workflow_status
query parameter.
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.
Get score percentiles back when sending an event. If you are using client libraries, please refer to the corresponding code snippet for the correct query parameter value.
curl -X POST "https://api.sift.com/v205/events?return_workflow_status=true&return_route_info&abuse_types=legacy&fields=score_percentiles"" -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, return_route_info=True, abuse_types=['promo_abuse', 'content_abuse', 'payment_abuse'], include_score_percentiles=True)
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, :return_route_info => True, :abuse_types => ['promo_abuse', 'payment_abuse'], :include_score_percentiles => true)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'YOUR_API_KEY')); $properties = array( '$user_id' => 'sample_user51', '$user_email' => 'sample_user@gmail.com' ); $opts = array( 'return_workflow_status' => True, 'return_route_info' => True, 'abuse_types' => array( 'promo_abuse', 'payment_abuse' ), 'include_score_percentiles' => true )); $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() .withRouteInfo() .withScores("promo_abuse", "payment_abuse") .withScorePercentiles(); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; }
Success or Error Code of the event ingestion.
The event you sent
Time event was processed
Success or Error Code of the re-score.
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.
The run ID of this specific Workflow run. Pass to the Workflow Status API to view the latest Workflow Status for this ID.
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.
Details about the Workflow ID and version.
The static, unique identifier ID of the Workflow
The version of this Workflow. This updates each time the Workflow logic is updated
The Workflow's current display name
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
.
Information about the entity that this Workflow is Deciding on.
The type of entity on which the Decision was taken. Possible Values are user
,
order
, content
, or session
The unique identifier of the entity on which the Decision was taken.
A list of apps/stages that have occurred in the Workflow 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.
The display name of the app which was run.
The state of this app. Options are either running
, finished
, or failed
.
The configuration information of the app.
The unique identifier of the Decision taken in this app. This will only be returned if the app is a decision app.
A list of Decision buttons currently configured in the Review Queue.
The unique Decision ID for this button.
The display name for this button.
The route information of the app.
The display name of the route.
{ "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, "percentiles": { "last_1_day": 0.98456721, "last_5_days": 0.97544325, "last_7_days": 0.97515456, "last_10_days":0.96773876 }, "reasons": [ { "name": "UsersPerDevice", "value": 4, "details": { "users": "a, b, c, d" } } ] }, "promotion_abuse": { "score": 0.472838192111, "percentiles": { "last_1_day": 0.42744325, "last_5_days": 0.41545672, "last_7_days": 0.41773876, "last_10_days":0.40515456 }, "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": "user_scorer", "name": "Entity", "state": "finished" }, { "app": "event_processor", "name": "Event", "state": "finished" } ], "route": { "name": "route 1" } } ] } } }
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.
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.
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.
Get score percentiles back when sending an event. If you are using client libraries, please refer to the corresponding code snippet for the correct query parameter value.
curl -X POST "https://api.sift.com/v205/events?return_workflow_status=true&abuse_types=legacy&fields=score_percentiles" -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'], include_score_percentiles=True)
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'], :include_score_percentiles => true)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => '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' ), 'include_score_percentiles' => true )); $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") .withScorePercentiles(); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; }
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.
curl -XGET https://api.sift.com/v3/accounts/{accountId}/workflows/runs/{workflow_run_id} -H "Accept: application/json" \n-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"
The run ID of this Workflow, identifying this specific instance of the Workflow.
The state of this Workflow instance.
An object containing the configuration information for this Workflow.
The configuration ID of the Workflow. This is the unique identifier of this Workflow, but not this Workflow instance.
The version of this Workflow.
The display name given to this Workflow in the Workflow editor.
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
.
Information about the entity that this Workflow is Deciding on.
The type of entity on which the Decision was taken. Possible Values are user
,
order
, content
, or session
The unique identifier of the entity on which the Decision was taken.
A list of apps objects that have occurred in the Workflow run. You can think of these as Workflow stages.
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.
The app display name.
The state of this app. The possible values are running
, finished
, or failed
The configuration information of the app.
The unique identifier of the Decision taken in this app.
This field only exists if the app type is decision
.
A list of button objects associated with the review queue
.
The unique Decision ID for this button.
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", } ] }
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:
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:
Whenever you send an event, you can receive a Sift Score back synchronously in the response back from the API. This is particularly useful for when you are sending an event that maps to a key decision point for your business. Typically, customers find it most useful to get scores back after creating an account, order, content, or adding a promotion, but you can get scores back after passing any of the events we support.
For events that you don't plan on using the score, it’s best that you don’t ask for the score as it will add some latency to the request.
To get scores back when sending an event, just append the query parameter return_score=true
to your API request.
You can also request scores for specific abuse types using the abuse_types
query parameter.
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.
To get score percentiles back when sending an event, just append the query parameter fields=score_percentiles
to your API request.
If you are using client libraries, please refer to the corresponding code snippet for the correct query parameter value.
curl -X POST "https://api.sift.com/v205/events?return_score=true&abuse_types=payment_abuse,promotion_abuse&fields=score_percentiles" -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, include_score_percentiles=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, :include_score_percentiles => 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, 'include_score_percentiles' => 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") .withScorePercentiles(); EventResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; }
The success or error code (see relevant error codes below).
Description of status code.
The content of the event you sent.
The time the request was processed, in seconds since epoch.
The requested scoring information for the given user.
The success or error code (see relevant error codes below).
Description of error if applicable.
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 for the user between 0.0 and 1.0. A score of 0.5 translates to a score a 50 in the console.
The percentiles
map contains all computed score percentiles for all applicable time periods
across which the percentiles are computed. The map is keyed by time window, which could be one of:
last_1_day
, last_5_days
, last_7_days
, last_10_days
. The values in this map
are floats representing the score percentile.
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 of the risk signal.
Value of the risk signal.
Additional details. Provided only when relevant. E.g., may contain a details
field
which contains the IDs of related users.
The id of the user, matching what was passed in the Score API call.
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:
true
if the user is labeled Fraud, false
if the user is labeled Not Fraud.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, "percentiles": { "last_1_day": 0.98456721, "last_5_days": 0.97544325, "last_7_days": 0.97515456, "last_10_days":0.96773876 }, "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) # get payment abuse score percentile for 7 days time window. payment_abuse_score_percentiles = round((response.body['scores']['payment_abuse']['percentiles']['last_7_days'] * 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) # get payment abuse score percentile for 7 days time window. payment_abuse_score_percentiles = (response.body['scores']['payment_abuse']['percentiles']['last_7_days'] * 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); # To grab the payment_abuse score percentiles for 7 days time window: $siftScorePercentiles = round(($response->body['scores']['payment_abuse']['percentiles']['last_7_days'] * 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 Sift Score Percentiles map for a specific abuse type Map<String,Double> percentiles = response.getBody().getScoreResponse().getScores().get("payment_abuse").getPercentiles(); // get reasons for a Sift Score List<Reason> reasons = response.getReasons("payment_abuse");
-4
Service currently unavailable. Please try again later.
-3
Server-side timeout processing request. Please try again later.
-2
Unexpected server-side error
-1
Unexpected server-side error
0
OK
51
Invalid API key
54
60
Rate limited; too many events have been received in a short period of time
Note: This API is deprecated. To get scores without sending an event, we recommend using the Get Scores API.
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:
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.
$user_id
values we've received Events
API events or JavaScript activity for.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; }
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);
The success or error code (see relevant error codes below).
Description of error if applicable.
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 for the user between 0.0 and 1.0. A score of 0.5 translates to a score a 50 in the console.
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 of the risk signal.
Value of the risk signal.
Additional details. Provided only when relevant. E.g., may contain a details
field
which contains the IDs of related users.
The id of the user, matching what was passed in the Score API call.
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:
true
if the user is labeled Fraud, false
if the user is labeled Not Fraud.
The time this label was applied to the user. It is a UNIX timestamp in seconds.
Freeform text description of the user and/or incident triggering the label.
-4
Service currently unavailable. Please try again later.
-3
Server-side timeout processing request. Please try again later.
-2
Unexpected server-side error
-1
Unexpected server-side error
0
OK
51
Invalid API key
54
60
Rate limited; too many events have been received in a short period of time
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:
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.
Request scores for a user and abuse types using the (optional) abuse_types
query parameter.
Include scores percentiles by adding the (optional) fields=score_percentiles
query parameter.
curl -XGET https://api.sift.com/v205/users/{UserId}/score?api_key={apiKey}&abuse_types=payment_abuse,promotion_abuse&fields=score_percentiles
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"], include_score_percentiles=True)
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"], :include_score_percentiles => true)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php'; require 'sift-php/lib/SiftRequest.php'; require 'sift-php/lib/SiftResponse.php'; require 'sift-php/lib/SiftClient.php'; require 'sift-php/lib/Sift.php'; $client = new SiftClient(array('api_key' => 'REST_API_KEY_HERE')); $response = $client->get_user_score('USER_ID_HERE', array('abuse_types' => array('payment_abuse', 'promotion_abuse')), 'include_score_percentiles' => true);
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"))) .withScorePercentiles(); EntityScoreResponse response; try { response = request.send(); } catch (SiftException e) { System.out.println(e.getApiErrorMessage()); return; }
The success or error code (see relevant error codes below).
Description of error if applicable.
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 for the user between 0.0 and 1.0. A score of 0.5 translates to a score a 50 in the console.
The time at which the score was generated, as a UNIX timestamp.
The percentiles
map contains all computed score percentiles for all applicable time periods
across which the percentiles are computed. The map is keyed by time window, which could be one of:
last_1_days
, last_5_days
, last_7_days
, last_10_days
. The values in this map
are floats representing the score percentile.
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 of the risk signal.
Value of the risk signal.
Additional details. Provided only when relevant. E.g., may contain a details
field
which contains the IDs of related users.
What type of entity is the score in reference to. This defaults to user
.
The id
for which the score was requested.
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:
The id
of the Decision that was applied.
One of the following: BLOCK
, WATCH
, ACCEPT
The source of this Decision. One of the following: AUTOMATED_RULE
, MANUAL_REVIEW
,
CHARGEBACK
The time the Decision was applied, as a UNIX timestamp.
The description of the Decision, if available.
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:
true
if the user is labeled Fraud, false
if the user is labeled Not Fraud.{ "status": 0, "error_message": "OK", "user_id": "billy_jones_301", "scores": { "payment_abuse": { "status": 0, "error_message": "OK", "score": 0.898391231245, "time": 84710383103092309, "percentiles": { "last_1_day": 0.98456721, "last_5_days": 0.97544325, "last_7_days": 0.97515456, "last_10_days":0.96773876 }, "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) # get payment abuse score percentile for 7 days time window. payment_abuse_score_percentiles = round((response.body['scores']['payment_abuse']['percentiles']['last_7_days'] * 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) # get payment abuse score percentile for 7 days time window. payment_abuse_score_percentiles = (response.body['scores']['payment_abuse']['percentiles']['last_7_days'] * 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); # To grab the payment_abuse score percentiles for 7 days time window: $siftScorePercentiles = round(($response->body['scores']['payment_abuse']['percentiles']['last_7_days'] * 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); // get Sift Score Percentiles map for a specific abuse type Map<String,Double> percentiles = response.getBody().getScoreResponse().getScores().get("payment_abuse").getPercentiles();
-4
Service currently unavailable. Please try again later.
-3
Server-side timeout processing request. Please try again later.
-2
Unexpected server-side error
-1
Unexpected server-side error
0
OK
51
Invalid API key
54
60
Rate limited; too many events have been received in a short period of time
64
Specified user does not have a previously computed score.
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.
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; }
The success or error code (see relevant error codes below).
Description of error if applicable.
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 for the user between 0.0 and 1.0. A score of 0.5 translates to a score a 50 in the console.
The time at which the score was generated, as a UNIX timestamp.
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 of the risk signal.
Value of the risk signal.
Additional details. Provided only when relevant. E.g., may contain a details
field
which contains the IDs of related users.
What type of entity is the score in reference to. This defaults to user
.
The id
for which the score was requested.
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:
The id
of the Decision that was applied.
One of the following: BLOCK
, WATCH
, ACCEPT
The source of this Decision. One of the following: AUTOMATED_RULE
, MANUAL_REVIEW
,
CHARGEBACK
The time the Decision was applied, as a UNIX timestamp.
The description of the Decision, if available.
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:
true
if the user is labeled Fraud, false
if the user is labeled Not Fraud.{ "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);
-4
Service currently unavailable. Please try again later.
-3
Server-side timeout processing request. Please try again later.
-2
Unexpected server-side error
-1
Unexpected server-side error
0
OK
51
Invalid API key
54
60
Rate limited; too many events have been received in a short period of time
64
Specified user does not have a previously computed score.
100
111
112
Sift's two-factor authentication solution enables triggering one-time passcodes 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 2FA sms/email templates and generating CNAMEs to update your DNS records so we can send emails on your behalf.
This service is intended to be used to send OTPs to email addresses and/or phone numbers that have already been validated as real and able to be accessed by the account owners. This service is not designed to validate the ability to deliver messages to a phone number or email address.
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:
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 + ":")
User ID of user being verified, e.g. johndoe123.
The code the user sent to the customer for validation.
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
.
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" }'
The success or error code (see relevant error codes below).
Human readable description of the error.
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 }
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, verification type).
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 + ":")
User ID of user being verified, e.g. johndoe123.
$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
.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" }'
The success or error code (see relevant error codes below).
Human readable description of the error.
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 }
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 + ":")
User ID of user being verified, e.g. johndoe123
The phone number or email address to send the OTP to.
The value in this field must match verification_type. If this field contains a phone number, it should be in E.164 format including+
and a country code.The session being verified. See $verification in the Sift Events API documentation.
The channel used for verification. Should be either $email
or $sms
.
The ID of the entity impacted by the event being verified.
The type of the reserved event being verified.
Name of the brand of product or service the user interacts with.
Country of the content of the site.
Language the application content is being delivered in.
Language of the content of the web site.
The user’s IP address
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.
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.
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" } } }'
The success or error code (see relevant error codes below).
Human readable description of the error.
The time the OTP was sent, as a UNIX timestamp in milliseconds.
{ "status": 0, "error_message": "OK", "sent_at": 1566324368002, "segment_id": "4", "segment_name": "Default template", "brand_name": "", "site_country": "", "content_language": "" }
{ "status": 0, "error_message": "OK", "sent_at": 1566324368002, "segment_id": "4", "segment_name": "Default template", "brand_name": "", "site_country": "", "content_language": "" }
{ "status": 0, "error_message": "OK", "sent_at": 1566324368002, "segment_id": "4", "segment_name": "Default template", "brand_name": "", "site_country": "", "content_language": "" }
{ "status": 0, "error_message": "OK", "sent_at": 1566324368002, "segment_id": "4", "segment_name": "Default template", "brand_name": "", "site_country": "", "content_language": "" }
{ "status": 0, "error_message": "OK", "sent_at": 1566324368002, "segment_id": "4", "segment_name": "Default template", "brand_name": "", "site_country": "", "content_language": "" }
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.
You can use the data returned from this endpoint to help investigate suspicious devices. Data like the first time you've seen a device in addition to how the Sift network has labeled a device can help you determine whether to allow a user to continue interacting with your site.
Example Request
$ curl -XGET 'https://api.sift.com/v3/accounts/{id}/devices/{id}' \n -H 'Content-Type: application/json' \n -u {API_KEY}:
Example Response
{ "id" : "{id}", "label" : "fraud", "labeled_at" : 1241241214000, "first_seen" : 1412990802000, "users" : { "data" : [ { "id" : "bob123", "href" : "https://api.sift.com/v3/accounts/{id}/users/bob123" } ] }, "network" : { "first_seen" : 1412386033000, "score" : 0.8 }, "sessions" : { "has_more" : false, "total_results" : 1, "data" : [ { "time" : 1412990802000 } ] } }
Your Sift Account ID, which can be found in the Sift Console under the Developer Tab
A device fingerprint is an identifier that represents a device.
A device fingerprint is an identifier that represents a device.
The time (represented as POSIX time in milliseconds) when Sift first identified this device on your site
A list of references to external entities that this object is associated with
The list of data elements
id of the referenced resource
True if there are more data elements available
A link to the next set of data elements, if available
The total number of results, if known
A list of sessions in which this device has been seen
A list of data related to sessions in which this device has been seen
The time at which this Session ID was first set in the Sift JavaScript snippet.
True if there are more sessions available
A link to the next set of sessions, if available
The total number of results, if known
The label applied to this device. If no label has been applied, this field is undefined
The time at which the latest label was applied to this device. If no label has been applied, this field is null
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.
The time (represented as POSIX time in milliseconds) when Sift first identified this device within our network of customers.
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.
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'.
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/{id}/devices/{id}/label' \n -H 'Content-Type: application/json' \n -u {API_KEY}: \n -d '{ "label" : "fraud" }'
Example Response
{ "label" : "fraud" }
Your Sift Account ID, which can be found in the Sift Console under the Developer Tab
A device fingerprint is an identifier that represents a device.
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/{id}/sessions/465733823' \n -H 'Content-Type: application/json' \n -u {API_KEY}:
Example Response
{ "id" : 465733823, "time" : 1412990802000, "device" : { "id" : "{id}", "label" : "fraud", "labeled_at" : 1241241214000, "first_seen" : 1412990802000, "network" : { "first_seen" : 1412386033000, "score" : 0.8 }, "sessions" : { "total_results" : 1, "has_more" : false, "data" : [ { "time" : 1412990802000 } ] } } }
Your Sift Account ID, which can be found in the Sift Console under the Developer Tab
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.
The time at which this Session ID was first set in the Sift JavaScript snippet.
Data related to a Device Fingerprint
A device fingerprint is an identifier that represents a device.
The time (represented as POSIX time in milliseconds) when Sift first identified this device on your site
A list of references to external entities that this object is associated with
The list of data elements
id of the referenced resource
True if there are more data elements available
A link to the next set of data elements, if available
The total number of results, if known
A list of sessions in which this device has been seen
A list of data related to sessions in which this device has been seen
The time at which this Session ID was first set in the Sift JavaScript snippet.
True if there are more sessions available
A link to the next set of sessions, if available
The total number of results, if known
The label applied to this device. If no label has been applied, this field is undefined
The time at which the latest label was applied to this device. If no label has been applied, this field is null
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.
The time (represented as POSIX time in milliseconds) when Sift first identified this device within our network of customers.
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.
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'.
Call this endpoint to determine the devices associated for a given user_id
Example Request
$ curl -XGET 'https://api.sift.com/v3/accounts/{id}/users/465733823/devices' \n -H 'Content-Type: application/json' \n -u {API_KEY}:
Example Response
{ "data" : [ { "id" : "{id}", "href" : "https://api.sift.com/v3/accounts/{id}/devices/{id}" }, { "id" : "{id}", "href" : "https://api.sift.com/v3/accounts/{id}/devices/{id}" } ] }
Your Sift Account ID, which can be found in the Sift Console under the Developer Tab
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.
Reference to the json schema that the data in the array conforms to
A list of data items
id of the referenced resource
Whether there are more results
A link to the next set of data, if available
The total number of results, if known
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.
We have written client libraries in several languages to make using this API even easier.
Partners can:
Before using the Partner API, please contact our partner support team and ask to be enabled as a partner.
The operations below will require two credentialing pieces of information:
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".
All authentication is based on API keys.
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 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.
The Labels API is not recommended for customers signing up after February 1st, 2017.
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.
Note: you can find the documentation for the previous version of this API here.
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 \n'{ "$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" : "{ "$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" }" , "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
Your Sift API key.
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.
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.
Freeform text description of the user and/or incident triggering the label. Useful as annotation on why the label was added.
String describing the original source of the label information (e.g. payment gateway, manual review, etc.).
Unique identifier (e.g. email address) of the analyst who applied the label. Useful for tracking purposes after the fact.
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
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.
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.
Creates a new webhook with a specified URL.
The type of payload.
The status of the webhook.
The URL of the webhook endpoint. This must be HTTPS.
The list of events to enable for this endpoint. These correspond to our Reserved Events in our Events API.
An optional name you specify for this webhook
An optional description about what the webhook is used for.
curl -X POST https://api.sift.com/v3/accounts/{accountId}/webhooks \n-H 'Content-Type: application/json' \n-u {YOUR_API_KEY}: \n-d \n '{ "payload_type": "ORDER_V1_0", "status": "draft", "url": "https://example.com/", "enabled_events": ["$create_order"], "name": "My webhook name", "description": "This is a webhook!" }'
The id of the webhook.
The time at which the webhook was created as a UNIX timestamp.
The time at which the webhook endpoint was last updated as a UNIX timestamp.
The specified name of the webhook.
The specified description of the webhook
The type of payload.
The list of events to enable for this endpoint. These correspond to our Reserved Events in our Events API.
The status of the webhook.
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/" }
Retrieves a webhook when given an ID.
No arguments.
curl -X GET https://api.sift.com/v3/accounts/{accountId}/webhooks/{id} \n -H 'Content-Type: application/json' \n -u {YOUR_API_KEY}:
The id of the webhook.
The time at which the webhook was created as a UNIX timestamp.
The time at which the webhook endpoint was last updated as a UNIX timestamp.
The specified name of the webhook.
The specified description of the webhook
The type of payload.
The list of events to enable for this endpoint. These correspond to our Reserved Events in our Events API.
The status of the webhook.
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/" }
Returns a list of all webhooks.
No arguments.
curl -X GET https://api.sift.com/v3/accounts/{accountId}/webhooks \n -H 'Content-Type: application/json' \n -u {YOUR_API_KEY}:
A list of all webhooks.
The id of the webhook.
The time at which the webhook was created as a UNIX timestamp.
The time at which the webhook endpoint was last updated as a UNIX timestamp.
The specified name of the webhook.
The specified description of the webhook
The type of payload.
The list of events to enable for this endpoint. These correspond to our Reserved Events in our Events API.
The status of the webhook.
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 }
Updates a webhook when given an ID. This will overwrite the entire existing webhook object.
The type of payload.
The status of the webhook.
The URL of the webhook endpoint. This must be HTTPS.
The list of events to enable for this endpoint. These correspond to our Reserved Events in our Events API.
An optional name you specify for this webhook
An optional description about what the webhook is used for.
curl -X PUT https://api.sift.com/v3/accounts/{accountId}/webhooks/{id} \n-H 'Content-Type: application/json' \n-u {YOUR_API_KEY}: \n-d \n '{ "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!" }'
The id of the webhook.
The time at which the webhook was created as a UNIX timestamp.
The time at which the webhook endpoint was last updated as a UNIX timestamp.
The specified name of the webhook.
The specified description of the webhook
The type of payload.
The list of events to enable for this endpoint. These correspond to our Reserved Events in our Events API.
The status of the webhook.
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" }
Deletes a webhook when given an ID.
No arguments.
curl -X DELETE https://api.sift.com/v3/accounts/{accountId}/webhooks/{id} -u {YOUR_API_KEY}:
Response will contain no content and have an HTTP status of 204.
The order's Sift Account ID, which can be found in the Sift Console under the Developer Tab.
Provided triggered via webhook, indicates the triggering webhook event. One of $create_order
, $update_order
, $order_status
, $transaction
, or $update_order
.
The UNIX timestamp in milliseconds at which the order was created.
The UNIX timestamp in milliseconds at which the order was last updated.
The ID for tracking this order in your system.
The user's account ID according to your systems. Note that user IDs are case sensitive.
Email of the user who has created this order.
The ip address of the user that created the order.
Indicates the state of the order. One of $approved, $canceled, $held, $fulfilled, or $returned.
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
ISO-4217 currency code for the amount.
The payment information associated with the order. Contains the following attributes:
The general type of payment being used.
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.
The last four digits of the credit card number.
The specific gateway, company, product, etc. being used to process payment.
Response code from the AVS address verification system. Used in payments involving credit cards.
Response code from the credit card company indicating if the CVV number matches the number on the record. Used in payments involving credit cards.
The billing address entered by the user. See Address.
The details about the specific location providing the good or service. This can be used to capture pickup, delivery locations, etc. See Ordered From.
The shipping address entered by the user. See Address.
Whether the user requested priority/expedited shipping on their order
Indicates the method of delivery to the user.
Shipping carrier for the shipment of the product.
Shipping tracking number of the product
Shipping tracking number(s) for the shipment of the product(s).
The list of items ordered. Each item contains:
The item’s unique identifier.
The item’s name.
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.
ISO-4217 currency code for the price.
The list of bookings made. This may include tickets and reservations like flights, hotels, rideshares etc.
Note: can be used in conjunction with $items
.
The list of transactions associated with the order. Each transaction contains:
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.
The type of transaction being recorded. One of sale, authorize, capture, void, refund, deposit, withdrawal, or transfer.
The UNIX timestamp in milliseconds at which the transaction occurred.
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.
ISO-4217 currency code for the amount.
The list of chargebacks associated with the order. Each chargeback contains:
The transaction_id that this chargeback is linked to.
The UNIX timestamp in milliseconds at which the transaction occurred.
The current state of the chargeback.
The reason for why the chargeback occurred. One of fraud, duplicate, product_not_received, product_unacceptable, other.
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:
The ID of the decision. This is derived from the decision name in the Console.
The type of the decision taken on the entity. One of Red, Yellow, or Green
The UNIX timestamp of when the decision was made.
A description of the decision.
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 of the user between 0.0 and 1.0. A score of 0.5 translates to a score of 50 in the console.
The time at which the score was generated, as a UNIX timestamp.
Percentile score indicates the proportion of scores that fall below a particular value in a given set of data over a certain time interval.
Country the company is providing service from.
Domain being interfaced with.
The details about the merchant or seller providing the goods or service. Note: The merchant profile fields will have the '$' prefix removed in the response. See Merchant Profile.
The custom fields map contains the custom fields of an order.
The billing address of the order. See Address.
The UNIX timestamp in milliseconds of when the order was inserted into the database.
{ "account_id": "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, "percentiles": { "last_1_day": 0.95839123124, "last_7_days": 0.95839123124, } } }, "site_domain": "sift.com", "site_country": "US", "merchant_profile": { "merchant_id": "12345", "merchant_category_code": "5000", "merchant_name": "merchant_name", "merchant_address": { "name": "Alexander Frizler", "address_1": "Spitzwegstr. 17", "city": "Kuenzelsau", "country": "DE", "zipcode": "74653", "phone": "+4915152362576" } }, "custom_fields": { "custom_field_key_1": "custom_field_value_1", "custom_field_key_2": "custom_field_value_2" }, "billing_address": { "name": "Jake Joseph", "address_1": "1111 Oak St", "address_2": "Unit 111", "city": "New Orleans", "region": "Louisiana", "country": "US", "zipcode": "03254" }, "inserted_time": 1721221149000 // Jul 17 2024 12:59:09 UTC }
The PSP Merchants API allows payment service providers to create a summary of their merchant portfolio in the Sift console. The API is an automated way to onboard, off-board merchants providing fraud teams with a quick and easy way to view a summary of all merchants. A PSP can use this API to create a record of key metadata related to the merchant including MCC, Location, or an internal risk level.
On-board a PSP merchant summary to Sift Platform.
Every PSP merchant has to have a unique {id}
.
Be sure to replace ${accountId}
with your Sift account ID, found on the
Profile Tab on the Console. Lastly, replace
${YOUR_API_KEY}
with your REST API key, found in the
API Keys tab of the Developer
page in the Console.
The Account ID of your organisation.
The unique ID of the PSP merchant for search
The merchant object payload. See PSP Merchant Object.
merchantObject='{ "id": "cf51f0ec-6078-46e9-a796-700af25e668c", "name": "Watson and Holmes", "description": "An example of a PSP Merchant. Illustrative.", "address": { "name": "Dr Watson", "address_1": "221B, Baker street", "address_2": "apt., 1", "city": "London", "region": "London", "country": "GB", "zipcode": "00001", "phone": "0122334455" }, "category": "1002", "service_level": "Platinum", "status": "active", "risk_profile": { "level": "low", "score": 10 } }' # Create a merchant curl -X POST https://api.sift.com/v3/accounts/${accountId}/psp_management/merchants -H 'Content-Type: application/json' -u ${YOUR_API_KEY}: -d ${merchantObject}
Update a merchant summary to reflect changes in the status or service level or address etc.
Be sure to replace ${accountId}
with your Sift account ID, found on the
Profile Tab on the Console. Lastly, replace
${YOUR_API_KEY}
with your REST API key, found in the
API Keys tab of the Developer
page in the Console.
The Account ID of your organisation.
The unique ID of the PSP merchant for search
The merchant object payload. See PSP Merchant Object.
merchantObject='{ "id": "cf51f0ec-6078-46e9-a796-700af25e668c", `"name": "Watson and Holmes", "description": "An example of a PSP Merchant. Illustrative.", "address": { "name": "Dr Watson", "address_1": "221B, Baker street", "address_2": "apt., 1", "city": "London", "region": "London", "country": "GB", "zipcode": "00001", "phone": "0122334455" }, "category": "1002", "service_level": "Platinum", "status": "active", "risk_profile": { "level": "low", "score": 10 } }' # Update a merchant curl -X PUT https://api.sift.com/v3/accounts/${accountId}/psp_management/merchants/${merchantId} -H 'Content-Type: application/json' -u ${YOUR_API_KEY}: -d ${merchantObject}
Browse existing PSP merchant summaries.
Obtain the latest PSP Merchant metadata by {id}
.
Be sure to replace ${accountId}
with your Sift account ID, found on the
Profile Tab on the Console. Lastly, replace
${YOUR_API_KEY}
with your REST API key, found in the
API Keys tab of the Developer
page in the Console.
Batch or page size of the paginated sequence.
Batch or page position of the paginated sequence.
The Account ID of your organisation.
The unique ID of the PSP merchant for search
# Get a merchant array curl -XGET https://api.sift.com/v3/accounts/${accountId}/psp_management/merchants -H 'Content-Type: application/json' -u ${YOUR_API_KEY}: # Get a merchant array paginated curl -XGET https://api.sift.com/v3/accounts/${accountId}/psp_management/merchants?batch_size=${batchSize}&batch_token=${batchToken} -H 'Content-Type: application/json' -u ${YOUR_API_KEY}: # Get a specific merchant by id curl -XGET https://api.sift.com/v3/accounts/${accountId}/psp_management/merchants/${merchantId} -H 'Content-Type: application/json' -u ${YOUR_API_KEY}:
A reference to the next batch of merchants to iterate. For pagination.
Indicates if this PSP merchants batch is the last one. For pagination.
A schema name of the data items.
An array of Merchants in the current response batch. See PSP Merchant Object item.
{ "has_more": false, "next_ref": "-" "schema": "psp_merchant.json", "data": [ { "id": "cf51f0ec-6078-46e9-a796-700af25e668c", "name": "Watson and Holmes", "description": "An example of a PSP Merchant. Illustrative.", "created_at": 1663162925457, "created_by": "hhdkka888rKKc", "last_updated_at": 1663162982915, "last_updated_by": "jkdjnueu7e7", "address": { "name": "Dr Watson", "address_1": "221B, Baker street", "address_2": "apt., 1", "city": "London", "region": "London", "country": "GB", "zipcode": "00001", "phone": "0122334455" }, "category": "1002", "service_level": "Platinum", "status": "active", "risk_profile": { "level": "low", "score": 10 } } ] }
A successful response will contain a PSP Merchant Object item.
{ "id": "cf51f0ec-6078-46e9-a796-700af25e668c", "name": "Watson and Holmes", "description": "An example of a PSP Merchant. Illustrative.", "created_at": 1663162925457, "created_by": "hhdkka888rKKc", "last_updated_at": 1663162982915, "last_updated_by": "jkdjnueu7e7", "address": { "name": "Dr Watson", "address_1": "221B, Baker street", "address_2": "apt., 1", "city": "London", "region": "London", "country": "GB", "zipcode": "00001", "phone": "0122334455" }, "category": "1002", "service_level": "Platinum", "status": "active", "risk_profile": { "level": "low", "score": 10 } }
A unique PSP merchant identifier.
A PSP merchant name.
A PSP merchant description.
A merchants category code or ISO-18245 Merchant Category Code.
A merchants service level as defined by the PSP if they offer a variety of services.
The time the PSP merchant was created, as a UNIX timestamp in milliseconds.
The unique identifier of the creater agent.
The unique identifier of the updater agent.
The time the PSP merchant was changed, as a UNIX timestamp in milliseconds.
The status of the PSP merchant.
The risk profile of the merchant as defined by the PSP during the on-boarding. This can be an internal score or level.
The risk score interpretation from lowest 0 to highest 100.
The risk level name.
Postal address of the PSP merchant.
Address name
Address line 1.
Address line 2.
Address city.
Address region.
Address country.
Address zipcode.
Phone number.
{ "id": "cf51f0ec-6078-46e9-a796-700af25e668c", "name": "Watson and Holmes", "description": "An example of a PSP Merchant. Illustrative.", "created_at": 1663162925457, "created_by": "hhdkka888rKKc", "last_updated_at": 1663162982915, "last_updated_by": "jkdjnueu7e7", "address": { "name": "Dr Watson", "address_1": "221B, Baker street", "address_2": "apt., 1", "city": "London", "region": "London", "country": "GB", "zipcode": "00001", "phone": "0122334455" }, "category": "1002", "service_level": "Platinum", "status": "active", "risk_profile": { "level": "low", "score": 10 } }
Stop fraud, break down data silos, and lower friction with Sift.
$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."$create_content"
Your Sift REST API key.
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.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..
The user's current session ID, used to tie a user's action before and after login or account creation.
The status of the comment. After you update a posting, you can also update its status via the
$content_status
event.Allowed Values
$active
at a later date.IP address of the request made by the user. Recommended for historical backfills and customers with mobile apps.
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
.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
.Contains information about the comment.
The text content of the comment.
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.
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.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.The list of images shared by the user with their comment. It includes images pasted inline or attached separately.
Name of the brand of product or service being purchased.
Country the company is providing service from. Use ISO-3166 country code.
Domain being interfaced with. Use fully qualified domain name.