NAV Navbar
cURL

API Reference

By integrating our REST APIs you can reduce fraudulent activity on your online platform. You can also score user actions (login, signup etc.) not only payments. It can boost our machine learning capabilities in order to stop fraudulent transactions. Your first step is to obtain a license key to get access to our APIs. Please sign up at our website.

Geo API

Our Geo API delivers the geolocation data for an IP address. It involves the ISP, organization name, as well as the latitude and longitude information. This is a free API, by obtaining a license key you can use it forever and for unlimited queries.

Request

$ curl "https://api.seon.io/SeonRestService/geo-api/v1.0/?ip=[ip]&license_key=[license_key]"

HTTP Endpoint

GET https://api.seon.io/SeonRestService/geo-api/v1.0/

Query Parameters

Parameter Required Description
ip yes Client’s IP address.
license_key yes Your license key.

Response

{
  "success": true,
  "data": {
    "country": "HU",
    "state_prov": "Budapest",
    "city": "Budapest",
    "timezone_offset": "2",
    "timezone_name": "Europe/Budapest",
    "isp_name": "DIGI",
    "connection_name": "",
    "organization_name": "DIGI Tavkozlesi es Szolgaltato Kft.",
    "latitude": "47.4979",
    "longitude": "19.0402",
    "connection_type":"DSL"
  }
}

The endpoint returns JSON structured response.

JSON Data Attributes

Name Type Description
country string IP country code.
state_prov string IP state.
city strng IP city.
timezone_offset integer IP timezone offset.
timezone_name string IP timezone name.
isp_name string IP ISP name.
@Deprecated connection_name string IP connection name.
@Deprecated organization_name string IP organization name.
latitude string IP latitude.
longitude string IP longitude.
connection_type string IP connection type.

Proxy API

Our Proxy API determines how likely an IP address is a proxy / VPN / hosting / bad IP using advances mathematical and modern computing techniques. You can block TOR / VPN / proxy users, as well as malware and spyware / criminal netblocks / spiders / botnets / spammers and exploit scanners. Spammers and trolls will try to bypass a ban by hiding their real IP address using proxies. Proxy API helps you to reduce fake views, clicks, and activity that results in click fraud and view fraud. This also helps to prevent ATO (Account take over).

Request

$ curl "https://api.seon.io/SeonRestService/proxy-api/v1.0/?ip=[ip]&license_key=[license_key]"

HTTP Endpoint

GET https://api.seon.io/SeonRestService/proxy-api/v1.0/

Query Parameters

Parameter Required Description
ip yes Client’s IP address.
license_key yes Your license key.

Response

{
  "success": true,
  "data": {
    "ip": "213.1.156.1",
    "proxy_score": "0.98"
  }
}

The endpoint returns JSON structured response.

JSON Data Attributes

Name Type Description
ip string User IP.
proxy_score string A score from 0-100 indicating the likelihood that the user’s using proxy.

Fraud API

Our Fraud API is the end-to-end solution to reduce fraud. It involves all of our module APIs, you can disable and enable Email API or the device fingerprint function (JavaScript snippet) if needed. You can send us historical data to preset the scoring algorithm for your use-case. The more data you provide more accurate the scoring gets. You can use your business specific labels to make the scoring more accurate by the user_label. By the default over 10 score, the transaction considered as risky, the scoring status thresholds are the following: 0 - 10 approve, 10 - 20 review and over 20 decline.

Request

