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
    cURL
  • Java
    Java
  • Python
    Python
  • PHP
    PHP
Select your industry
Please choose your industry to see relevant example payloads
  • iGaming
    iGaming
  • Online Lending
    Online Lending
  • Ecommerce
    Ecommerce
  • Payment Gateways
    Payment Gateways
  • Banking and Insurance
    Banking and Insurance
  • Travel and Ticketing
    Travel and Ticketing
  • Crypto exchange
    Crypto exchange
Select your use case
Please choose your use case to see relevant example payloads
  • Register
    Register
  • Login
    Login
  • Deposit
    Deposit
  • Withdrawal
    Withdrawal
  • Payment
    Payment

Available Digital Footprint Analysis modules are

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]

 

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. 

 

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.

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

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.

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:

StateThreshold
APPROVE0 - 10
REVIEW10 - 20
DECLINE20+

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:

StateCategory
APPROVESafe transaction.
REVIEWSuspicious transaction, not confirmed fraud yet.
DECLINEConfirmed 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.)

negative labels

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.

Request

 

Request Attributes

TypeRequired
config
objectno
action_type
stringno
ip
stringno
transaction_id
stringno
affiliate_id
stringno
affiliate_name
stringno
order_memo
stringno
email
stringno
email_domain
stringno
password_hash
stringno
user_fullname
stringno
user_name
stringno
user_id
stringno
user_created
integerno
user_category
stringno
user_account_status
stringno
user_bank_account
stringno
user_bank_name
stringno
user_balance
floatno
user_verification_level
stringno
user_dob
dateno
user_country
stringno
user_city
stringno
user_region
stringno
user_zip
stringno
user_street
stringno
user_street2
stringno
session_id
stringno
session
stringno
device_id
stringno
payment_mode
stringno
payment_provider
stringno
card_fullname
stringno
card_bin
stringno
card_hash
stringno
card_expire
dateno
card_last
stringno
avs_result
stringno
cvv_result
booleanno
status_3d
stringno
sca_method
stringno
phone_number
stringno
transaction_type
stringno
transaction_amount
floatno
transaction_currency
stringno
items
array of objectsno
shipping_country
stringno
shipping_city
stringno
shipping_region
stringno
shipping_zip
stringno
shipping_street
stringno
shipping_street2
stringno
shipping_phone
stringno
shipping_fullname
stringno
shipping_method
stringno
billing_country
stringno
billing_city
stringno
billing_region
stringno
billing_zip
stringno
billing_street
stringno
billing_street2
stringno
billing_phone
stringno
discount_code
stringno
gift
booleanno
gift_message
booleanno
merchant_category
stringno
merchant_id
stringno
merchant_created_at
integerno
merchant_country
stringno
receiver_fullname
stringno
receiver_bank_account
stringno
details_url
stringno
regulation
stringno
bonus_campaign_id
stringno
brand_id
stringno
custom_fields
objectno

HTTP Endpoint

POST

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

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.

  1. 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.
  2. Set a unique session_id for your client using the seon.config() function.
  3. Call the seon.getBase64Session() function to get the encrypted payload for the device.
  4. 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.

 

 

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

 

 

 

 

 

 

 

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);
  }
});

 

 

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.
negative labels

Request

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

Request Attributes

TypeRequired
label
stringyes

 

HTTP Endpoint

PUT

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

Request (multiple)

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

JSON Attributes

TypeRequired
transactions
array of label objectsyes

HTTP Endpoint

PUT

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

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.

Request

Request Attributes

TypeRequired
data_field
stringyes
value
stringyes
state
stringyes
comment
stringno
expire_day
integerno

HTTP Endpoint

PUT

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

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.

Request

Request Attributes

TypeRequired
user_ids
array No
emails
array No

HTTP Endpoint

PUT

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

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

TypeRequired
user_ids
array No
emails
array No

HTTP Endpoint

DELETE

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

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

TypeRequired
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

ValueRequired
dry_run
boolean no

HTTP Endpoint

POST

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

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.
negative labels

Available events

EventDescription
transaction:status_updateAny time a transaction state has changed.
lists:blacklist-whitelistAny 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

ValueRequired
include
historyno
include
flagsno
include
idno
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]
PHP
Generic
Generic

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

ValueRequired
include
id no

HTTP Endpoint

GET

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

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

ValueRequired
include
historyno
include
flagsno
include
idno
include
cnam_lookupno
include
hlr_detailsno
flags_timeframe_days
[number of days]no
exclude
photono
exclude
last_seenno
timeout
[number of milliseconds]no

HTTP Endpoint

GET

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

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

ValueRequired
include
historyno
include
flagsno
include
idno
flags_timeframe_days
[number of days]no

HTTP Endpoint

GET

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

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

TypeRequired
ip
stringno
action_type
stringno
transaction_id
stringno
affiliate_id
stringno
affiliate_name
stringno
user_order_memo
stringno
run_email_api
booleanno
email
stringno
email_domain
stringno
password_hash
stringno
user_fullname
stringno
user_name
stringno
user_id
stringno
user_created
integerno
user_country
stringno
user_city
stringno
user_region
stringno
user_zip
stringno
user_street
stringno
user_street2
stringno
session_id
stringno
device_id
stringno
payment_mode
stringno
card_fullname
stringno
card_bin
stringno
card_hash
stringno
card_last
stringno
avs_result
stringno
cvv_result
booleanno
phone_number
stringno
transaction_type
stringno
transaction_amount
floatno
transaction_currency
stringno
items
array of item objectsno
shipping_country
stringno
shipping_city
stringno
shipping_region
stringno
shipping_zip
stringno
shipping_street
stringno
shipping_street2
stringno
shipping_phone
stringno
shipping_fullname
stringno
shipping_method
stringno
billing_country
stringno
billing_city
stringno
billing_region
stringno
billing_zip
stringno
billing_street
stringno
billing_street2
stringno
billing_phone
stringno
discount_code
stringno
gift
booleanno
gift_message
booleanno
merchant_id
stringno
merchant_created_at
integerno
merchant_country
stringno
details_url
stringno
user_label
objectno

 

HTTP Endpoint

POST

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

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

TypeRequired
email
stringyes

HTTP Endpoint

POST

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

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

ValueRequired
include
historyno
include
flagsno
include
idno
include
cnam_lookupno
include
hlr_detailsno
flags_timeframe_days
[number of days]no
exclude
photono
exclude
last_seenno
timeout
[number of milliseconds]no

HTTP Endpoint

GET

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

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:

  1. Include SEON JavaScript agent in your header, between <head></head> tags.
  2. Insert the initialization code to the bottom of your page, just before the </body> tag.
  3. Replace [session_id] with the unique identifier of user’s session.
  4. 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.

 

 

Options

JSON Attributes

TypeDefault
social_detection
booleanfalse
audio_fingerprint
booleanfalse
use_flash
booleantrue

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.

 

 

Step-by-step guide

  1. 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).
  2. During the user’s session use the same session_id in Fraud API calls.
  3. 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.
  4. 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"
 }
}

?Got a question

Talk to sales