Quick Start
Please select the product you wish to use to quickly set up the optimal payloads for your use-case
Choose your setup
Server
Please choose your backend environment for quick integration
Industry
Please choose your industry to see relevant example payloads
Use case
Please choose your use case to see relevant example payloads
Available Digital Footprint Analysis modules are:
Check the Admin Panel overview to learn more about the interface.
Risk Scores can be customized in the Admin Panel.
Please refer to the SDK references 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: [license_key]
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
All client integrations should be able to cope with client-side timeout responses to avoid timeout errors in case of degraded API performance. We recommend adding at least 500-1000 ms to the timeout set on the SEON's setting page when configuring timeout in your back-side API implementation.
Integration Steps
At its core, our fraud prevention platform operates in three simple steps:
- You send user / transaction / device data.
- We enrich the data and deliver a risk score based on rules.
- You give feedback on the results.
Integration timeline
You can find a detailed timeline here to see how long it takes to get results with SEON.
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 is designed to give you full transparency behind every score and decision (a.k.a. state). This is why every data point will be available in the response.
By default, the fraud scores are based on preset rules, which can be reviewed in the Scoring Engine. A score of 10+ is considered risky. Standard thresholds for each state are:
State | Threshold |
---|---|
APPROVE | 0 - 10 |
REVIEW | 10 - 20 |
DECLINE | 20+ |
Step 3 - Feedback
Providing feedback is the key to refining the rules and getting more precise fraud scores. This is particularly important when discovering false positives and false negatives.
Every transaction state should therefore be set to the appropriate category:
State | Category |
---|---|
APPROVE | Safe transaction. |
REVIEW | Suspicious transaction, not confirmed fraud yet. |
DECLINE | Confirmed fraudulent transaction. |
You can also create categories of fraud reasons in the Machine Learning section of your Settings page , which support the Label API (e.g. chargeback, bonus abuser or postback data from payment: authorized, lost or stolen etc.)

