openapi: 3.0.1
info:
title: SEON REST API
description: >-
SEON's fraud prevention and anti-money-laundering REST API. Combines
digital-footprint analysis, device fingerprinting, and machine-learning
risk scoring to return real-time fraud scores and enriched intelligence
from an email address, phone number, IP address, or full transaction
payload, plus AML screening and transaction labeling. All requests
authenticate with an X-API-KEY header and are case-sensitive.
termsOfService: https://seon.io/legal/terms-and-conditions/
contact:
name: SEON Support
email: support@seon.io
url: https://docs.seon.io
version: '2.0'
servers:
- url: https://api.seon.io
description: Primary (EU) transaction processing environment
security:
- ApiKeyAuth: []
tags:
- name: Fraud
description: Combined transaction fraud scoring.
- name: Email
description: Email address digital footprint and risk scoring.
- name: Phone
description: Phone number digital footprint and risk scoring.
- name: IP
description: IP address proxy/VPN/Tor detection and risk scoring.
- name: AML
description: Sanctions, watchlist, PEP, and adverse-media screening.
- name: Labels
description: Transaction outcome labeling for machine-learning feedback.
paths:
/SeonRestService/fraud-api/v2.0:
post:
operationId: scoreFraud
tags:
- Fraud
summary: Score a transaction for fraud
description: >-
Submits a combined transaction payload (user, transaction, payment,
device, email, phone, and IP signals) and returns a fraud_score, a
state decision, and the applied_rules that fired, enriched with module
details for email, phone, IP, BIN, device, and AML.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FraudRequest'
responses:
'200':
description: Fraud scoring result.
content:
application/json:
schema:
$ref: '#/components/schemas/FraudResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/SeonRestService/email-api/v3:
post:
operationId: analyzeEmail
tags:
- Email
summary: Analyze an email address
description: >-
Returns the digital footprint behind an email address, including
deliverability, domain details, breach history, registration across
250+ online platforms, and a machine-learning risk score.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmailRequest'
responses:
'200':
description: Email analysis result.
content:
application/json:
schema:
$ref: '#/components/schemas/EmailResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/SeonRestService/phone-api/v2:
post:
operationId: analyzePhone
tags:
- Phone
summary: Analyze a phone number
description: >-
Returns the digital footprint behind a phone number, including carrier
and HLR details, CNAM, telco attributes such as SIM-swap and porting
history, account aggregates, and a global network risk score.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneRequest'
responses:
'200':
description: Phone analysis result.
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/SeonRestService/ip-api/v1/{ip}:
get:
operationId: analyzeIp
tags:
- IP
summary: Analyze an IP address
description: >-
Detects fake, harmful, and suspicious IP addresses - including Tor,
VPN, web, public, data-center, and residential proxies - with
geolocation, ISP, open ports, and a risk score for a given IPv4 or
IPv6 address.
parameters:
- name: ip
in: path
required: true
description: Full IPv4 or IPv6 address to analyze.
schema:
type: string
- name: include
in: query
required: false
description: Comma-separated extra data sets to include (history, flags, id).
schema:
type: string
- name: flags_timeframe_days
in: query
required: false
description: Number of days of flag history to include.
schema:
type: integer
responses:
'200':
description: IP analysis result.
content:
application/json:
schema:
$ref: '#/components/schemas/IpResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/SeonRestService/aml-api/v1:
post:
operationId: screenAml
tags:
- AML
summary: Screen a person for AML risk
description: >-
Screens a person against sanctions, watchlists, crime lists,
politically exposed persons (PEP), and adverse-media sources, returning
per-category match flags and a result payload.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AmlRequest'
responses:
'200':
description: AML screening result.
content:
application/json:
schema:
$ref: '#/components/schemas/AmlResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/SeonRestService/fraud-api/transaction-label/v2:
put:
operationId: labelTransactions
tags:
- Labels
summary: Label scored transactions
description: >-
Applies fraud-outcome labels (such as fraud_detection_fraud) to up to
50 previously scored transactions per request, feeding SEON's
machine-learning models. A transaction can hold a single label at a
time; existing labels can be overwritten.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LabelRequest'
responses:
'200':
description: Labeling result.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
description: SEON license key sent as the X-API-KEY request header.
responses:
Unauthorized:
description: Authentication failed - missing or invalid X-API-KEY.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
schemas:
FraudRequest:
type: object
properties:
config:
type: object
description: Per-module configuration controlling which enrichments run.
ip:
type: string
description: IP address associated with the transaction.
email:
type: string
description: Email address associated with the user.
phone_number:
type: string
description: Phone number in international format.
user_fullname:
type: string
user_id:
type: string
transaction_id:
type: string
maxLength: 255
transaction_amount:
type: number
transaction_currency:
type: string
maxLength: 4
card_hash:
type: string
maxLength: 500
card_bin:
type: string
maxLength: 15
session:
type: string
description: Device fingerprinting session payload.
custom_fields:
type: object
description: Arbitrary key/value pairs used in custom rules.
FraudResponse:
type: object
properties:
success:
type: boolean
error:
$ref: '#/components/schemas/Error'
data:
type: object
properties:
id:
type: string
state:
type: string
description: Decision such as APPROVE, REVIEW, or DECLINE.
fraud_score:
type: number
applied_rules:
type: array
items:
$ref: '#/components/schemas/AppliedRule'
calculation_time:
type: integer
description: Processing time in milliseconds.
email_details:
type: object
phone_details:
type: object
ip_details:
type: object
bin_details:
type: object
device_details:
type: object
aml_details:
type: object
AppliedRule:
type: object
properties:
id:
type: string
name:
type: string
operation:
type: string
score:
type: number
EmailRequest:
type: object
required:
- email
properties:
email:
type: string
config:
type: object
EmailResponse:
type: object
properties:
success:
type: boolean
error:
$ref: '#/components/schemas/Error'
data:
type: object
properties:
id:
type: string
email:
type: string
score:
type: number
deliverable:
type: boolean
domain_details:
type: object
account_details:
type: object
description: Registration on 250+ online platforms.
breach_details:
type: object
applied_rules:
type: array
items:
$ref: '#/components/schemas/AppliedRule'
PhoneRequest:
type: object
required:
- phone
properties:
phone:
type: string
config:
type: object
PhoneResponse:
type: object
properties:
success:
type: boolean
error:
$ref: '#/components/schemas/Error'
data:
type: object
properties:
id:
type: string
phone:
type: string
score:
type: number
account_details:
type: object
carrier_details:
type: object
hlr_details:
type: object
cnam_details:
type: object
applied_rules:
type: array
items:
$ref: '#/components/schemas/AppliedRule'
IpResponse:
type: object
properties:
success:
type: boolean
error:
$ref: '#/components/schemas/Error'
data:
type: object
properties:
id:
type: string
ip:
type: string
score:
type: number
country:
type: string
city:
type: string
isp_name:
type: string
type:
type: string
open_ports:
type: array
items:
type: integer
tor:
type: boolean
harmful:
type: boolean
vpn:
type: boolean
web_proxy:
type: boolean
public_proxy:
type: boolean
data_center_proxy:
type: boolean
residential_proxy:
type: boolean
applied_rules:
type: array
items:
$ref: '#/components/schemas/AppliedRule'
AmlRequest:
type: object
required:
- user_fullname
properties:
user_fullname:
type: string
user_id:
type: string
user_firstname:
type: string
user_middlename:
type: string
user_lastname:
type: string
user_dob:
type: string
format: date
user_pob:
type: string
user_photoid_number:
type: string
user_country:
type: string
config:
type: object
AmlResponse:
type: object
properties:
success:
type: boolean
error:
$ref: '#/components/schemas/Error'
data:
type: object
properties:
has_sanction_match:
type: boolean
has_watchlist_match:
type: boolean
has_crimelist_match:
type: boolean
has_pep_match:
type: boolean
has_adversemedia_match:
type: boolean
local_aml_match:
type: object
result_payload:
type: object
LabelRequest:
type: object
required:
- transactions
properties:
transactions:
type: array
maxItems: 50
items:
type: object
required:
- transaction_id
- label
properties:
transaction_id:
type: string
label:
type: string
description: >-
A predefined label value such as fraud_detection_fraud or
bnpl_credit_risk_default.
GenericResponse:
type: object
properties:
success:
type: boolean
error:
$ref: '#/components/schemas/Error'
data:
type: object
Error:
type: object
properties:
code:
type: string
message:
type: string