Skip to content
Switch branches/tags
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time



The official Ruby bindings for the latest version (v205) of the Sift API.


  • Ruby 2.0.0 or above.


If you want to build the gem from source:

$ gem build sift.gemspec

Alternatively, you can install the gem from

gem install sift


Creating a Client:

require "sift"

Sift.api_key = '<your_api_key_here>'
Sift.account_id = '<your_account_id_here>'
client =

##### OR

client = '<your_api_key_here>', account_id: '<your_account_id_here>')

Sending a transaction event

event = "$transaction"

user_id = "23056"  # User ID's may only contain a-z, A-Z, 0-9, =, ., -, _, +, @, :, &, ^, %, !, $

properties = {
 "$user_id" => user_id,
  "$user_email" => "",
  "$seller_user_id" => "2371",
  "seller_user_email" => "",
  "$transaction_id" => "573050",
  "$payment_method" => {
    "$payment_type"    => "$credit_card",
    "$payment_gateway" => "$braintree",
    "$card_bin"        => "542486",
    "$card_last4"      => "4444"
  "$currency_code" => "USD",
  "$amount" => 15230000,

response = client.track(event, properties)

response.ok?  # returns true or false
response.body  # API response body
response.http_status_code  # HTTP response code, 200 is ok.
response.api_status  # status field in the return body, Link to Error Codes
response.api_error_message  # Error message associated with status Error Code

# Request a score for the user with user_id 23056
response = client.score(user_id)


To learn more about the decisions endpoint visit our developer docs.

List of Configured Decisions

Get a list of your decisions.

Optional Params

  • entity_type: :user or :order or :session or :content
  • abuse_types: ["payment_abuse", "content_abuse", "content_abuse", "account_abuse", "legacy", "account_takeover"]


A Response object


# fetch a list of all your decisions
response = client.decisions({
  entity_type: :user,
  abuse_types: ["payment_abuse", "content_abuse"]

# Check that response is okay.
unless response.ok?
  raise "Unable to fetch decisions #{response.api_error_message} " +

# find a decisions with the id "block_bad_user"
user_decision = response.body["data"].find do |decision|
  decision["id"] == "block_bad_user"

# Get the next page

if response.body["has_more"]

Apply a decision

Applies a decision to an entity. Visit our developer docs for more information.

Required Params:

  • decision_id, source, user_id

Other Params

  • order_id: when applying a decision to an order, you must pass in the order_id
  • session_id: when applying a decision to a session, you must pass in the session_id
  • analyst: when source is set to manual_review, this field is required

Returns Response object.


# apply decision to a user
response = client.apply_decision({
  decision_id: "block_bad_user",
  source: "manual_review",
  analyst: "",
  user_id: ""

# apply decision to ""'s order
response = client.apply_decision({
  decision_id: "block_bad_order",
  source: "manual_review",
  analyst: "",
  user_id: "",
  order_id: "ORDER_1234"

# apply decision to ""'s session
response = client.apply_decision({
  decision_id: "block_bad_session",
  source: "manual_review",
  analyst: "",
  user_id: "",
  session_id: "SESSION_ID_1234"

# apply decision to ""'s content
response = client.apply_decision({
  decision_id: "block_bad_session",
  source: "manual_review",
  analyst: "",
  user_id: "",
  content_id: "CONTENT_ID_1234"

# Make sure you handle the response after applying a decision:

if response.ok?
  # do stuff
  # Error message

  # Summary of the error

  # hash of errors:
  #  key: field in question
  #  value: description of the issue

Sending a Label

# Label the user with user_id 23056 as Bad with all optional fields
response = client.label(user_id, {
  "$is_bad" => true,
  "$abuse_type" => "payment_abuse",
  "$description" => "Chargeback issued",
  "$source" => "Manual Review",
  "$analyst" => ""

# Get the status of a workflow run
response = client.get_workflow_status('my_run_id')

# Get the latest decisions for a user
response = client.get_user_decisions('example_user_id')

# Get the latest decisions for an order
response = client.get_order_decisions('example_order_id')

# Get the latest decisions for a session
response = client.get_session_decisions('example_user_id', 'example_session_id')

# Get the latest decisions for an content
response = client.get_content_decisions('example_user_id', 'example_order_id')

Response Object

All requests to our apis will return a Response instance.

Public Methods:

  • ok? returns true when the response is a 200-299, false if it isn't
  • body returns a hash representation of the json body returned.
  • api_error_message returns a string describing the api error code.
  • api_error_description a summary of the error that occured.
  • api_error_issues a hash describing the items the error occured. The key is the item and the value is the description of the error.


Building and publishing the gem is captured by the following steps:

$ gem build sift.gemspec
$ gem push sift-<current version>.gem

$ bundle
$ rake -T
$ rake build
$ rake install
$ rake release


To run the various tests use the rake command as follows:

$ rake spec