$ curl 'https://api.seon.io/SeonRestService/fraud-api/v1.0/' \
  -X POST \
  -H 'Content-Type: application/json; charset=UTF-8' \
  -d '{
    "ip": "123.123.123.123",
    "license_key": "8bbbe856-c498-4a70-b61c-ac0d990794ba",
    "javascript": true,
    "transaction_id": "",
    "user_id": "",
    "affiliate_id": "",
    "user_fullname": "",
    "user_name": "",
    "affiliate_name": "",
    "user_order_memo": "",
    "email": "",
    "run_email_api": true,
    "password_hash": "",
    "user_created": "",
    "user_country": "",
    "user_city": "",
    "user_region": "",
    "user_zip": "",
    "user_street": "",
    "user_street2": "",
    "device_id": "",
    "session_id": "2FCFA7EFB3300428CE27D4D1CF35E76D",
    "payment_mode": "",
    "action_type": "",
    "card_fullname": "",
    "card_bin": "",
    "card_hash": "",
    "card_last": "",
    "avs_result": "",
    "cvv_result": "",
    "phone_number": "",
    "transaction_type": "",
    "transaction_amount": 354.55,
    "items": [{
      "item_id": "",
      "item_quantity": "",
      "item_name": "",
      "item_price": "",
      "item_store": "",
      "item_store_country": "",
      "item_categories": "",
      "item_url": "",
      "item_user_label": ""
    }, {
      "item_id": "",
      "item_quantity": "",
      "item_name": "",
      "item_price": "",
      "item_store": "",
      "item_store_country": "",
      "item_categories": "",
      "item_url": "",
      "item_user_label": ""
    }],
    "transaction_currency": "",
    "shipping_country": "",
    "shipping_city": "",
    "shipping_region": "",
    "shipping_zip": "",
    "shipping_street": "",
    "shipping_street2": "",
    "shipping_fullname": "",
    "shipping_phone": "",
    "shipping_method": "",
    "billing_country": "",
    "billing_city": "",
    "billing_region": "",
    "billing_zip": "",
    "billing_street": "",
    "billing_street2": "",
    "billing_phone": "",
    "discount_code": "",
    "gift": "",
    "gift_message": "",
    "merchant_id": "",
    "merchant_created_at": "",
    "merchant_created_at": "",
    "user_label": {"is_intangible_item": true,"is_pay_on_delivery":true,"departure_airport":"BUD","days_to_board":1,"arrival_airport":"MXP"}
  }'

HTTP Endpoint

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

JSON Attributes

