MaxMind minFraud Factors API
Most detailed fraud scoring with component-level risk factor decomposition
OpenAPI Specification
openapi: 3.0.3
info:
title: MaxMind GeoIP Web Services GeoIP City minFraud Factors API
description: 'MaxMind''s GeoIP web services provide IP geolocation data including country, city, ISP, organization, ASN, connection type, and VPN/proxy detection. Services are available at three tiers: Country, City Plus, and Insights. All endpoints use HTTP Basic Auth with your MaxMind account ID and license key.
'
version: '2.1'
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://geoip.maxmind.com
description: MaxMind GeoIP production server
- url: https://geolite.info
description: MaxMind GeoLite production server
security:
- basicAuth: []
tags:
- name: minFraud Factors
description: 'Most detailed fraud scoring with component-level risk factor decomposition
'
paths:
/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:
schemas:
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.
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
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
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'
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
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: user@example.com
domain:
type: string
maxLength: 255
description: The domain of the email address (without the @ symbol)
example: example.com
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
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
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.
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
FactorsResponse:
allOf:
- $ref: '#/components/schemas/InsightsResponse'
- type: object
description: 'Response from the minFraud Factors web service, extending Insights with component-level risk factor decomposition
'
properties:
risk_score_reasons:
type: array
description: 'Array of reasons that contributed to the overall risk score, with multipliers showing each reason''s relative impact
'
items:
$ref: '#/components/schemas/RiskScoreReason'
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'
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
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
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
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
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
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
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
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
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.
ErrorResponse:
type: object
description: Standard error response
properties:
code:
type: string
description: Error code
example: JSON_INVALID
error:
type: string
description: Human-readable error description
example: The request body could not be decoded as JSON.
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
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.0
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/schemas/ShippingAddressResponse'
shipping_phone:
$ref: '#/components/schemas/PhoneResponse'
billing_address:
$ref: '#/components/schemas/AddressResponse'
billing_phone:
$ref: '#/components/schemas/PhoneResponse'
disposition:
$ref: '#/components/schemas/DispositionResponse'
warnings:
type: array
items:
$ref: '#/components/schemas/Warning'
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
responses:
Forbidden:
description: 'The request is forbidden. Your account may not be enabled for this service or the IP is blocked.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
TooManyRequests:
description: 'Request rate limit exceeded. Reduce your request rate.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
NotFound:
description: 'The requested resource was not found.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
PaymentRequired:
description: 'Insufficient funds in your MaxMind account. Purchase additional transaction credits.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: 'Authentication failed. Verify your MaxMind account ID and license key.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
BadRequest:
description: 'There was an error with the request body. Check the code and error fields for details about the specific problem.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
InternalServerError:
description: 'An unexpected error occurred on MaxMind''s servers.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
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.
'
externalDocs:
description: MaxMind GeoIP Web Services Documentation
url: https://dev.maxmind.com/geoip/docs/web-services/