MaxMind's most detailed fraud-scoring tier, adding component-level risk factor decomposition on top of all minFraud Insights features. Returns the individual risk reasons that make up the composite transaction score, enabling model interpretability and rule refinement. Priced at $0.020 per query and best suited for fraud teams that need explainability alongside raw scores.
openapi: 3.0.3
info:
title: MaxMind minFraud API
description: >
MaxMind's minFraud web services provide real-time transaction risk scoring
using over 80 data points on IPs, email addresses, devices, and payment cards
to help businesses detect and prevent fraud. Three service tiers are available:
Score (risk score only), Insights (score plus detailed signals), and Factors
(score plus component-level risk factor decomposition).
All endpoints use HTTP Basic Auth with your MaxMind account ID and license key.
version: '2.0'
contact:
name: MaxMind Support
url: https://support.maxmind.com/
termsOfService: https://www.maxmind.com/en/terms_of_service
license:
name: MaxMind End User License Agreement
url: https://www.maxmind.com/en/end_user_license_agreement
servers:
- url: https://minfraud.maxmind.com
description: MaxMind minFraud production server
security:
- basicAuth: []
paths:
/minfraud/v2.0/score:
post:
operationId: getMinFraudScore
summary: minFraud Score
description: >
Returns a single overall transaction risk score (0-99) and an IP risk
score for each transaction submitted. Accepts custom inputs and supports
custom rules for risk tuning. Priced at $0.005 per query.
tags:
- minFraud Score
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionRequest'
responses:
'200':
description: Successful score response
content:
application/json:
schema:
$ref: '#/components/schemas/ScoreResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
/minfraud/v2.0/insights:
post:
operationId: getMinFraudInsights
summary: minFraud Insights
description: >
Extends minFraud Score with over 80 data points on IPs, email addresses,
devices, and payment cards, plus IP risk reasons that explain contributing
risk factors. Priced at $0.015 per query.
tags:
- minFraud Insights
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionRequest'
responses:
'200':
description: Successful insights response
content:
application/json:
schema:
$ref: '#/components/schemas/InsightsResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
/minfraud/v2.0/factors:
post:
operationId: getMinFraudFactors
summary: minFraud Factors
description: >
MaxMind's most detailed fraud-scoring tier, adding component-level risk
factor decomposition on top of all minFraud Insights features. Returns
the individual risk reasons that make up the composite transaction score,
enabling model interpretability and rule refinement. Priced at $0.020 per
query.
tags:
- minFraud Factors
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionRequest'
responses:
'200':
description: Successful factors response
content:
application/json:
schema:
$ref: '#/components/schemas/FactorsResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >
Use your MaxMind account ID as the username and your license key as the
password. All requests must be made over HTTPS using TLS 1.2 or higher.
schemas:
DeviceRequest:
type: object
description: Device information about the transaction
properties:
ip_address:
type: string
description: IPv4 or IPv6 address of the device initiating the transaction
example: '128.101.101.101'
user_agent:
type: string
maxLength: 512
description: Browser HTTP User-Agent header value
example: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'
accept_language:
type: string
maxLength: 255
description: Browser HTTP Accept-Language header value
example: 'en-US,en;q=0.9'
session_age:
type: number
format: double
description: Number of seconds elapsed since the current session began
example: 3600.5
session_id:
type: string
maxLength: 255
description: Unique identifier for the visitor's session
example: 'abc123def456'
tracking_token:
type: string
description: Device tracking add-on token for fingerprinting
EventRequest:
type: object
description: Data about the event being scored
properties:
transaction_id:
type: string
maxLength: 255
description: Your internal transaction or order identifier
example: 'txn_abc123'
shop_id:
type: string
maxLength: 255
description: Your internal identifier for the shop, affiliate, or merchant
example: 'shop_001'
time:
type: string
format: date-time
description: >
RFC 3339 date-time of the event. Must be within the past year.
If not provided, the current time is used.
example: '2024-03-15T10:30:00Z'
type:
type: string
description: >
Type of event. Possible values: account_creation, account_login,
email_change, password_reset, payout_change, purchase,
recurring_purchase, referral, survey
enum:
- account_creation
- account_login
- email_change
- password_reset
- payout_change
- purchase
- recurring_purchase
- referral
- survey
example: purchase
party:
type: string
description: The party submitting the transaction. Either customer or agent.
enum:
- customer
- agent
example: customer
AccountRequest:
type: object
description: Account data associated with the transaction
properties:
user_id:
type: string
maxLength: 255
description: Unique permanent identifier for the user in your system
example: 'user_12345'
username_md5:
type: string
maxLength: 32
description: MD5 hash of the username or login name
example: '4f9726678491da7f0aa33f453ae38ba8'
EmailRequest:
type: object
description: Email address data for the transaction
properties:
address:
type: string
maxLength: 255
description: >
The email address used in the transaction. May be a plain email
address or an MD5 hash of the lowercased email address.
example: '[email protected]'
domain:
type: string
maxLength: 255
description: The domain of the email address (without the @ symbol)
example: 'example.com'
AddressRequest:
type: object
description: Address information (used for both billing and shipping)
properties:
first_name:
type: string
maxLength: 255
description: First name
example: John
last_name:
type: string
maxLength: 255
description: Last name
example: Doe
company:
type: string
maxLength: 255
description: Company name
example: Acme Corp
address:
type: string
maxLength: 255
description: First line of the street address
example: '1234 Main St'
address_2:
type: string
maxLength: 255
description: Second line of the street address
example: 'Suite 100'
city:
type: string
maxLength: 255
description: City name
example: Minneapolis
region:
type: string
maxLength: 4
description: ISO 3166-2 subdivision code
example: MN
country:
type: string
maxLength: 2
description: ISO 3166-1 alpha-2 country code
example: US
postal:
type: string
maxLength: 255
description: Postal code
example: '55420'
phone_number:
type: string
maxLength: 255
description: Phone number without country code
example: '612-555-0100'
phone_country_code:
type: string
maxLength: 4
description: Country code for the phone number
example: '1'
ShippingRequest:
allOf:
- $ref: '#/components/schemas/AddressRequest'
- type: object
properties:
delivery_speed:
type: string
description: Shipping delivery speed
enum:
- same_day
- overnight
- expedited
- standard
example: standard
PaymentRequest:
type: object
description: Payment method information
properties:
method:
type: string
description: >
Payment method. Possible values: card, bank_debit, crypto,
digital_wallet, google_pay, interac, invoice, paypal, poli, sepa,
sofort, square_cash, ukash, venus_point, webmoney
example: card
processor:
type: string
description: >
Payment processor. Possible values: adyen, affirm, afterpay,
amazon, authorizenet, balanced, beanstream, bluepay, bluesnap,
bpoint, braintree, cardknox, cardpay, cashnet, ccnow, chase_paymentech,
checkout_com, cielo, collector, conekta, ct_payments, cybersource,
dibs, digital_river, elavon, epay, eprocessing_network, eway,
exact, fiserv, global_payments, heartland, hipay, ipp, keyclient,
keypaynz, komoju, litle, mastercard_payment_gateway, mercadopago,
merchant_esolutions, mirjeh, mollie, moneris_solutions, nmi,
orbital, other, paidy, pay4later, payco, paydirekt, payeezy,
payfast, paygate, payme, payone, payoneer, paypalec, paysafe,
paytrace, payway, payza, pinpayments, posconnect, princeton_payment_solutions,
psigate, qiwi, quickpay, raberil, rede, redpagos, rewardspay,
sagepay, securetrading, simplify_commerce, skrill, smartpay,
solidtrust_pay, sps_decidir, stripe, telerecargas, towah, usa_epay,
verepay, vme, vpos, worldpay, * (custom processor)
example: stripe
was_authorized:
type: boolean
description: Whether the payment was authorized
example: true
decline_code:
type: string
maxLength: 255
description: Decline code returned by the payment processor
example: 'insufficient_funds'
CreditCardRequest:
type: object
description: Credit card information for the transaction
properties:
issuer_id_number:
type: string
maxLength: 8
description: >
The first 6 or 8 digits of the credit card number (IIN/BIN).
Must be 6 or 8 digits.
example: '411111'
last_digits:
type: string
maxLength: 4
description: Last 2 or 4 digits of the credit card number
example: '1111'
token:
type: string
maxLength: 255
description: >
A unique card identifier that does not directly identify the card
number, such as a token from your payment processor
example: 'tok_abc123def456'
bank_name:
type: string
maxLength: 255
description: Name of the bank issuing the credit card
example: 'US Bank'
bank_phone_country_code:
type: string
maxLength: 4
description: Country code for the bank's phone number
example: '1'
bank_phone_number:
type: string
maxLength: 255
description: Phone number for the issuing bank
example: '800-555-1234'
country:
type: string
maxLength: 2
description: ISO 3166-1 alpha-2 country code where the issuer is located
example: US
avs_result:
type: string
maxLength: 1
description: AVS check result code from the payment processor
example: Y
cvv_result:
type: string
maxLength: 1
description: CVV check result code from the payment processor
example: M
was_3d_secure_successful:
type: boolean
description: Whether 3-D Secure verification was successful
example: true
OrderRequest:
type: object
description: Order-level information for the transaction
properties:
amount:
type: number
format: double
description: Total order value before taxes and discounts, in the currency specified
example: 123.45
currency:
type: string
maxLength: 3
description: ISO 4217 currency code for the order
example: USD
discount_code:
type: string
maxLength: 255
description: Comma-separated list of discount codes applied to the order
example: 'SUMMER20,LOYALTY5'
affiliate_id:
type: string
maxLength: 255
description: Affiliate identifier for the order
example: 'aff_001'
subaffiliate_id:
type: string
maxLength: 255
description: Sub-affiliate identifier for the order
example: 'subaff_002'
referrer_uri:
type: string
maxLength: 1024
description: Absolute URI of the referring website
example: 'https://example.com/products'
is_gift:
type: boolean
description: Whether the order is marked as a gift
example: false
has_gift_message:
type: boolean
description: Whether the order has a gift message
example: false
ShoppingCartItem:
type: object
description: A single item in the shopping cart
properties:
category:
type: string
maxLength: 255
description: Category of the item
example: Electronics
item_id:
type: string
maxLength: 255
description: Your internal item identifier
example: 'sku_12345'
quantity:
type: integer
description: Quantity of the item ordered
minimum: 1
example: 2
price:
type: number
format: double
description: Per-unit price of the item in the order currency
example: 49.99
TransactionRequest:
type: object
description: >
The transaction data to be scored. At minimum, the device.ip_address
is required. Total request body size is limited to 20,000 bytes.
properties:
device:
$ref: '#/components/schemas/DeviceRequest'
event:
$ref: '#/components/schemas/EventRequest'
account:
$ref: '#/components/schemas/AccountRequest'
email:
$ref: '#/components/schemas/EmailRequest'
billing:
$ref: '#/components/schemas/AddressRequest'
shipping:
$ref: '#/components/schemas/ShippingRequest'
payment:
$ref: '#/components/schemas/PaymentRequest'
credit_card:
$ref: '#/components/schemas/CreditCardRequest'
order:
$ref: '#/components/schemas/OrderRequest'
shopping_cart:
type: array
description: List of items in the shopping cart
items:
$ref: '#/components/schemas/ShoppingCartItem'
custom_inputs:
type: object
description: >
Custom input fields configured for your account. Values may be
booleans, strings, numbers, or phone numbers.
additionalProperties:
oneOf:
- type: boolean
- type: string
- type: number
IpAddressRiskReason:
type: object
description: A reason contributing to the IP risk score
properties:
code:
type: string
description: Machine-readable reason code
example: ANONYMOUS_IP
reason:
type: string
description: Human-readable reason description
example: The IP address is associated with an anonymous network.
IpAddressResponse:
type: object
description: IP address risk and geolocation data
properties:
risk:
type: number
format: double
description: >
Risk score from 0.01 to 99 indicating the likelihood of fraud
associated with this IP address
minimum: 0.01
maximum: 99
example: 0.5
city:
type: object
properties:
names:
type: object
additionalProperties:
type: string
continent:
type: object
properties:
code:
type: string
names:
type: object
additionalProperties:
type: string
country:
type: object
properties:
is_high_risk:
type: boolean
iso_code:
type: string
names:
type: object
additionalProperties:
type: string
location:
type: object
properties:
local_time:
type: string
time_zone:
type: string
postal:
type: object
properties:
code:
type: string
registered_country:
type: object
properties:
iso_code:
type: string
names:
type: object
additionalProperties:
type: string
represented_country:
type: object
properties:
iso_code:
type: string
names:
type: object
additionalProperties:
type: string
risk_reasons:
type: array
items:
$ref: '#/components/schemas/IpAddressRiskReason'
subdivisions:
type: array
items:
type: object
properties:
iso_code:
type: string
names:
type: object
additionalProperties:
type: string
traits:
type: object
properties:
ip_address:
type: string
network:
type: string
autonomous_system_number:
type: integer
autonomous_system_organization:
type: string
connection_type:
type: string
domain:
type: string
is_anonymous:
type: boolean
is_anonymous_vpn:
type: boolean
is_hosting_provider:
type: boolean
is_public_proxy:
type: boolean
is_residential_proxy:
type: boolean
is_tor_exit_node:
type: boolean
isp:
type: string
organization:
type: string
user_type:
type: string
CreditCardResponse:
type: object
description: Credit card risk and metadata
properties:
brand:
type: string
description: Card brand (e.g., Visa, Mastercard)
example: Visa
country:
type: string
description: ISO 3166-1 alpha-2 country code of the issuing bank
example: US
is_business:
type: boolean
description: Whether the card is a business card
example: false
is_issued_in_billing_address_country:
type: boolean
description: Whether the card was issued in the same country as the billing address
example: true
is_prepaid:
type: boolean
description: Whether the card is prepaid
example: false
is_virtual:
type: boolean
description: Whether the card is a virtual card number
example: false
issuer:
type: object
properties:
name:
type: string
description: Name of the issuing bank
example: US Bank
phone_number:
type: string
description: Phone number for the issuing bank
example: '800-555-1234'
matches_provided_name:
type: boolean
description: Whether the bank name matches the provided name
example: true
matches_provided_phone_number:
type: boolean
description: Whether the bank phone matches the provided number
example: true
type:
type: string
description: Card type (e.g., credit, debit)
example: credit
DeviceResponse:
type: object
description: Device fingerprint information
properties:
confidence:
type: number
format: double
description: >
Confidence percent (0-100) that the device_id refers to a unique
device
minimum: 0
maximum: 100
example: 99
id:
type: string
format: uuid
description: Unique device identifier
example: '7835b099-d385-4e5b-969e-7df26181d73c'
last_seen:
type: string
format: date-time
description: Date and time this device was last seen
example: '2024-01-15T10:00:00Z'
local_time:
type: string
description: Local time in the device's time zone (ISO 8601)
example: '2024-01-15T10:00:00-06:00'
EmailResponse:
type: object
description: Email address risk data
properties:
domain:
type: object
properties:
classification:
type: string
description: Classification of the email domain
example: free
first_seen:
type: string
description: Date the domain was first seen (ISO 8601)
example: '2010-01-01'
risk:
type: number
format: double
description: Domain risk score from 0.01 to 99
example: 0.5
visit:
type: object
properties:
has_redirect:
type: boolean
description: Whether the domain redirects to another URL
last_visited_on:
type: string
description: Date the domain was last checked
status:
type: string
description: HTTP status of the domain
volume:
type: number
format: double
description: Relative email volume for the domain
first_seen:
type: string
description: Date the email address was first seen by MaxMind (ISO 8601)
example: '2018-06-15'
is_disposable:
type: boolean
description: Whether the email address is from a disposable email provider
example: false
is_free:
type: boolean
description: Whether the email address is from a free email provider
example: false
is_high_risk:
type: boolean
description: Whether the email address is considered high risk
example: false
AddressResponse:
type: object
description: Address verification data
properties:
distance_to_ip_location:
type: integer
description: Distance in kilometers from the address to the IP location
example: 15
is_in_ip_country:
type: boolean
description: Whether the address is in the same country as the IP
example: true
is_postal_in_city:
type: boolean
description: Whether the postal code is within the provided city
example: true
latitude:
type: number
format: double
description: Approximate latitude of the address
example: 44.9532
longitude:
type: number
format: double
description: Approximate longitude of the address
example: -93.0875
ShippingAddressResponse:
allOf:
- $ref: '#/components/schemas/AddressResponse'
- type: object
properties:
distance_to_billing_address:
type: integer
description: >
Distance in kilometers between the shipping and billing addresses
example: 0
is_high_risk:
type: boolean
description: Whether the shipping address is considered high risk
example: false
PhoneResponse:
type: object
description: Phone number risk data
properties:
country:
type: string
description: ISO 3166-1 alpha-2 country code for the phone number
example: US
is_voip:
type: boolean
description: Whether the phone number is a VOIP number
example: false
matches_postal:
type: boolean
description: Whether the phone number area code matches the postal code
example: true
network_operator:
type: string
description: Name of the carrier/operator
example: 'US Cellular'
number_type:
type: string
description: Type of phone number (e.g., landline, mobile, voip)
example: landline
DispositionResponse:
type: object
description: The disposition determined by custom rules
properties:
action:
type: string
description: >
The action to take (e.g., accept, reject, manual_review, test)
example: accept
reason:
type: string
description: The reason for the action
example: default
rule_label:
type: string
description: Label for the custom rule that triggered the action
example: 'low_risk_rule'
RiskScoreReason:
type: object
description: A reason contributing to the overall risk score
properties:
multiplier:
type: number
format: double
description: Factor by which this reason multiplies the overall risk score
example: 45.0
reasons:
type: array
items:
type: object
properties:
code:
type: string
description: Machine-readable code for the reason
example: ANONYMOUS_IP
reason:
type: string
description: Human-readable reason description
example: The IP address is associated with an anonymous network.
Warning:
type: object
description: A non-fatal warning about the transaction data
properties:
code:
type: string
description: Machine-readable warning code
example: EMAIL_ADDRESS_INVALID
input_pointer:
type: string
description: JSON Pointer to the field that triggered the warning
example: /email/address
warning:
type: string
description: Human-readable warning description
example: The email address supplied is not valid.
ScoreResponse:
type: object
description: Response from the minFraud Score web service
properties:
id:
type: string
format: uuid
description: Unique identifier for this transaction
example: '7835b099-d385-4e5b-969e-7df26181d73c'
risk_score:
type: number
format: double
description: >
Overall risk score from 0.01 to 99, where 99 is the highest risk
minimum: 0.01
maximum: 99
example: 0.01
funds_remaining:
type: number
format: double
description: Number of transaction credits remaining in your account
example: 125.00
queries_remaining:
type: integer
description: Number of transaction queries remaining in your account
example: 5000
ip_address:
type: object
properties:
risk:
type: number
format: double
description: Risk score for the IP address from 0.01 to 99
minimum: 0.01
maximum: 99
example: 0.5
disposition:
$ref: '#/components/schemas/DispositionResponse'
warnings:
type: array
items:
$ref: '#/components/schemas/Warning'
InsightsResponse:
type: object
description: Response from the minFraud Insights web service
properties:
id:
type: string
format: uuid
description: Unique identifier for this transaction
example: '7835b099-d385-4e5b-969e-7df26181d73c'
risk_score:
type: number
format: double
description: >
Overall risk score from 0.01 to 99, where 99 is the highest risk
minimum: 0.01
maximum: 99
example: 0.01
funds_remaining:
type: number
format: double
description: Number of transaction credits remaining in your account
example: 125.00
queries_remaining:
type: integer
description: Number of transaction queries remaining in your account
example: 5000
ip_address:
$ref: '#/components/schemas/IpAddressResponse'
credit_card:
$ref: '#/components/schemas/CreditCardResponse'
device:
$ref: '#/components/schemas/DeviceResponse'
email:
$ref: '#/components/schemas/EmailResponse'
shipping_address:
$ref: '#/components/schem
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/maxmind/refs/heads/main/openapi/maxmind-minfraud-openapi.yml