Use the REST API to tell Sift Science about events that can't be captured with the Javascript API. An event can be a transaction, a signup, a listing of an item for sale, or anything else that matters to you. Our machine learning system will analyze event sequences, velocities, and specific field values to learn what looks like fraud and what doesn't. Where possible, we'll pool fraud signals across our network of customers.

Need help? Email support@siftscience.com or click on the "Chat with us!" tab in the bottom-right corner of this window.

Hello, world!

Let's say you operate a car-sharing marketplace where users can borrow each other's cars for a fee. On January 26th, 2012, at 10:57 a.m. PST, user al_capone (the buyer) borrowed the car of user 2371 (the seller). The transaction was for $15.23 US dollars, and user al_capone borrowed the car for 930 seconds and drove 5.26 miles. This event would just be an HTTP POST to our API (v202 denotes version 202):

  https://api.siftscience.com/v202/events

The following JSON would be in the HTTP request body:

  {
      "$api_key": "XXXXXXXXXXX",    // Your Sift Science API key
      "$type": "$transaction",      // Event type - $type is a reserved field (starts with "$")
      "$user_id": "al_capone",          // The primary key of the user executing the transaction (as on your site)
      "$user_email": "buyer@gmail.com",
      "$seller_user_id": "2371",
      "$seller_email": "seller@gmail.com",
      "$transaction_id": "573050",
      "$currency_code": "USD",
      "$amount": 15230000,          // Transaction amount in micros (defined as total number of cents * 10,000)
      "$time": 1327604222,          // 1/26/2012 10:57 a.m. represented as number of seconds since the epoch
      "trip_time": 930,             // Custom field (field name does not start with "$")
      "distance_traveled": 5.26     // Custom field (field name does not start with "$")
  }

Field names that start with a dollar sign are reserved. Anything else is a custom field. This difference is explained below.

Here's a simple CURL command -- try it out!

  curl -X POST -d '{ "$api_key": "XXXXXXXXXXX", "$type": "$transaction", "$user_id": "al_capone", "$user_email": "buyer@gmail.com", "$seller_user_id": "2371", "$seller_email": "seller@gmail.com", "$transaction_id": "573050", "$currency_code": "USD", "$amount": 15230000, "$time": 1327604222, "trip_time": 930, "distance_traveled": 5.26 }' -H "Accept: application/json" https://api.siftscience.com/v202/events

Each request sent to the REST API is a simple JSON object describing a user event on your service. This JSON object must be flat -- field values can only be of type String, Integer, Float, or Boolean. Arrays and nested objects are not permitted. Two event types, transactions and labels, are reserved events and require a leading dollar sign. Any other event type is a custom event.

Universal Fields

These fields are common to all events.

Name Type Description Required
$api_key String Your unique API key, as provided by Sift Science. Without it, API requests will not be accepted. See the Quickstart for your API key. Required
$type String The type of the event being tracked. This value can be a reserved event, e.g. $transaction or a custom event, e.g. user_feedback. Required
$user_id String Unique primary key of the user responsible for this event. Critical for linking Sift Science with your internal system. Valid characters: =, ., -, _, +, @, :, &, ^, %, !, $. This should match the ID you set in the Javascript snippet. Required
$other_user_id String Unique primary key of a second user involved with this event, such as the recipient of a message or a seller being given feedback. Not used for $transaction events -- use $seller_user_id instead. Optional
$time Integer Time at which this event occurred, represented as the number of seconds since the epoch. See Unix time. This defaults to the current time if not specified. Optional
$user_email String The user's email address. Strongly recommended. Used to evaluate suspicious email domains and patterns, e.g. joe+1@hotmail.com, joe+2@hotmail.com, joe+3@hotmail.com Optional
$ip String The user's IP address at the time of the event, if known. Very useful for analyzing geolocation signals. Optional

Reserved Fields & Custom Fields

Throughout this document, you'll notice certain fields start with a dollar sign, e.g. $user_id and $time. The leading dollar sign denotes a reserved field. These fields have special significance in our machine learning system, and enables us to leverage a standard set of signals across our network of customers. For best results, we recommend providing as many reserved fields as possible.

Any non-reserved field is a custom field. Custom fields capture data elements specific to your business logic. For example, a car-sharing service could log the distance_traveled with each trip. This might be an important fraud signal, but wouldn't make sense for an online shoe store. It's OK! Our machine learning system takes advantage of every piece of data, no matter how business-specific. For best results, provide as much data as possible. You can add any number of custom fields to any event. They're just additional key-value pairs on the JSON object. Values may be a String, Integer, Float, or Boolean.

Transaction Events

"$type":"$transaction"

A transaction represents a payment for goods and/or services. This is a basic unit of action that requires risk evaluation, typically after a credit card AUTH or SETTLE. Reserved fields for the transaction event are specified below. At the start of this page is an example transaction event.

These are the reserved fields on a transaction event:

