Quick Start

Please select the product you wish to use to quickly set up the optimal payloads for your use-case

Show

Product

Select your server

Please choose your backend environment for quick integration

cURL
Java
Python
PHP

Select your industry

Please choose your industry to see relevant example payloads

iGaming
Online Lending
Ecommerce
Payment Gateways
Banking and Insurance
Travel and Ticketing
Crypto exchange

Select your use case

Please choose your use case to see relevant example payloads

Register
Login
Deposit
Withdrawal
Payment

Available Digital Footprint Analysis modules are

Email API Phone API IP API Email Verification API Device Fingerprinting

Check theOverview & Steps for Senseto understand the Admin Interface

Risk Scores can be customized in the Admin Panel

Please refer to theSDKreferences to use our device fingerprinting functionality

Developer Resources

Authentication

Our API uses a standard HTTP Authorization header. This protects your account and the data within it, so only you and SEON can access them.

You must provide authentication for all API requests using the following format:
X-API-KEY: [licensekey]

Note

Please replace [license_key] with your unique license_key found on your account page.

Error Details

In case of problems with the API request payload or authentication, SEON returns specific error codes in the error property of the response body. You should be able to understand the exact issue based on the returned error codes.

For a detailed list of error codes, please check the API Reference - Error codes.

Rate Limits

Rate limits are in place to prevent misuse and overloading of our systems. The limit takes into account all requests with a specific license key, not individual API requests.

There is a 2 request/second limit for trial accounts. After the trial period, this limit increases to 10 requests/second.

In case the rate limit is hit SEON returns 429 HTTP response code, in this case, please get in touch with our support team in case you wish to increase your rate limit.

Timeout logic

We recommend that all client integration codes should be able to cope with client side timeout responses on their end to avoid timeout errors in case of degraded API performance. Timeout parameters for the API execution can be set either in Admin settings or be changed in the API requests' configuration object - in this case; the configuration object parameters would override the settings in Admin. In general, if a response, either success or error, is not returned within the Timeout settings for the Email/Phone API request, we recommend that the client accept the transaction by default. The transaction should only be blocked if a response is received from SEON with a state or score trigger indicating that this action should occur. For further information, please refer to our whitepaper on dealing with high scores and states.

Steps for Sense

At its core, our fraud prevention platform operates in three simple steps.

You send user / transaction / device data
We enrich the data and deliver a risk score based on rules
You give feedback on the results

Note

Remember that the more data we have, the better. Historical data and feedback are fed to our Machine Learning algorithms, which helps refine the rules for better scoring.

Integration timeline

You can find a detailed timeline here to see how long it takes to get results with SEON Sense.

Step 1 - Providing the Data

All the user, transaction and device data is sent via the Fraud API. Your first step is to define payloads for the API, populating it with as many relevant data points as possible. All the fields are optional, but the more you fill, the more precise our results will be.

For custom business-specific data points, use the custom_fields object.
The config object helps you to fine-tune settings such as versions, response and aggregating data enrichment APIs, when required.
You must define the authentication points aka. action_type-s (account_register, account_login, purchase etc.) where risk assessment data can be collected or fraud should be prevented.
For device fingerprinting, you can use our JavaScript snippet for web apps, and the SDKs for iOS and Android mobile apps. Use the session to send the encrypted payload returned by the SDK (supported by JS Agent v4, iOS SDK 3.0.1, Android SDK 3.0.2) for device data collection.

Custom support

Please get in touch with your dedicated account manager to tailor and validate your specific payloads.

Warning!

We recommend you only use the Email / Phone API at the earliest user access point of action_type-s (for instance, at the user registration stage). These APIs fetch data from social networks, which can be a bottleneck in your response time, and the risk doesn’t increase later in the customer journey. You can define a desired timeout threshold in the Settings page. We recommend at least 1000ms for a minimum 95% accuracy.

Step 2 - Enrichment and Scoring

SEON Sense is designed to give you full transparency behind every score and decision (a.k.a. state). This is why every data point will be available in the response.

By default, the fraud scores are based on preset rules, which can be reviewed in the Scoring Engine. A score of 10+ is considered risky. Standard thresholds for each state are:

State	Threshold
APPROVE	0 - 10
REVIEW	10 - 20
DECLINE	20+

Note

These thresholds are tailored to high-risk merchants. You can edit them in the Settings page. We recommend you adjust the DECLINE state thresholds between 20-35, depending on the amount of false positives you might encounter in the first few days.

Step 3 - Feedback

Providing feedback is the key to refining the rules and getting more precise fraud scores. This is particularly important when discovering false positives and false negatives.

Every transaction state should therefore be set to the appropriate category:

State	Category
APPROVE	Safe transaction.
REVIEW	Suspicious transaction, not confirmed fraud yet.
DECLINE	Confirmed fraudulent transaction.

You can also create categories of fraud reasons in the Machine Learning section of your Settings page , which support the Label API (e.g. chargeback, bonus abuser or postback data from payment: authorized, lost or stolen etc.)

Note

Our Machine Learning algorithm retrains itself hourly. You can see the updated rule recommendations based on your feedback in the Scoring Engine / Machine Learning page. The more historical data and feedback you can provide, the more precise the scoring will be.

Fraud API

SEON’s Fraud API is at the core of our fraud fighting solution. It is only available through SEON Sense, so please see the setup guide above to get started.

As our tool is fully modular, you can choose to enable or disable the other APIs (Email, Phone, IP) and the device fingerprinting tool.

Use the config object to enable or disable modules.
Use the custom_fields object for custom data points.

For Sense Platform users only: If you are an Intelligence Tool user you will not be able to access this API.

Request

Request Attributes	Type	Required
config	object	no

action_type	string	no

ip	string	no

transaction_id	string	no

affiliate_id	string	no

affiliate_name	string	no

order_memo	string	no

email	string	no

email_domain	string	no

password_hash	string	no

user_fullname	string	no

user_name	string	no

user_id	string	no

user_created	integer	no

user_category	string	no

user_account_status	string	no

user_bank_account	string	no

user_bank_name	string	no

user_balance	float	no

user_verification_level	string	no

user_dob	date	no

user_country	string	no

user_city	string	no

user_region	string	no

user_zip	string	no

user_street	string	no

user_street2	string	no

session_id	string	no

session	string	no

device_id	string	no

payment_mode	string	no

payment_provider	string	no

card_fullname	string	no

card_bin	string	no

card_hash	string	no

card_expire	date	no

card_last	string	no

avs_result	string	no

cvv_result	boolean	no

status_3d	string	no

sca_method	string	no

phone_number	string	no

transaction_type	string	no

transaction_amount	float	no

transaction_currency	string	no

items	array of objects	no

shipping_country	string	no

shipping_city	string	no

shipping_region	string	no

shipping_zip	string	no

shipping_street	string	no

shipping_street2	string	no

shipping_phone	string	no

shipping_fullname	string	no

shipping_method	string	no

billing_country	string	no

billing_city	string	no

billing_region	string	no

billing_zip	string	no

billing_street	string	no

billing_street2	string	no

billing_phone	string	no

discount_code	string	no

gift	boolean	no

gift_message	boolean	no

merchant_category	string	no

merchant_id	string	no

merchant_created_at	integer	no

merchant_country	string	no

receiver_fullname	string	no

receiver_bank_account	string	no

details_url	string	no

regulation	string	no

bonus_campaign_id	string	no

brand_id	string	no

custom_fields	object	no

Warning!

The maximum length of all request parameters is 100 characters, except 64 characters for the session_id (sent directly or within the session field) and 19 characters for the phone_number.

HTTP Endpoint

POST

https://api.seon.io/SeonRestService/fraud-api/v2.0/

Language

Industry

Use case

Response

The endpoint returns JSON structured response.

JSON Attributes	Type
id	string

state	string

fraud_score	number

ip_details	object

email_details	object

bin_details	object

phone_details	object

version	string

applied_rules	array of object

device_details	object

calculation_time	integer

seon_id	integer

Response

