MaxMind minFraud Insights API
Extended fraud scoring with over 80 data points on IPs, emails, devices, and payment cards
OpenAPI Specification
openapi: 3.0.3
info:
title: MaxMind GeoIP Web Services GeoIP City minFraud Insights 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 Insights
description: 'Extended fraud scoring with over 80 data points on IPs, emails, devices, and payment cards
'
paths:
/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'
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
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
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/