Parameter Type Required Description
ip string no User’s IP address at transactions time.
license_key string yes Your license key
javascript boolean no It’s optional to install our JavaScript snippet. Please enter false if you have not, and true if you have. It provides in-depth analysis of the browser and device of a user and transaction. We strongly recommend to work implement this agent to your site.
action_type string no Type of user action, which is being scored, following types are valid: purchase, recur_purchase, deposit, withdrawal, account_register, account_login, account_login_fail, account_password_change, account_email_change, account_edit
user_id string no User’s unique identifier in your system. If it is not specified, we automatically generate one. Example: 00ab11-as2233
affiliate_id string no User’s unique affiliate identifier in your system.
user_fullname string no User’s registered full name. Can be hash in ASCII encoding as well (e.g. MD5, SHA-2 family). Example: John Doe
user_name string no User’s registered username. Can be hash in ASCII encoding as well (e.g. MD5, SHA-2 family). Example: jdoe325
affiliate_name string no User’s registered affiliate name. Can be hash in ASCII encoding as well (e.g. MD5, SHA-2 family). Example: jdoe325
user_order_memo string no Description of a transaction by merchant. Maximum 250 characters.
run_email_api boolean no It’s optional to run our Email API. Please enter false if you would not like to, and true if you would like to. It provides in-depth analysis of the user’s email address.
email string no User’s registered email address. Can be hash in ASCII encoding as well (e.g. MD5, SHA-2 family), but in this case we strongly recommend to provide email_domain.
email_domain string no Domain of the email address used by the user. Example: gmail.com
password_hash string no Hash of the user’s password in ASCII encoding (e.g. MD5, SHA-2 family).
user_created integer no Date of user first registered to your site in UNIX time format and UTC time zone. Example: 1446370717 (Sun, 01 Nov 2015 09:38:37 +0000)
user_country string no A two-character ISO 3166-1 country code for the country associated with the user’s registered address. Examples: US, DE
user_city string no Full name of city associated with the user’s registered address. Examples: London, New York
user_region string no A two character ISO 3166-2 code for the state/region associated with the user’s registered address. Example: NY
user_zip string no Zip/postal code of an user’s registered address. Examples: 10005, PH1 1EU
user_street string no User’s registered street address line 1. Can be hash in ASCII encoding as well (e.g. MD5, SHA-2 family). Example: 157 W 26th St
user_street2 string no User’s registered street address line 2. Can be hash in ASCII encoding as well (e.g. MD5, SHA-2 family). Example: Apt. 432
session_id string no An unique identifier of the user session, for example tracking cookies.
device_id string no An unique identifier of the user’s device, for mobile devices it can be the unique device ID (UDID).
payment_mode string no Method of payment used. Examples: card, paypal, wire transfer, bitcoin
payment_id string no Unique payment identifier in your system. If it is not specified, we automatically generate one. Example: 001122-334455
card_fullname string no User’s full name as present on the card. Can be hash in ASCII encoding as well (e.g. MD5, SHA-2 family).
card_bin string no The credit card BIN number. This is the first 6 digits of the credit card number. It identifies the issuing bank.
card_hash string no Hash of the credit card used by the user in ASCII encoding (e.g. PAN, RSA, SHA-2 family). We do not recommend MD5 hash for this value.
avs_result string no Standard AVS codes returned to you by the credit card processor. Examples: N, A
cvv_result boolean no Result of the CVV check. Accepted values: true, false
phone_number string no Registered phone number of a user, with country code and without spaces/hyphens. Example: 0018889607230
transaction_type string no Transaction’s type, according to your business. Examples: purchase, return
transaction_amount float no Transaction amount, Example: 539.99, it is the sum of the prices in the transaction, decimal point should be .
transaction_currency string no ISO 4217 Code for the currency used by the user. Example: EUR, USD
items array of item objects no List of items of the transaction purchase. Every field starting with items_ is part of this array.
shipping_street string no User’s shipping street address line 1. Can be hash in ASCII encoding as well (e.g. MD5, SHA-2 family). Example: 157 W 26th St
shipping_street2 string no User’s shipping street address line 2. Can be hash in ASCII encoding as well (e.g. MD5, SHA-2 family). Example: Apt. 432
shipping_city string no Full name of city associated with the user’s shipping address. Examples: London, New York
shipping_region string no A two character ISO 3166-2 code for the state/region associated with the user’s shipping address. Example: NY
shipping_zip string no Zip/postal code of an user’s shipping address. Examples: 10005, PH1 1EU
shipping_country string no A two-character ISO 3166-1 country code for the country associated with the user’s shipping address. Examples: US, DE
shipping_fullname string no User’s registered full name. Can be hash in ASCII encoding as well (e.g. MD5, SHA-2 family). Example: John Doe
shipping_phone string no Shipping phone number of a user, with country code and without spaces / hyphens. Example: 0018889607230.
billing_street string no User’s billing street address line 1. Can be MD5 hash in ASCII encoding as well. Example: 157 W 26th St
billing_street2 string no User’s billing street address line 2. Can be MD5 hash in ASCII encoding as well. Example: Apt. 432
billing_city string no Full name of city associated with the user’s billing address. Examples: London, New York
billing_region string no A two character ISO 3166-2 code for the state/region associated with the user’s billing address. Example: NY
billing_zip string no Zip/postal code of an user’s billing address. Examples: 10005, PH1 1EU
billing_country string no A two-character ISO 3166-1 country code for the country associated with the user’s billing address. Examples: US, DE
billing_phone string no Billing phone number of a user, with country code and without spaces / hyphens. Example: 0018889607230
merchant_id string no Unique identifier of a merchant to determine between several merchants. Example: ab01-cd23-4567
merchant_created_at integer no Date of merchant created on your site in UNIX time format and UTC time zone. Example: 1446370717 (Sun, 01 Nov 2015 09:38:37 +0000)
merchant_country string no A two-character ISO 3166-1 country code for the country associated with the merchant. Examples: US, DE
details_url string no URL of the transaction in your own order management platform. Example: electronics.example.com/orders/order-1234
user_label object no If you want to inform our machine learning system and scoring engine with some other fields, our platform supports unlimited number of user defined fields, which can be string, boolean and numeric. Examples: is_intangible_item, is_pay_on_delivery, departure_airport, arrival_airport, days_to_board

Item Object

