Device Fingerprinting API Guide

1) Install our JavaScript snippet

Install our JavaScript snippet on every public-facing page on your site.

2) Identify and block fraudulent devices

Let's use the example of fake listings on an apartment rentals site to see how we could identify and block fraudulent users. Let's assume the goal here is to redirect fraudulent users to an error page once they attempt to post a listing (instead of persisting that listing and directing the user to a confirmation page).

To accomplish this, you would need to do the following in a relevant route handler in your server code:

1. Call our /sessions endpoint to swap a session_id for data associated with the device
2. Check the device label, if it exists
3. If the label is set to “bad”, then take a negative action (i.e. redirecting to an error page, etc)
4. Else, continue as normal

Alternately, you can use our /users endpoint to query for devices seen for a given user, then check for the label placed on each associated device.

The following pseudocode outlines the basic steps we would take while handling the post in our server:

# Constants
ACCOUNT_ID = <YOUR SIFT ACCOUNT ID>
REST_API_KEY = <YOUR SIFT REST API KEY>

# Route handler called after a user attempts to post a listing
def post_listing():
  # First, you would call our /sessions endpoint to fetch
  # the device associated with the current session. You will
  # need to pass in the session_id provided by your webserver,
  # which is encased in this example in the request.session_id
  # variable.
  sift_session_url = \n    "https://api3.siftscience.com/v3/accounts/{account_id}/sessions/{session_id}"
    .format(account_id=ACCOUNT_ID, session_id=request.session_id)

  # You’ll need to authenticate the request by setting the "Authorization" header
  # as shown below
  headers = {"Authorization": "Basic {}".format(base64.b64encode(REST_API_KEY + ":"))}
  response = http.get(sift_session_url, headers = headers)

  # From the response body, you would want to examine
  # the "device" paragraph
  device_json = response.json()["device"]

  # If the label field is set for this device and
  # the device has been labeled bad by you in the past,
  # then redirect to an error page
  if "label" in device_json and device_json["label"] == "bad":
    return redirect_to("error.html")

  # Else continue as normal
  return redirect_to("success.html")

3) Label fraudulent devices

In order to prevent fraudulent users from interacting with your site, you'll need to flag (or "label") devices those users have been linked with in the past.

Continuing with the example before, let's say you or your customer service team found that a certain user was posting fake listings. Let's also say you have an internal admin tool that agents can use to take action on your users.

You would want to add a link to your admin system to allow agents to block every device associated with a fraudulent user. Here's pseudocode that outlines a handler on your server that would block these devices after an agent clicks that link.

# Constants
ACCOUNT_ID = <YOUR SIFT ACCOUNT ID>
REST_API_KEY = <YOUR SIFT REST API KEY>

# Route handler called when an agent clicks a "block user" link in your
# internal admin system
def block_user_devices():
  # You’ll need to authenticate a request by setting the “Authorization” header
  # as shown below
  headers = {"Authorization": "Basic {}".format(base64.b64encode(REST_API_KEY + ":"))}

  # First, let's fetch all devices associated with a user
  user_devices_url = \n    "https://api3.siftscience.com/v3/accounts/{account_id}/users/{user_id}/devices"
    .format(ACCOUNT_ID, user_id)

  response = http.get(user_devices_url, headers=headers)
  device_fingerprints = [d["id"] for d in response.json()["data"]]

  # Call the /devices/{device_fingerprint}/label endpoint to PUT a “bad” label
  # for every device associated with this user
  device_label_url = \n    "https://api3.siftscience.com/v3/accounts/{account_id}/devices/{device_fingerprint}/label"

  # You’ll need to PUT the following object to denote
  # that a device is bad
  bad_label = {"label": "bad"}

  for device_fingerprint in device_fingerprints:
    url = \n      device_label_url.format(account_id=account_id, device_fingerprint=device_fingerprint)
    http.put(url,
             data = bad_label,
             headers = headers)