{
    "success": true,
    "error": {},
    "data": {
        "id": "213-321",
        "state": "APPROVE",
        "fraud_score": 4.24,
        "ip_details": {
            "ip": "1.1.1.1",
            "score": 100,
            "country": "HK",
            "state_prov": "Hong Kong",
            "city": "Hong Kong",
            "timezone_offset": "+08:00",
            "isp_name": "APNIC and CloudFlare DNS Resolver Project",
            "latitude": 22.28552,
            "longitude": 114.15769,
            "type": "CDN",
            "open_ports": [
                80
            ],
            "tor": false,
            "harmful": false,
            "vpn": false,
            "web_proxy": false,
            "public_proxy": false,
            "spam_number": 3,
            "spam_urls": [
                "bl.emailbasura.org",
                "l2.apews.org",
                "dyna.spamrats.com"
            ],
            "history": {
                "hits": 3,
                "customer_hits": 1,
                "first_seen": 1573567581,
                "last_seen": 1573639346
            },
            "flags": [
                {
                    "note": "Blacklisted by API",
                    "date": 1573138956,
                    "industry": "Online gambling operator"
                }
            ],
            "id": "b06c5055-d1bf-4400-b2c9-ab3edd7171d6"
        },
        "email_details": {
            "email": "example@example.com",
            "score": 80,
            "deliverable": false,
            "domain_details": {
                "domain": "example.com",
                "tld": ".com",
                "created": "1995-08-14 04:00:00",
                "updated": "2019-08-14 07:04:41",
                "expires": null,
                "registered": true,
                "registrar_name": null,
                "registered_to": null,
                "disposable": true,
                "free": false,
                "custom": false,
                "dmarc_enforced": false,
                "spf_strict": true,
                "valid_mx": false,
                "accept_all": false,
                "suspicious_tld": false,
                "website_exists": true
            },
            "account_details": {
                "facebook": {
                    "registered": false,
                    "photo": null,
                    "url": null,
                    "name": null
                },
                "google": {
                    "registered": false,
                    "photo": null
                },
                "apple": {
                    "registered": false
                },
                "twitter": {
                    "registered": false
                },
                "microsoft": {
                    "registered": false
                },
                "yahoo": {
                    "registered": false
                },
                "ebay": {
                    "registered": false
                },
                "gravatar": {
                    "registered": false
                },
                "instagram": {
                    "registered": false
                },
                "spotify": {
                    "registered": false
                },
                "tumblr": {
                    "registered": false
                },
                "linkedin": {
                    "registered": false,
                    "photo": null,
                    "url": null,
                    "location": null,
                    "name": null,
                    "company": null,
                    "title": null,
                    "website": null,
                    "twitter": null
                },
                "weibo": {
                    "registered": false
                },
                "github": {
                    "registered": false
                },
                "vimeo": {
                    "registered": false
                },
                "flickr": {
                    "registered": false
                },
                "foursquare": {
                    "registered": false
                },
                "lastfm": {
                    "registered": false
                },
                "myspace": {
                    "registered": false
                },
                "pinterest": {
                    "registered": false
                },
                "skype": {
                    "registered": false,
                    "photo": null,
                    "name": null,
                    "country": null,
                    "city": null,
                    "gender": null,
                    "id": null,
                    "handle": null,
                    "bio": null,
                    "age": null,
                    "language": null,
                    "state": null
                }
            },
            "breach_details": {
                "breaches": null,
                "haveibeenpwned_listed": false,
                "number_of_breaches": null,
                "first_breach": null
            },
            "history": {
                "hits": 1,
                "customer_hits": 1,
                "first_seen": 1576682328,
                "last_seen": 1576682328
            },
            "flags": [],
            "id": "a03fd029-4a9b-4010-97ee-8d1f5f5c0123"
        },
        "bin_details": {
            "card_bin": "550000",
            "bin_bank": "NORTHERN NECK STATE BANK",
            "bin_card": "VISA",
            "bin_type": "DEBIT",
            "bin_level": "BUSINESS",
            "bin_country": "UNITED STATES",
            "bin_countrycode": "US",
            "bin_website": "",
            "bin_phone": "(804) 435-1626",
            "bin_valid": true,
            "card_issuer": "VISA"
        },
        "phone_details": {
            "number": 36301234567,
            "valid": true,
            "type": "MOBILE",
            "country": "HU",
            "carrier": "T-Mobile",
            "score": 0.0,
            "account_details": {
                "facebook": {
                    "registered": true
                },
                "google": {
                    "registered": true
                },
                "instagram": {
                    "registered": true
                },
                "twitter": {
                    "registered": true
                },
                "yahoo": {
                    "registered": true
                },
                "telegram": {
                    "registered": false,
                    "last_seen": null,
                    "photo": null
                },
                "whatsapp": {
                    "registered": true,
                    "last_seen": 1559825148,
                    "photo": "/9j/4AAQSkZJRgABAQAAAQAB...",
                    "about": "Hey there! I am using WhatsApp."
                },
                "viber": {
                    "registered": true,
                    "last_seen": 1564948016,
                    "photo": "/9j/4AAQSkZJRgABAQAAAQAB...",
                    "name": "Sample Name"
                },
                "kakao": {
                    "registered": false
                },
                "ok": {
                    "registered": false
                },
                "zalo": {
                    "registered": false
                },
                "line": {
                    "registered": false,
                    "photo": null,
                    "name": null
                },
                "microsoft": {
                    "registered": false
                },
                "snapchat": {
                    "registered": false
                },
                "skype": {
                    "registered": false,
                    "photo": null,
                    "name": null,
                    "country": null,
                    "city": null,
                    "gender": null,
                    "id": null,
                    "handle": null,
                    "bio": null,
                    "age": null,
                    "language": null,
                    "state": null
                }
            },
            "history": {
                "hits": 19,
                "customer_hits": 2,
                "first_seen": 1572825600,
                "last_seen": 1572825600
            },
            "flags": [
                {
                    "note": "Sample note added by Admin user",
                    "date": 1572858397,
                    "industry": "Airline company"
                },
                {
                    "note": "",
                    "date": 1571319439,
                    "industry": "Online gambling operator"
                }
            ],
            "id": "71585377-4b5c-4fba-bc42-785bb6889c59"
        },
        "version": "v2.0",
        "applied_rules": [
            {
                "id": "3",
                "name": "IP country does not match with billing country",
                "operation": "+",
                "score": 2
            }
        ],
        "device_details": {
             "type": "web",
             "source": "js-4.1.1",
             "session_id": "de153dd3996e46ce84b32fda82208f4e",
             "adblock": false,
             "audio_hash": "124.04345808873768",
             "battery_charging": false,
             "battery_level": 58,
             "browser_hash": "4ab1d9549382520af59f4bce9db31ace",
             "browser": "CHROME",
             "browser_version": "76.0.3809.100",
             "canvas_hash": "48bfc395be892bba7d9d8abc68f83450",
             "cookie_enabled": true,
             "cookie_hash": "61d786b165b74e15d8c55b1e96a8cdb3",
             "device_hash": "e4e3dcc9c15debf45dd09f2683012356",
             "device_memory": 8,
             "device_type": "desktop",
             "dns_ip": "89.134.46.85",
             "dns_ip_country": "HU",
             "dns_ip_isp": "Sample Service Provider",
             "do_not_track": false,
             "flash_enabled": false,
             "font_count": 27,
             "font_hash": "0f7664682b2a6c3baeda70c094658dac",
             "font_list": [
                "Andale Mono",
                "..."
            ],
              "hardware_concurrency": 4,
              "java_enabled": false,
              "device_ip_address": "80.99.46.168",
              "device_ip_country": "HU",
              "device_ip_isp": "Sample Service Provider",
              "accept_language": [
                "en-us",
                "..."
            ]
              "os": "MacOS",
              "platform": "MacIntel",
              "plugin_count": 3,
              "plugin_hash": "9c33fe15e3ec251f799666de471de1e9",
              "plugin_list": [
                 "Chrome PDF Plugin",
                 "..."
            ],
             "private": false,
             "region_language": "hu",
             "region_timezone": "+02:00",
             "screen_available_resolution": "2048x1129",
             "screen_color_depth": 24,
             "screen_pixel_ratio": 1,
             "screen_resolution": "2048x1152",
             "touch_support": false,
             "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.100 Safari/537.36",
             "webgl_hash": "9908db6eb8007ad94e0f8dc0fa974fb4",
             "webgl_vendor": "Intel Inc.~Intel(R) Iris(TM) Plus Graphics 650",
            "webrtc_activated": false,
            "webrtc_count": 0,
            "webrtc_ips": [],
            "window_size": "1060x649",
        },
        "calculation_time": 554,
        "seon_id": 1505147
    }
}

JavaScript Agent v4

You can integrate our optional device fingerprinting module directly into a web app, by using our JavaScript agent. Please, always use our CDN hosted script to ensure you always load the latest available version.

Include the JavaScript Agent for example inside the <head> tags of your website or web app. You can also lazy-load it or execute upon specific actions (e.g. clicking on Login, Payment, Registration buttons, before calling the API). In this case you must ensure that the module has been loaded successfully before invoking its methods.
Set a unique session_id for your client using the seon.config() function.
Call the seon.getBase64Session() function to get the encrypted payload for the device.
Send the returned session payload string to your backend and add to the session property in your Fraud API request. The Fraud API call should be still executed if the session is missing, due to non-executed JS snippet. Tip: Add timeout to JS and utilise Fraud API call after.

All the device fingerprinting data will be available in the response of the Fraud API, and accessible on the Admin Panel of the Transactions Details page.

Note

Including the lightweight JavaScript agent or mobile SDKs are optional, but it provides in-depth analysis for each user’s device.

Configuration parameters

To configure the JavaScript module, you need to call seon.config() function:

JSON Attributes	Required
host	no

session_id	yes

audio_fingerprint	no

canvas_fingerprint	no

webgl_fingerprint	no

onSuccess	no

onError	no

Integration

Fingerprinting can be triggered by seon.getBase64Session() function. After collecting all the available information, the function returns an encrypted base64 encoded payload.

Payload

SEON JavaScript library collects device information and prepares an encrypted payload to use in Fraud API. The information on client side is not readable, we’ll reveal in the Fraud API response and on the Admin Panel. Some fields can be null, if the actual browser does not support or return data for that specific data point. In every other case, data types are preserved. Find a sample payload on the right side.

Common issues

The session is provided in the Fraud API request, but the device_details is null in the response and there is no device information on the Transaction details page. - This means the encrypted payload is corrupted. Please look into your integration and check again.
The v4 version of the JavaScript Agent is not compatible with the Fraud API v1, we highly recommend to upgrade because of security and performance reasons.
If you use CSP (Content Security Policy) headers on your site, you must allow the following domains in connect-src directive for full functionality based on your host configuration.

Default: *.seondnsresolve.com
seondf.com: *.seondfresolver.com
deviceinf.com: *.deviceinfresolver.com
getdeviceinf.com: *.getdeviceinfresolver.com

<html>
  <head>
    ...
    <script src="[source_url]"></script>
  </head>
  <body>
    ...
  </body>
</html>