Name Type Required Description
item_id string no Unique product identifier in your system.
item_quantity integer no Quantity of the purchased items.
item_name string no Name of the purchased item. Example: Apple iPhone 6S 128Gb Silver.
item_price float no Price of the purchased item, Example: 539.99, decimal point should be . .
item_store string no When customers can buy on the same platform from different sellers, merchant_id would identify the marketplace that takes the order and items_store the store which fulfills it. Example: Brooklyn Electronics
item_store_country string no A two-character ISO 3166-1 country code for the country associated with the items_store. Examples: US, DE
item_categories array no List of the categories where the items belongs to. It includes sub-categories so can be multi-level. It represents a list of string, for example: ["Electronics", "Smartphones"] stand for a subcategory of Smartphone and main category of Electronics. Examples: ["Magazines"], ["Electronics", "Consoles"].
item_url string no URL of the product’s description. Example: https://electronics.example.com/pd_1234.php.
item_user_label object no If you want to inform our machine learning system with some other fields, our platform supports unlimited number of user defined fields, which can be string, boolean and integer. Examples: color, size.

Response

{
  "success": true,
  "data": {
    "id": "213-321",
    "is_fraud": "false",
    "state": "APPROVE",
    "fraud_score": "4.24",
    "proxy_score": "0.6",
    "ip_details": {
      "ip": "178.48.165.161",
      "country": "HU",
      "state_prov": "Budapest",
      "city": "Budapest",
      "timezone_offset": "2",
      "timezone_name": "Europe/Budapest",
      "isp_name": "UPC",
      "connection_name": "unknown",
      "organization_name": "UPC Magyarorszag Kft.",
      "latitude":"47.4861",
      "longitude":"19.0669",
      "connection_type":"DSL"
    },
    "email_details": {
      "email": "info@seon.io",
      "email_score": "18.04",
      "email_exists": "false",
      "disposable": "false",
      "free": "false",
      "email_domain_details": {
        "domain": "seon.io",
        "suffix": ".io",
        "registered": "true",
        "created": "null",
        "updated": "null"
      },
      "email_account_details": {
        "facebook_exists": "false",
        "facebook_profile": "unknown",
        "facebook_name": "unknown",
        "facebook_photo": "unknown",
        "google_exists": "false",
        "google_profile": "unknown",
        "google_name": "unknown",
        "google_photo": "unknown",
        "apple_exists": "false",
        "twitter_exists": "false",
        "microsoft_exists": "false",
        "yahoo_exists": "false",
        "yahoo_created": "unknown",
        "ebay_exists": "false",
        "gravatar_exists": "false",
        "instagram_exists": "false",
        "spotify_exists": "false",
        "tumblr_exists": "false"
      }
    },
    "bin_details": {
      "card_bin": "403298",
      "bin_bank": "NORTHERN NECK STATE BANK",
      "bin_card": "VISA",
      "bin_type": "DEBIT",
      "bin_level": "BUSINESS",
      "bin_country": "UNITED STATES",
      "bin_countrycode": "US",
      "bin_phone": "(804) 435-1626",
      "bin_valid": "true"
    },
    "phone_details":{  
      "phone_number":"+36 70 666 6666",
      "phone_is_valid":true,
      "phone_is_possible":true,
      "phone_type":"MOBILE",
      "phone_country":"HU",
      "phone_carrier":"Vodafone"
    },
    "credit_remaining": "0",
    "version": "v1",
    "applied_rules": [
      {
        "id": "3",
        "name": "#3 IP country does not match with billing country",
        "operation": "+",
        "score": "2"
      }
    ],
    "calculation_time": "930"
  }
}

The endpoint returns JSON structured response.

JSON Data Attributes