Fraud API
SEON's proprietary API combines our email, phone number, IP, and AML APIs with device fingerprinting so that you can request and receive our enriched data, rules, and scoring in a single API call.
Good to know
- The API is fully modular, meaning you can choose to enable or disable each sub-APIs (Email, Phone, IP, or AML) or the device fingerprinting tool. Use the
config
object to enable or disable modules. - You can use the
custom_fields
object to send almost any custom data point to SEON. Your team can also use custom fields in rules to create a completely custom ruleset. - All SEON API requests are case-sensitive. Please follow the formatting below to avoid errors.
Request
Request Attributes | Type | Required | |
---|---|---|---|
config | object | no | |
action_type | string | no | |
ip | string | no | |
transaction_id | string | no | |
affiliate_id | string | no | |
affiliate_name | string | no | |
order_memo | string | no | |
string | no | ||
email_domain | string | no | |
payment_id | string | no | |
password_hash | string | no | |
user_fullname | string | no | |
user_name | string | no | |
user_firstname | string | no | |
user_middlename | string | no | |
user_lastname | string | no | |
user_pob | string | no | |
user_photoid_number | string | no | |
user_id | string | no | |
user_created | integer | no | |
user_category | string | no | |
user_account_status | string | no | |
user_bank_account | string | no | |
user_bank_name | string | no | |
user_balance | float | no | |
user_verification_level | string | no | |
user_dob | date | no | |
user_country | string | no | |
user_city | string | no | |
user_region | string | no | |
user_zip | string | no | |
user_street | string | no | |
user_street2 | string | no | |
session_id | string | no | |
session | string | no | |
device_id | string | no | |
payment_mode | string | no | |
payment_provider | string | no | |
card_fullname | string | no | |
card_bin | string | no | |
card_hash | string | no | |
card_expire | date | no | |
card_last | string | no | |
avs_result | string | no | |
cvv_result | boolean | no | |
status_3d | string | no | |
sca_method | string | no | |
phone_number | string | no | |
transaction_type | string | no | |
transaction_amount | float | no | |
transaction_currency | string | no | |
items | array of objects | no | |
shipping_country | string | no | |
shipping_city | string | no | |
shipping_region | string | no | |
shipping_zip | string | no | |
shipping_street | string | no | |
shipping_street2 | string | no | |
shipping_phone | string | no | |
shipping_fullname | string | no | |
shipping_method | string | no | |
billing_country | string | no | |
billing_city | string | no | |
billing_region | string | no | |
billing_zip | string | no | |
billing_street | string | no | |
billing_street2 | string | no | |
billing_phone | string | no | |
discount_code | string | no | |
gift | boolean | no | |
gift_message | boolean | no | |
merchant_category | string | no | |
merchant_id | string | no | |
merchant_created_at | integer | no | |
merchant_country | string | no | |
receiver_fullname | string | no | |
receiver_bank_account | string | no | |
details_url | string | no | |
regulation | string | no | |
bonus_campaign_id | string | no | |
brand_id | string | no | |
custom_fields | object | no | |
HTTP Endpoint
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 | |
aml_details | object | |
version | string | |
applied_rules | array of object | |
device_details | object | |
calculation_time | integer | |
seon_id | integer | |
rule_category_details | array of object | |
Response
JavaScript Agent v5
You can integrate our optional device fingerprinting module directly into a web app, by using our JavaScript agent. Please, use our CDN hosted script to ensure you always load the latest available version.
- Include the JavaScript Agent for example inside the
<head>
tags of your website or web app. You can also lazy-load it or execute it upon specific actions (e.g. clicking on Login, Payment, and Registration buttons, before calling the API). In this case, you must ensure that the module has been loaded successfully before invoking its methods. - Set a unique
session_id
for your client using theseon.config()
function. - Call the
seon.getBase64Session()
function to get the encrypted payload for the device. - Send the returned session payload string to your backend and add to the
session
property in your Fraud API request. The Fraud API call should be still executed if thesession
is missing, due to a non-executed JS snippet. Tip: Add timeout to JS and utilize 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 thedevice_details
isnull
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/v5/agent.js
https://cdn.deviceinf.com/js/v5/agent.js
https://cdn.getdeviceinf.com/js/v5/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 | integer | |
carrier_country | string | |
carrier_name | string | |
cpu_count | integer | |
cpu_type | string | |
device_adid | string | |
device_hash | string | |
device_name | string | |
device_orientation | string | |
device_udid | string | |
free_storage | unsigned long | |
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 | integer | |
network_config | string | |
pasteboard_hash | string | |
physical_memory | unsigned long | |
region_country | string | |
region_language | string | |
region_timezone | string | |
screen_brightness | integer | |
screen_height | double | |
screen_width | double | |
system_uptime | integer | |
total_storage | unsigned long | |
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
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
Label API
Label API allows you to automatically feedback to improve our machine learning algorithm. This helps to reduce the number of false positives and false negatives for you.
Good to know
- You can create custom positive and negative labels on your Settings page.
- You can label any transaction that is less than a year old with Label API.
- For the most consistent results, please add max 10,000 transactions to each API request. Feel free to send multiple requests to label more transactions.
- Providing feedback is key to refining the rules and getting more precise fraud scores. Learn more about the feedback loop on our Feedback Loops & Label API page.
- All SEON API requests are case-sensitive. Please follow the formatting below to avoid errors.
Request
You must replace [id]
with your transaction_id
that you have provided during the Fraud API call or was generated automatically.
Request Attributes | Type | Required | |
---|---|---|---|
label | string | yes | |
HTTP Endpoint
Request (multiple)
You can also label multiple transactions with one API call using the URL below.
JSON Attributes | Type | Required | |
---|---|---|---|
transactions | array of label objects | yes | |
HTTP Endpoint
Lists API
Add any data point to a blacklist, whitelist, or custom list with this API. Reset any Fraud API request and response parameters, add a comment, and expiration through a single request.
Good to know
- Use a PUT request to add any data points to a list.
- All SEON API requests are case-sensitive. Please follow the formatting below to avoid errors.
Request
Request Attributes | Type | Required | |
---|---|---|---|
data_field | string | yes | |
value | string | yes | |
state | string | yes | |
comment | string | no | |
expire_day | integer | no | |
HTTP Endpoint
Self Exclusion API
Online gambling operators can enable self-exclusion lists using our bespoke API if required by law. The API uses the email address, phone number, full name, date of birth, user country, and user zip fields.
Good to know
- Identify users with their email addresses or user IDs.
- Use PUT request to exclude users, and use DELETE request to reverse the exclusion.
- All SEON API requests are case-sensitive. Please follow the formatting below to avoid errors.
Request
Request Attributes | Type | Required | |
---|---|---|---|
user_ids | array | No | |
emails | array | No | |
HTTP Endpoint
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
Delete request
JSON Attributes | Type | Required | |
---|---|---|---|
user_ids | array | no | |
emails | array | no | |
HTTP Endpoint
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
Exclude User from Rule API
Created for highly API-dependent integrations, this API allows you to exclude specific users from the effects of a certain custom rule.
Good to know
- Use the Rule ID to define which rule should not be applied to the selected user.
- Identify the users with their user ID, email address, card hash, or IP address.
- Use POST requests to exclude users from rules and DELETE requests to reverse the exclusion.
- All SEON API requests are case-sensitive. Please follow the formatting below to avoid errors.
Request
Request Attributes | Type | Required | |
---|---|---|---|
rule_id | integer | yes | |
field | string | yes | |
value | string | yes | |
expiration | string | no | |
HTTP Endpoint
Response
The endpoint returns JSON structured response.
JSON Attributes | Type | |
---|---|---|
data | object | |
error | object | |
success | boolean | |
Response
Delete request
Request Attributes | Type | Required | |
---|---|---|---|
rule_id | integer | yes | |
field | string | yes | |
value | string | yes | |
HTTP Endpoint
Delete response
The endpoint returns JSON structured response.
JSON Attributes | Type | |
---|---|---|
data | object | |
error | object | |
success | boolean | |
Response
Erase API
Under certain data protection regulations, companies that handle personal data are required to delete it upon request. With our Erase API, you can erase all data related to one or multiple users by providing email addresses or user IDs.
Good to know
- Identify user data to be deleted using email addresses or user IDs.
- You can send up to 50 emails or IDs in each request to delete all data connected to them.
- All SEON API requests are case-sensitive. Please follow the formatting below to avoid errors.
Request
Request Attributes | Type | Required | |
---|---|---|---|
user_ids | array | no | |
emails | array | no | |
Optional query string parameters
JSON Attributes | Value | Required | |
---|---|---|---|
dry_run | boolean | no | |
HTTP Endpoint
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
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.
Our webhooks are delivered in most cases but should there be a failure, we don’t retry or queue the request.
- You can set up the events and webhook URLs in the Admin Panel of your Settings page.