Name Type Description Required
$user_id String Unique primary key of user making the transaction (the buyer). Critical for linking Sift's machine learning decisions to your internal system. Required
$seller_user_id String If applicable, unique primary key of user who is selling a the good/service. Optional
$seller_email String If applicable, seller's email address. Optional
$amount Integer Total transaction amount in micros, in the base unit of the $currency_code. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros. Required
$currency_code String ISO-4217 currency code for the amount. Required
$time Integer Time at which the transaction occurred, represented as the number of seconds since the epoch. Optional
$transaction_id String Primary key of this transaction in your system. Optional
$billing_name String Full name of the buyer as it appears on their credit card. Optional
$billing_bin String First six digits of the credit card, also known as the Issuer Identification Number (IIN). If specified, this must be six digits, with no alphabetic characters. Optional
$billing_last4 String Last four digits of the credit card. If specified, this must be four digits, with no alphabetic characters. Optional
$billing_address1 String Billing address first line, e.g. "123 Main St". Optional
$billing_address2 String Billing address second line, e.g. "Apt 5". Optional
$billing_city String Billing address city. Optional
$billing_region String Billing state/province/region, e.g. “CA” for California or “ON” for Ontario, Canada. Optional
$billing_country String ISO-3166 country code for the billing address. Optional
$billing_zip String Billing zip/postal code Optional
$shipping_address1 String Shipping address first line, e.g. "456 Main St". Optional
$shipping_address2 String Shipping address second line, e.g. "Apt 7". Optional
$shipping_city String Shipping address city. Optional
$shipping_region String Shipping state/province/region, e.g. “CA” for California or “ON” for Ontario, Canada. Optional
$shipping_country String ISO-3166 country code for the shipping address. Optional
$shipping_zip String Shipping zip/postal code Optional

Label Events

"$type":"$label"

Labels are a special type of event. Labels mark users that our machine learning system should learn from. An obvious example is banned users, e.g. "$label":"$ban".

Example using the reserved $ban label:

  {
      "$api_key": "XXXXXXXXXXX",
      "$type": "$label",
      "$label": "$ban",           // $ban is a reserved label (it has a leading dollar sign)
      "$user_id": "al_capone",
      "$time": 1334139615,
      "reason": "Harassing other users with spammy messages."
  }

There are a few reserved values for $label:

Name Description
$ban User abused your system or abused other users and should be marked as bad. Our machine learning will learn from this example.
$unban A user was mistakenly banned in your sytem. Without correction, our machine learning system may inadvertently treat good behavior as bad behavior.

Custom Events

"$type":"my_custom_event"

Anything that's not a transaction or label is a custom event. Custom events do not start with a dollar sign, e.g. "$type":"email_verified", instead of "$type":"$transaction". Custom event names can only contain letters a-z and A-Z, numbers 0-9, and underscores. Custom event names cannot begin with an underscore.

Don't be shy with custom events and custom fields! This is the true flexibility of our machine learning system. It will learn based on your data, no matter how specific to your business. For example, on an eBay-style marketplace, a seller might signup and then list_item. Several buyers might then bid on the item, and the winning bidder executes a $transaction with the seller. Finally, the buyer may leave some seller_feedback.

How might the seller_feedback event look?

  {
      "$api_key": "XXXXXXXXXXX",
      "$type": "seller_feedback",   // Note that seller_feedback does not start with a dollar sign
      "$user_id": "al_capone",
      "$other_user_id": "13098",
      "$time": 1334139615,          // Reserved field
      "feedback_stars": 5.0,        // Custom field
      "feedback_message": "Seller delivered goods on-time and in perfect condition!"
  }

With the above eBay-style marketplace, our machine learning system can mine interesting signals:

  • A typical seller might take an average of 10 minutes between a signup and list_item. A user who takes just 5 seconds between the two events might be suspicious.
  • A typical buyer might bid twice a day. A user with 100 bid events a day might be suspicious.
  • Prior banned users might tend to rate sellers with fewer feedback_stars and shorter-length feedback_message than "good" users.

All these signals use custom events: bid, signup, and list_item, along with custom fields feedback_stars and feedback_message. Bottom line: send as many events, with as many fields as you'd like! Our system loves data.

Backfill prior events by setting the $time field to when that event occurred. This is especially useful if you've banned fraudulent users. Our machine learning system can learn from these examples! Just send $label events for those users, and any $transaction or custom events associated with those users. Training examples really help us improve the accuracy of your results — more is better.

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. For example:

  {
      "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\": \"$transaction\"... }"
  }

Any non-zero status indicates an error. Possible status codes:

Name Description
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; please contact us to increase this limit
104 Invalid API version
105 Not a valid reserved field

If our servers are dealing with unexpected problems, you'll likely see an HTTP 500 response.

{"signed_in":false,"env":"production","event":{"name":"View Documentation","properties":{"page":"REST API"}}}