Name Type Description
id string A unique identifier, it equals the transaction_id which was sent with input data, if nothing was sent an id is generated.
@Deprecated is_fraud string Indicates whether the transaction is fraudelent or not.
state string Transaction state, which indicates the further action. State can be either APPROVE, REVIEW or DECLINE. You can adjust score thresholds from the settings panel.
fraud_score string A score from 0-100 indicating the likelihood that the user’s is fraud.
proxy_score string A score from 0-100 indicating the likelihood that the user’s is using proxy.
ip_details object ip: The IP address of the customer.
country: A two-character ISO 3166-1 country code for the country associated with the IP address.
state_prov: A two character ISO 3166-2 code for the state/region associated with the IP address.
city: Full name of city.
timezone_offset: Timezone offset.
timezone_name: Timezone name.
isp_name: ISP name.
@Deprecated connection_name: Connection name.
@Deprecated organization_name: Organization name.
latitude: IP latitude.
longitude: IP longitude.
connection_type: Connection type.
email_details object email: The email address of the customer.
email_score: A score from 0-100 indicating the likelihood that the user’s email address is fraud.
email_exists: Indicates that the email address is actually exists or not.
disposable: Email domain is fraudulent (such as disposable email, previous fraudulent domains).
free: Email domain is free (such as outlook, yahoo, gmail etc.).
email_domain_details: object view details
email_account_details: object view details
bin_details object card_bin: The credit card BIN number.
bin_bank: Card’s bank name.
bin_card: Card’s network.
bin_type: Type of card.
bin_level: Level of card.
bin_country: Country of card.
bin_countrycode: Country code of card.
bin_website: Website of owner bank.
bin_phone: Phone of owner bank.
bin_valid: Is the card valid or not.
phone_details object phone_number: User’s phone number.
phone_is_valid: User’s phone number is valid or not using length and prefix information.
phone_is_possible: User’s phone number is possible or not based on length and validation.
phone_type: User’s phone type based on the number, types: Fixed-line, Mobile, Toll-free, Premium Rate, Shared Cost, VoIP and Personal Numbers.
phone_country: User’s phone country based on prefix information.
phone_carrier: User’s phone carrier based on number.
credit_remaining integer Number of credit remaining for the customer with the associated license key.
version string Version of the SEON API.
applied_rules array of objects Array of rules which were configured in Rule Configurator.

id: Unique identifier of the rule.
name: Name of the rule.
operation: Operation of the rule.
score: Score of the rule.
calculation_time string Calculation time of the score in milliseconds.

Transaction Labeling

$ curl 'https://api.seon.io/SeonRestService/fraud-api/label/[id]' \
   -X PUT \
   -H 'Content-Type: application/json; charset=UTF-8' \
   -d \
   '{
     "license_key": "[license_key]",
     "label": "fraud"
   }'

You can label the transactions with different statuses and results if it was actually fraudulent or not. It can boost our machine learning algorithm to minimize false negatives and positives. This is achieved through a PUT request.

HTTP Endpoint

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

JSON Attributes

Parameter Type Required Description
label string yes The label you would like to apply for the transacation.
license_key string yes Your license key.

Blacklist and Whitelist Users

$ curl 'https://api.seon.io/SeonRestService/fraud-api/user/123-123' \
   -X PUT \
   -H 'Content-Type: application/json' \
   -d \
   '{
     "license_key": "550e8400-e29b-41d4-a716-446655440000",
     "state": "blacklist",
     "label_email": true,
     "label_address": true,
     "label_fingerprints": true,
     "label_ip": true,
     "comment": "this is a fake user",
   }'

We provide the opportunity to blacklist or whitelist the users based on the user_id, if the customer knows that specific users are bad and wants to block them automatically or there are trusted users with suspicious activities. This is achieved through a PUT request.

HTTP Endpoint

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

JSON Attributes

Parameter Type Required Description
license_key string yes Your license key.
state string yes Accepted values: blacklist, whitelist, normal.
label_email boolean no State of the previous email addresses used by the user. Please enter false if you would not like to, and true if you would like to.
label_address boolean no State the previous addresses (normal, shipping, billing) used by the user. Please enter false if you would not like to, and true if you would like to.
label_fingerprints boolean no State the previous browser fingerprints used by the use. Please enter false if you would not like to, and true if you would like to.
label_ip boolean no State the previous IP addresses used by the user. Please enter false if you would not like to, and true if you would like to.
comment string no Any comment which will be visible on the admin panel.

Javascript Agent

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

<html>
  <head>
    ...
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
    <script src="https://api.seon.io/SeonRestService/js/agent.js"></script>
    ...
  </head>
  <body>
    ...
    <script>
    start('[session_id]');
    </script>
  </body>
</html>

