Advanced Digital Footprint Migration Guide
This document details the integration process for SEON’s new Advanced Digital Footprint, available for limited customers to trial through an exclusive beta program. SEON’s new email and phone solution includes the following key updates.
Overview
Machine-Learning-Powered Risk Scores
Two proprietary network scores are available for email and phone, which can be used as a new confidence indicator when assessing a user's digital profile. These risk scores leverage machine learning alongside consortium data from over 5,000 customers. Risk scores are derived from an anonymized model trained on millions of onboarding events with over six years of historical data, ensuring precise and accurate risk assessments.
Additional Data Signals
The number of data signals is increasing from 90 to over 200+, including an additional 80 email and 13 phone signals. This provides a comprehensive overview of the user’s digital profile, increasing analysis capabilities and improving risk precision accuracy.
Aggregated Categories
Email and phone signals are organized into 13 categories in the digital footprint section of Email information and Phone information modules. Aggregated categories group together signals such as email service, entertainment, social media and technology (see the example below to see how this information is displayed). Using these categories to assess risk instead of specific signals eliminates the need to fine-tune individual signals and continuously update rules to add new signals.
Global Consortium-Based Threat Intelligence
The consortium-based threat intelligence pools data from diverse sectors and geographies for comprehensive threat detection. Consortium data from SEON’s proprietary network is available in two ways:
- It is incorporated into the email and phone network risk scores;
- There is a new section within the Email information and Phone information modules called the Fraudulent Network Transaction History section.
Below is how fraudulent network transaction history is displayed in the UI:
In this example above, the user was reported in a fraudulent transaction four out of six times in the SEON network. While the user was found in the SEON network six times, the user impacted two companies. It was first seen on the network on July 9, 2024, and last seen on the network on July 15. However, the first transaction deemed fraudulent was on July 11th, with the most recent transaction marked fraudulent occurring on July 15.
Elevated Performance Ceilings and Consistency
With the new Advanced Digital Footprint, customers can experience higher performance thresholds and consistent delivery, ensuring robust and reliable data intelligence for decision-making. This update is designed to handle high volumes of data providing scalable solutions for businesses of all sizes while improving fraud detection.
Guidance on what signals to incorporate within your risk decisioning framework:
- Use the two new proprietary machine learning-based Email network score and Phone network score.
- Integrate aggregated social categories of the advanced digital footprint, such as Messenger, Email Service and Entertainment.
Using proprietary scores and aggregated signals eliminates the need to manage and tune individual signals, which will free up resources. Additionally, future signals will be automatically added to this new version, requiring no additional development work.
Advanced Digital Footprint is available in the latest module API versions - Email v3 and Phone v2.
Integration Overview
New API Policy
The API Policy has been changed. More details about the new policy can be found here.
Breaking changes
Request Payload
Please note that the request methods for both Email and Phone API have been changed from GET to POST and the available request parameters have been changed. Please refer to the Request sections under Interface Changes of the individual services to see what has been changed.
Response Payload
Please note that with the two major versions, we also introduced interface-breaking changes in the API responses:
- The most notable change is removing the rule evaluation and email and phone scores from the standalone Email and Phone APIs. That means that no applied rules and email and phone rule-based scores will be returned when calling Email API or Phone API as standalone services without calling Fraud API. By calling Fraud API, applied rules will still be returned that contribute to the overall Fraud Score, but no individual scores will be returned under email details and phone details. These scores are replaced by SEON’s new proprietary network risk scores.
- Individual account registration details are no longer returned by default in the API and have been replaced by aggregated account categories for better stability and more convenient rule management. If you still wish to get account registration details in the API response, please contact support@seon.io.
- In the new API versions, the seon_fraud_history feature, previously named history, changes how hits are counted:
- In the previous version, the hits count included the current query, meaning it started from 1 if the target email address or phone number was new in the system.
- In the latest version, the hits count now excludes the current query. For a target that hasn’t been queried before, the hits field will return 0 instead of 1.
- Impact: This change affects the initial hits count returned for new targets. If you rely on the hits field for decision-making, please adjust your integration accordingly to account for this update.
Integration Tips
- Advanced Digital Footprint is available in the following API versions:
- Email API v3 and above
- Phone API v2 and above
- Use the Fraud API if you want to use the modules together, including the Email, Phone, and IP APIs and Device Fingerprinting.
- All SEON API requests are case-sensitive. Please follow the formatting below to avoid errors.
- Consider using a higher, 4-5 seconds timeout setting for better data coverage.
- You can improve network scoring accuracy by labeling data via the Label API or adjusting transaction states on the Admin Panel. Labels help the model learn from past fraudulent activities and update itself regularly to provide better accuracy.
New API Services
Email API Interface Changes
For privacy and security reasons, we changed the request method from GET to POST. With this solution, no email or phone number will be included in the request URL.
POST https://api.seon.io/SeonRestService/email-api/v3/Request
The request structure has changed due to the request method change.
At the top level there is an email parameter and a config object. The request parameters are moved under the config object.
- include:
flags,idandhistoryare included by default, therefore these are not accepted as include parameters anymore, so include parameter should be removed. - Request parameter
data_enrichment_modeis removed from Email API v3. - All other request parameters are unchanged from the previous version.
Example:
{
"email":"example@example.com",
"config":{
"timeout":5000,
"priority_timeout":8000,
"priority_sites": "facebook, google_plus"
"flags_timeframe_days":365"
}
}
Response
Removed and changed parameters
score-> removed and replaced byglobal_network_scoreapplied_rules-> applied rules list is not returned when calling the standalone Email APIdeliverable-> moved underemail_detailsdomain_details-> renamed toemail_domain_detailshistory-> renamed toseon_fraud_historywith extended field setflags-> moved underseon_fraud_historyaccount_details– removed and replaced byaccount_aggregates
New parameters
risk_scores– object: Contains a risk score ranging from 0–100 indicating the likelihood that the user’s email address is fraudulent.global_network_score– integer: A risk score that predicts the likelihood of fraud associated with the email address. It's generated by our machine learning model using data points from various sources and our own proprietary consortium data.
account_aggregates– object: We check if an account is registered with the email address on more than 170 sites and return the number of registrations found categorized by type. The service may return null results for categories where no online registration was found.- Aggregated results are returned for two top–level categories:
businessandpersonal. - Under the
businesscategory we return aggregated results for the following subcategories as separate objects:technology,science_and_education,jobs_and_employment,money_transfer_remittance. - Under
personalcategory we return aggregated results for the following subcategories as separate objects:email_service,technology,adult_sites,delivery,ecommerce,entertainment,health_and_fitness,social_media,travel. - The total number of registrations found is returned for the top–level categories as well as overall. For the subcategories, we return the total number of registrations found under the subcategory as well as the total number of sites checked:
total_registration– integer: The total number of online registrations found.registered– integer: The total number of sites where a registration with the target email address was found.checked– integer: The total number of sites where the email address was checked.
- Aggregated results are returned for two top–level categories:
email_details– object: Returns key information about the email address such as deliverability, format validity and whether the user inbox is full.deliverable– boolean: Indicates whether the email address actually exists or not, using a fast SMTP–MX check.full_inbox– boolean: Indicates if an account can't accept emails because the inbox is full.valid_format– boolean: Indicates whether the email address format is valid or not.
seon_fraud_history– object: Fraudulent network transaction history (consortium data) built on SEON’s global intelligence for millions of onboarding events.fraudulent_decline_first_seen– integer: The first date and time when the email address was reported as fraudulent by any SEON customer in UNIX time format and UTC timezone.fraudulent_decline_last_seen– integer: The most recent date and time when the email address was reported as fraudulent by any SEON customer in UNIX time format and UTC timezone.fraudulent_decline_customer_hits– integer: The number of unique companies that reported the email address as fraudulent.fraudulent_decline_hits– integer: The total number of times the email address was reported as fraudulent by any SEON customer.first_seen– integer: First time the email address was queried by any SEON customer in UNIX time format and UTC time zone, without milliseconds.last_seen– integer: Last time the email address was queried by any SEON customer in UNIX time format and UTC time zone, without milliseconds.customer_hits– integer: Number of unique customers who queried the email address with SEON.hits– integer: Number of times the email address was queried with SEON.flags– object: An array of active flags.note– string: Additional note added to the flag by SEON’s client.date– integer: Timestamp of when the value was flagged in UNIX time format and UTC time zone, without milliseconds.industry– string: Industry of SEON’s client that flagged the value.
Unchanged parameters
email– string: The target email address included in the transaction.id– string: A generated unique request identifier.email_domain_details– object: Details about the domain of the email address.accept_all– boolean: It indicates if the server is set to receive all emails at this domain.created– dateTime: Creation date and time of the email domain (UTC time zone).custom– boolean: It indicates if the email’s domain is a custom (such as company domain, not free or disposable).disposable– boolean: It indicates if the email’s domain is fraudulent (such as disposable email, previous fraudulent domains).dmarc_enforced– boolean: It indicates if the email’s domain is DMARC (Domain–based Message Authentication Reporting and Conformance) enforced.domain– string: The domain of the email address of the customer.expires– dateTime: Date and time of expiration of the email domain (UTC time zone).free– boolean: It indicates if the email’s domain is a free provider (such as gmail, hotmail, etc).registered– boolean: It indicates if the email’s domain is registered or not.registered_to– string: Name of the company that the domain is registered to.registrar_name– string: Name of the company that manages the reservation of the domain name.spf_strict– boolean: It indicates if the SPF is sufficiently strict enough to prevent spoofing.suspicious_tld– boolean: It indicates if the email’s top–level–domain is likely fraudulent, risky or not.tld– string: The top–level domain.updated– dateTime: Date and time of the last updated time of the email domain (UTC time zone).valid_mx– boolean: It indicates if the MX records of the domain are valid or not.website_exists– boolean: It indicates if the email’s domain has a website or not.
breach_details– object: Details about data breaches if the email address has been compromised.breaches– array of object: Array of breaches to the email address.name– string: Name of the platform where the email address was compromised.domain– string: Domain of the platform where the email address was compromised.date– string: The time when the email address was compromised.
haveibeenpwned_listed– boolean: Indicates if an email address has been compromised in a data breach.number_of_breaches– integer: Number of data breaches where the email address has been compromised.first_breach– string: First time when the email address was compromised.
Example:
{
"success": true,
"error": {},
"data": {
"id": "67b0f0e5-42df-40d3-b744-5fb510d83cf2",
"email": "johndoe@seon.io",
"risk_scores": {
"global_network_score": 11.26
},
"email_details": {
"deliverable": true,
"full_inbox": false,
"valid_format": true
},
"email_domain_details": {
"accept_all": false,
"created": "2015-03-20 12:42:37",
"custom": true,
"disposable": false,
"dmarc_enforced": true,
"domain": "seon.io",
"expires": "2025-03-20 12:42:37",
"free": false,
"registered": true,
"registered_to": "Seon Ltd.",
"registrar_name": "NameCheap, Inc.",
"spf_strict": true,
"suspicious_tld": false,
"tld": "io",
"updated": "2024-02-24 08:11:02",
"valid_mx": true,
"website_exists": true
},
"account_aggregates": {
"total_registration": 39,
"business": {
"total_registration": 14,
"technology": {
"registered": 11,
"checked": 34
},
"science_and_education": {
"registered": 2,
"checked": 7
},
"jobs_and_employment": {
"registered": 1,
"checked": 4
},
"money_transfer_remittance": {
"registered": 0,
"checked": 2
}
},
"personal": {
"total_registration": 25,
"email_service": {
"registered": 2,
"checked": 6
},
"technology": {
"registered": 2,
"checked": 7
},
"adult_sites": {
"registered": 0,
"checked": 2
},
"delivery": {
"registered": 0,
"checked": 2
},
"ecommerce": {
"registered": 3,
"checked": 16
},
"entertainment": {
"registered": 7,
"checked": 28
},
"health_and_fitness": {
"registered": 2,
"checked": 4
},
"social_media": {
"registered": 8,
"checked": 21
},
"travel": {
"registered": 1,
"checked": 7
}
}
},
"seon_fraud_history": {
"fraudulent_decline_first_seen": 1625384237,
"fraudulent_decline_last_seen": 1713949826,
"fraudulent_decline_customer_hits": 2,
"fraudulent_decline_hits": 2,
"first_seen": 1584887689,
"last_seen": 1713949826,
"customer_hits": 4,
"hits": 9,
"flags": []
},
"breach_details": {
"breaches": [
{
"date": "2018-07-23",
"domain": "apollo.io",
"name": "Apollo"
},
{
"date": "2019-05-24",
"domain": "canva.com",
"name": "Canva"
},
{
"date": "2020-09-28",
"domain": "gonitro.com",
"name": "Nitro"
},
{
"date": "2021-08-01",
"domain": "opensubtitles.org",
"name": "Open Subtitles"
},
{
"date": "2018-12-13",
"domain": "wanelo.com",
"name": "Wanelo"
}
],
"first_breach": "2018-07-23",
"haveibeenpwned_listed": true,
"number_of_breaches": 5
}
}
}
Phone API Interface Changes
For privacy and security reasons, we changed the request method from GET to POST. With this solution, no email or phone number will be included in the request URL.
POST https://api.seon.io/SeonRestService/phone-api/v2/Request
The request structure has changed due to the request method change.
At the top level there is a phone parameter and a config object. The request parameters are moved under the config object.
- include:
flags,idandhistoryare included by default, therefore these are not accepted as include parameters anymore, onlyhlr_detailsandcnam_lookup. - Request parameter
data_enrichment_modeis removed from Phone API v2. - All other request parameters are unchanged from the previous version.
Example:
{
"phone":"17252800241",
"config":{
"timeout":5000,
"priority_timeout":8000,
"priority_sites": "whatsapp"
"include": "hlr_details,cnam_lookup",
"flags_timeframe_days":365
}
}
Response
Removed and changed parameters
number-> renamed to phonescore-> removed and replaced byglobal_network_scorecarrier-> moved underprovider_carrier_detailsvalid-> renamed tophone_is_validand moved underprovider_carrier_detailsdisposable-> moved underprovider_carrier_detailstype-> moved underprovider_carrier_detailscountry-> moved underprovider_carrier_detailshistory-> renamed toseon_fraud_historywith extended field setflags-> moved underseon_fraud_historyaccount_details– removed and replaced byaccount_aggregates
New parameters
risk_scores– object: Contains a risk score ranging from 0–100 indicating the likelihood that the user’s phone number is fraudulent.global_network_score– integer: A risk score that predicts the likelihood of fraud associated with the phone number. It's generated by our machine learning model using data points from various sources and our own proprietary consortium data.
account_aggregates– object: We check if an account is registered with the phone number on more than 30 sites and return the number of registrations found categorized by type. The service may return null results for categories where no online registration was found.- Aggregated results are returned for two top–level categories:
businessandpersonal. - Under the
businesscategory we return aggregated results for the following subcategories as separate objects:technology,science_and_education,jobs_and_employment,money_transfer_remittance. - Under
personalcategory we return aggregated results for the following subcategories as separate objects:email_service,messenger,technology,delivery,ecommerce,entertainment,social_media,travel. - The total number of registrations found is returned for the top–level categories as well as overall. For the subcategories, we return the total number of registrations found under the subcategory as well as the total number of sites checked:
total_registration– integer: The total number of online registrations found.registered– integer: The total number of sites where a registration with the target phone number was found.checked– integer: The total number of sites where the phone number was checked.
- Aggregated results are returned for two top–level categories:
provider_carrier_details– object: General information about the phone number and its carrier.carrier– string: SPID (Service Provider ID) name, if the requested phone number has been ported; otherwise, the name of the carrier who owns the phone number block.country– string: Origin country of phone number carrier.disposable– boolean: Indicates if the phone number is disposable.phone_is_valid– boolean: Indicates whether the requested target is a valid phone number.type– string: A phone number type that identifies the type of service associated with the requested phone number.
seon_fraud_history– object: Fraudulent network transaction history (consortium data) built on SEON’s global intelligence for millions of onboarding events.fraudulent_decline_first_seen– integer: The first date and time when the phone number was reported as fraudulent by any SEON customer in UNIX time format and UTC timezone.fraudulent_decline_last_seen– integer: The most recent date and time when the phone number was reported as fraudulent by any SEON customer in UNIX time format and UTC timezone.fraudulent_decline_customer_hits– integer: The number of unique companies that reported the phone number as fraudulent.fraudulent_decline_hits– integer: The total number of times the phone number was reported as fraudulent by any SEON customer.first_seen– integer: First time the phone number was queried by any SEON customer in UNIX time format and UTC time zone, without milliseconds.last_seen– integer: Last time the phone number was queried by any SEON customer in UNIX time format and UTC time zone, without milliseconds.customer_hits– integer: Number of unique customers who queried the phone number with SEON.hits– integer: Number of times the phone number was queried with SEON.flags– object: An array of active flags.note– string: Additional note added to the flag by SEON’s client.date– integer: Timestamp of when the value was flagged in UNIX time format and UTC time zone, without milliseconds.industry– string: Industry of SEON’s client that flagged the value.
Unchanged parameters
phone– string: The target phone number included in the transaction.id– string: A generated unique request identifier.
Example:
{
"success": true,
"error": {},
"data": {
"id": "9c02924f-9fa0-432c-9f0b-9a12873870b7",
"phone": 36301234567,
"risk_scores": {
"global_network_score": 67.62
},
"seon_fraud_history": {
"fraudulent_decline_first_seen": 1625384237,
"fraudulent_decline_last_seen": 1713949826,
"fraudulent_decline_customer_hits": 2,
"fraudulent_decline_hits": 2,
"first_seen": 1584887689,
"last_seen": 1713949826,
"customer_hits": 4,
"hits": 9,
"flags": []
},
"provider_carrier_details": {
"carrier": "Verizon Ltd",
"country": "US",
"disposable": false,
"phone_is_valid": true,
"type": "MOBILE"
},
"hlr_details": {
"imsi": "316000000000000",
"original_carrier": {
"carrier": "Verizon Wireless",
"carrier_prefix": "212333"
},
"ported_carrier": {
"carrier": "USA - Landline and Other Carriers",
"carrier_prefix": "252271"
},
"roaming_carrier": {
"carrier": null,
"carrier_prefix": null,
"carrier_country": null
},
"serving_msc": null,
"status": "delivered"
},
"cnam_details": {
"name": "John Doe"
}
}
}
Fraud API Interface Changes
To enable Advanced Digital Footprint, configure the newest Email API (v3) and Phone API (v2) versions under Fraud API config.
POST https://api.seon.io/SeonRestService/fraud-api/v2/Request
The request structure has changed due to changes introduced to the underlying standalone APIs.
config->email- include:
flags,idandhistoryare included by default, therefore these are not accepted as include parameters anymore, so include parameter should be removed. - Request parameter
data_enrichment_modeis removed from Email API v3.
- include:
config->phone- include:
flags,idandhistoryare included by default, therefore these are not accepted as include parameters anymore, onlyhlr_detailsandcnam_lookup. - Request parameter
data_enrichment_modeis removed from Phone API v2.
- include:
- All other request parameters are unchanged from the previous version.
Example:
{
"config": {
"email": {
"timeout": 5000,
"version": "v3"
},
"phone": {
"timeout": 5000,
"version": "v2"
},
"ip_api": false,
"email_api": true,
"phone_api": true,
"device_fingerprinting": false
},
"email": "feer.zavala97@gmail.com",
"phone_number": 525516454841
}
Response
email_details– will include the full response of Email API v3 except for:applied_rules– as these are at another place in the responsescore– this field has been removed, and a newglobal_network_scorefield will be returned underrisk_scores
phone_details- will include the full response of Phone API v2 except for:applied_rules– as these are at another place in the responsescore– this field has been removed, and a newglobal_network_scorefield will be returned underrisk_scores