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 -X POST \
  https://api.seon.io/SeonRestService/geo-api/v1.0 \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
    "license_key": "8bbbe856-c498-4a70-b61c-ac0d990794ba",
    "ip": "213.1.156.1"
}'

HTTP Endpoint

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

JSON Attributes

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

Response

{
  "success": true,
  "data": {
    "ip_country": "HU",
    "ip_state_prov": "Budapest",
    "ip_city": "Budapest",
    "ip_timezone_offset": "2",
    "ip_timezone_name": "Europe/Budapest",
    "ip_isp_name": "DIGI",
    "ip_connection_name": "",
    "ip_organization_name": "DIGI Tavkozlesi es Szolgaltato Kft.",
    "ip_latitude": "47.4979",
    "ip_longitude": "19.0402",
    "ip_connection_type":"DSL"
  }
}

The endpoint returns JSON structured response.

JSON Data Attributes

Name Type Description
ip_country string IP country code.
ip_state_prov string IP state.
ip_city strng IP city.
ip_timezone_offset integer IP timezone offset.
ip_timezone_name string IP timezone name.
ip_isp_name string IP ISP name.
@Deprecated ip_connection_name string IP connection name.
@Deprecated ip_organization_name string IP organization name.
ip_latitude string IP latitude.
ip_longitude string IP longitude.
ip_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 -X POST \
  https://api.seon.io/SeonRestService/proxy-api/v1.0 \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
    "license_key": "8bbbe856-c498-4a70-b61c-ac0d990794ba",
    "ip": "213.1.156.1"
}'

HTTP Endpoint

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

JSON Attributes

Parameter Type Required Description
ip string yes Client’s IP address.
license_key string 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 '{
    "license_key": "8bbbe856-c498-4a70-b61c-ac0d990794ba",
    "ip": "123.123.123.123",
    "javascript": true,
    "action_type": "",
    "transaction_id": "",
    "affiliate_id": "",
    "affiliate_name": "",
    "user_order_memo": "",
    "run_email_api": true,
    "email": "",
    "email_domain": "",
    "password_hash": "",
    "user_fullname": "",
    "user_name": "",
    "user_id": "",
    "user_created": "",
    "user_country": "",
    "user_city": "",
    "user_region": "",
    "user_zip": "",
    "user_street": "",
    "user_street2": "",
    "session_id": "2FCFA7EFB3300428CE27D4D1CF35E76D",
    "device_id": "",
    "payment_mode": "",
    "card_fullname": "",
    "card_bin": "",
    "card_hash": "",
    "card_last": "",
    "avs_result": "",
    "cvv_result": "",
    "phone_number": "",
    "transaction_type": "",
    "transaction_amount": 354.55,
    "transaction_currency": "",
    "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": ""
    }],
    "shipping_country": "",
    "shipping_city": "",
    "shipping_region": "",
    "shipping_zip": "",
    "shipping_street": "",
    "shipping_street2": "",
    "shipping_phone": "",
    "shipping_fullname": "",
    "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_country": "",
    "details_url": "",
    "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