Please follow the steps below to begin collect session and device specific data with our javascript agent.

  1. Include jQuery (min 1.11.2) in your header, between “<head> … <head>” tags.
  2. Include SEON JavaScript agent in your header, between “<head> … </head>” tags.
  3. Insert the initialization code to the bottom of your page, just before the “</body>” tag.
  4. Replace [session_id] with the unique identifier of user’s session.

Email API

Email API: Our Email API provides the most accurate and insightful email address investigation tool by combining hundreds of data sources to protect your business against fraud. We collect not only open but any reachable social data in order to stop fraudsters just by looking at the email address.

Request

$ curl "https://api.seon.io/SeonRestService/email-api/v1.0/?email=[email]&license_key=[license_key]"

HTTP Endpoint

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

Query Parameters

Parameter Required Description
email yes Email address.
license_key yes Your license key.

Response

{
  "success": true,
  "data": {
    "email": "example@seon.io",
    "email_score": "0.0",
    "email_exists": "false",
    "disposable": "false",
    "free": "false",
    "email_domain_details": {
      "domain": "seon.io",
      "suffix": ".io",
      "registered": "true",
      "created": "null",
      "updated": "null"
    },
    "email_account_details": {
      "facebook_exists": "false",
      "facebook_profile": "unknown",
      "facebook_name": "unknown",
      "facebook_photo": "unknown",
      "google_exists": "false",
      "google_profile": "unknown",
      "google_name": "unknown",
      "google_photo": "unknown",
      "apple_exists": "false",
      "twitter_exists": "false",
      "microsoft_exists": "false",
      "yahoo_exists": "false",
      "yahoo_created": "unknown",
      "ebay_exists": "false",
      "gravatar_exists": "false",
      "instagram_exists": "false",
      "spotify_exists": "false",
      "tumblr_exists": "false"
    }
  }
}

The endpoint returns JSON structured response.

JSON Data Attributes

Name Type Description
email string User’s email address.
email_score string A score from 0-100 indicating the likelihood that the user’s using a fake email address.
email_exists string true if the email address exists or not by SMTP-MX ping.
disposable string true if the email address is on blacklist.
free string true if the email address is on free list.
email_domain_details object Details about the domain of the email address.
email_account_details object We check if a Facebook, Google Plus, Twitter, Microsoft, Apple, Yahoo account is registered with the email address. If available, we provide details like avatar URL, name or registration date.

email_domain_details Object

Name Type Description
domain string The domain of the email address of the customer.
suffix string The suffix of the domain.
registered boolean Email domain is registered or not.
created date Creation date of the email domain.
updated date Date of the last updated time of the email domain.

email_account_details Object

Name Type Description
facebook_exists boolean Email address is registered in Facebook or not.
facebook_profile string URL of the Facebook profile with the email address if exists.
facebook_name string Name of the Facebook profile of the email profile if exists.
facebook_photo string URL of the Facebook photo of the email profile if exists.
google_exists boolean Email address is registered in Google Plus or not.
google_profile string URL of the Google profile with the email address if exists.
google_name string Name of the Google profile of the email profile if exists.
google_photo string URL of the Google photo of the email profile if exists.
apple_exists boolean Email address is registered in Apple or not.
twitter_exists boolean Email address is registered in Twitter or not.
microsoft_exists boolean Email address is registered in Microsoft or not.
yahoo_exists boolean Email address is registered in Yahoo or not.
yahoo_created date Registration date of the email address in Yahoo.
ebay_exists boolean Email address is registered in Ebay or not.
gravatar_exists boolean Email address is registered in Gravatar or not.
instagram_exists boolean Email address is registered in Instagram or not.
spotify_exists boolean Email address is registered in Spotify or not.
tumblr_exists boolean Email address is registered in Tumblr or not.

Errors

Example error response

{
  "success": false,
  "data": {},
  "error": {
    "message": "invalid email address",
    "code": "1008"
  }
}

Application Errors

Error Code Explanation
1001 Empty request body.
1002 IP address is invalid.
1003 License key is missing.
1004 License key is invalid.
1006 JSON input is invalid.
1008 Missing email address.
1009 Invalid email address.
2001 System database error.
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.