You can use the following script source URLs ([source_url):

https://cdn.seondf.com/js/v4/agent.js
https://cdn.deviceinf.com/js/v4/agent.js
https://cdn.getdeviceinf.com/js/v4/agent.js

Make sure you use the same domain as host in the seon.config() as you used for loading the script.

seon.config({
  host: "seondf.com",
  session_id: "[session_id]",
  audio_fingerprint: true,
  canvas_fingerprint: true,
  webgl_fingerprint: true,
  onSuccess: function(message) {
    console.log("success", message);
  },
  onError: function(message) {
    console.log("error", message);
  }
});

Don’t forget to replace [session_id] with your unique session identifier. We recommend to use UUID, but you can use your own implementation as well.

seon.getBase64Session(function(data) {
  if (data) {
    console.log("Session payload", data);
  } else {
    console.log("Failed to retrieve session data.");
  }
});

iOS SDK

You can integrate our device fingerprinting module directly into iOS mobile apps, by using our SDK found on GitHub. It will collect information based on the user’s software and hardware configuration.

The SDK returns an encrypted, base64 encoded string to add in the session property in the Fraud API request. It isn’t permitted to access or modify the payload on the clients.
JSON structured device details will be returned in the Fraud API response.

JSON Attributes	Type
type	string

source	string

session_id	string

accessories_count	integer

audio_mute_status	boolean

audio_volume_current	integer

battery_charging	boolean

battery_level	string

carrier_country	string

carrier_name	string

cpu_count	string

cpu_type	string

device_adid	string

device_hash	string

device_name	string

device_orientation	string

device_udid	string

free_storage	string

icloud_ubiquity_token	string

ios_device_name	string

ios_version	string

is_emulator	boolean

is_jailbroken	boolean

kernel_arch	string

kernel_name	string

kernel_version	string

last_boot_time	string

network_config	string

pasteboard_hash	string

physical_memory	string

region_country	string

region_language	string

region_timezone	string

screen_brightness	string

screen_height	string

screen_width	string

system_uptime	string

total_storage	string

wifi_mac_address	string

wifi_ssid	string

dns_ip	string

dns_ip_country	string

dns_ip_isp	string

device_ip_address	string

device_ip_country	string

device_ip_isp	string

Response

{
 "device_details": {
  "type": "ios",
  "source": "ios-3.0.1",
  "session_id": "seosseion_id",
  "accessories_count": 0,
  "audio_mute_status": true,
  "audio_volume_current": 97,
  "battery_charging": false,
  "battery_level": 82,
  "carrier_country": "HU",
  "carrier_name": "Telenor HU",
  "cpu_count": 6,
  "cpu_type": "ARM_64",
  "device_adid": "00000000-0000-0000-0000-000000000000",
  "device_hash": "3b3ca138e2bf5cb97997dd7321bf2bc0efbfbe129f43e67b845e685baf090000",
  "device_name": "iPhone 11 Pro",
  "device_orientation": "Portrait",
  "device_udid": "E7E185B2-9991-4B53-0000-7C4A2FFA8059",
  "free_storage": 176508846080,
  "icloud_ubiquity_token": "0d5705a4 dd8fe10b 69fa14a9 a8ad1a06 5b088f2a",
  "ios_device_name": "iPhone 11",
  "ios_version": "14.6",
  "is_emulator": false,
  "is_jailbroken": false,
  "kernel_arch": "arm64",
  "kernel_name": "Darwin",
  "kernel_version": "18F72",
  "last_boot_time": 1623312341,
  "network_config": "WIFI",
  "pasteboard_hash": null,
  "physical_memory": 3960438784,
  "region_country": "HU",
  "region_language": "en",
  "region_timezone": "+02:00",
  "screen_brightness": 52,
  "screen_height": 2436,
  "screen_width": 1125,
  "system_uptime": 5906,
  "total_storage": 255881465856,
  "wifi_mac_address": "ea:63:da:b5:5a:e0",
  "wifi_ssid": "WIFI_SSID",
  "dns_ip": "89.134.46.87",
  "dns_ip_country": "HU",
  "dns_ip_isp": "UPC Magyarorszag Kft.",
  "device_ip_address": null,
  "device_ip_country": null,
  "device_ip_isp": null
 }
}

Android SDK

You can integrate our device fingerprinting module directly into Android mobile apps, by using our SDK found on GitHub. It will collect information based on the user’s software and hardware configuration.

The SDK returns an encrypted, base64 encoded string to add in the session property in the Fraud API request. It isn’t permitted to access or modify the payload on the clients.
JSON structured device details will be revealed in the Fraud API response.

JSON Attributes	Type
type	string

source	string

session_id	string

android_id	string

android_version	string

app_guid	string

audio_mute_status	boolean

audio_volume_current	integer

battery_charging	boolean

battery_health	string

battery_level	integer

battery_temperature	float

battery_voltage	integer

build_device	string

build_id	string

build_manufacturer	string

build_number	string

build_time	integer

carrier_country	string

carrier_name	string

cpu_count	integer

cpu_hash	string

cpu_speed	double

cpu_type	string

device_hash	string

device_cellular_id	string

device_name	string

free_storage	integer

has_proximity_sensor	boolean

is_emulator	boolean

is_rooted	boolean

kernel_arch	string

kernel_name	string

kernel_version	string

last_boot_time	integer

network_config	string

pasteboard_hash	string

physical_memory	integer

region_country	string

region_language	string

region_timezone	string

screen_brightness	integer

screen_height	integer

screen_scale	integer

screen_width	integer

sensor_hash	string

system_uptime	integer

total_storage	integer

wifi_mac_address	string

wifi_ssid	string

dns_ip	string

dns_ip_country	string

dns_ip_isp	string

device_ip_address	string

device_ip_country	string

device_ip_isp	string

Response

{
 "device_details": {
  "session_id": "test_session",
  "type": "android",
  "dns_ip": "89.134.46.87",
  "dns_ip_country": "HU",
  "dns_ip_isp": "UPC Magyarorszag Kft.",
  "source": "android-3.0.2",
  "device_hash": "702ec69fa2538ed37ddca2d29210bba6f7801ab9cf2f47bdec260f5dc84fd9cc",
  "device_name": "LGE LG-H502",
  "device_cellular_id": "352104070316496",
  "android_id": "9cb5c5698c590fdc",
  "build_id": "MRA58K",
  "build_device": "my90ds",
  "build_time": 1550069867,
  "build_number": "MRA58K",
  "build_manufacturer": "LGE",
  "app_guid": "66dc9430-a09f-4dcb-ab16-cd5b1c3d7316",
  "android_version": "23 (6.0)",
  "last_boot_time": 1623315851,
  "system_uptime": 495,
  "sensor_hash": "ea8170d27b08a39d3a697c9da5e8c0190174ebb302fc35e77da17690abb61576",
  "audio_volume_current": 28,
  "audio_mute_status": true,
  "battery_level": 80,
  "battery_charging": false,
  "battery_temperature": 29,
  "battery_voltage": 4063,
  "battery_health": "GOOD",
  "has_proximity_sensor": true,
  "cpu_type": "ARMv7 Processor rev 3 (v7l)",
  "cpu_count": 4,
  "cpu_speed": 1300,
  "cpu_hash": "6bae8487b6bd0d18f12910a12d79b43e79a21f8fa11bb0b44ca15b6a9f4c5cbe",
  "kernel_name": "Linux",
  "kernel_version": "3.10.72",
  "kernel_arch": "armv7l",
  "physical_memory": 979608000,
  "screen_brightness": 100,
  "screen_height": 1187,
  "screen_width": 720,
  "screen_scale": 2,
  "total_storage": 3854680064,
  "free_storage": 395546624,
  "network_config": "WIFI",
  "wifi_mac_address": "64:BC:0C:91:DC:01",
  "wifi_ssid": "WIFI_SSID",
  "carrier_name": null,
  "pasteboard_hash": "50ba875a2d572ed0c2632d3920d73a827588f0d86500b2e3145a788c86fdc83c",
  "region_timezone": "+02:00",
  "region_language": "en",
  "region_country": "GB",
  "carrier_country": null,
  "is_emulator": false,
  "is_rooted": false,
  "device_ip_address": null,
  "device_ip_country": null,
  "device_ip_isp": null
 }
}

Label API

This API lets you label transactions as fraudulent or not via a PUT request. It is important feedback that helps refine our machine learning algorithm, which then reduces the number of false positives and negatives.

You can create custom positive and negative labels in your Settings page
Read more about the feedback loop here.

For Sense Platform users only: If you are an Intelligence Tool user you will not be able to access this API.

Request

You must replace [id] with your transaction_id that you have provided during the Fraud API call or was generated automatically.

Request Attributes	Type	Required
label	string	yes

HTTP Endpoint

PUT

https://api.seon.io/SeonRestService/fraud-api/label/[id]

Language

Industry

Use case

Request (multiple)

You can also label multiple transactions with one API call using the URL below.

JSON Attributes	Type	Required
transactions	array of label objects	yes

HTTP Endpoint

PUT

https://api.seon.io/SeonRestService/fraud-api/label/

Language

Industry

Use case

Lists API

This API lets you blacklist, whitelist or reset any Fraud API request and response parameter, with a comment and expiration. This is achieved through a PUT request.

For Sense Platform users only: If you are an Intelligence Tool user you will not be able to access this API.

Request

Request Attributes	Type	Required
data_field	string	yes

value	string	yes

state	string	yes

comment	string	no

expire_day	integer	no

HTTP Endpoint

PUT

https://api.seon.io/SeonRestService/fraud-api/state-field/

Language

Industry

Use case

Self Exclusion API

A special API for gambling operators who need to enable self exclusion lists. This API uses email address, phone number, full name, date of birth, user country, user zip data fields. Users can be defined by email addresses or user ids in the requests. Use PUT request to exclude users, use DELETE request to reverse the exclusion.

For Sense Platform users only: If you are an Intelligence Tool user you will not be able to access this API.

Request

Request Attributes	Type	Required
user_ids	array	No

emails	array	No

HTTP Endpoint

PUT

https://api.seon.io/SeonRestService/fraud-api/exclude

Language

Industry

Use case

Response

The endpoint returns JSON structured response.

JSON Attributes	Type
created_id_rules	object map

created_email_rules	object map

failed_ids	object

failed_emails	object

Response

{
 "success": true,
 "error": {},
 "data": {
  "created_id_rules": {
   "id1": {
    "id": "1000001",
    "name": "Exclude customer [id: 123]",
    "operation": "DECLINE",
    "score": 100
   }
  },
  "created_email_rules": {
   "example1@example.com": {
    "id": "100000",
    "name": "Exclude customer [email: example1@example.com]",
    "operation": "DECLINE",
    "score": 100
   }
  },
  "failed_ids": {},
  "failed_emails": {}
 }
}

Delete request

JSON Attributes	Type	Required
user_ids	array	No

emails	array	No

HTTP Endpoint

DELETE

https://api.seon.io/SeonRestService/fraud-api/exclude

Language

Industry

Use case

Delete response

The endpoint returns JSON structured response.

JSON Attributes	Type
created_id_rules	object map

created_email_rules	object map

failed_ids	object

failed_emails	object

Response

{
  "success": true,
  "error": {},
  "data": {
    "deleted_id_rules": {
        "deleted_id_rules": [
            "1000000 - Exclude customer [id: id1]",
            "1000001 - Exclude customer [id: id2]",
        ],
        "deleted_email_rules": [
            "1000002 - Exclude customer [email: example1@example.com]",
            "1000003 - Exclude customer [email: example2@example.com]"
        ],
        "failed_ids": [],
        "failed_emails": []
    }
}

Erase API

Under GDPR, data controllers and processors are obliged to delete all personal data upon request. With our Erase API you can erase all data related to one or multiple users by providing email addresses or user ids.

Request

Request Attributes	Type	Required
user_ids	array	No

emails	array	No

Optional query string parameters

By default the Erase API performs a dry run, and collects the related records. In order to erase data please include the dry_run=false parameter.

POST

https://api.seon.io/SeonRestService/erase-api?dry_run=true

JSON Attributes	Value	Required
dry_run	boolean	no

HTTP Endpoint

POST

https://api.seon.io/SeonRestService/erase-api?dry_run=true

Language

Industry

Use case

Response

The endpoint returns JSON structured response.

JSON Attributes	Type
transaction_records	integer

email_records	integer

phone_records	integer

ip_records	integer

dry_run	boolean

Response

{
 "success": true,
 "error": {},
 "data": {
  "transaction_records": 1,
  "email_records": 0,
  "phone_records": 0,
  "ip_records": 1,
  "dry_run": false
 }
}

Webhooks

Webhooks let you set up connections between third party platforms or apps with real time information regarding certain events. When one of those events is triggered, we’ll send a HTTP POST request with JSON payload to the configured webhook URL.

Each webhook request sent by SEON is cryptographically signed to ensure the integrity and authenticity of the payload. The payload is signed using the HMAC-SHA256 algorithm. The signing key is the customer's license key, and the signature is sent in the Digest header. An example of this header would be the following: Digest: SHA-256=<hash>. To verify the digest, please hash the whole HTTP payload using the HMAC-SHA256 algorithm and compare it to the hash provided in the Digest header.

You can set up the events and webhook URLs in the Admin Panel of your Settings page.

Available events

Event	Description
transaction:status_update	Any time a transaction state has changed.
lists:blacklist-whitelist	Any value has been added to blacklist or whitelist or removed from them.

{
  "event": "transaction:status_update",
  "date": "2017-08-30T13:47:42+00:00",
  "transactions": [
    {
      "id": "e601f2dae8f9",
      "seon_id": 1488721,
      "state": "REVIEW"
    }
  ]
}

{
  "event": "lists:blacklist-whitelist",
  "date": "2017-08-30T13:47:42+00:00",
  "values": [
    {
      "data_field": "user_id",
      "value": "111",
      "state": "blacklist"
    },
    {
      "data_field": "user_id",
      "value": "222",
      "state": "whitelist"
    },
    {
      "data_field": "user_id",
      "value": "333",
      "state": "normal"
    }
  ]
}

Email API

Our Email API v2.1 aggregates hundreds of open and reachable social data sources to provide an in-depth email address investigation tool.

Free trial SEON customers get a maximum of 120 Email API requests / minute.

Request

The [email_address] in the request URI should include the full email address, for example: example@example.com

Optional query string parameters

Add the following parameters to the request URL for more control over the returned data, as seen in the example URL below.

GET

https://api.seon.io/SeonRestService/email-api/v2.1/[email_address]?include=history,flags,id&flags_timeframe_days=10&timeout=3000

Request Attributes	Value	Required
include	history	no

include	flags	no

include	id	no

flags_timeframe_days	[number of days]	no

timeout	[number of milliseconds]	no

HTTP Endpoint

GET

https://api.seon.io/SeonRestService/email-api/v2.1/[email_address]

Language

Industry

Use case

Response

The endpoint returns JSON structured response.

JSON Attributes	Type
email	string

score	number

deliverable	boolean

domain_details	object

account_details	object

breach_details	object

applied_rules	array of object

history	object

flags	array of object

id	string

Response

{
 "success": true,
 "error": {},
 "data": {
  "email": "example@example.com",
  "score": 80,
  "deliverable": false,
  "domain_details": {
   "domain": "example.com",
   "tld": ".com",
   "created": "1995-08-14 04:00:00",
   "updated": "2019-08-14 07:04:41",
   "expires": null,
   "registered": true,
   "registrar_name": null,
   "registered_to": null,
   "disposable": true,
   "free": false,
   "custom": false,
   "dmarc_enforced": false,
   "spf_strict": true,
   "valid_mx": false,
   "accept_all": false,
   "suspicious_tld": false,
   "website_exists": true
  },
  "account_details": {
   "facebook": {
    "url": null,
    "name": null,
    "photo": null,
    "registered": false
   },
   "google": {
    "photo": null,
    "registered": false
   },
   "apple": {
    "registered": false
   },
   "twitter": {
    "registered": false
   },
   "microsoft": {
    "registered": false
   },
   "yahoo": {
    "registered": false
   },
   "ebay": {
    "registered": false
   },
   "gravatar": {
    "registered": false
   },
   "instagram": {
    "registered": false
   },
   "spotify": {
    "registered": false
   },
   "tumblr": {
    "registered": false
   },
   "linkedin": {
    "url": null,
    "name": null,
    "company": null,
    "title": null,
    "location": null,
    "website": null,
    "twitter": null,
    "photo": null,
    "registered": false
   },
   "weibo": {
    "registered": false
   },
   "github": {
    "registered": false
   },
   "vimeo": {
    "registered": false
   },
   "flickr": {
    "registered": false
   },
   "foursquare": {
    "registered": false
   },
   "lastfm": {
    "registered": false
   },
   "myspace": {
    "registered": false
   },
   "pinterest": {
    "registered": false
   },
   "skype": {
    "country": null,
    "city": null,
    "gender": null,
    "name": null,
    "id": null,
    "handle": null,
    "bio": null,
    "age": null,
    "language": null,
    "state": null,
    "photo": null,
    "registered": false
   },
   "discord": {
    "registered": false
   },
   "ok": {
    "registered": false,
    "city": null,
    "age": null,
    "date_joined": null
   },
   "kakao": {
    "registered": false
   },
   "booking": {
    "registered": false
   },
   "airbnb": {
    "registered": false,
    "about": null,
    "created_at": null,
    "first_name": null,
    "identity_verified": null,
    "location": null,
    "image": null,
    "reviewee_count": null,
    "trips": null,
    "work": null
   },
   "amazon": {
    "registered": false
   },
   "qzone": {
    "registered": false
   }
  },
  "breach_details": {
   "breaches": null,
   "haveibeenpwned_listed": false,
   "number_of_breaches": null,
   "first_breach": null
  },
  "applied_rules": [
   {
    "id": "E100",
    "name": "Domain is disposable",
    "operation": "+",
    "score": 80
   }
  ],
  "history": {
   "hits": 1,
   "customer_hits": 1,
   "first_seen": 1576682328,
   "last_seen": 1576682328
  },
  "flags": [],
  "id": "a03fd029-4a9b-4010-97ee-8d1f5f5c0123"
 }
}

Email Verification API

Our Email Verification API lets you know whether an email address is valid or not, using a fast SMTP-MX check.

Free trial SEON customers get a maximum of 120 Email Verification API requests / minute.

Request

The [email_address] in the request URI should include the full email address, for example: example@example.com

Optional query string parameters

Add the following parameters to the request URL for more control over the returned data, as seen in the example URL below.

GET

https://api.seon.io/SeonRestService/email-verification/v1.0/[email_address]?include=id

Request Attributes	Value	Required
include	id	no

HTTP Endpoint

GET

https://api.seon.io/SeonRestService/email-verification/v1.0/[email_address]

Language

Industry

Use case

Response

The endpoint returns JSON structured response.

JSON Attributes	Type
valid_format	boolean

deliverable	boolean

inbox_full	boolean

domain_details	object

Response

{
  "success": true,
  "error": {},
  "data": {
    "valid_format": true,
    "deliverable": true,
    "inbox_full": false,
    "domain_details": {
      "domain": "example.com",
      "tld": ".com",
      "registered": true,
      "disposable": false,
      "free": false,
      "custom": true,
      "dmarc_enforced": false,
      "spf_strict": true,
      "valid_mx": true,
      "accept_all": false,
      "suspicious_tld": false,
      "website_exists": true,
      "created”: “1994-11-01 05:00:00",
      “updated”: “2019-05-07 20:09:37"
    }
  }
}

Phone API

Our Phone API combines numerous data sources to provide an in-depth phone number investigation tool. It aggregates open and reachable social and messenger data to flag fraudsters based on a phone number only.

Free trial SEON customers get a maximum of 120 Phone API requests / minute.

Request

The [phone_number] in the request URL should include the full phone number including country code. Cannot contain spaces or hyphens, the + sign is optional. The maximum length is 19 characters for the [phone_number]. For example: 36301234567

Optional query string parameters

In order to request additional or receive less information, use the following parameters in the request URL as in the example below:

GET

https://api.seon.io/SeonRestService/phone-api/v1.1/[phone_number]?include=history,flags,id&flags_timeframe_days=10&exclude=photo,last_seen&timeout=3000

Request Attributes	Value	Required
include	history	no

include	flags	no

include	id	no

include	cnam_lookup	no

include	hlr_details	no

flags_timeframe_days	[number of days]	no

exclude	photo	no

exclude	last_seen	no

timeout	[number of milliseconds]	no

HTTP Endpoint

GET

https://api.seon.io/SeonRestService/phone-api/v1.1/[phone_number]

Language

Industry

Use case

Response

The endpoint returns JSON structured response.

JSON Attributes	Type
number	integer

valid	boolean

type	string

country	string

carrier	string

score	number

account_details	object

applied_rules	array of object

hlr_details	object

cnam_details	object

history	object

flags	array of object

id	string

Response

{
 "success": true,
 "error": {},
 "data": {
  "number": 36301234567,
  "valid": true,
  "type": "MOBILE",
  "country": "HU",
  "carrier": "T-Mobile",
  "score": 0,
  "account_details": {
   "facebook": {
    "registered": true
   },
   "google": {
    "registered": true
   },
   "instagram": {
    "registered": true
   },
   "twitter": {
    "registered": true
   },
   "yahoo": {
    "registered": true
   },
   "telegram": {
    "registered": false,
    "last_seen": null,
    "photo": null
   },
   "whatsapp": {
    "registered": true,
    "about": "Hey there! I am using WhatsApp.",
    "last_seen": 1559825148,
    "photo": "/9j/4AAQSkZJRgABAQAAAQAB..."
   },
   "viber": {
    "registered": true,
    "name": "Sample Name",
    "last_seen": 1564948016,
    "photo": "/9j/4AAQSkZJRgABAQAAAQAB..."
   },
   "kakao": {
    "registered": false
   },
   "ok": {
    "registered": false
   },
   "zalo": {
    "registered": false
   },
   "line": {
    "registered": false,
    "name": null,
    "photo": null
   },
   "microsoft": {
    "registered": false
   },
   "snapchat": {
    "registered": false
   },
   "skype": {
    "registered": false,
    "age": null,
    "city": null,
    "bio": null,
    "country": null,
    "gender": null,
    "language": null,
    "name": null,
    "handle": null,
    "id": null,
    "photo": null,
    "state": null
   }
  },
  "applied_rules": [
   {
    "id": "PH100",
    "name": "At least 2 online profiles were found",
    "operation": "+",
    "score": 0
   }
  ],
  "history": {
   "hits": 19,
   "customer_hits": 2,
   "first_seen": 1572825600,
   "last_seen": 1572825600
  },
  "flags": [
   {
    "note": "Sample note added by Admin user",
    "date": 1572858397,
    "industry": "Airline company"
   },
   {
    "note": "",
    "date": 1571319439,
    "industry": "Online gambling operator"
   }
  ],
  "id": "71585377-4b5c-4fba-bc42-785bb6889c59"
 }
}

IP API

Fraudsters bypass IP address bans with proxies and VPNs. This API determines how likely an IP address is to be faked using modern computing techniques, so you can block TOR, VPN and proxy users. This reduces ATO (account takeover), spyware, malware, criminal netblocks, botnets, spammers and exploit scanners.

Free trial SEON customers get a maximum of 120 IP API requests / minute.

Request

The [ip] in the request URI should include the full IP address, example: 1.1.1.1.

Optional query string parameters

In order to request additional or receive less information, use following parameters in the request URL as in the example below:

GET

https://api.seon.io/SeonRestService/ip-api/v1.1/[ip]?include=history,flags,id&flags_timeframe_days=10

Request Attributes	Value	Required
include	history	no

include	flags	no

include	id	no

flags_timeframe_days	[number of days]	no

HTTP Endpoint

GET

https://api.seon.io/SeonRestService/ip-api/v1.1/[ip]

Language

Industry

Use case

Response

The endpoint returns JSON structured response.

JSON Attributes	Type
ip	string

score	number

country	string

state_prov	string

city	string

timezone_offset	string

isp_name	string

latitude	string

longitude	string

type	string

open_ports	array

tor	boolean

harmful	boolean

vpn	boolean

web_proxy	boolean

public_proxy	boolean

spam_number	integer

spam_urls	array

applied_rules	array of object

history	object

flags	array of object

id	string

Response

{
 "success": true,
 "error": {},
 "data": {
  "ip": "1.1.1.1",
  "score": 100,
  "country": "HK",
  "state_prov": "Hong Kong",
  "city": "Hong Kong",
  "timezone_offset": "+08:00",
  "isp_name": "APNIC and CloudFlare DNS Resolver Project",
  "latitude": 22.28552,
  "longitude": 114.15769,
  "type": "CDN",
  "open_ports": [
   80
  ],
  "tor": false,
  "harmful": false,
  "vpn": false,
  "web_proxy": false,
  "public_proxy": false,
  "spam_number": 3,
  "spam_urls": [
   "bl.emailbasura.org",
   "l2.apews.org",
   "dyna.spamrats.com"
  ],
  "applied_rules": [
   {
    "id": "P102",
    "name": "Port 80 is open on the IP address",
    "operation": "+",
    "score": 1
   },
   {
    "id": "P100",
    "name": "There is 1 suspicious open port on the IP address",
    "operation": "+",
    "score": 4
   },
   {
    "id": "P109",
    "name": "IP address was found on 3 spam blacklists",
    "operation": "+",
    "score": 2
   }
  ],
  "history": {
   "hits": 3,
   "customer_hits": 1,
   "first_seen": 1573567581,
   "last_seen": 1573639346
  },
  "flags": [
   {
    "note": "Blacklisted by API",
    "date": 1573138956,
    "industry": "Online gambling operator"
   }
  ],
  "id": "b06c5055-d1bf-4400-b2c9-ab3edd7171d6"
 }
}

Errors

Application Errors

Error Code	Explanation
1000	Empty request body.
1001	Incorrect config object: `[data_field_name]` should be sent as `[format]`.
1002	Invalid IP address.
1005	Invalid public key.
1006	Invalid input json.
1009	Invalid email address.
1014	Invalid phone number.
2000	Invalid authorization header.
2001	Missing license key.
2002	Invalid license key.
2003	Your subscription has ended.
2004	Inactive license.
2006	Requested feature `[feature_name]` is not enabled.
3000	Incorrect type: `[data_field_name]` should be sent as `[format]`.
3001	Incorrect value: `[data_field_name]` is invalid.
3002	Incorrect value: `[data_field_name]` should be sent as one of `[value-1]`, `[value-2]`.
3003	Length error: `[data_field_name]` size must be between `[minimum_value]` and `[maximum_value]`.
3004	`transaction_amount` not provided along with `transaction_currency`.
3005	Unrecognized property: `[data_field_name]`. Please check the documentation for supported properties.

Response

{
 "success": false,
 "data": {},
 "error": {
  "message": "empty request body",
  "code": "1000"
 }
}

Changelog

Update 2021-06-15

Service changes

Email API v2.1 has been released with new supported online platforms: discord, ok, kakao, booking, airbnb, amazon, qzone. Using the v2.1 changes the account_details in the API response. Version differences:
- All supported online platforms for Email API v2.1: facebook, google, apple, twitter, microsoft, yahoo, ebay, gravatar, instagram, spotify, tumblr, linkedin, weibo, github, vimeo, flickr, foursquare, lastfm, myspace, pinterest, skype, discord, ok, kakao, booking, airbnb, amazon, qzone
- All supported online platforms for Email API v2.0: facebook, google, apple, twitter, microsoft, yahoo, ebay, gravatar, instagram, spotify, tumblr, linkedin, weibo, github, vimeo, flickr, foursquare, lastfm, myspace, pinterest, skype

Update 2021-06-10

Service changes

Phone API v1.1 has been released with new supported online platforms: zalo, line, kakao, microsoft, ok, skype, snapchat. Using the v1.1 changes the account_details in the API response. Version differences:
- All supported online platforms for Phone API v1.1: zalo, line, kakao, microsoft, ok, skype, snapchat, facebook, google, instagram, twitter, yahoo, telegram, whatsapp, viber
- All supported online platforms for Phone API v1.0: facebook, google, instagram, twitter, yahoo, telegram, whatsapp, viber
HMAC Signature added for service webhook events.

Update 2021-03-24

New admin features

Advanced rule management implemented with the ability to duplicate, activate, deactivate multiple rules and copy them from or to your Sandbox account (Scoring Engine).
Cardholder full name added to Customer connections (Transaction details page / Customer connections).

Update 2021-02-25

New admin features

Ability to exclude users from rules based on User ID, Email address, Card hash and IP address (Scoring Engine, Customer details and Transaction details page).
Case-insensitivity added to additional rule parameter settings in Compare and Data match type rules (Scoring Engine).

Service changes

Optional case-insensitivity in Compare and Data match type rules.

Update 2021-02-17

New admin features

If condition option added for all aggregates in velocity rules (Scoring Engine).
Add applied rules to Velocity IF conditions (Scoring Engine).
Phone score added to Compare rules (Scoring Engine).
Email score, IP score, Phone score added to Velocity rule Present field and Past field options (Scoring Engine).
Compare to current value and Compare to historical value options added for velocity conditions (Scoring Engine).
Advanced time frame option added to Velocity rules to calculate on past time frames (Scoring Engine).
Comparison of two time frames added to Velocity rules (Scoring Engine).
Phone country, Item store country, Merchant country, Receiver full name, Item custom fields added to Data match rules (Scoring Engine).
Enforce two-factor authentication (2FA) for all users option added (Settings page).
Export function (CSV) added for logs (Logs page).
Team Activity widget on the Dashboard is now restricted to read permission for logs (Team / Role Groups).
Login with credentials is now disabled for users using Single sign-on (SSO) authentication.
IP restriction added to settings (Settings page).
Warning message added for rule parameter limitations (Scoring Engine).

Update 2021-02-05

Service changes

IP restriction option added to Service.
Advanced velocity rule features Service side implementation.
Async Fraud API v2.0 requests support added.
New endpoint added for Zapier integration.
Data match rule applying improvements.
Rule applying backward compatibility added in Fraud API v2.0 for user_dob sent in custom_fields (Equivalent to User date of birth field, user_dob).
Case insensitive comparison for data match rules containing User full name, Card holder full name, Shipping full name, Receiver full name.

Update 2021-02-01

New admin features

Single sign-on (SSO) authentication support added to Admin Panel (Settings page).

Update 2021-01-18

Service changes

Client Certificate support added for the REST Service.

Update 2020-11-13

New admin features

Custom fields compatibility added to Velocity rules (Scoring Engine).
Timezone offset compatibility added to data match rules (Scoring Engine).
COP - Colombian Pesos - added to currencies (Settings page).
Option to only train Machine Learning on feedback labels added to Settings (Settings page).
User full name and DOB (User date of birth) added to Customer connections (Transaction details page / Customer connections).
IP location and Card country added to Addresses widget (Transaction details page).
Cookie hash, Browser hash, Card hash added to Lists status popup (Transaction details page).
HLR and CNAM lookups added to manual queries if the functionality is turned on for the account. These requests have additional fees, please contact us for more details. (Manual page).

Update 2020-09-28

Service changes

Erase API introduced.

Update 2020-09-07

New admin features

Lists page custom expiration days support added.
WebGL vendor added to filters.

Update 2020-08-24

Service changes

Self-Exclusion API DELETE request introduced.

Update 2020-08-13

New admin features

Manual page added for Intelligence tool users.

Update 2020-06-16

Service changes

Fraud API v2.0 has been released.
hlr_details and cnam_lookup optional query string parameters were added to Phone API. Requests with these parameters have additional fees, please contact us for more details.
custom_fields (formerly used as user_label) support added to Lists.
Case insensitivity added to user_name, user_fullname, user_city, user_region, user_street values in velocity rules.
Email Verification API introduced.
custom_fields (formerly used as user_label), amount_in_eur fields are now supported in velocity rules.

Data field mapping from Fraud API v1.0 to v2.0:

proxy_score -> ip_details/score
ip_details/ip_country -> ip_details/country
ip_details/ip_state_prov -> ip_details/state_prov
ip_details/ip_city -> ip_details/city
ip_details/ip_latitude -> ip_details/latitude
ip_details/ip_longitude -> ip_details/longitude
ip_details/ip_isp_name -> ip_details/isp_name
ip_details/ip_timezone_offset -> ip_details/timezone_offset
email_details/email_score -> email_details/score
email_details/email_exists -> email_details/deliverable
email_details/disposable -> email_details/domain_details/disposable
email_details/free -> email_details/domain_details/free
email_details/domain_exists -> email_details/domain_details/website_exists
email_details/email_domain_details -> email_details/domain_details
email_details/email_domain_details/domain -> email_details/domain_details/domain
email_details/email_domain_details/suffix -> email_details/domain_details/tld
email_details/email_domain_details/created -> email_details/domain_details/created
email_details/email_domain_details/updated -> email_details/domain_details/updated
email_details/email_domain_details/registered -> email_details/domain_details/registered
email_details/email_account_details -> email_details/account_details
email_details/email_account_details/facebook_exists -> email_details/account_details/facebook/registered
email_details/email_account_details/facebook_profile -> email_details/account_details/facebook/url
email_details/email_account_details/facebook_name -> email_details/account_details/facebook/name
email_details/email_account_details/facebook_photo -> email_details/account_details/facebook/photo
email_details/email_account_details/google_exists -> email_details/account_details/google/registered
email_details/email_account_details/google_profile -> removed
email_details/email_account_details/google_name -> removed
email_details/email_account_details/google_photo -> email_details/account_details/google/photo
email_details/email_account_details/apple_exists -> email_details/account_details/apple/registered
email_details/email_account_details/twitter_exists -> email_details/account_details/twitter/registered
email_details/email_account_details/microsoft_exists -> email_details/account_details/microsoft/registered
email_details/email_account_details/yahoo_exists -> email_details/account_details/yahoo/registered
email_details/email_account_details/ebay_exists -> email_details/account_details/ebay/registered
email_details/email_account_details/gravatar_exists -> email_details/account_details/gravatar/registered
email_details/email_account_details/instagram_exists -> email_details/account_details/instagram/registered
email_details/email_account_details/spotify_exists -> email_details/account_details/spotify/registered
email_details/email_account_details/tumblr_exists -> email_details/account_details/tumblr/registered
email_details/email_account_details/linkedin_exists -> email_details/account_details/linkedin/registered
email_details/email_account_details/weibo_exists -> email_details/account_details/weibo/registered
email_details/email_account_details/vk_exists -> removed
email_details/email_account_details/haveibeenpwned_exists -> email_details/breach_details/haveibeenpwned_listed
email_details/email_account_details/number_of_breaches -> email_details/breach_details/number_of_breaches
email_details/email_account_details/first_breach -> email_details/breach_details/first_breach
phone_details/phone_number -> phone_details/number
phone_details/phone_is_valid -> phone_details/valid
phone_details/phone_is_possible -> removed
phone_details/phone_type -> phone_details/type
phone_details/phone_country -> phone_details/country
phone_details/phone_carrier -> phone_details/carrier

Update 2020-04-08

Service changes

flags_timeframe_days, exclude, timeout query string parameters added to Email API, Phone API and IP API.
Username - User full name and Email - User full name similarity calculation updated in Compare rules.
Email, user name, user address hash similarity support added to Velocity rules.
user_label field support added to data match rules.

Update 2020-02-17

New admin features

Phone number flagging support added to Phone widget.
Dropdown selector added for Device type and IP type (Scoring Engine, Filters).
Custom URLs is now recognised as links on widgets (User labels, Order details / Details URL).
Self exclusion rules moved into a separate Exclude rules category.

Update 2020-01-13

New admin features

State conflict settings added (Settings page).
Batch test maximum number of records increased to 30 000 (Manual Page / Batch Test).
Phone API runner added to Phone widget (Transaction details page / Customer details page).
IP and Phone widget updated (Transaction details page / Customer details page).
Action type, Phone type, IP timezone offset, Timezone offset filters improved (Transactions / Filters, Customers / Filters)
Public proxy, VPN data fields added to Scoring Engine (Scoring Engine).
Phone API v1.0 data fields added to Scoring Engine (Scoring Engine).
Bulk selection added to Activity (Transaction details page / Activity).
Card country code data field renamed to Card country, Card country removed from Admin Panel (All pages).

Update 2019-11-22

New admin features

Phone API statistics added to user menu and Billing Details (Billing Details).
Transaction list export limit increased to 30 000 records (Transactions / Exports).
Quick filter for address hashes added (Transaction details page).

Update 2019-11-13

Service changes

IP API v1.0 added to Service.
Optional query string parameters added to Phone API and IP API.

Update 2019-10-30

New admin features

Applied rule notification added (My Account / Notifications).
Modify score by velocity value function added to Scoring Engine (Scoring Engine).
Multiple distinct values support added to Velocity rules (Scoring Engine).
Additional ordering added to New risky transactions (Workbench / New Risky Transactions).
Warning added if session arrived later than the transaction (Transaction details page).
Rule tester accuracy calculation improved (Rule edit page).
View on Google link removed from Email widget, since Google+ was shut down (Transaction details page).
Deleted rules got labelled on Applied Rule Statistics (Scoring Engine / Dashboard).
Separate user id sequencing for customers added (Team).

Update 2019-10-18

Service changes

Phone API v1.0 added to Service.

Update 2019-10-09

New admin features

Scoring Engine page updated. Rule categorizing and filtering added, new Applied Rule Statistics widget introduced on Scoring Engine Dashboard (Scoring Engine).
Default rule configuration added to Scoring Engine (Scoring Engine / Default Rules).

Update 2019-09-30

Service changes

Multiply and divide functions removed from Scoring Engine.
Modify score by velocity value function added.
Multiple distinct values support added to Velocity rules.
Phone number input validation added.
Using Domain update date when Domain creation date not available.

Update 2019-09-10

Service changes

Default rules got configurable.
Missing user_id generated from user_name or email address.
Separate rule id sequencing for customers added.
Lowercase country code support added.
API request field length validation added. The maximum length of all request parameters is 100 characters, except 64 characters for session_id.

Update 2019-08-15

New admin features

Previous months view added to Billing Details page (Billing Details).
Merchants page added (Merchants).
New device fingerprinting fields added to Admin Panel, device widget updated.
New action types added to Filters, Scoring Engine.
Previously sent User label field options added to Filters, Scoring Engine.
Canceled invoices got highlighted (Billing Details).
Optional payment mode statistics added to Dashboard.
Currency dropdown added to Filters, Scoring Engine.
Sandbox restriction added to user options (Team).
Hiding all email_account_details information on Admin Panel optionally.
Public keys added to profile information (My Account page).

Update 2019-08-05

Machine learning changes

ML rule names converted to human-readable format.

Update 2019-07-26

Service changes

Hiding email_account_details optionally.
Gift (boolean) and Gift message (boolean) input fields validation added to Service.

Update 2019-07-19

Machine learning changes

New device fingerprinting fields added to Machine learning algorithm.

Update 2019-07-11

Service changes

New device fingerprinting fields added to Scoring Engine.

Update 2019-06-21

Service changes

Does not contain operator added to Compare rules.
New action types added to service: add_item_to_cart, remove_item_from_cart, add_promotion, create_content, account_logout, submit_Review, update_content, verification
Count current transaction option added to Scoring Engine.

New admin features

Count current transaction option added to Velocity and User behavior rules (Scoring Engine).

Update 2019-06-13

New admin features

Sandbox environment option implemented.
Notification enabled for all user types.

Update 2019-05-16

Service changes

Percentage comparison added to Scoring Engine.

New admin features

Percentage comparison added to Velocity rules (Scoring Engine).

Update 2019-05-10

New admin features

Manual page UI updated (Manual page).
Team activity widget added to Dashboard (Dashboard).
LinkedIn profile link added to Email widget (Transaction details page).
Ability to add multiple billing emails (Billing details page).

Update 2019-04-25

New admin features

Exclude customer feature added (Transaction details page).
Logging extended with direct links (Logs page).

Update 2019-03-29

New admin features

Workbench page added.
New supported currencies: KZT, VND, BYN, UAH, AZN, BTC, ETH, BCH, XRP, LTC, USDT.

Update 2019-03-18

New admin features

Separate commenting added to Notes widget (Transaction details page).

Update 2019-02-14

New admin features

New data field added to Scoring Engine called “Missing device details” (Scoring Engine).
Profile pictures added to team members (Team).
Affected transactions and affected amount added to machine learning complex rules (Scoring Engine / Machine learning).

Update 2019-01-24

New admin features

Role groups added to Team with customizable roles and permissions (Team / Role groups).
Readable names and numbering added to user devices (Activity tab).
Dropdown selector added to country data fields (Transactions / Filters, Scoring Engine).

Update 2018-12-21

Service changes

Count of numbers and count of numbers in a row added to email handle / username analysis.
Disposable email check for subdomains.

New admin features

Quick search added to transaction list (Transactions page).
Readable names and numbering added to user devices in Devices & OS widget (Transaction details page).
Count of numbers and count of numbers in a row in email handle / username added to filters (Transactions page).
Count of numbers and count of numbers in a row in email handle / username added to Scoring Engine (Scoring Engine).

Update 2018-11-20

Service changes

Turn on machine learning rules over a certain accuracy.

New admin features

Filters for machine learning rules (Scoring Engine / Machine learning).
Set accuracy to auto deploy machine learning rules (Settings page).
State change with label selection (Transactions page).
First seen value added to Identity widget (Transaction details page).
Machine learning rule details design update (Scoring Engine / Machine learning).

Update 2018-10-15

New admin features

User specific notification settings (My account / Notifications).
Base currency added to every currency dropdown.

Update 2018-09-25

Service changes

Default IP expiration time added to service.

New admin features

Email handle / username analysis added to widgets (Transaction details page).
Email handle / username analysis added to filters (Transactions page).
Action type, rule type filter added to machine learning rules (Scoring Engine / Machine learning).
Rule export functionality added (Scoring Engine).

Update 2018-09-14

Service changes

Lists API added to service. It is able to blacklist/normal/whitelist all data fields.
Email handle, username, full name similarity and analysis added to Scoring Engine.
JavaScript boolean field removed from request. No longer needed in requests. Backward compatibility provided.

New admin features

Email handle, username, full name similarity and analysis added to Filters (Transactions / Filters).
Base currency added to currency selectors.

Update 2018-09-04

Service changes

VKontakte added to Email API response and Scoring Engine.

New admin features

Email handle, username, full name similarity and analysis added to widgets (Transaction details page).
VKontakte result added to Email widget (Transaction details page).
VKontakte added to Scoring Engine (Scoring Engine / Rule).

Update 2018-08-07

Service changes

Automatic billing implemented.
Automatic boarding process implemented.
New fields added to Scoring Engine: Shipping method, Discount code, IP latitude, IP longitude, Card issuer, Card country, Phone possible, Email exists, Email disposable, Email free, Have I been pwned? exists, Data breaches, First breach, Domain suffix, Domain registered, Domain creation date, Domain updated, Tor, HTTP proxy, Web proxy, Open ports, IP blacklist names, IP blacklist number, Datacenters, Plugin names, Logged in social sites, DNS IP Country, DNS IP ISP, WebRTC count, Transaction amount (exchanged).

New admin features

Rule history added to Scoring Engine (Scoring Engine / Rule).
Currency selector added to statistics (Transactions / Statistics).
Locale settings added to format dates and numbers (Settings page).
Billing details added to Admin Panel (Billing page).

Update 2018-06-15

Service changes

Transaction amounts are now saved in the account’s default currency too.

New admin features

Ability to modify list columns (Transactions page).
Set default currency for the admin interface (Settings page).
Filter for exchanged transaction amount based on the default currency (Transactions page).

Update 2018-06-01

Service changes

Heuristic rules inspect all data fields.
Automatically turn on heuristic rules over a certain accuracy.

New admin features

Instant Google search added to Email widget (Transaction details page).
Downloadable User Guide and Product Features documents added to support page (Support page).

Update 2018-04-26

Service changes

Ability to label multiple transactions at the same time.

New admin features

Ability to turn off flagging feature (Settings page).
Airline specific widgets added to Transaction details page (Transaction details page).
Action type filtering added to rule list (Scoring Engine / Custom rules).
Transaction list page update with viewed, not-viewed-yet sign (Transactions page).
Registration score added to Identity widget (Transaction details page).

Update 2018-04-10

Service changes

Machine learning rule generation added to Scoring Engine.
Automatic flagging option for blacklisted values.
The ‘ip_connection_type’ attribute was removed from API response.

New admin features

Rule tester added to Rule editor (Scoring Engine / Rule).
Auto flag blacklisted values option added (Settings page).
Admin Panel tutorial added (Tutorial menu).
Multiple row selection added (Transactions, Customers, Rules)

Update 2018-03-20

Service changes

“type” attribute added to device_details Object. If the request is sent through one of our SDKs, the device_details object changes accordingly.
Heuristic rules added to Scoring Engine.
Flagged values added to Scoring Engine.
Scoring Engine compare type rules now can handle IP ranges.

New admin features

New “Raw data” tab added in order to inspect API requests and responses (Transaction Detials page).
Customer Connections multiple datapoint selection added (Transaction Details page).
Machine learning settings added in order to set bad and negative labels and heuristic rule data points (Settings page).
Machine learning tab added to scoring engine (Scoring Engine page).

Update 2018-02-28

Service changes

Flagging feature added.

New admin features

Email address, IP address and Browser Hash can be flagged from the Admin Panel (Transaction Detials page).
Flagged as suspicious page added (Lists page).

Update 2018-02-09

Service changes

IPv6 support added to Fraud and Proxy API.

New admin features

Blacklist page filter added (Lists page).
Quick filter added to blacklist page (Lists page).
Customer Status widget impoved with comments and expiration date options (Transaction Detials page).
Lockable filters to transaction and customer filtering (Transaction page, Customers page).

Update 2017-11-20

Service changes

The way of authentication has been changed, from now on header authentication is used. Our deprecated version of authentication (POST payload) is also available until 28th of February 2018.
js_ip, js_ip_country, js_ip_isp has been added to device_details in Fraud API response. JS IP is the user’s IP address where the session data is coming from.

Update 2017-11-09

Service changes

Added support for blacklisting/whitelisting multiple user ID-s with one API request.
Since Yahoo no longer supports creation date information, we removed the attribute from our API response.
Weibo has been added to our Email API.
Device timezone format has been changed in our API response (“timezone”: “+2:00”).
The fraud_score, email_score and proxy_score format has changed to number in our API response.

New admin features

Quick blacklisting/whitelisting in the new Customer status pop-up (Transaction Detials page).
Applied velocity rule details can be seen in the Applied rules widget (Transaction Detials page).
Filtering tool has been updated (Transactions).

Update 2017-10-06

API request changes

From now on you can call our Fraud API’s label parameters with: “true”, true, 1, “1”, false, “false”,0,“0”. Parameters: label_email, label_address, label_fingerprints, label_ip, label_phone.

Data point name changes

fonts_as_string -> font_names
logged_in_social_sites -> social_sites

Response format changes

webrtc_ips, logged_in_social_sites, social_sites are now in JSON format.

Device details timezone

Device Fingerprinting: Released version v2.0 of our agent JS / Device Fingerprint modul, extended with browser based social media data.

New admin features

Email notification option from now allows you to notify you in certain events (My account / Notifications).
Scoring Engine update with new grouping, AND/OR operators function (Scoring Engine).
Instant chat support (Every page bottom right corner).
Webhook function for transaction state changes (Settings / Webhook settings).
New customer status widget for better data point blacklisting (Transaction Details page).
Qucik filter button added to every data point for faster search (Transaction Details page).

Deprecated versions

Fraud API v1.0

Request

SEON’s Fraud API is the core end-to-end solution designed to reduce fraud. It includes all our module APIs, but you can enable or disable them such as the Email API or the device fingerprint function via JavaScript snippet. It supports business-specific data fields for scores, using the user_label.

JSON Attributes	Type	Required
ip	string	no

action_type	string	no

transaction_id	string	no

affiliate_id	string	no

affiliate_name	string	no

user_order_memo	string	no

run_email_api	boolean	no

email	string	no

email_domain	string	no

password_hash	string	no

user_fullname	string	no

user_name	string	no

user_id	string	no

user_created	integer	no

user_country	string	no

user_city	string	no

user_region	string	no

user_zip	string	no

user_street	string	no

user_street2	string	no

session_id	string	no

device_id	string	no

payment_mode	string	no

card_fullname	string	no

card_bin	string	no

card_hash	string	no

card_last	string	no

avs_result	string	no

cvv_result	boolean	no

phone_number	string	no

transaction_type	string	no

transaction_amount	float	no

transaction_currency	string	no

items	array of item objects	no

shipping_country	string	no

shipping_city	string	no

shipping_region	string	no

shipping_zip	string	no

shipping_street	string	no

shipping_street2	string	no

shipping_phone	string	no

shipping_fullname	string	no

shipping_method	string	no

billing_country	string	no

billing_city	string	no

billing_region	string	no

billing_zip	string	no

billing_street	string	no

billing_street2	string	no

billing_phone	string	no

discount_code	string	no

gift	boolean	no

gift_message	boolean	no

merchant_id	string	no

merchant_created_at	integer	no

merchant_country	string	no

details_url	string	no

user_label	object	no

Warning!

The maximum length of all request parameters is 100 characters, except 64 characters for session_id and 19 characters for the phone number.

HTTP Endpoint

POST

https://api.seon.io/SeonRestService/fraud-api/v1.0/

Language

Industry

Use case

Response

The endpoint returns JSON structured response.

JSON Attributes	Type
id	string

state	string

fraud_score	number

proxy_score	number

ip_details	object

email_details	object

bin_details	object

phone_details	object

version	string

applied_rules	array of object

device_details	object

calculation_time	integer

seon_id	integer

Response

{
 "success": true,
 "error": {},
 "data": {
  "id": "213-321",
  "state": "APPROVE",
  "fraud_score": 4.24,
  "proxy_score": 0.6,
  "ip_details": {
   "ip": "192.0.2.0",
   "ip_country": "HU",
   "ip_state_prov": "Budapest",
   "ip_city": "Budapest",
   "ip_timezone_offset": "+2:00",
   "ip_isp_name": "UPC Magyarorszag Kft.",
   "ip_latitude": 47.4861,
   "ip_longitude": 19.0669
  },
  "email_details": {
   "email": "example@example.com",
   "email_score": 5.52,
   "email_exists": true,
   "disposable": false,
   "free": false,
   "domain_exists": true,
   "email_domain_details": {
    "domain": "example.com",
    "suffix": ".com",
    "registered": true,
    "created": null,
    "updated": null
   },
   "email_account_details": {
    "facebook_exists": false,
    "facebook_profile": null,
    "facebook_name": null,
    "facebook_photo": null,
    "google_exists": false,
    "google_profile": null,
    "google_name": null,
    "google_photo": null,
    "apple_exists": false,
    "twitter_exists": false,
    "microsoft_exists": false,
    "yahoo_exists": false,
    "ebay_exists": false,
    "gravatar_exists": false,
    "instagram_exists": false,
    "spotify_exists": false,
    "tumblr_exists": false,
    "linkedin_exists": false,
    "haveibeenpwned_exists": false,
    "weibo_exists": false,
    "vk_exists": false,
    "number_of_breaches": 0,
    "first_breach": null
   }
  },
  "bin_details": {
   "card_bin": "550000",
   "bin_bank": "NORTHERN NECK STATE BANK",
   "bin_card": "VISA",
   "bin_type": "DEBIT",
   "bin_level": "BUSINESS",
   "bin_country": "UNITED STATES",
   "bin_countrycode": "US",
   "bin_website": "",
   "bin_phone": "(804) 435-1626",
   "bin_valid": true,
   "card_issuer": "VISA"
  },
  "phone_details": {
   "phone_number": "+36704316088",
   "phone_is_valid": true,
   "phone_is_possible": true,
   "phone_type": "MOBILE",
   "phone_country": "HU",
   "phone_carrier": "Vodafone"
  },
  "version": "v1.0",
  "applied_rules": [
   {
    "id": "3",
    "name": "IP country does not match with billing country",
    "operation": "+",
    "score": 2
   }
  ],
  "device_details": {
   "type": "web",
   "session_id": "de153dd3996e46ce84b32fda82208f4e",
   "source": "js-3.1-op",
   "cookie_hash": "61d786b165b74e15d8c55b1e96a8cdb3",
   "region_timezone": "+02:00",
   "cookie_enabled": true,
   "os": "MacOS",
   "flash_enabled": false,
   "java_enabled": false,
   "device_type": "desktop",
   "private": false,
   "webrtc_activated": false,
   "webrtc_count": 0,
   "webrtc_ips": [],
   "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.100 Safari/537.36",
   "window_size": "1060x649",
   "screen_resolution": "2048x1152",
   "screen_available_resolution": "2048x1129",
   "screen_color_depth": 24,
   "screen_pixel_ratio": 1,
   "plugin_count": 3,
   "plugin_list": [
    "Chrome PDF Plugin",
    "..."
   ],
   "plugin_hash": "9c33fe15e3ec251f799666de471de1e9",
   "browser_hash": "4ab1d9549382520af59f4bce9db31ace",
   "browser": "CHROME",
   "browser_version": "76.0.3809.100",
   "font_count": 27,
   "font_list": [
    "Andale Mono",
    "..."
   ],
   "font_hash": "0f7664682b2a6c3baeda70c094658dac",
   "device_hash": "e4e3dcc9c15debf45dd09f2683012356",
   "touch_support": false,
   "device_memory": 8,
   "hardware_concurrency": 4,
   "platform": "MacIntel",
   "region_language": "hu",
   "webgl_hash": "9908db6eb8007ad94e0f8dc0fa974fb4",
   "webgl_vendor": "Intel Inc.~Intel(R) Iris(TM) Plus Graphics 650",
   "audio_hash": "124.04345808873768",
   "do_not_track": false,
   "adblock": false,
   "battery_level": 58,
   "battery_charging": false,
   "canvas_hash": "48bfc395be892bba7d9d8abc68f83450",
   "dns_ip": "89.134.46.85",
   "dns_ip_country": "HU",
   "dns_ip_isp": "Sample Service Provider",
   "device_ip_address": "80.99.46.168",
   "device_ip_country": "HU",
   "device_ip_isp": "Sample Service Provider",
   "accept_language": [
    "en-us",
    "..."
   ]
  },
  "calculation_time": 554,
  "seon_id": 1505147
 }
}

Errors for Fraud API v1.0

Error Code	Explanation
1000	Empty request body.
1001	IP address is missing.
1002	IP address is invalid.
1003	License key is missing.
1004	License key is invalid.
1005	Invalid public key.
1006	JSON input is invalid.
1008	Missing email address.
1009	Invalid email address.
1010	Invalid authorization header.
1011	Inactive license.
1012	Your subscription has ended.
2001	System database error.
3000	`[data_field_name]` size must be between `[minimum_value]` and `[maximum_value]`.
3001	Invalid ‘user_created’ input parameter.
3002	Invalid ‘cvv_result’ input parameter.
3003	Invalid ‘transaction_amount’ input parameter.
3004	Invalid ‘items_quantity’ input parameter.
3005	Invalid ‘items_price’ input parameter.
3006	Invalid ‘merchant_created_at’ input parameter.
3007	Invalid ‘action_type’ input parameter.
3008	‘transaction_amount’ not provided along with ‘transaction_currency’.
3009	Invalid ‘gift’ input parameter.
3010	Invalid ‘gift_message’ input parameter.

Migration from Fraud API v1.0 to v2.0

New config object for Fraud API

run_email_api field in input is deprecated for v2.0, Email API should be set in config object (set email_api: true).
IP API won’t be executed by default, need to set explicitly in config object. (set ip_api: true).
Device fingerprint won’t be enabled by default, need to set explicitly in config object. (set device_fingerprinting: true).
Phone API is supported for Fraud API. (set phone_api: true).

Session Handling

Instead of the session_id you need to send the encrypted payload returned by the SDK (supported by JS Agent v4, iOS SDK 3.0.0, Android SDK 3.0.0). The session_id parameter is still required for the configuration, the change affects the data that you need to send in the Fraud API request related to the Device Fingerprint module.
The previous SDK versions are still supported with the session_id field, but we highly recommend to migrate the Device Fingerprint module.
The public key is no longer necessary with the latest SDK versions.
You must set device_fingerprinting: true in the config object to enable the feature.

Keep in mind the following input fields were renamed in Fraud API v2.0:

user_label -> custom_fields
item_user_label -> item_custom_fields
user_order_memo -> order_memo

Response changes: Please find the full data field mapping from Fraud API v1.0 to v2.0 here.

Email API v1.0

Request

JSON Attributes	Type	Required
email	string	yes

HTTP Endpoint

POST

https://api.seon.io/SeonRestService/email-api/v1.0/

Language

Industry

Use case

Response

The endpoint returns JSON structured response.

JSON Attributes	Type
email	string

email_score	number

email_exists	boolean

disposable	boolean

free	boolean

domain_exists	boolean

email_domain_details	object

email_account_details	object

Response

{
 "success": true,
 "error": null,
 "data": {
  "email": "example@example.com",
  "email_score": 5.52,
  "email_exists": false,
  "disposable": false,
  "free": false,
  "domain_exists": false,
  "email_domain_details": {
   "domain": "example.com",
   "suffix": ".com",
   "registered": true,
   "created": null,
   "updated": null
  },
  "email_account_details": {
   "facebook_exists": false,
   "facebook_profile": null,
   "facebook_name": null,
   "facebook_photo": null,
   "google_exists": false,
   "google_profile": null,
   "google_name": null,
   "google_photo": null,
   "apple_exists": false,
   "twitter_exists": false,
   "microsoft_exists": false,
   "yahoo_exists": false,
   "ebay_exists": false,
   "gravatar_exists": false,
   "instagram_exists": false,
   "spotify_exists": false,
   "tumblr_exists": false,
   "linkedin_exists": false,
   "haveibeenpwned_exists": false,
   "weibo_exists": false,
   "vk_exists": false,
   "number_of_breaches": 0,
   "first_breach": null
  }
 }
}

Phone API v1.0

Request

The [phone_number] in the request URI should include the full phone number, including country code. Cannot contain hyphens or spaces, the + sign is optional. The maximum length for the [phone_number] is 19 characters. For example: 36301234567

Optional query string parameters

In order to request additional or receive less information, use following parameters in the request URL as in the example below:

GET

https://api.seon.io/SeonRestService/phone-api/v1.0/[phone_number]?include=history,flags,id&flags_timeframe_days=10&exclude=photo,last_seen&timeout=3000

JSON Attributes	Value	Required
include	history	no

include	flags	no

include	id	no

include	cnam_lookup	no

include	hlr_details	no

flags_timeframe_days	[number of days]	no

exclude	photo	no

exclude	last_seen	no

timeout	[number of milliseconds]	no

HTTP Endpoint

GET

https://api.seon.io/SeonRestService/phone-api/v1.0/[phone_number]

Language

Industry

Use case

Response

The endpoint returns JSON structured response.

JSON Attributes	Type
number	integer

valid	boolean

type	string

country	string

carrier	string

score	number

account_details	object

applied_rules	array of object

hlr_details	object

cnam_details	object

history	object

flags	array of object

id	string

Response

{
 "success": true,
 "error": {},
 "data": {
  "number": 36301234567,
  "valid": true,
  "type": "MOBILE",
  "country": "HU",
  "carrier": "T-Mobile",
  "score": 0,
  "account_details": {
   "facebook": {
    "registered": true
   },
   "google": {
    "registered": true
   },
   "instagram": {
    "registered": true
   },
   "twitter": {
    "registered": true
   },
   "yahoo": {
    "registered": true
   },
   "telegram": {
    "registered": false,
    "last_seen": null,
    "photo": null
   },
   "whatsapp": {
    "registered": true,
    "last_seen": 1559825148,
    "photo": "/9j/4AAQSkZJRgABAQAAAQAB..."
   },
   "viber": {
    "registered": true,
    "last_seen": 1564948016,
    "photo": "/9j/4AAQSkZJRgABAQAAAQAB..."
   }
  },
  "applied_rules": [
   {
    "id": "PH100",
    "name": "At least 2 online profiles were found",
    "operation": "+",
    "score": 0
   }
  ],
  "history": {
   "hits": 19,
   "customer_hits": 2,
   "first_seen": 1572825600,
   "last_seen": 1572825600
  },
  "flags": [
   {
    "note": "Sample note added by Admin user",
    "date": 1572858397,
    "industry": "Airline company"
   },
   {
    "note": "",
    "date": 1571319439,
    "industry": "Online gambling operator"
   }
  ],
  "id": "71585377-4b5c-4fba-bc42-785bb6889c59"
 }
}

JavaScript Agent v2.0

Our JavaScript Agent collects data through the browser for device fingerprinting purposes. Please follow the steps below to enable session and device data-collection with our JavaScript agent:

Include SEON JavaScript agent in your header, between <head> … </head> tags.
Insert the initialization code to the bottom of your page, just before the </body> tag.
Replace [session_id] with the unique identifier of user’s session.
We recommend to use onSuccess and onError callback functions to make sure that the data has been saved successfully. Fraud API requests initiated before the successful callback won’t be able to reference the collected device data.

Note

Including the lightweight JavaScript agent is optional, but it provides in-depth analysis for each user.

Options

JSON Attributes	Type	Default
social_detection	boolean	false

audio_fingerprint	boolean	false

use_flash	boolean	true

Don’t forget to replace [session_id] with your unique session identifier.

<html>
  <head>
    ...
    <script src="https://cdn.seon.io/v2.0/js/agent.js"></script>
    ...
  </head>
  <body>
    ...
    <script>

      seon.start({
        session_id: '[session_id]',
        social_detection: false,
        audio_fingerprint: false,
        use_flash: true,
        onSuccess: function() {
          console.log("Session data was sucessfully saved!");
        },
        onError: function() {
          console.log("Something went wrong. Session data was not saved sucessfully!");
        }
      });

    </script>
  </body>
</html>

`device_details` Object with JavaScript Agent v2.0

JSON Attributes	Type
session_id	string

timezone	string

private_mode	boolean

useragent	string

fonts	integer

plugins	integer

op_sys	string

cookie_enabled	boolean

screen	string

avail_screen	string

window_screen	string

webrtc_count	integer

cookie_hash	string

device_hash	string

js_ip	string

js_ip_country	string

js_ip_isp	string

browser_hash	string

webrtc_ips	array

webrtc_activated	boolean

flash	boolean

java	boolean

plugins_hash	string

fonts_hash	string

plugin_names	array

device_type	string

fonts_names	array

social_sites	array

dns_ip	string

dns_ip_country	string

dns_ip_isp	string

Response

{
 "device_details": {
  "session_id": "1CFFDFC5EAA7D13ABA3F78C469135CCF",
  "timezone": "+2:00",
  "private_mode": false,
  "useragent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36",
  "fonts": 51,
  "plugins": 4,
  "op_sys": "Windows",
  "cookie_enabled": true,
  "screen": "1920x1080",
  "avail_screen": "1920x1050",
  "window_screen": "1336x939",
  "webrtc_count": 1,
  "cookie_hash": "8310306c4f8b0a63bf823aeaf351eab4",
  "device_hash": "f8a9124ac1c436b538a8b611a8654aea",
  "js_ip": "79.172.220.140",
  "js_ip_country": "HU",
  "js_ip_isp": "ARCHI-HOST Kft.",
  "browser_hash": "889fa456b59427a920ef628a7692c26f",
  "webrtc_ips": [
   "10.5.20.159"
  ],
  "webrtc_activated": true,
  "flash": false,
  "java": false,
  "plugins_hash": "-1978200868",
  "fonts_hash": "1035283043",
  "plugin_names": [
   "Chrome PDF Plugin",
   "Chrome PDF Viewer",
   "Native Client"
  ],
  "device_type": "desktop",
  "font_names": [
   "Arial",
   "Arial Black",
   "Arial Narrow",
   "Calibri",
   "Century Schoolbook",
   "Comic Sans MS",
   "Consolas",
   "Courier",
   "Courier New",
   "Garamond",
   "Impact",
   "Microsoft Sans Serif",
   "Monotype Corsiva",
   "MS Gothic",
   "MS PGothic",
   "MS Reference Sans Serif",
   "MS Sans Serif",
   "MS Serif",
   "Times",
   "Times New Roman",
   "Trebuchet MS",
   "Verdana"
  ],
  "social_sites": [
   "gmail",
   "youtube",
   "facebook",
   "airbnb",
   "twitter",
   "slack",
   "dropbox"
  ],
  "dns_ip": "89.134.46.86",
  "dns_ip_country": "HU",
  "dns_ip_isp": "UPC Magyarorszag Kft."
 }
}

JavaScript Agent v3.0

Our JavaScript Agent collects data through the browser for device fingerprinting purposes. In order to use it, you need to add the JavaScript file inside <head> tags. We recommend to use our CDN hosted JavaScript for fast page load and continuous support of the script.

Note

Including the lightweight JavaScript agent is optional, but it provides in-depth analysis for each user.

Step-by-step guide

Integrate the JavaScript Agent into your website or web application, which will send the device information to SEON’s platform including the session_id that you generated (max. 64 characters).
During the user’s session use the same session_id in Fraud API calls.
The device details will be provided in the response of the Fraud API, and will be displayed on the Admin Panel on the Transaction details page.
We recommend to use onSuccess and onError callback functions to make sure that the data has been saved successfully. Fraud API requests initiated before the successful callback won’t be able to reference the collected device data.

<html>
  <head>
    ...
    <script src="https://cdn.seon.io/v3.0/js/agent.js"></script>
  </head>
  <body>
    ...
  </body>
</html>

Configuration parameters

To configure the JavaScript module, you need to call seon.config() function:

JSON Attributes	Required
public_key	yes

session_id	yes

audio_fingerprint	no

canvas_fingerprint	no

webgl_fingerprint	no

onSuccess	no

onError	no

Don’t forget to replace [session_id] with your unique session identifier, and [public_key] with your own public key. Your public key can be found on the My Account page.

seon.config({
  public_key: "[public_key]",
  session_id: "[session_id]",
  audio_fingerprint: true,
  canvas_fingerprint: true,
  webgl_fingerprint: true,
  onSuccess: function(message) {
    console.log('success', message);
  },
  onError: function(message) {
    console.log('error', message);
  }
});

Integration

Fingerprinting can be triggered by the seon.saveSession() function. After collection, all the available information will automatically be sent to the configured endpoint.

seon.saveSession(function(success) {
  if (success) {
    console.log("Session data has been saved!");
  } else {
    console.log("Failed to save session data.");
  }
});

Payload

SEON JavaScript SDK sends a POST request to the configured endpoint with a JSON payload. Some fields can be ‘null’, if the actual browser does not support or return data for that specific data point. In every other case, data types are preserved. Find a sample payload on the right side.

Common issues

The session_id is provided in the Fraud API request, but the device_details is null in the response and there is no device information on the Transaction details page. - This means the JavaScript agent could not send the device data to SEON correctly. Please look into your integration and check again.

The session_id is provided in the Fraud API request, but the device_details is null in the response but there is device information on the Transaction details page. - This means the device data arrived later than the Fraud API request at SEON. Please wait until the JavaScript finished successfully (use callbacks).

`device_details` Object with JavaScript Agent v3.0

JSON Attributes	Type
type	string

source	string

session_id	string

adblock	boolean

audio_hash	string

battery_charging	boolean

battery_level	integer

browser_hash	string

browser	string

browser_version	string

canvas_hash	string

cookie_enabled	string

cookie_hash	string

device_hash	string

device_memory	integer

device_type	string

dns_ip	string

dns_ip_country	string

dns_ip_isp	string

do_not_track	boolean

flash_enabled	boolean

font_count	integer

font_hash	string

font_list	array

hardware_concurrency	integer

java_enabled	boolean

device_ip_address	string

device_ip_country	string

device_ip_isp	string

accept_language	array

os	string

platform	string

plugin_count	integer

plugin_hash	string

plugin_list	array

private	boolean

region_language	string

region_timezone	string

screen_available_resolution	string

screen_color_depth	integer

screen_pixel_ratio	integer

screen_resolution	string

social_logins	array

touch_support	boolean

user_agent	string

webgl_hash	string

webgl_vendor	string

webrtc_activated	boolean

webrtc_count	integer

webrtc_ips	array

window_size	string

Response

{
 "device_details": {
  "type": "web",
  "source": "js-3.0",
  "session_id": "df740ff5-74ae-48c7-8434-1e6c053697f9",
  "cookie_hash": "6173ed1cc5be0fd8ddb6ec7f19cc1388",
  "region_timezone": "+02:00",
  "cookie_enabled": true,
  "os": "MacOS",
  "flash_enabled": false,
  "java_enabled": false,
  "device_type": "desktop",
  "webrtc_activated": false,
  "webrtc_count": 0,
  "webrtc_ips": [],
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36",
  "window_size": "1440x821",
  "screen_resolution": "900x1440",
  "screen_available_resolution": "900x1440",
  "screen_color_depth": 24,
  "screen_pixel_ratio": 2,
  "plugin_count": 3,
  "plugin_list": [
   "Chrome PDF Plugin",
   "Chrome PDF Viewer",
   "Native Client"
  ],
  "plugin_hash": "9c33fe15e3ec251f799666de471de1e9",
  "browser_hash": "27d58443827b9c31e5ff555486cdcece",
  "browser": "CHROME8",
  "browser_version": "83.0.4103.116",
  "font_count": 27,
  "font_list": [
   "Andale Mono",
   "Arial",
   "Arial Black",
   "Arial Hebrew",
   "Arial Narrow",
   "Arial Rounded MT Bold",
   "Arial Unicode MS",
   "Comic Sans MS",
   "Courier",
   "Courier New",
   "Geneva",
   "Georgia",
   "Helvetica",
   "Helvetica Neue",
   "Impact",
   "LUCIDA GRANDE",
   "Microsoft Sans Serif",
   "Monaco",
   "Palatino",
   "Tahoma",
   "Times",
   "Times New Roman",
   "Trebuchet MS",
   "Verdana",
   "Wingdings",
   "Wingdings 2",
   "Wingdings 3"
  ],
  "font_hash": "0f7664682b2a6c3bauda70c094658dac",
  "device_hash": "a7bcdbcd6db9d4da1178acc60bc00c8b",
  "touch_support": false,
  "device_memory": 8,
  "hardware_concurrency": 4,
  "platform": "MacIntel",
  "region_language": "hu",
  "webgl_hash": "6da654d7d9efe14b5f8e62c95bb9ai30",
  "webgl_vendor": "Intel Inc.~Intel(R) Iris(TM) Plus Graphics 650",
  "audio_hash": "124.04345808873768",
  "do_not_track": null,
  "adblock": false,
  "battery_level": 100,
  "battery_charging": true,
  "canvas_hash": "1dc56b87f56afb0f52c70i529362254c",
  "dns_ip": "3.248.186.137",
  "dns_ip_country": "IE",
  "dns_ip_isp": "Amazon Data Services Ireland Limited",
  "device_ip_address": "37.76.83.88",
  "device_ip_country": "HU",
  "device_ip_isp": "Public Pool For Mobile Internet Users",
  "social_logins": [
   "gmail",
   "facebook",
   "youtube",
   "blogger",
   "slack"
  ],
  "accept_language": [
   "hu",
   "en-us",
   "en"
  ],
  "private": false
 }
}

iOS SDK v1.0

`device_details` Object with iOS SDK v1.0

JSON Attributes	Type
type	string

session_id	string

device_udid	string

ios_version	string

ip_address	string

app_platform_type	string

device_adid	string

wifi_mac_address	string

network_config	string

battery_level	string

device_orientation	string

file_system_size	string

physical_memory	string

cpu_type	string

cpu_count	integer

cpu_speed	string

accessories_number	string

has_proximity_sensor	boolean

screen_brightness	string

screen_resolution	string

ios_device_name	string

kernel_version	string

icloud_ubiquity_token	string

local_language	string

currency_code	string

system_uptime	string

Response

{
 "device_details": {
  "type": "ios",
  "session_id": "3UeZWaHrRT",
  "device_udid": "A51E1FFC-9C09-43AF-9477-9276A011E3CE",
  "ios_version": "11.2.2",
  "ip_address": "112.196.3.212",
  "app_platform_type": "iPhone 5s (GSM+CDMA)",
  "device_adid": "6DD386F9-5B70-495C-B466-B3AF85534511",
  "wifi_mac_address": "d4:9a:20:5a:81:b9",
  "network_config": "Wifi",
  "battery_level": "100%",
  "device_orientation": "Portrait",
  "file_system_size": "1250209792",
  "physical_memory": "1048576000",
  "cpu_type": "ARM_64V8",
  "cpu_count": 0,
  "cpu_speed": "0",
  "accessories_number": "0",
  "has_proximity_sensor": true,
  "screen_brightness": "0.42",
  "screen_resolution": null,
  "ios_device_name": "Bansal",
  "kernel_version": "15C202",
  "icloud_ubiquity_token": "9928f58d e1ab9d3c 63707e75 e240e45f 4b0b9c8b",
  "local_language": "en-IN",
  "currency_code": "IN",
  "system_uptime": "92790"
 }
}

Android SDK v1.0

`device_details` Object with Android SDK v1.0

JSON Attributes	Type
type	string

device_id	string

android_id	string

device_name	string

build_id	string

build_device	string

build_manufacture	string

build_time	date

network_name	string

is_plugged_in	boolean

android_version	string

build_number	string

kernel_version	string

locale_country_code	string

wifi_mac_address	string

session_id	string

cpu_type	string

cpu_count	integer

cpu_speed	string

cpu_hash	string

system_uptime	time

ip_address	string

has_proximity_sensor	boolean

physical_memory	string

locale_language	string

Response

{
 "device_details": {
  "type": "android",
  "device_id": "8547c5c2466aa0a3",
  "android_id": "8c9965c2466aa0a3",
  "device_name": "Android SDK built for x86",
  "build_id": "LMY48X",
  "build_device": "generic_x86",
  "build_manufacture": null,
  "build_time": "2018-03-16T22:11:26",
  "network_name": "Android",
  "is_plugged_in": true,
  "android_version": "22 (5.1.1)",
  "build_number": "sdk_google_phone_x86-userdebug 5.1.1 LMY48X 4660545 test-keys",
  "kernel_version": "3.10.0+",
  "locale_country_code": "us",
  "wifi_mac_address": null,
  "session_id": "android_testsession_id",
  "cpu_type": "Android 32-bit virtual processor",
  "cpu_count": 2,
  "cpu_speed": "2591.937",
  "cpu_hash": "4fe2f91f9c4e5e19f40a77711ffba9f0e78b7184",
  "system_uptime": "04:04:50",
  "ip_address": "10.0.2.15",
  "has_proximity_sensor": true,
  "physical_memory": "1007.3 MB",
  "local_language": "English"
 }
}

User Manual: Admin Panel Functions and Data Interpretation

Whitepapers

Quick Start

Product

Select your server

Please choose your backend environment for quick integration

Select your industry

Please choose your industry to see relevant example payloads

Select your use case

Please choose your use case to see relevant example payloads

Developer Resources

Authentication

Error Details

Rate Limits

Timeout logic

Steps for Sense

Integration timeline

Step 1 - Providing the Data

Custom support

Step 2 - Enrichment and Scoring

Step 3 - Feedback

Fraud API

Request

Request Attributes

config

action_type

ip

transaction_id

affiliate_id

affiliate_name

order_memo

email

email_domain

password_hash

user_fullname

user_name

user_id

user_created

user_category

user_account_status

user_bank_account

user_bank_name

user_balance

user_verification_level

user_dob

user_country

user_city

user_region

user_zip

user_street

user_street2

session_id

session

device_id

payment_mode

payment_provider

card_fullname

card_bin

card_hash

card_expire

card_last

avs_result

cvv_result

status_3d

sca_method

phone_number

transaction_type

transaction_amount

transaction_currency

items

shipping_country

shipping_city

shipping_region

shipping_zip

shipping_street

shipping_street2

shipping_phone

shipping_fullname

shipping_method

billing_country