Available events
Event | Description |
---|---|
transaction:status_update | Any time a transaction state has changed. |
lists:blacklist-whitelist | Any value has been added to blacklist or whitelist or removed from them. |
lists:customlist | Any value has been added to Custom lists or removed from them. |
{
"event": "transaction:status_update",
"date": "2017-08-30T13:47:42+00:00",
"transactions": [
{
"id": "e601f2dae8f9",
"seon_id": 1488721,
"state": "REVIEW",
"label": "Marked as 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"
}
]
}
{
"event": "lists:customlist",
"date": "2017-08-30T13:47:42+00:00",
"values": [
{
"data_field": "user_id",
"value": "413132231",
"state": "watchlist"
},
{
"data_field": "user_id",
"value": "3243112",
"state": "custom_sample_list"
}
]
}
Email API
Our standalone email enrichment tool that will help you learn about the approximate minimum age of an email address, its provider, and any connected online profiles.
Good to know
- Use the Fraud API if you want to use the Email API together with any of our Phone API, IP API, and Device Fingerprinting.
- All SEON API requests are case-sensitive. Please follow the formatting below to avoid errors.
- Email API requests are limited to 120/minute during your SEON free trial.
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.
Request Attributes | Value | Required | |
---|---|---|---|
include | history | no | |
include | flags | no | |
include | id | no | |
flags_timeframe_days | [number of days] | no | |
timeout | [number of milliseconds] | no | |
HTTP Endpoint
Response
The endpoint returns JSON structured response.
JSON Attributes | Type | |
---|---|---|
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
Email Verification API
Our quick email verification tool will tell you whether an email address is valid and deliverable using a fast SMTP-MX check.
Good to know
- All SEON API requests are case-sensitive. Please follow the formatting below to avoid errors.
- Email Verification API requests are limited to 120/minute during your SEON free trial.
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.
Request Attributes | Value | Required | |
---|---|---|---|
include | id | no | |
HTTP Endpoint
Response
The endpoint returns JSON structured response.
JSON Attributes | Type | |
---|---|---|
id | string | |
valid_format | boolean | |
deliverable | boolean | |
inbox_full | boolean | |
domain_details | object | |
Response
Phone API
Unlock insights into a user's phone number's history and find social or digital profiles connected to it.
Good to know
- Use the Fraud API if you want to use the Phone API together any of our Email API, IP API, and Device Fingerprinting.
- All SEON API requests are case-sensitive. Please follow the formatting below to avoid errors.
- Phone API requests are limited to 120/minute during your SEON free trial.
Request
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:
Request Attributes | Value | Required | |
---|---|---|---|
include | history | no | |
include | flags | no | |
include | id | no | |
include | cnam_lookup | no | |
include | hlr_details | no | |
flags_timeframe_days | [number of days] | no | |
exclude | photo | no | |
exclude | last_seen | no | |
timeout | [number of milliseconds] | no | |
HTTP Endpoint
Response
The endpoint returns JSON structured response.
JSON Attributes | Type | |
---|---|---|
number | integer | |
valid | boolean | |
disposable | 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
IP API
Identify suspicious VPN and proxy connections and pinpoint users with accurate geolocation information.
Good to know
- Use the Fraud API if you want to use the IP API together with any of our Email API, Phone API, and Device Fingerprinting.
- All SEON API requests are case-sensitive. Please follow the formatting below to avoid errors.
- IP API requests are limited to 120/minute during your SEON free trial.
Request
The [ip]
in the request URI should include the full IPv4 or IPv6 address, example: 1.1.1.1
or 2001:db8:3333:4444:5555:6666:7777:8888
.
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:
Request Attributes | Value | Required | |
---|---|---|---|
include | history | no | |
include | flags | no | |
include | id | no | |
flags_timeframe_days | [number of days] | no | |
HTTP Endpoint
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 | number | |
longitude | number | |
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
AML API
Check PEP, sanctions, and high-risk names list to counter fincrime all in one place using SEON. Maintain anti-money laundering compliance easily by turning on automatic monitoring.
Good to know:
- Enter a customer's full name and their name separated into each of the first, middle, and last name fields for the best results.
- If you'd like to enable automatic monitoring for a name set
monitoring_required
to true in your request. - AML screening is not fully automatic, your team will have to review potential matches.
- All SEON API requests are case-sensitive. Please follow the formatting below to avoid errors.
Request
Attributes | Type | Required | |
---|---|---|---|
config | object | no | |
user_id | string | no | |
user_fullname | string | yes | |
user_firstname | string | no | |
user_middlename | string | no | |
user_lastname | string | no | |
user_dob | date | no | |
user_pob | string | no | |
user_photoid_number | string | no | |
HTTP Endpoint
Response
JSON attributes | |||
---|---|---|---|
has_crimelist_match | boolean | ||
has_pep_match | boolean | ||
has_watchlist_match | boolean | ||
has_sanction_match | boolean | ||
result_payload | object | ||
Response
BIN API
Unearth information about a card's bank, issuer, country, type, and validity using our BIN API. Identify pre-paid, gift, and credit cards to counter payment fraud effectively.
Good to know
- Use the Fraud API if you want to use the BIN API together with any of our Email API, IP API, and Device Fingerprinting.
- All SEON API requests are case-sensitive. Please follow the formatting below to avoid errors.
Request
Request Attributes | Value | Required | |
---|---|---|---|
include | id | no | |
HTTP Endpoint
Response
The endpoint returns JSON structured response.
JSON Attributes | Type | |
---|---|---|
bin_bank | string | |
bin_card | string | |
bin_type | string | |
bin_level | string | |
bin_country | string | |
bin_country_code | string | |
bin_website | string | |
bin_phone | string | |
bin_valid | boolean | |
card_issuer | string | |
id | ||
Response
Errors
Fraud API v2 Errors
Error code | HTTP status code | Error message and description |
1000 | 400 | "Empty request body." Our servers are receiving your API request, but it does not contain anything. Check your request for formatting errors and take a look at our reference codes above. |
1001 | 400 | "Incorrect config object: [data_field_name] should be sent as [format] ."The field named in the error message is formatted incorrectly. Please refer to our API reference and confirm your formatting is correct. |
1006 | 400 | "Invalid input json." The json you are trying to send seems to be formatted incorrectly. Please double-check your API request. |
1009 | 400 | "Invalid email address." The input provided is not an email address, e.g., it does not contain an @ sign, or the TLD (.dom, .org, etc.) is missing. |
1016 | 400 | "Lookup limit for your plan has been reached." Your plan includes a limited number of API lookups. Please contact our Customer Success Team if you have reached this limit. |
1017 | 401 | "Invalid authorization IP." You are sending your API request from an IP address that is not authorized for your account. Double-check your settings or reach out to our team. |
1018 | 400 | "Invalid card_last format." The field must only contain the last four digits (numerals) of the card number – remove any additional information. |
1019 | 401 | "Your trial has expired." Your 14-day free trial has expired. Reach out to our team to continue using SEON. |
2001 | 401 | "Missing license key." You have not authenticated your API request with your license key. You can find your license key on the Organization page. |
2001 | 401 | "System database error." An error has occurred when the service tried to access the database, for example, the database may be down. Check our status page for updates or contact our team. |
2002 | 401 | "Invalid license key." The license key sent over in your request is incorrect. Find your license key on the My Account page. If you still have issues, reach out to our Customer Success Team. |
2003 | 401 | "Your subscription has ended." If you would like to continue using SEON, reach out to our team. |
2004 | 401 | "Inactive license." The license you have provided has expired or has not been activated yet. Double-check that you are using the correct key on your My Account page and contact our Customer Success Team for assistance. |
2006 | 400 | "Requested feature [feature_name] is not enabled, for instance the HLR or CNAM lookup functionality."The feature you are trying to use is not enabled on your account. Reach out to our Customer Success Team – they can help you in upgrading your account or finding the cause. |
3000 | 400 | "Incorrect type: [data_field_name] should be sent as [format] ."The field named in the error message is formatted incorrectly. Please refer to our API reference and confirm your formatting is correct. |
3001 | 400 | "Incorrect value: [data_field_name] is invalid."Refer to the API reference and request code examples above to confirm you are using the correct name for each field. |
3002 | 400 | "Incorrect value: [data_field_name] should be sent as one of [value-1] , [value-2] ."The format of the named field should follow the format of the examples in the error message. Refer to the API reference above for more details. |
3003 | 400 | "Length error: [data_field_name] size must be between [minimum_value] and [maximum_value] ."You can find details about the maximum length of each API field on the API reference page. |
3003 | 400 | "Invalid transaction_amount input parameter."The transaction amount parameter should only contain numeric characters. Remove any full stops or commas from the string. |
3004 | 400 | "Error: [error_message] ."The data entered in this field is invalid, for reasons other than those stated in error codes 3001 and 3003. Check our API reference for code examples, and contact our Customer Success Team if you need more assistance. |
3004 | 400 | "transaction_amount not provided along with transaction_currency ."The data entered in this field is invalid, for reasons other than those stated in error codes 3001 and 3003. Check our API reference for code examples, and contact our Customer Success Team if you need more assistance. |
3004 | 400 | "Unrecognized property: [data_field_name] . Please check the documentation for supported properties."Your API request should contain both fields. |
3005 | 400 | “Unrecognized property: [data_field_name] ."Your API request contains an unsupported property. Refer to the reference documentation above and check your API request for typos. |
3007 | 400 | "Invalid action_type input parameter."The action_type field can contain almost any correctly formatted string. Check your request for unwanted spaces, special characters, etc. |
4001 | 400 | "System error." An error has occurred in the SEON system. Please check our status page for updates or contact our team. |
4004 | 400 | "Too Many Requests." The number of requests sent exceeds your transactions/seconds rate limit. Our Customer Success team can assist you in increasing your limit if needed. |
Error message
{
"success": false,
"error": {
"code": "3000",
"message": "Incorrect type: 'transaction_amount' should be sent as number"
},
"data": {}
}
Fraud API v1 Errors
Error Code | Error description |
1000 | Empty request body. |
1001 | IP address is missing. |
1002 | IP Address is invalid. |
1003 | License key is missing. |
1004 | License key is invalid. |
1005 | Invalid public key. |
1006 | JSON input is invalid. |
1008 | Email address is missing. |
1009 | Email address is invalid. |
1010 | Invalid authorization header. |
1011 | Inactive license. |
1012 | Your subscription has ended |
2001 | System database error. |
3000 | Length error: [data_field_name] size must be between [minimum_value] and [maximum_value] . |
3001 | Incorrect value: [data_field_name] is invalid. |
3002 | Invalid cvv_result input parameter. |
3003 | Invalid transaction_amount input, should be provided as number. |
3004 | Invalid items_quantity input parameter. |
3005 | Invalid items_price input parameter. |
3006 | Incorrect value: merchant_created_at value is invalid |
3007 | Incorrect value: action_type parameter is invalid |
3008 | transaction_amount not provided along with transaction_currency . |
3009 | Invalid gift input parameter. |
3010 | Invalid gift_message input parameter. |
JavaScript Agent Changelog
Click on any row to read a more detailed description of update to our device fingerprinting tools.
Version | Date | Summary | |
---|---|---|---|
5.7.0 | May 17, 2023 | Font list changes | |
5.6.1 | Apr 12, 2023 | Bug fixes and performance improvements | |
5.5.4 | Feb 16, 2023 | Device identification & performance | |
5.5.1 | Dec 13, 2022 | Improved timeout handling | |
5.5.0 | Dec 8, 2022 | Device IP updates | |
5.4.0 | Nov 10, 2022 | Mobile device identification improvements | |
5.3.1 | Oct 26, 2022 | Unit tests | |
5.3.0 | Sep 30, 2022 | Fraud browser detection | |
5.2.1 | Sep 9, 2022 | Minor bugfixes | |
5.2.0 | Sep 8, 2022 | Improved spoofing detection | |
5.1.0 | Jul 26, 2022 | Fraud browser detection | |
5.0.1 | Jun 1, 2022 | Minor bugfixes | |
5.0.0 | May 30, 2022 | Font & fraud browser detection | |
API Changelog
Update 2022-05-25
Service changes
- Email API v2.2 has been released with new supported online platforms:
adobe
,mailru
,wordpress
,imgur
,disneyplus
,netflix
,jdid
,flipkart
,bukalapak
,archiveorg
,lazada
,zoho
,samsung
,evernote
,envato
,patreon
,tokopedia
,rambler
,quora
,atlassian
Using thev2.2
changes theaccount_details
in the API response. Version differences:- All supported online platforms for Email API v2.2:
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
,adobe
,mailru
,wordpress
,imgur
,disneyplus
,netflix
,jdid
,flipkart
,bukalapak
,archiveorg
,lazada
,zoho
,samsung
,evernote
,envato
,patreon
,tokopedia
,rambler
,quora
,atlassian
- 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.2:
- Phone API v1.3 has been released with new supported online platforms:
flipkart
,bukalapak
,jdid
. Using thev1.3
changes theaccount_details
in the API response. Version differences:- All supported online platforms for Phone API v1.3:
zalo
,line
,kakao
,microsoft
,ok
,skype
,snapchat
,facebook
,google
,instagram
,twitter
,yahoo
,telegram
,whatsapp
,viber
,flipkart
,bukalapak
,jdid
- All supported online platforms for Phone API v1.2:
zalo
,line
,kakao
,microsoft
,ok
,skype
,snapchat
,facebook
,google
,instagram
,twitter
,yahoo
,telegram
,whatsapp
,viber
- Phone API v1.3 deprecated and removed fields:
cnam
,cnam_gender
- All supported online platforms for Phone API v1.3:
Update 2021-10-25
Service changes
- New standalone BIN API was released. Its response contains the same data as the
bin_details
object in the Fraud API. - Webhooks are now available for blacklisting, whitelisting and custom listing actions.
- For
transaction:status_update
Webhook events thelabel
value is provided in the payload.
New Admin features
- Introducing Custom Lists: alongside the current blacklist and whitelist, now custom ones can be created and used for scoring (Lists page).
- User full name similarity support added to Velocity rules (Scoring Engine).
- Similarity operators were added to Data match rules (Scoring Engine).
- Session source was added as a new field to Compare rules (Scoring Engine).
- User Behavior rule parameter type was removed from the system. Same functionality is available with the Velocity type.
Update 2021-09-29
Service changes
- Phone API v1.2 was released with a new
disposable
field. - IP API v1.1 was released with a new
harmful
field.
Update 2021-09-15
Service changes
- Slash character is now accepted in the local part of the emails.
Update 2021-09-02
New admin features
- User Revenue widget introduced for clients in the iGaming industry (Transaction details page).
Update 2021-08-03
Service changes
- Exclude User from Rule API has been introduced.
Update 2021-07-08
Service changes
- Alternative domain options added for JavaScript Agent v4. 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
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 thev2.1
changes theaccount_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
- All supported online platforms for Email API v2.1:
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 thev1.1
changes theaccount_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
- All supported online platforms for Phone API v1.1:
- 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 incustom_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 to SEON.
Update 2020-06-16
Service changes
- Fraud API v2.0 has been released.
hlr_details
andcnam_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 asuser_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 asuser_label
),amount_in_eur
fields are now supported in velocity rules.
Data field mapping from Fraud API v1.0 to v2.0:
- proxy_score -> ip_details/score
- ip_details/ip_country -> ip_details/country
- ip_details/ip_state_prov -> ip_details/state_prov
- ip_details/ip_city -> ip_details/city
- ip_details/ip_latitude -> ip_details/latitude
- ip_details/ip_longitude -> ip_details/longitude
- ip_details/ip_isp_name -> ip_details/isp_name
- ip_details/ip_timezone_offset -> ip_details/timezone_offset
- email_details/email_score -> email_details/score
- email_details/email_exists -> email_details/deliverable
- email_details/disposable -> email_details/domain_details/disposable
- email_details/free -> email_details/domain_details/free
- email_details/domain_exists -> email_details/domain_details/website_exists
- email_details/email_domain_details -> email_details/domain_details
- email_details/email_domain_details/domain -> email_details/domain_details/domain
- email_details/email_domain_details/suffix -> email_details/domain_details/tld
- email_details/email_domain_details/created -> email_details/domain_details/created
- email_details/email_domain_details/updated -> email_details/domain_details/updated
- email_details/email_domain_details/registered -> email_details/domain_details/registered
- email_details/email_account_details -> email_details/account_details
- email_details/email_account_details/facebook_exists -> email_details/account_details/facebook/registered
- email_details/email_account_details/facebook_profile -> email_details/account_details/facebook/url
- email_details/email_account_details/facebook_name -> email_details/account_details/facebook/name
- email_details/email_account_details/facebook_photo -> email_details/account_details/facebook/photo
- email_details/email_account_details/google_exists -> email_details/account_details/google/registered
- email_details/email_account_details/google_profile -> removed
- email_details/email_account_details/google_name -> removed
- email_details/email_account_details/google_photo -> email_details/account_details/google/photo
- email_details/email_account_details/apple_exists -> email_details/account_details/apple/registered
- email_details/email_account_details/twitter_exists -> email_details/account_details/twitter/registered
- email_details/email_account_details/microsoft_exists -> email_details/account_details/microsoft/registered
- email_details/email_account_details/yahoo_exists -> email_details/account_details/yahoo/registered
- email_details/email_account_details/ebay_exists -> email_details/account_details/ebay/registered
- email_details/email_account_details/gravatar_exists -> email_details/account_details/gravatar/registered
- email_details/email_account_details/instagram_exists -> email_details/account_details/instagram/registered
- email_details/email_account_details/spotify_exists -> email_details/account_details/spotify/registered
- email_details/email_account_details/tumblr_exists -> email_details/account_details/tumblr/registered
- email_details/email_account_details/linkedin_exists -> email_details/account_details/linkedin/registered
- email_details/email_account_details/weibo_exists -> email_details/account_details/weibo/registered
- email_details/email_account_details/vk_exists -> removed
- email_details/email_account_details/haveibeenpwned_exists -> email_details/breach_details/haveibeenpwned_listed
- email_details/email_account_details/number_of_breaches -> email_details/breach_details/number_of_breaches
- email_details/email_account_details/first_breach -> email_details/breach_details/first_breach
- phone_details/phone_number -> phone_details/number
- phone_details/phone_is_valid -> phone_details/valid
- phone_details/phone_is_possible -> removed
- phone_details/phone_type -> phone_details/type
- phone_details/phone_country -> phone_details/country
- phone_details/phone_carrier -> phone_details/carrier
Update 2020-04-08
Service changes
flags_timeframe_days
,exclude
,timeout
query string parameters added to Email API, Phone API and IP API.- Username - User full name and Email - User full name similarity calculation updated in Compare rules.
- Email, user name, user address hash similarity support added to Velocity rules.
user_label
field support added to data match rules.
Update 2020-02-17
New admin features
- Phone number flagging support added to Phone widget.
- Dropdown selector added for Device type and IP type (Scoring Engine, Filters).
- Custom URLs is now recognised as links on widgets (User labels, Order details / Details URL).
- Self exclusion rules moved into a separate Exclude rules category.
Update 2020-01-13
New admin features
- State conflict settings added (Settings page).
- Batch test maximum number of records increased to 30 000 (Manual Page / Batch Test).
- Phone API runner added to Phone widget (Transaction details page / Customer details page).
- IP and Phone widget updated (Transaction details page / Customer details page).
- Action type, Phone type, IP timezone offset, Timezone offset filters improved (Transactions / Filters, Customers / Filters)
- Public proxy, VPN data fields added to Scoring Engine (Scoring Engine).
- Phone API v1.0 data fields added to Scoring Engine (Scoring Engine).
- Bulk selection added to Activity (Transaction details page / Activity).
- Card country code data field renamed to Card country, Card country removed from Admin Panel (All pages).
Update 2019-11-22
New admin features
- Phone API statistics added to user menu and Billing Details (Billing Details).
- Transaction list export limit increased to 30 000 records (Transactions / Exports).
- Quick filter for address hashes added (Transaction details page).
Update 2019-11-13
Service changes
- IP API v1.0 added to Service.
- Optional query string parameters added to Phone API and IP API.
Update 2019-10-30
New admin features
- Applied rule notification added (My Account / Notifications).
- Modify score by velocity value function added to Scoring Engine (Scoring Engine).
- Multiple distinct values support added to Velocity rules (Scoring Engine).
- Additional ordering added to New risky transactions (Workbench / New Risky Transactions).
- Warning added if session arrived later than the transaction (Transaction details page).
- Rule tester accuracy calculation improved (Rule edit page).
- View on Google link removed from Email widget, since Google+ was shut down (Transaction details page).
- Deleted rules got labelled on Applied Rule Statistics (Scoring Engine / Dashboard).
- Separate user id sequencing for customers added (Team).
Update 2019-10-18
Service changes
- Phone API v1.0 added to Service.
Update 2019-10-09
New admin features
- Scoring Engine page updated. Rule categorizing and filtering added, new Applied Rule Statistics widget introduced on Scoring Engine Dashboard (Scoring Engine).
- Default rule configuration added to Scoring Engine (Scoring Engine / Default Rules).
Update 2019-09-30
Service changes
- Multiply and divide functions removed from Scoring Engine.
- Modify score by velocity value function added.
- Multiple distinct values support added to Velocity rules.
- Phone number input validation added.
- Using Domain update date when Domain creation date not available.
Update 2019-09-10
Service changes
- Default rules got configurable.
- Missing user_id generated from user_name or email address.
- Separate rule id sequencing for customers added.
- Lowercase country code support added.
- API request field length validation added. The maximum length of all request parameters is 100 characters, except 64 characters for
session_id
.
Update 2019-08-15
New admin features
- Previous months view added to Billing Details page (Billing Details).
- Merchants page added (Merchants).
- New device fingerprinting fields added to Admin Panel, device widget updated.
- New action types added to Filters, Scoring Engine.
- Previously sent User label field options added to Filters, Scoring Engine.
- Canceled invoices got highlighted (Billing Details).
- Optional payment mode statistics added to Dashboard.
- Currency dropdown added to Filters, Scoring Engine.
- Sandbox restriction added to user options (Team).
- Hiding all email_account_details information on Admin Panel optionally.
- Public keys added to profile information (My Account page).
Update 2019-08-05
Machine learning changes
- ML rule names converted to human-readable format.
Update 2019-07-26
Service changes
- Hiding email_account_details optionally.
- Gift (boolean) and Gift message (boolean) input fields validation added to Service.
Update 2019-07-19
Machine learning changes
- New device fingerprinting fields added to Machine learning algorithm.
Update 2019-07-11
Service changes
- New device fingerprinting fields added to Scoring Engine.
Update 2019-06-21
Service changes
- Does not contain operator added to Compare rules.
- New action types added to service:
add_item_to_cart
,remove_item_from_cart
,add_promotion
,create_content
,account_logout
,submit_Review
,update_content
,verification
- Count current transaction option added to Scoring Engine.
New admin features
- Count current transaction option added to Velocity and User behavior rules (Scoring Engine).
Update 2019-06-13
New admin features
- Sandbox environment option implemented.
- Notification enabled for all user types.
Update 2019-05-16
Service changes
- Percentage comparison added to Scoring Engine.
New admin features
- Percentage comparison added to Velocity rules (Scoring Engine).
Update 2019-05-10
New admin features
- Manual page UI updated (Manual page).
- Team activity widget added to Dashboard (Dashboard).
- LinkedIn profile link added to Email widget (Transaction details page).
- Ability to add multiple billing emails (Billing details page).
Update 2019-04-25
New admin features
- Exclude customer feature added (Transaction details page).
- Logging extended with direct links (Logs page).
Update 2019-03-29
New admin features
- Workbench page added.
- New supported currencies: KZT, VND, BYN, UAH, AZN, BTC, ETH, BCH, XRP, LTC, USDT.
Update 2019-03-18
New admin features
- Separate commenting added to Notes widget (Transaction details page).
Update 2019-02-14
New admin features
- New data field added to Scoring Engine called “Missing device details” (Scoring Engine).
- Profile pictures added to team members (Team).
- Affected transactions and affected amount added to machine learning complex rules (Scoring Engine / Machine learning).
Update 2019-01-24
New admin features
- Role groups added to Team with customizable roles and permissions (Team / Role groups).
- Readable names and numbering added to user devices (Activity tab).
- Dropdown selector added to country data fields (Transactions / Filters, Scoring Engine).
Update 2018-12-21
Service changes
- Count of numbers and count of numbers in a row added to email handle / username analysis.
- Disposable email check for subdomains.
New admin features
- Quick search added to transaction list (Transactions page).
- Readable names and numbering added to user devices in Devices & OS widget (Transaction details page).
- Count of numbers and count of numbers in a row in email handle / username added to filters (Transactions page).
- Count of numbers and count of numbers in a row in email handle / username added to Scoring Engine (Scoring Engine).
Update 2018-11-20
Service changes
- Turn on machine learning rules over a certain accuracy.
New admin features
- Filters for machine learning rules (Scoring Engine / Machine learning).
- Set accuracy to auto deploy machine learning rules (Settings page).
- State change with label selection (Transactions page).
- First seen value added to Identity widget (Transaction details page).
- Machine learning rule details design update (Scoring Engine / Machine learning).
Update 2018-10-15
New admin features
- User specific notification settings (My account / Notifications).
- Base currency added to every currency dropdown.
Update 2018-09-25
Service changes
- Default IP expiration time added to service.
New admin features
- Email handle / username analysis added to widgets (Transaction details page).
- Email handle / username analysis added to filters (Transactions page).
- Action type, rule type filter added to machine learning rules (Scoring Engine / Machine learning).
- Rule export functionality added (Scoring Engine).
Update 2018-09-14
Service changes
- Lists API added to service. It is able to blacklist/normal/whitelist all data fields.
- Email handle, username, full name similarity and analysis added to Scoring Engine.
- JavaScript boolean field removed from request. No longer needed in requests. Backward compatibility provided.
New admin features
- Email handle, username, full name similarity and analysis added to Filters (Transactions / Filters).
- Base currency added to currency selectors.
Update 2018-09-04
Service changes
- VKontakte added to Email API response and Scoring Engine.
New admin features
- Email handle, username, full name similarity and analysis added to widgets (Transaction details page).
- VKontakte result added to Email widget (Transaction details page).
- VKontakte added to Scoring Engine (Scoring Engine / Rule).
Update 2018-08-07
Service changes
- Automatic billing implemented.
- Automatic boarding process implemented.
- New fields added to Scoring Engine: Shipping method, Discount code, IP latitude, IP longitude, Card issuer, Card country, Phone possible, Email exists, Email disposable, Email free, Have I been pwned? exists, Data breaches, First breach, Domain suffix, Domain registered, Domain creation date, Domain updated, Tor, HTTP proxy, Web proxy, Open ports, IP blacklist names, IP blacklist number, Datacenters, Plugin names, Logged in social sites, DNS IP Country, DNS IP ISP, WebRTC count, Transaction amount (exchanged).
New admin features
- Rule history added to Scoring Engine (Scoring Engine / Rule).
- Currency selector added to statistics (Transactions / Statistics).
- Locale settings added to format dates and numbers (Settings page).
- Billing details added to Admin Panel (Billing page).
Update 2018-06-15
Service changes
- Transaction amounts are now saved in the account’s default currency too.
New admin features
- Ability to modify list columns (Transactions page).
- Set default currency for the admin interface (Settings page).
- Filter for exchanged transaction amount based on the default currency (Transactions page).
Update 2018-06-01
Service changes
- Heuristic rules inspect all data fields.
- Automatically turn on heuristic rules over a certain accuracy.
New admin features
- Instant Google search added to Email widget (Transaction details page).
- Downloadable User Guide and Product Features documents added to support page (Support page).
Update 2018-04-26
Service changes
- Ability to label multiple transactions at the same time.
New admin features
- Ability to turn off flagging feature (Settings page).
- Airline specific widgets added to Transaction details page (Transaction details page).
- Action type filtering added to rule list (Scoring Engine / Custom rules).
- Transaction list page update with viewed, not-viewed-yet sign (Transactions page).
- Registration score added to Identity widget (Transaction details page).
Update 2018-04-10
Service changes
- Machine learning rule generation added to Scoring Engine.
- Automatic flagging option for blacklisted values.
- The ‘ip_connection_type’ attribute was removed from API response.
New admin features
- Rule tester added to Rule editor (Scoring Engine / Rule).
- Auto flag blacklisted values option added (Settings page).
- Admin Panel tutorial added (Tutorial menu).
- Multiple row selection added (Transactions, Customers, Rules)
Update 2018-03-20
Service changes
- “type” attribute added to device_details Object. If the request is sent through one of our SDKs, the device_details object changes accordingly.
- Heuristic rules added to Scoring Engine.
- Flagged values added to Scoring Engine.
- Scoring Engine compare type rules now can handle IP ranges.
New admin features
- New “Raw data” tab added in order to inspect API requests and responses (Transaction Detials page).
- Customer Connections multiple datapoint selection added (Transaction Details page).
- Machine learning settings added in order to set bad and negative labels and heuristic rule data points (Settings page).
- Machine learning tab added to scoring engine (Scoring Engine page).
Update 2018-02-28
Service changes
- Flagging feature added.
New admin features
- Email address, IP address and Browser Hash can be flagged from the Admin Panel (Transaction Detials page).
- Flagged as suspicious page added (Lists page).
Update 2018-02-09
Service changes
- IPv6 support added to Fraud and Proxy API.
New admin features
- Blacklist page filter added (Lists page).
- Quick filter added to blacklist page (Lists page).
- Customer Status widget impoved with comments and expiration date options (Transaction Detials page).
- Lockable filters to transaction and customer filtering (Transaction page, Customers page).
Update 2017-11-20
Service changes
- The way of authentication has been changed, from now on header authentication is used. Our deprecated version of authentication (POST payload) is also available until 28th of February 2018.
- js_ip, js_ip_country, js_ip_isp has been added to device_details in Fraud API response. JS IP is the user’s IP address where the session data is coming from.
Update 2017-11-09
Service changes
- Added support for blacklisting/whitelisting multiple user ID-s with one API request.
- Since Yahoo no longer supports creation date information, we removed the attribute from our API response.
- Weibo has been added to our Email API.
- Device timezone format has been changed in our API response (“timezone”: “+2:00”).
- The fraud_score, email_score and proxy_score format has changed to number in our API response.
New admin features
- Quick blacklisting/whitelisting in the new Customer status pop-up (Transaction Detials page).
- Applied velocity rule details can be seen in the Applied rules widget (Transaction Detials page).
- Filtering tool has been updated (Transactions).
Update 2017-10-06
API request changes
- From now on you can call our Fraud API’s label parameters with: “true”, true, 1, “1”, false, “false”,0,“0”. Parameters: label_email, label_address, label_fingerprints, label_ip, label_phone.
Data point name changes
- fonts_as_string -> font_names
- logged_in_social_sites -> social_sites
Response format changes
- webrtc_ips, logged_in_social_sites, social_sites are now in JSON format.
Device details timezone
- Device Fingerprinting: Released version v2.0 of our agent JS / Device Fingerprint modul, extended with browser based social media data.
New admin features
- Email notification option from now allows you to notify you in certain events (My account / Notifications).
- Scoring Engine update with new grouping, AND/OR operators function (Scoring Engine).
- Instant chat support (Every page bottom right corner).
- Webhook function for transaction state changes (Settings / Webhook settings).
- New customer status widget for better data point blacklisting (Transaction Details page).
- Qucik filter button added to every data point for faster search (Transaction Details page).
Deprecated versions
Fraud API v1.0
Request
SEON’s Fraud API is the core end-to-end solution designed to reduce fraud. It includes all our module APIs, but you can enable or disable them such as the Email API or the device fingerprint function via JavaScript snippet. It supports business-specific data fields for scores, using the user_label.
JSON Attributes | Type | Required | |
---|---|---|---|
ip | string | no | |
action_type | string | no | |
transaction_id | string | no | |
affiliate_id | string | no | |
affiliate_name | string | no | |
user_order_memo | string | no | |
run_email_api | boolean | no | |
string | no | ||
email_domain | string | no | |
password_hash | string | no | |
user_fullname | string | no | |
user_name | string | no | |
user_id | string | no | |
user_created | integer | no | |
user_country | string | no | |
user_city | string | no | |
user_region | string | no | |
user_zip | string | no | |
user_street | string | no | |
user_street2 | string | no | |
session_id | string | no | |
device_id | string | no | |
payment_mode | string | no | |
card_fullname | string | no | |
card_bin | string | no | |
card_hash | string | no | |
card_last | string | no | |
avs_result | string | no | |
cvv_result | boolean | no | |
phone_number | string | no | |
transaction_type | string | no | |
transaction_amount | float | no | |
transaction_currency | string | no | |
items | array of item objects | no | |
shipping_country | string | no | |
shipping_city | string | no | |
shipping_region | string | no | |
shipping_zip | string | no | |
shipping_street | string | no | |
shipping_street2 | string | no | |
shipping_phone | string | no | |
shipping_fullname | string | no | |
shipping_method | string | no | |
billing_country | string | no | |
billing_city | string | no | |
billing_region | string | no | |
billing_zip | string | no | |
billing_street | string | no | |
billing_street2 | string | no | |
billing_phone | string | no | |
discount_code | string | no | |
gift | boolean | no | |
gift_message | boolean | no | |
merchant_id | string | no | |
merchant_created_at | integer | no | |
merchant_country | string | no | |
details_url | string | no | |
user_label | object | no | |
HTTP Endpoint
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
Errors for Fraud API v1.0
Error Code | Explanation |
---|---|
1000 | Empty request body. |
1001 | IP address is missing. |
1002 | IP address is invalid. |
1003 | License key is missing. |
1004 | License key is invalid. |
1005 | Invalid public key. |
1006 | JSON input is invalid. |
1008 | Missing email address. |
1009 | Invalid email address. |
1010 | Invalid authorization header. |
1011 | Inactive license. |
1012 | Your subscription has ended. |
2001 | System database error. |
3000 | [data_field_name] size must be between [minimum_value] and [maximum_value] . |
3001 | Invalid ‘user_created’ input parameter. |
3002 | Invalid ‘cvv_result’ input parameter. |
3003 | Invalid ‘transaction_amount’ input parameter. |
3004 | Invalid ‘items_quantity’ input parameter. |
3005 | Invalid ‘items_price’ input parameter. |
3006 | Invalid ‘merchant_created_at’ input parameter. |
3007 | Invalid ‘action_type’ input parameter. |
3008 | ‘transaction_amount’ not provided along with ‘transaction_currency’. |
3009 | Invalid ‘gift’ input parameter. |
3010 | Invalid ‘gift_message’ input parameter. |
Migration from Fraud API v1.0 to v2.0
New config object for Fraud API
run_email_api
field in input is deprecated for v2.0, Email API should be set inconfig
object (setemail_api: true
).- IP API won’t be executed by default, need to set explicitly in
config
object. (setip_api: true
). - Device fingerprint won’t be enabled by default, need to set explicitly in
config
object. (setdevice_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). Thesession_id
parameter is still required for the configuration, the change affects the data that you need to send in the Fraud API request related to the Device Fingerprint module. - The previous SDK versions are still supported with the
session_id
field, but we highly recommend to migrate the Device Fingerprint module. - The public key is no longer necessary with the latest SDK versions.
- You must set
device_fingerprinting: true
in the config object to enable the feature.
Keep in mind the following input fields were renamed in Fraud API v2.0:
user_label
->custom_fields
item_user_label
->item_custom_fields
user_order_memo
->order_memo
Response changes: Please find the full data field mapping from Fraud API v1.0 to v2.0 here.
Email API v1.0
Request
JSON Attributes | Type | Required | |
---|---|---|---|
string | yes | ||
HTTP Endpoint
Response
The endpoint returns JSON structured response.
JSON Attributes | Type | |
---|---|---|
string | ||
email_score | number | |
email_exists | boolean | |
disposable | boolean | |
free | boolean | |
domain_exists | boolean | |
email_domain_details | object | |
email_account_details | object | |
Response
Email API v2.0
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.
Request Attributes | Value | Required | |
---|---|---|---|
include | history | no | |
include | flags | no | |
include | id | no | |
flags_timeframe_days | [number of days] | no | |
timeout | [number of milliseconds] | no | |
HTTP Endpoint
Response
The endpoint returns JSON structured response.
JSON Attributes | Type | |
---|---|---|
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
Email API v2.1
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.
Request Attributes | Value | Required | |
---|---|---|---|
include | history | no | |
include | flags | no | |
include | id | no | |
flags_timeframe_days | [number of days] | no | |
timeout | [number of milliseconds] | no | |
HTTP Endpoint
Response
The endpoint returns JSON structured response.
JSON Attributes | Type | |
---|---|---|
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
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:
JSON Attributes | Value | Required | |
---|---|---|---|
include | history | no | |
include | flags | no | |