license_key string yes Your license key.
ip string no User’s IP address at transactions time.
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 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
transaction_id string no Transaction’s unique identifier in your system. If it is not specified, we automatically generate one. Example: 98db9a56b2e3.
affiliate_id string no User’s unique affiliate identifier in your system.
affiliate_name string no User’s registered affiliate name. Can be hashed 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. It provides in-depth analysis of the user’s email address.
email string no User’s registered email address. Can be hashed 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_fullname string no User’s registered full name. Can be hashed in ASCII encoding as well (e.g. MD5, SHA-2 family). Example: John Doe
user_name string no User’s registered username. Can be hashed in ASCII encoding as well (e.g. MD5, SHA-2 family). Example: jdoe325
user_id string no User’s unique identifier in your system. If it is not specified, we automatically generate one. Example: 00ab11-as2233
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 a user’s registered address. Examples: 10005, PH1 1EU
user_street string no User’s registered street address line 1. Can be hashed 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 hashed in ASCII encoding as well (e.g. MD5, SHA-2 family). Example: Apt. 432
session_id string no A unique identifier of the user session, for example tracking cookies.
device_id string no A 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
card_fullname string no User’s full name as present on the card. Can be hashed 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 Transactionidentifies 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.
card_last string no The last four digits of the card number used, in order to identify the uniqueness of the card.
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, without spaces/hyphens. Example: 0018889607230
transaction_type string no Transaction 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_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_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_street string no User’s shipping street address line 1. Can be hashed 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 hashed in ASCII encoding as well (e.g. MD5, SHA-2 family). Example: Apt. 432
shipping_phone string no Shipping phone number of a user, with country code, without spaces / hyphens. Example: 0018889607230.
shipping_fullname string no User’s registered full name. Can be hashed in ASCII encoding as well (e.g. MD5, SHA-2 family). Example: John Doe
shipping_method string no The type of shipping method used by the customer. Examples: standard, UPS, FedEx.
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_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_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_phone string no Billing phone number of a user, with country code, without spaces / hyphens. Example: 0018889607230
discount_code string no The discount code that the user applied during checkout.
gift boolean no true or false. whether the order was marked as a gift by the user.
gift_message boolean no true or false whether the gift order had a gift message attached by the user.
merchant_id string no Unique identifier of a merchant to differentiate 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 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",
      "ip_country": "HU",
      "ip_state_prov": "Budapest",
      "ip_city": "Budapest",
      "ip_timezone_offset": "2",
      "ip_timezone_name": "Europe/Budapest",
      "ip_isp_name": "UPC",
      "ip_connection_name": "unknown",
      "ip_organization_name": "UPC Magyarorszag Kft.",
      "ip_latitude":"47.4861",
      "ip_longitude":"19.0669",
      "ip_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_website": "",
      "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",
    "device_details":{  
      "session_id":"EB224562AE34C1AAEB85FE6DC9C250A7",
      "timezone":"-120",
      "private_mode":false,
      "useragent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36",
      "fonts":31,
      "plugins":5,
      "op_sys":"Windows",
      "cookie_enabled":true,
      "screen":"1920x1080",
      "avail_screen":"1920x1040",
      "window_screen":"1924x954",
      "webrtc_count":1,
      "cookie_hash":"0bc73b038cd5553fdc5d3ccd13751c2d",
      "device_hash":"becabac7889519f9c6a1f759b99e3c4e",
      "dns_ip":"{\"dns_ip\":\"79.172.220.140\",\"dns_ip_country\":\"HU\",\"dns_ip_isp\":\"ARCHI-HOST Kft.\"}",
      "browser_hash":"3f99b39967ae438208a8efa80732196b",
      "webrtc_ips":"{\"1\":\"10.5.20.168\"}",
      "webrtc_activated":true,
      "flash":true,
      "java":false,
      "plugins_hash":"32857508",
      "fonts_hash":"-8993837"
    },
    "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 is fraud.
proxy_score string A score from 0-100 indicating the likelihood that the user is using proxy.
ip_details object ip: The IP address of the customer.
ip_country: A two-character ISO 3166-1 country code for the country associated with the IP address.
ip_state_prov: A two character ISO 3166-2 code for the state/region associated with the IP address.
ip_city: Full name of city.
ip_timezone_offset: Timezone offset.
ip_timezone_name: Timezone name.
ip_isp_name: ISP name.
@Deprecated ip_connection_name: Connection name.
@Deprecated ip_organization_name: Organization name.
ip_latitude: IP latitude.
ip_longitude: IP longitude.
ip_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 fraudulent.
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.
device_details object session_id: A unique identifier of the user session, for example tracking cookies.
timezone: User’s timezone offset in JS format.
private_mode: Is user browsing in private mode.
useragent: User’s user agent.
fonts: User’s number of installed fonts on its device.
plugins: User’s number of installed plugins on its browser.
op_sys: Operating system of user’s device.
cookie_enabled: Are cookies enabled in user’s browser.
screen: User’s screen resolution.
avail_screen: User’s avalaible screen resolution.
window_screen: User’s current window resolution.
webrtc_count: Number of WebRTC IPs in client’s browser.
cookie_hash: Unique identifier of user’s current session.
device_hash: Unique identifier of user’s device using hardware rendering.
dns_ip: User’s DNS IP address. dns_ip_isp : User’s DNS IP’s ISP. dns_ip_country: User’s DNS IP’s country.
browser_hash: Unique identifier of user’s browser environment using hundreds of datapoints.
webrtc_ips: WebRTC IPs in clients browser.
webrtc_activated: Is WebRTC enabled or not in client’s browser.
flash: Is Flash turned on user’s browser.
java: Is Java turned on user’s browser.
plugins_hash: Unique identifier of user’s installed plugins.
fonts_hash: Unique identifier of user’s installed fonts.
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
license_key string yes Your license key.
label string yes The label you would like to apply for the transacation.

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.
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 .
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.
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.
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>
    var callbackFunction = function callbackFunction(success){
        if(success)
            console.log("Session data was sucessfully saved!");
        else
            console.log("Something went wrong. Session data was not saved sucessfully!");
    };

    start('[session_id]', callbackFunction);
    </script>
  </body>
</html>

Please follow the steps below to begin collecting 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.
  5. The parameter callbackFunction is optional. It is called after the session was saved with a boolean parameter (true or false), which indicates whether the session data was saved successfully or not.

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 -X POST \
  https://api.seon.io/SeonRestService/email-api/v1.0 \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
    "license_key": "8bbbe856-c498-4a70-b61c-ac0d990794ba",
    "email": "example@seon.io"
}'

HTTP Endpoint

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

Query Parameters

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

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 is 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.