--- title: "minFraud API Responses" url: https://00c26a0e.dev-site-4ua.pages.dev/minfraud/api-documentation/responses/ --- # minFraud API Responses ## Headers The `Content-Type` for a successful response varies based on the service as outlined below:
Service Content-Type
Score `application/vnd.maxmind.com-minfraud-score+json; charset=UTF-8; version=2.0`
Insights `application/vnd.maxmind.com-minfraud-insights+json; charset=UTF-8; version=2.0`
Factors `application/vnd.maxmind.com-minfraud-factors+json; charset=UTF-8; version=2.0`
Errors may be returned with the `Content-Type` set to `application/vnd.maxmind.com-error+json; charset=UTF-8; version=2.0`. If this is the case, then the body of the response contains a JSON document with two keys, `code` and `error`. See the [Errors](/minfraud/api-documentation/responses/#errors) section for more details. A `Content-Length` header will be provided. ## Errors When the server returns an error (`4xx` or `5xx`), the response may include a JSON document in the body. This document is a single object with the keys `code` and `error`. The `code` field is a static error code for machine use. The value of any given code will never change, though codes can be added or removed. The `error` field is a human-readable description of the error and may change at any time. Not all errors include a JSON body. Some `4xx` errors, such as a `403` for a plain HTTP request, and many `5xx` errors, which typically happen outside of our web service request handling code, do not include one. You should check the `Content-Type` header of an error response before attempting to decode the body as JSON. In addition to the errors documented below, client code should also be prepared to handle any valid HTTP `4xx` or `5xx` status code.
Code HTTP Status Description
JSON_INVALID 400 Bad Request We cannot decode the body as a JSON object.
REQUEST_INVALID 400 Bad Request The request body is valid JSON but contains no valid input values.
BAD_REQUEST 400 Bad Request There was a problem reading or decoding the request.
REQUEST_TOO_BIG 400 Bad Request The request body is too large. Keep the request body at 20,000 bytes or less to avoid both this error and the 413 response.
AUTHORIZATION_INVALID 401 Unauthorized You have supplied an invalid MaxMind account ID and/or license key in the Authorization header.
LICENSE_KEY_REQUIRED 401 Unauthorized You have not supplied a MaxMind license key in the Authorization header.
ACCOUNT_ID_REQUIRED 401 Unauthorized You have not supplied a MaxMind account ID in the Authorization header.
INSUFFICIENT_FUNDS 402 Payment Required The license key you have provided does not have sufficient funds to use this service. Please purchase more service credits.
PERMISSION_REQUIRED 403 Forbidden You do not have permission to use the service. Please contact our support team for more information.
(none) 413 Content Too Large This status is returned when the request body is larger than 20,000 bytes. The response does not have a JSON body.
(none) 429 Too Many Requests Your request has been denied due to rate-limiting imposed by MaxMind. This is likely due to excessive previous requests resulting in error responses.
SERVER_ERROR 500 Internal Server Error There was an error when processing this request.
(none) 503 Service Unavailable There is a problem with the web service server. You can try this request again later.
### Rate-limiting If customer requests result in excessive errors, MaxMind may impose rate limits for a period of time. ## Response Body All services return data as a JSON document. The document that is returned always consists of an object (aka map or hash). Keys with undefined or empty values will not be included in the returned document. The data returned in the document will be in UTF-8 encoding. Note that a given key and value may be omitted from the response entirely if there is no relevant information to include. For example, if you do not pass any information about the credit card in your request, then the response will not contain a `credit_card` key or value. For full examples of response bodies, select one of the following: - [minFraud Score Body Example](#minfraud-score-body-example) - [minFraud Insights Body Example](#minfraud-insights-body-example) - [minFraud Factors Body Example](#minfraud-factors-body-example) - [Error Body Example](#error-body-example) ### Top-Level Fields ```json { "id": "5bc5d6c2-b2c8-40af-87f4-6d61af86b6ae", "risk_score": 0.01, "funds_remaining": 25, "queries_remaining": 5000, "ip_address": {...}, "credit_card": {...}, "device": {...}, "email": {...}, "shipping_address": {...}, "shipping_phone": {...}, "billing_address": {...}, "billing_phone": {...}, "disposition": {...}, "risk_score_reasons": [...], "warnings": [...] } ``` #### `id` Type: string (format: UUID). Available in: minFraud Score, minFraud Insights, minFraud Factors. This is the minFraud ID, a [UUID](https://en.wikipedia.org/wiki/Universally%5Funique%5Fidentifier) that identifies the minFraud response. Use this ID to [search your minFraud logs](https://www.maxmind.com/en/accounts/current/query-usage-report) or when making support requests to MaxMind. #### `risk_score` Type: decimal (min: 0.01, max: 99). Available in: minFraud Score, minFraud Insights, minFraud Factors. This field contains the overall risk score, from 0.01 to 99. A higher score indicates a higher risk of fraud. For example, a score of 20 indicates a 20% chance that a transaction is fraudulent. We never return a risk score of 0, since all transactions have the possibility of being fraudulent. Likewise, we never return a risk score of 100. [Learn more about the overall risk score on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/overall-risk-score-minfraud-maxmind) #### `funds_remaining` Type: decimal (min: 0). Available in: minFraud Score, minFraud Insights, minFraud Factors. The approximate US dollar value of the funds remaining on your MaxMind account. #### `queries_remaining` Type: integer (min: 0). Available in: minFraud Score, minFraud Insights, minFraud Factors. The approximate number of queries remaining for the service before your account runs out of funds. #### `ip_address` Type: object. Available in: minFraud Score, minFraud Insights, minFraud Factors. This object contains IP intelligence data. [See more](#ip-address). #### `credit_card` Type: object. Available in: minFraud Insights, minFraud Factors. This object contains information related to the credit card. [See more](#credit-card). #### `device` Type: object. Available in: minFraud Insights, minFraud Factors. This object contains information about the device that MaxMind believes is associated with the IP address passed in the request. [See more](#device). #### `email` Type: object. Available in: minFraud Insights, minFraud Factors. This object contains email intelligence data. [See more](#email). #### `shipping_address` Type: object. Available in: minFraud Insights, minFraud Factors. This object contains information related to the shipping address. [See more](#shipping-address). #### `shipping_phone` Type: object. Available in: minFraud Insights, minFraud Factors. This object contains information related to the shipping phone number. [See more](#shipping-phone). #### `billing_address` Type: object. Available in: minFraud Insights, minFraud Factors. This object contains information related to the billing address. [See more](#billing-address). #### `billing_phone` Type: object. Available in: minFraud Insights, minFraud Factors. This object contains information related to the billing phone number. [See more](#billing-phone). #### `disposition` Type: object. Available in: minFraud Score, minFraud Insights, minFraud Factors. This object contains information about how a request was handled by the custom rules that you have defined. [See more](#disposition). #### `risk_score_reasons` Type: array. Available in: minFraud Factors. This array contains risk score reason objects. [See more](#risk-score-reasons). #### `warnings` Type: array. Available in: minFraud Score, minFraud Insights, minFraud Factors. This array contains warning objects detailing issues with the request that was sent, such as invalid or unknown inputs. [See more](#warnings). ### IP Address For minFraud Score, this object only contains the `risk` for the IP address. For minFraud Insights and Factors, the object is the [GeoIP Insights response body](/geoip/docs/web-services/responses/#geoip-insights-body-example) with five modifications: 1. `risk` has been added directly to the `ip_address` object. 2. `risk_reasons` has been added directly to the `ip_address` object. 3. `is_high_risk` has been added to the `country` sub-object. This field is deprecated. 4. `local_time` has been added to the `location` sub-object. 5. The `maxmind` object is not present. See below for descriptions of the added fields. minFraud Insights and Factors return anonymous IP outputs in the [`anonymizer` object](/geoip/docs/web-services/responses/#anonymizer): - `confidence` - `is_anonymous` - `is_anonymous_vpn` - `is_hosting_provider` - `is_public_proxy` - `is_residential_proxy` - `is_tor_exit_node` - `network_last_seen` - `provider_name` - `residential` The six `is_*` outputs above are also returned in the `traits` object for backwards compatibility, but they are deprecated there. Use the `anonymizer` object instead. ```json { "risk": 0.01, "anonymizer": { "confidence": 99, "is_anonymous": true, "is_anonymous_vpn": true, "is_hosting_provider": true, "is_public_proxy": true, "is_residential_proxy": true, "is_tor_exit_node": true, "network_last_seen": "2025-01-15", "provider_name": "nordvpn", "residential": { "confidence": 82, "network_last_seen": "2026-05-11", "provider_name": "quickshift" } }, "city": { "confidence": 25, "geoname_id": 54321, "names": { "de": "Los Angeles", "en": "Los Angeles", "es": "Los Ángeles", "fr": "Los Angeles", "ja": "ロサンゼルス市", "pt-BR": "Los Angeles", "ru": "Лос-Анджелес", "zh-CN": "洛杉矶" } }, "continent": { "code": "NA", "geoname_id": 123456, "names": { "de": "Nordamerika", "en": "North America", "es": "América del Norte", "fr": "Amérique du Nord", "ja": "北アメリカ", "pt-BR": "América do Norte", "ru": "Северная Америка", "zh-CN": "北美洲" } }, "country": { "confidence": 75, "geoname_id": 6252001, "is_in_european_union": true, "iso_code": "US", "names": { "de": "USA", "en": "United States", "es": "Estados Unidos", "fr": "États-Unis", "ja": "アメリカ合衆国", "pt-BR": "Estados Unidos", "ru": "США", "zh-CN": "美国" } }, "location": { "accuracy_radius": 20, "average_income": 50321, "latitude": 37.6293, "local_time": "2015-04-26T01:37:17-08:00", "longitude": -122.1163, "metro_code": 807, "population_density": 7122, "time_zone": "America/Los_Angeles" }, "postal": { "code": "90001", "confidence": 10 }, "registered_country": { "geoname_id": 6252001, "is_in_european_union": true, "iso_code": "US", "names": { "de": "USA", "en": "United States", "es": "Estados Unidos", "fr": "États-Unis", "ja": "アメリカ合衆国", "pt-BR": "Estados Unidos", "ru": "США", "zh-CN": "美国" } }, "represented_country": { "geoname_id": 6252001, "is_in_european_union": true, "iso_code": "US", "names": { "de": "USA", "en": "United States", "es": "Estados Unidos", "fr": "États-Unis", "ja": "アメリカ合衆国", "pt-BR": "Estados Unidos", "ru": "США", "zh-CN": "美国" }, "type": "military" }, "risk_reasons": [ { "code": "ANONYMOUS_IP", "reason": "The IP address belongs to an anonymous network." }, { "code": "MINFRAUD_NETWORK_ACTIVITY", "reason": "Suspicious activity has been seen on this IP address across minFraud customers." } ], "subdivisions": [ { "confidence": 50, "geoname_id": 5332921, "iso_code": "CA", "names": { "de": "Kalifornien", "en": "California", "es": "California", "fr": "Californie", "ja": "カリフォルニア", "ru": "Калифорния", "zh-CN": "加州" } } ], "traits": { "autonomous_system_number": 1239, "autonomous_system_organization": "Linkem IR WiMax Network", "connection_type": "Cable/DSL", "domain": "example.com", "ip_address": "1.2.3.4", "ip_risk_snapshot": 45.5, "is_anonymous": true, "is_anonymous_vpn": true, "is_anycast": true, "is_hosting_provider": true, "is_public_proxy": true, "is_residential_proxy": true, "is_tor_exit_node": true, "isp": "Linkem spa", "mobile_country_code": "310", "mobile_network_code": "004", "network": "1.2.3.0/24", "organization": "Linkem IR WiMax Network", "static_ip_score": 1.5, "user_count": 1, "user_type": "traveler" } } ``` #### `risk` Type: decimal (min: 0.01, max: 99). Available in: minFraud Score, minFraud Insights, minFraud Factors. This field contains the risk associated with the IP address. The value ranges from 0.01 to 99. A higher score indicates a higher risk. [Learn more about the IP risk score on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/minfraud-ip-risk-score) #### `country` Type: object. Available in: minFraud Insights, minFraud Factors. This object contains country-level geolocation data for the IP address associated with the event. #### `location` Type: object. Available in: minFraud Insights, minFraud Factors. This object contains city-level geolocation data for the IP address associated with the event. #### `risk_reasons` Type: array. Available in: minFraud Insights, minFraud Factors. This array contains IP Address Risk Reason objects identifying the reasons why the IP address received the associated risk. [Learn how to use IP risk reasons for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/minfraud-ip-risk-reasons-maxmind) ### IP Address > Country This object contains country-level geolocation data for the IP address associated with the event. [See the GeoIP Insights response body](/geoip/docs/web-services/responses/#country) for more information. ```json { "confidence": 75, "geoname_id": 6252001, "is_in_european_union": true, "iso_code": "US", "names": { "de": "USA", "en": "United States", "es": "Estados Unidos", "fr": "États-Unis", "ja": "アメリカ合衆国", "pt-BR": "Estados Unidos", "ru": "США", "zh-CN": "美国" } } ``` ### IP Address > Location This object contains city-level geolocation data for the IP address associated with the event. [See the GeoIP Insights response body](/geoip/docs/web-services/responses/#location) for more information. ```json { "accuracy_radius": 20, "average_income": 50321, "latitude": 37.6293, "local_time": "2015-04-26T01:37:17-08:00", "longitude": -122.1163, "metro_code": 807, "population_density": 7122, "time_zone": "America/Los_Angeles" } ``` #### `local_time` Type: string (max length: 255). Available in: minFraud Insights, minFraud Factors. The date and time of the transaction in the time zone associated with the IP address. The value is formatted according to [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). For instance, the local time in Boston might be returned as `2015-04-27T19:17:24-04:00`. ### IP Address > Risk Reasons This array contains IP Address Risk Reason objects identifying the reasons why the IP address received the associated risk. ```json [ { "code": "ANONYMOUS_IP", "reason": "The IP address belongs to an anonymous network." }, { "code": "MINFRAUD_NETWORK_ACTIVITY", "reason": "Suspicious activity has been seen on this IP address across minFraud customers." } ] ``` #### `code` Type: string (format: enum, max length: 255). Available in: minFraud Insights, minFraud Factors. This value is a machine-readable code identifying the reason. Although more codes may be added in the future, the current codes are: | Code | Explanation | | ---------------------------- | ------------------------------------------------------------------------------------------------------ | | `ANONYMOUS_IP` | The IP address belongs to an anonymous network. | | `BILLING_POSTAL_VELOCITY` | Many different billing postal codes have been seen on this IP address. | | `EMAIL_VELOCITY` | Many different email addresses have been seen on this IP address. | | `HIGH_RISK_DEVICE` | A high risk device was seen on this IP address. | | `HIGH_RISK_EMAIL` | A high risk email address was seen on this IP address in your past transactions. | | `ISSUER_ID_NUMBER_VELOCITY` | Many different issuer ID numbers have been seen on this IP address. | | `MINFRAUD_NETWORK_ACTIVITY` | Suspicious activity has been seen on this IP address across minFraud customers. | [Learn how to use IP risk reasons for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/minfraud-ip-risk-reasons-maxmind) #### `reason` Type: string. Available in: minFraud Insights, minFraud Factors. This field provides an explanation of the reason, as seen in the table above. The explanation text may change at any time and should not be matched against. [Learn how to use IP risk reasons for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/minfraud-ip-risk-reasons-maxmind) ### Credit Card This object contains minFraud information related to the credit card. If an issuer ID number (IIN) was not provided in the request, this object will not be present in the response. ```json { "brand": "Visa", "country": "US", "is_business": true, "is_issued_in_billing_address_country": true, "is_prepaid": true, "is_virtual": true, "issuer": { "matches_provided_name": true, "matches_provided_phone_number": true, "name": "Bank of America", "phone_number": "800-732-9194" }, "type": "credit" } ``` #### `issuer` Type: object. Available in: minFraud Insights, minFraud Factors. This field contains a JSON object with information relating to the credit card issuer. #### `brand` Type: string (max length: 255). Available in: minFraud Insights, minFraud Factors. The card brand, such as "Visa", "Discover", "American Express", etc. [Learn how to use the credit card brand data for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/credit-card-risk-data-minfraud#cc-brand-name) #### `country` Type: string (max length: 2). Available in: minFraud Insights, minFraud Factors. The two-letter [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO%5F3166-1%5Falpha-2) associated with the location of the majority of customers using this credit card as determined by their billing address. In cases where the location of customers is highly mixed, this defaults to the country of the bank issuing the card. [Learn how to use the credit card country data for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/credit-card-risk-data-minfraud#cc-country) #### `is_business` Type: boolean. Available in: minFraud Insights, minFraud Factors. This field is `true` if the issuer ID number is for a business card. It is `false` if the issuer ID number is for a non-business card. The key is only present when a valid issuer ID number has been provided. #### `is_issued_in_billing_address_country` Type: boolean. Available in: minFraud Insights, minFraud Factors. This field is `true` if the country of the billing address matches the country of the majority of customers using that IIN. It is `false` if both countries are available but do not match. If one or both of the countries are missing, the key will not be present. In cases where the location of customers is highly mixed, the match is to the country of the bank issuing the card. [Learn how to use the billing address to credit card country matching for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/billing-and-shipping-address-risk-data-minfraud#billing-cc-match) #### `is_prepaid` Type: boolean. Available in: minFraud Insights, minFraud Factors. This field is `true` if the issuer ID number is for a prepaid card. It is `false` if the issuer ID number is for a non-prepaid card. The key is only present when a valid issuer ID number has been provided. [Learn how to use prepaid card detection for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/credit-card-risk-data-minfraud#detection-prepaid-virtual) #### `is_virtual` Type: boolean. Available in: minFraud Insights, minFraud Factors. This field is `true` if the issuer ID number is for a virtual card. It is `false` if the issuer ID number is for a non-virtual card. The key is only present when a valid issuer ID number has been provided. [Learn how to use virtual card detection for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/credit-card-risk-data-minfraud#detection-prepaid-virtual) #### `type` Type: string (format: enum). Available in: minFraud Insights, minFraud Factors. The card’s type. The valid values are: * `charge` – See [Wikipedia](https://en.wikipedia.org/wiki/Charge%5Fcard) for an explanation of the difference between charge and credit cards. * `credit` * `debit` ### Credit Card > Issuer This is a sub-object of `credit_card` that contains information related to the issuer of the card. ```json { "matches_provided_name": true, "matches_provided_phone_number": true, "name": "Bank of America", "phone_number": "800-732-9194" } ``` #### `name` Type: string (max length: 255). Available in: minFraud Insights, minFraud Factors. The name of the issuing bank. [Learn how to use the credit card issuer name for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/credit-card-risk-data-minfraud#cc-brand-name) #### `matches_provided_name` Type: boolean. Available in: minFraud Insights, minFraud Factors. This field is `true` if the name matches the name provided in the request for the card issuer. It is `false` if the name does not match. The field is not included if either no name or issuer ID number (IIN) is provided in the request or if MaxMind does not have a name associated with the IIN. #### `phone_number` Type: string (max length: 255). Available in: minFraud Insights, minFraud Factors. The phone number of the bank which issued the credit card. In some cases, the phone number we return may be out of date. #### `matches_provided_phone_number` Type: boolean. Available in: minFraud Insights, minFraud Factors. This field is `true` if the phone number matches the number provided in the request for the card issuer. It is `false` if the number does not match. The field is not included if either no phone number or issuer ID number (IIN) is provided in the request or if MaxMind does not have a phone number associated with the IIN. ### Device This object contains information about the device that MaxMind believes is associated with the IP address passed in the request. ```json { "confidence": 99, "id": "7835b099-d385-4e5b-969e-7df26181d73b", "last_seen": "2016-06-08T14:16:38Z", "local_time": "2018-01-02T10:40:11-08:00" } ``` #### `confidence` Type: decimal (min: 0.01, max: 99). Available in: minFraud Insights, minFraud Factors. A number from 0.01 to 99 representing the confidence that the `/device/id` refers to a unique device as opposed to a cluster of similar devices. A confidence of 0.01 indicates very low confidence that the device is unique, whereas 99 indicates very high confidence. [Learn how to use device confidence for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/device-risk-data-minfraud#device-confidence) #### `id` Type: string (format: UUID). Available in: minFraud Insights, minFraud Factors. A UUID that MaxMind uses for the device associated with this IP address. This is only available if you are using the [Device Tracking Add-On](/minfraud/api-documentation#device-tracking-add-on). #### `last_seen` Type: string (max length: 255). Available in: minFraud Insights, minFraud Factors. The date and time of the last sighting of the device. The value is formatted according to [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). [Learn how to use the last sighting data for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/device-risk-data-minfraud#device-last-seen) #### `local_time` Type: string (max length: 255). Available in: minFraud Insights, minFraud Factors. The local date and time of the transaction in the time zone of the device. This is determined by using the UTC offset associated with the device. The value is formatted according to [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). [Learn how to use local time data for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/device-risk-data-minfraud#device-local-time) ### Email ```json { "domain": { "classification": "business", "first_seen": "2019-01-20", "risk": 1.23, "visit": { "has_redirect": true, "last_visited_on": "2025-11-15", "status": "live" }, "volume": 6.5 }, "first_seen": "2016-02-03", "is_disposable": false, "is_free": false, "is_high_risk": true } ``` #### `domain` Type: object. Available in: minFraud Insights, minFraud Factors. This field contains a JSON object with information relating to the domain. #### `first_seen` Type: string (format: YYYY-MM-DD, max length: 10). Available in: minFraud Insights, minFraud Factors. A date string (e.g. 2017-04-24) to identify the date an email address was first seen by MaxMind. This is expressed using the ISO 8601 date format `YYYY-MM-DD`. The earliest date that may be returned is January 1, 2008. [Learn how to use email first seen data for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/minfraud-email-risk-data#email-first-seen) #### `is_disposable` Type: boolean. Available in: minFraud Insights, minFraud Factors. This field is `true` if MaxMind believes that the email address is from a disposable email provider. It is `false` if the address is not from a known disposable email provider. The key will only be present if a valid email address or email domain is provided. [Learn how to use disposable email detection for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/minfraud-email-risk-data#free-disposible-flags) #### `is_free` Type: boolean. Available in: minFraud Insights, minFraud Factors. This field is `true` if MaxMind believes that this email domain is for a free email provider such as Gmail or Yahoo! Mail. It is `false` if the domain is not for a known free email provider. The key will only be present if a valid email address or email domain is provided. [Learn how to use free email detection for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/minfraud-email-risk-data#free-disposible-flags) #### `is_high_risk` Type: boolean. Available in: minFraud Insights, minFraud Factors. This field is `true` if MaxMind believes that this email address is likely to be used for fraud. It is `false` if MaxMind does not believe the address is used for fraud. The key will only be present if a valid email address or email address hash is provided. Note that this is also factored into the overall `risk_score` in the response as well. [Learn how to use our high risk email flag for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/minfraud-email-risk-data#email-reputation-flagging) ### Email > Domain This is a sub-object of `email` that contains information related to the domain. ```json { "classification": "business", "first_seen": "2019-01-20", "risk": 1.23, "visit": { "has_redirect": true, "last_visited_on": "2025-11-15", "status": "live" }, "volume": 6.5 } ``` #### `classification` Type: string. Available in: minFraud Insights, minFraud Factors. A classification of the domain. One of the following values. Additional values may be added in the future. * `business` * `education` * `government` * `isp_email` [Learn more about the domain classification on our Knowledge Base.](https://support.maxmind.com/knowledge-base/minfraud-domain-risk-data#domain-classification) #### `first_seen` Type: string (format: YYYY-MM-DD, max length: 10). Available in: minFraud Insights, minFraud Factors. A date string (e.g. 2019-01-01) to identify the date an email address domain was first seen by MaxMind. This is expressed using the ISO 8601 date format `YYYY-MM-DD`. The earliest date that may be returned is January 1, 2019. [Learn how to use email first seen data for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/minfraud-email-risk-data#email-first-seen) #### `risk` Type: decimal (min: 0.01, max: 99). Available in: minFraud Insights, minFraud Factors. This field contains the risk associated with the domain. The value ranges from 0.01 to 99. A higher score indicates higher risk. [Learn more about the email domain risk score on our Knowledge Base.](https://support.maxmind.com/knowledge-base/minfraud-domain-risk-data#domain-reputation-score) #### `visit` Type: object. Available in: minFraud Insights, minFraud Factors. An object containing information about an automated visit to the email domain. See the [Email > Domain > Visit](#email--domain--visit) section for details about this object. #### `volume` Type: decimal (min: 0.001, max: 1000000). Available in: minFraud Insights, minFraud Factors. This field indicates how much activity we see on an email domain across the minFraud network, expressed in sightings per million. The value is rounded to 2 significant figures. Example domain sightings per million requests: * Consumer email domains: gmail.com (630,000), icloud.com (37,000) * Business domains: microsoft.com (6) Note: These are point-in-time examples to provide a relative sense of the values. They will change based on email usage patterns. [Learn more about email domain volume on our Knowledge Base.](https://support.maxmind.com/knowledge-base/minfraud-domain-risk-data#domain-volume) ### Email > Domain > Visit This is a sub-object of `email/domain` that contains information about an automated visit to the email domain. Domain visits are performed by an automated agent, so for newly-sighted domains on the minFraud network, it can take a few minutes for these outputs to be populated on later requests on the same domain. Domain visits are also limited to those with low volume on the network. High volume domains such as those for email providers and large businesses will not have domain visit outputs in the minFraud response. ```json { "has_redirect": true, "last_visited_on": "2025-11-15", "status": "live" } ``` #### `has_redirect` Type: boolean. Available in: minFraud Insights, minFraud Factors. This is `true` if the domain in the request has redirects (configured to automatically send visitors to another URL). Otherwise, the key is not included in the `/email/domain/visit` object. If `true`, the `/email/domain/visit/status` field corresponds to the last domain visited after redirecting. [Learn more about the email domain visit redirect flag on our Knowledge Base.](https://support.maxmind.com/knowledge-base/minfraud-domain-risk-data#domain-visit) #### `last_visited_on` Type: string (format: YYYY-MM-DD). Available in: minFraud Insights, minFraud Factors. A date string that corresponds to when the automated visit was completed. This is expressed using the ISO 8601 date format `YYYY-MM-DD`. Pair with the `/email/domain/visit/status` and `/email/domain/visit/has_redirect` fields to determine the recency of those values. #### `status` Type: string. Available in: minFraud Insights, minFraud Factors. A classification of the status of the domain (or the last domain visited after following redirects, if these are present and can be followed) based on an automated visit at a previous point in time. This field may be initially unavailable for a newly-sighted domain and populated at a future time after a visit is conducted. Pair with the `/email/domain/visit/last_visited_on` to determine the recency of the visit. One of the following values. Additional values may be added in the future. | Status | Description | | ----------------------------- | ---------------------------------------------------------------------------------------------------- | | `live` | The domain is reachable and serving content normally. | | `dns_error` | The domain is missing, expired, or DNS is misconfigured. | | `network_error` | The domain is offline, blocked, or unreachable. | | `http_error` | The domain is reachable but the web application had a problem or denied the request. | | `parked` | The domain is live and is in a parked state. | | `pre_development` | The domain is live and is in a pre-development state. | [Learn more about the email domain visit status on our Knowledge Base.](https://support.maxmind.com/knowledge-base/minfraud-domain-risk-data#domain-visit) ### Shipping Address ```json { "distance_to_billing_address": 22, "distance_to_ip_location": 15, "is_high_risk": true, "is_in_ip_country": true, "is_postal_in_city": true, "latitude": 37.632, "longitude": -122.313 } ``` #### `is_high_risk` Type: boolean. Available in: minFraud Insights, minFraud Factors. This field is `true` if the shipping address is an address associated with fraudulent transactions. The field is `false` when the address is not associated with increased risk. The key will only be present when a shipping address is provided. [Learn more about the flag for high risk shipping addresses on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/billing-and-shipping-address-risk-data-minfraud#high-risk-flag) #### `is_postal_in_city` Type: boolean. Available in: minFraud Insights, minFraud Factors. This field is `true` if the postal code provided with the address is in the city for the address. The field is `false` when the postal code is not in the city. The key will only be present when a shipping postal code, city, and country have been provided. We use [GeoNames data](https://www.geonames.org/postal-codes/postal-codes-us.html) for the postal-city match, which uses the [preferred place name](https://en.wikipedia.org/wiki/ZIP_Code) for a US ZIP code. [Alternative place names](https://en.wikipedia.org/wiki/ZIP_Code) for US ZIP codes may not trigger a match for this field. [Learn how to use the postal to city check for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/billing-and-shipping-address-risk-data-minfraud#postal-city-match) #### `latitude` Type: decimal. Available in: minFraud Insights, minFraud Factors. The approximate [WGS84](https://en.wikipedia.org/wiki/World%5FGeodetic%5FSystem) latitude associated with the address. **Latitude and longitude are not precise and should not be used to identify a particular street address or household.** #### `longitude` Type: decimal. Available in: minFraud Insights, minFraud Factors. The approximate [WGS84](https://en.wikipedia.org/wiki/World%5FGeodetic%5FSystem) longitude associated with the address. **Latitude and longitude are not precise and should not be used to identify a particular street address or household.** #### `distance_to_ip_location` Type: integer. Available in: minFraud Insights, minFraud Factors. The distance in kilometers from the address to the IP location. When we cannot locate the address or the IP address more precisely, we use country or subdivision coordinates, which may lead to inaccurate distance calculations. [Learn how to use the IP geolocation to address distance for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/billing-and-shipping-address-risk-data-minfraud#ip-geo-to-address-match) #### `distance_to_billing_address` Type: integer. Available in: minFraud Insights, minFraud Factors. The distance in kilometers from the shipping address to the billing address. When we cannot locate an address more precisely, we use country or subdivision coordinates, which may lead to inaccurate distance calculations. [Learn how to use the shipping to billing address distance for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/billing-and-shipping-address-risk-data-minfraud#distance) #### `is_in_ip_country` Type: boolean. Available in: minFraud Insights, minFraud Factors. This field is `true` if the address is in the IP country. The field is `false` when the address is not in the IP country. If the IP address could not be geolocated or no shipping address was provided, the field will not be included in the response. [Learn how to use the IP location to country check for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/billing-and-shipping-address-risk-data-minfraud#ip-geo-to-address-match) ### Shipping Phone ```json { "country": "CA", "is_voip": true, "matches_postal": true, "network_operator": "Telus Mobility-SVR/2", "number_type": "mobile" } ``` #### `country` Type: string. Available in: minFraud Insights, minFraud Factors. A two-character [ISO 3166-1](https://en.wikipedia.org/wiki/ISO%5F3166-1) country code for the country associated with the shipping phone number. #### `network_operator` Type: string. Available in: minFraud Insights, minFraud Factors. The name of the original network operator associated with the shipping phone number. This field does not reflect phone numbers that have been ported from the original operator to another, nor does it identify [mobile virtual network operators](https://en.wikipedia.org/wiki/Mobile%5Fvirtual%5Fnetwork%5Foperator). #### `number_type` Type: string. Available in: minFraud Insights, minFraud Factors. One of the following values: `fixed` or `mobile`. Additional values may be added in the future. #### `is_voip` Type: boolean. Available in: minFraud Insights, minFraud Factors. This is `true` if the shipping phone number is a Voice over Internet Protocol (VoIP) number allocated by a regulator. It is `false` if the shipping phone number is not a VoIP number allocated by a regulator. The key is only present when a valid shipping phone number has been provided and we have data for it. #### `matches_postal` Type: boolean. Available in: minFraud Insights, minFraud Factors. This field is `true` if the phone number's prefix is commonly associated with the shipping postal code. It is `false` if the prefix is not associated with the postal code. This key is only present when the phone number is in the US, the number prefix is in our database, and the postal code and country are provided in the request. ### Billing Address ```json { "distance_to_ip_location": 100, "is_in_ip_country": true, "is_postal_in_city": true, "latitude": 37.545, "longitude": -122.421 } ``` #### `is_postal_in_city` Type: boolean. Available in: minFraud Insights, minFraud Factors. This field is `true` if the postal code provided with the address is in the city for the address. The field is `false` when the postal code is not in the city. The key will only be present when a billing postal code, city, and country have been provided. We use [GeoNames data](https://www.geonames.org/postal-codes/postal-codes-us.html) for the postal-city match, which uses the [preferred place name](https://en.wikipedia.org/wiki/ZIP_Code) for a US ZIP code. [Alternative place names](https://en.wikipedia.org/wiki/ZIP_Code) for US ZIP codes may not trigger a match for this field. [Learn how to use the postal to city check for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/billing-and-shipping-address-risk-data-minfraud#postal-city-match) #### `latitude` Type: decimal. Available in: minFraud Insights, minFraud Factors. The approximate [WGS84](https://en.wikipedia.org/wiki/World%5FGeodetic%5FSystem) latitude associated with the address. **Latitude and longitude are not precise and should not be used to identify a particular street address or household.** #### `longitude` Type: decimal. Available in: minFraud Insights, minFraud Factors. The approximate [WGS84](https://en.wikipedia.org/wiki/World%5FGeodetic%5FSystem) longitude associated with the address. **Latitude and longitude are not precise and should not be used to identify a particular street address or household.** #### `distance_to_ip_location` Type: integer. Available in: minFraud Insights, minFraud Factors. The distance in kilometers from the address to the IP location. When we cannot locate the address or the IP address more precisely, we use country or subdivision coordinates, which may lead to inaccurate distance calculations. [Learn how to use the IP geolocation to address distance for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/billing-and-shipping-address-risk-data-minfraud#ip-geo-to-address-match) #### `is_in_ip_country` Type: boolean. Available in: minFraud Insights, minFraud Factors. This field is `true` if the address is in the IP country. The field is `false` when the address is not in the IP country. If the IP address could not be geolocated or no billing address was provided, the field will not be included in the response. [Learn how to use the IP location to country check for risk analysis on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/billing-and-shipping-address-risk-data-minfraud#ip-geo-to-address-match) ### Billing Phone ```json { "country": "US", "is_voip": true, "matches_postal": true, "network_operator": "Verizon/1", "number_type": "fixed" } ``` #### `country` Type: string. Available in: minFraud Insights, minFraud Factors. A two-character [ISO 3166-1](https://en.wikipedia.org/wiki/ISO%5F3166-1) country code for the country associated with the billing phone number. #### `network_operator` Type: string. Available in: minFraud Insights, minFraud Factors. The name of the original network operator associated with the billing phone number. This field does not reflect phone numbers that have been ported from the original operator to another, nor does it identify [mobile virtual network operators](https://en.wikipedia.org/wiki/Mobile%5Fvirtual%5Fnetwork%5Foperator). #### `number_type` Type: string. Available in: minFraud Insights, minFraud Factors. One of the following values: `fixed` or `mobile`. Additional values may be added in the future. #### `is_voip` Type: boolean. Available in: minFraud Insights, minFraud Factors. This is `true` if the billing phone number is a Voice over Internet Protocol (VoIP) number allocated by a regulator. It is `false` if the billing phone number is not a VoIP number allocated by a regulator. The key is only present when a valid billing phone number has been provided and we have data for it. #### `matches_postal` Type: boolean. Available in: minFraud Insights, minFraud Factors. This field is `true` if the phone number's prefix is commonly associated with the billing postal code. It is `false` if the prefix is not associated with the postal code. This key is only present when the phone number is in the US, the number prefix is in our database, and the postal code and country are provided in the request. ### Disposition This object contains information about how a request was handled by the custom rules you have defined. If your account does not have any custom rules defined, then this object will not be present in the response. [Learn about custom rules and dispositions on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/use-custom-rules-and-dispositions-minfraud-maxmind) ```json { "action": "accept", "reason": "custom_rule", "rule_label": "my_custom_rule" } ``` #### `action` Type: string (format: enum). Available in: minFraud Score, minFraud Insights, minFraud Factors. This describes how the request was handled. The valid values are: | Action | Explanation | | -------------- | -------------------------------------------------------------------------------------- | | `accept` | This is the default value that is used if none of your custom rules match the request. | | `reject` | | | `manual_review` | | | `test` | This value can be used to test custom rules. | #### `reason` Type: string (format: enum). Available in: minFraud Score, minFraud Insights, minFraud Factors. This describes why the `action` was set to a particular value. The valid values are: | Reason | Explanation | | ------------ | --------------------------------------------- | | `default` | No custom rules matched the request. | | `custom_rule` | A custom rule was applied and set the action. | #### `rule_label` Type: string. Available in: minFraud Score, minFraud Insights, minFraud Factors. The custom rule that was triggered. If you do not have custom rules set up, the triggered custom rule does not have a label, or no custom rule was triggered, the field will not be included in the response. ### Risk Score Reasons This array contains risk score reason objects. Risk score reasons are usually only returned for medium to high risk transactions. If there were no significant changes to the risk score due to these reasons, then this array will not be present in the response. ```json [ { "multiplier": 45, "reasons": [ { "code": "ANONYMOUS_IP", "reason": "The Anonymous IP address raised the overall risk score" }, { "code": "IP_ISSUER_ID_NUMBER_VELOCITY", "reason": "The number of distinct Issuer ID Numbers found in the velocity check on IP address raised the overall risk score" } ] }, { "multiplier": 1.6, "reasons": [ { "code": "ORG_DISTANCE_RISK", "reason": "The risk of the ISP combined with the distance between the billing address and IP address location raised the overall risk score" } ] }, { "multiplier": 0.34, "reasons": [ { "code": "PHONE_ACTIVITY", "reason": "minFraud network activity of the phone number lowered the overall risk score" } ] } ] ``` #### `multiplier` Type: decimal (min: 0.01, max: 100). Available in: minFraud Factors. The factor by which the risk score is increased (if the value is greater than 1) or decreased (if the value is less than 1) for given risk reason(s). Multipliers representing a significant percentage increase or decrease in the risk score lead to risk reason(s) being present. #### `reasons` Type: array. Available in: minFraud Factors. This array contains objects that describe one of the reasons for the multiplier. #### `code` Type: string (format: enum, max length: 255). Available in: minFraud Factors. A machine-readable code identifying the risk reason. Examples listed below. Although more codes may be added in the future, a list of current codes may be provided on request. | Code | | --------------- | | ANONYMOUS\_IP | | COUNTRY | | ORG\_DISTANCE\_RISK | #### `reason` Type: string. Available in: minFraud Factors. The human-readable description of the risk reason and its effect on the overall risk score. The explanation text may change at any time and should not be matched against. | Code | Reason | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | ANONYMOUS\_IP | The Anonymous IP address raised the overall risk score | | COUNTRY | The country associated with the request lowered the overall risk score | | ORG\_DISTANCE\_RISK | The risk of the ISP combined with the distance between the billing address and IP address location raised the overall risk score | ### Warnings This array contains warning objects detailing issues with the request that was sent, such as invalid or unknown inputs. It is highly recommended that you check this array for issues when integrating the web service. ```json [ { "code": "INPUT_INVALID", "input_pointer": "/shipping/city", "warning": "Encountered value at /shipping/city that does not meet the required constraints" } ] ``` #### `code` Type: string (max length: 255). Available in: minFraud Score, minFraud Insights, minFraud Factors. This value is a machine-readable code identifying the warning. Although more codes may be added in the future, the current codes are: | Code | Description | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `BILLING_CITY_NOT_FOUND` | The billing city could not be found in our database. This may impact our ability to provide accurate distance calculations. | | `BILLING_COUNTRY_MISSING` | Billing address information was provided without providing a billing country. This may impact our ability to provide accurate distance calculations. | | `BILLING_COUNTRY_NOT_FOUND` | The billing country could not be found in our database. This may impact our ability to provide accurate distance calculations. | | `BILLING_POSTAL_NOT_FOUND` | The billing postal code could not be found in our database. This may impact our ability to provide accurate distance calculations. | | `BILLING_REGION_NOT_FOUND` | The billing region could not be found in our database. This may impact our ability to provide accurate distance calculations. | | `EMAIL_ADDRESS_UNUSABLE` | The email address entered is likely incorrect due to an integration issue. To avoid false positives, it has not been used in scoring. Check how you are passing your [email address inputs](/minfraud/api-documentation/requests#schema--request--email). | | `INPUT_INVALID` | The value associated with the key does not meet the required constraints, e.g., "United States" in a field that requires a two-letter country code. | | `INPUT_UNKNOWN` | An unknown key was encountered in the request body. | | `IP_ADDRESS_INVALID` | The IP address supplied is not a valid IPv4 or IPv6 address. | | `IP_ADDRESS_NOT_FOUND` | The IP address could not be geolocated. | | `IP_ADDRESS_RESERVED` | The IP address supplied is in a reserved network. | | `SHIPPING_CITY_NOT_FOUND` | The shipping city could not be found in our database. This may impact our ability to provide accurate distance calculations. | | `SHIPPING_COUNTRY_MISSING` | Shipping address information was provided without providing a shipping country. This may impact our ability to provide accurate distance calculations. | | `SHIPPING_COUNTRY_NOT_FOUND` | The shipping country could not be found in our database. This may impact our ability to provide accurate distance calculations. | | `SHIPPING_POSTAL_NOT_FOUND` | The shipping postal code could not be found in our database. This may impact our ability to provide accurate distance calculations. | | `SHIPPING_REGION_NOT_FOUND` | The shipping region could not be found in our database. This may impact our ability to provide accurate distance calculations. | | `TRACKING_TOKEN_INVALID` | The tracking token provided was invalid or malformed. | | `TRACKING_TOKEN_NOT_FOUND` | The tracking token provided was not found in our system. | #### `warning` Type: string. Available in: minFraud Score, minFraud Insights, minFraud Factors. This field provides a human-readable explanation of the warning. The description may change at any time and should not be matched against. #### `input_pointer` Type: string (format: json pointer). Available in: minFraud Score, minFraud Insights, minFraud Factors. A [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) to the input field that the warning is associated with. For instance, if the warning was about the billing city, this would be `/billing/city`. If it was for the price in the second shopping cart item, it would be `/shopping_cart/1/price`. ## Example Response Bodies The examples show available fields using illustrative values. They do not describe a single real transaction. Each service returns data as a JSON document. The document that is returned always consists of an object (aka map or hash). Below are full examples of the JSON body document for the minFraud Score, minFraud Insights, and minFraud Factors services, and a full example of the JSON body document for an error. ### minFraud Score Body Example ```json { "disposition": { "action": "accept", "reason": "custom_rule", "rule_label": "my_custom_rule" }, "funds_remaining": 25, "id": "5bc5d6c2-b2c8-40af-87f4-6d61af86b6ae", "ip_address": { "risk": 0.01 }, "queries_remaining": 5000, "risk_score": 0.01, "warnings": [ { "code": "INPUT_INVALID", "input_pointer": "/shipping/city", "warning": "Encountered value at /shipping/city that does not meet the required constraints" } ] } ``` ### minFraud Insights Body Example ```json { "disposition": { "action": "accept", "reason": "custom_rule", "rule_label": "my_custom_rule" }, "funds_remaining": 25, "id": "5bc5d6c2-b2c8-40af-87f4-6d61af86b6ae", "ip_address": { "risk": 0.01, "anonymizer": { "confidence": 99, "is_anonymous": true, "is_anonymous_vpn": true, "is_hosting_provider": true, "is_public_proxy": true, "is_residential_proxy": true, "is_tor_exit_node": true, "network_last_seen": "2025-01-15", "provider_name": "nordvpn", "residential": { "confidence": 82, "network_last_seen": "2026-05-11", "provider_name": "quickshift" } }, "city": { "confidence": 25, "geoname_id": 54321, "names": { "de": "Los Angeles", "en": "Los Angeles", "es": "Los Ángeles", "fr": "Los Angeles", "ja": "ロサンゼルス市", "pt-BR": "Los Angeles", "ru": "Лос-Анджелес", "zh-CN": "洛杉矶" } }, "continent": { "code": "NA", "geoname_id": 123456, "names": { "de": "Nordamerika", "en": "North America", "es": "América del Norte", "fr": "Amérique du Nord", "ja": "北アメリカ", "pt-BR": "América do Norte", "ru": "Северная Америка", "zh-CN": "北美洲" } }, "country": { "confidence": 75, "geoname_id": 6252001, "is_in_european_union": true, "iso_code": "US", "names": { "de": "USA", "en": "United States", "es": "Estados Unidos", "fr": "États-Unis", "ja": "アメリカ合衆国", "pt-BR": "Estados Unidos", "ru": "США", "zh-CN": "美国" } }, "location": { "accuracy_radius": 20, "average_income": 50321, "latitude": 37.6293, "local_time": "2015-04-26T01:37:17-08:00", "longitude": -122.1163, "metro_code": 807, "population_density": 7122, "time_zone": "America/Los_Angeles" }, "postal": { "code": "90001", "confidence": 10 }, "registered_country": { "geoname_id": 6252001, "is_in_european_union": true, "iso_code": "US", "names": { "de": "USA", "en": "United States", "es": "Estados Unidos", "fr": "États-Unis", "ja": "アメリカ合衆国", "pt-BR": "Estados Unidos", "ru": "США", "zh-CN": "美国" } }, "represented_country": { "geoname_id": 6252001, "is_in_european_union": true, "iso_code": "US", "names": { "de": "USA", "en": "United States", "es": "Estados Unidos", "fr": "États-Unis", "ja": "アメリカ合衆国", "pt-BR": "Estados Unidos", "ru": "США", "zh-CN": "美国" }, "type": "military" }, "risk_reasons": [ { "code": "ANONYMOUS_IP", "reason": "The IP address belongs to an anonymous network." }, { "code": "MINFRAUD_NETWORK_ACTIVITY", "reason": "Suspicious activity has been seen on this IP address across minFraud customers." } ], "subdivisions": [ { "confidence": 50, "geoname_id": 5332921, "iso_code": "CA", "names": { "de": "Kalifornien", "en": "California", "es": "California", "fr": "Californie", "ja": "カリフォルニア", "ru": "Калифорния", "zh-CN": "加州" } } ], "traits": { "autonomous_system_number": 1239, "autonomous_system_organization": "Linkem IR WiMax Network", "connection_type": "Cable/DSL", "domain": "example.com", "ip_address": "1.2.3.4", "ip_risk_snapshot": 45.5, "is_anonymous": true, "is_anonymous_vpn": true, "is_anycast": true, "is_hosting_provider": true, "is_public_proxy": true, "is_residential_proxy": true, "is_tor_exit_node": true, "isp": "Linkem spa", "mobile_country_code": "310", "mobile_network_code": "004", "network": "1.2.3.0/24", "organization": "Linkem IR WiMax Network", "static_ip_score": 1.5, "user_count": 1, "user_type": "traveler" } }, "queries_remaining": 5000, "risk_score": 0.01, "warnings": [ { "code": "INPUT_INVALID", "input_pointer": "/shipping/city", "warning": "Encountered value at /shipping/city that does not meet the required constraints" } ], "billing_address": { "distance_to_ip_location": 100, "is_in_ip_country": true, "is_postal_in_city": true, "latitude": 37.545, "longitude": -122.421 }, "billing_phone": { "country": "US", "is_voip": true, "matches_postal": true, "network_operator": "Verizon/1", "number_type": "fixed" }, "credit_card": { "brand": "Visa", "country": "US", "is_business": true, "is_issued_in_billing_address_country": true, "is_prepaid": true, "is_virtual": true, "issuer": { "matches_provided_name": true, "matches_provided_phone_number": true, "name": "Bank of America", "phone_number": "800-732-9194" }, "type": "credit" }, "device": { "confidence": 99, "id": "7835b099-d385-4e5b-969e-7df26181d73b", "last_seen": "2016-06-08T14:16:38Z", "local_time": "2018-01-02T10:40:11-08:00" }, "email": { "domain": { "classification": "business", "first_seen": "2019-01-20", "risk": 1.23, "visit": { "has_redirect": true, "last_visited_on": "2025-11-15", "status": "live" }, "volume": 6.5 }, "first_seen": "2016-02-03", "is_disposable": false, "is_free": false, "is_high_risk": true }, "shipping_address": { "distance_to_billing_address": 22, "distance_to_ip_location": 15, "is_high_risk": true, "is_in_ip_country": true, "is_postal_in_city": true, "latitude": 37.632, "longitude": -122.313 }, "shipping_phone": { "country": "CA", "is_voip": true, "matches_postal": true, "network_operator": "Telus Mobility-SVR/2", "number_type": "mobile" } } ``` ### minFraud Factors Body Example ```json { "disposition": { "action": "accept", "reason": "custom_rule", "rule_label": "my_custom_rule" }, "funds_remaining": 25, "id": "5bc5d6c2-b2c8-40af-87f4-6d61af86b6ae", "ip_address": { "risk": 0.01, "anonymizer": { "confidence": 99, "is_anonymous": true, "is_anonymous_vpn": true, "is_hosting_provider": true, "is_public_proxy": true, "is_residential_proxy": true, "is_tor_exit_node": true, "network_last_seen": "2025-01-15", "provider_name": "nordvpn", "residential": { "confidence": 82, "network_last_seen": "2026-05-11", "provider_name": "quickshift" } }, "city": { "confidence": 25, "geoname_id": 54321, "names": { "de": "Los Angeles", "en": "Los Angeles", "es": "Los Ángeles", "fr": "Los Angeles", "ja": "ロサンゼルス市", "pt-BR": "Los Angeles", "ru": "Лос-Анджелес", "zh-CN": "洛杉矶" } }, "continent": { "code": "NA", "geoname_id": 123456, "names": { "de": "Nordamerika", "en": "North America", "es": "América del Norte", "fr": "Amérique du Nord", "ja": "北アメリカ", "pt-BR": "América do Norte", "ru": "Северная Америка", "zh-CN": "北美洲" } }, "country": { "confidence": 75, "geoname_id": 6252001, "is_in_european_union": true, "iso_code": "US", "names": { "de": "USA", "en": "United States", "es": "Estados Unidos", "fr": "États-Unis", "ja": "アメリカ合衆国", "pt-BR": "Estados Unidos", "ru": "США", "zh-CN": "美国" } }, "location": { "accuracy_radius": 20, "average_income": 50321, "latitude": 37.6293, "local_time": "2015-04-26T01:37:17-08:00", "longitude": -122.1163, "metro_code": 807, "population_density": 7122, "time_zone": "America/Los_Angeles" }, "postal": { "code": "90001", "confidence": 10 }, "registered_country": { "geoname_id": 6252001, "is_in_european_union": true, "iso_code": "US", "names": { "de": "USA", "en": "United States", "es": "Estados Unidos", "fr": "États-Unis", "ja": "アメリカ合衆国", "pt-BR": "Estados Unidos", "ru": "США", "zh-CN": "美国" } }, "represented_country": { "geoname_id": 6252001, "is_in_european_union": true, "iso_code": "US", "names": { "de": "USA", "en": "United States", "es": "Estados Unidos", "fr": "États-Unis", "ja": "アメリカ合衆国", "pt-BR": "Estados Unidos", "ru": "США", "zh-CN": "美国" }, "type": "military" }, "risk_reasons": [ { "code": "ANONYMOUS_IP", "reason": "The IP address belongs to an anonymous network." }, { "code": "MINFRAUD_NETWORK_ACTIVITY", "reason": "Suspicious activity has been seen on this IP address across minFraud customers." } ], "subdivisions": [ { "confidence": 50, "geoname_id": 5332921, "iso_code": "CA", "names": { "de": "Kalifornien", "en": "California", "es": "California", "fr": "Californie", "ja": "カリフォルニア", "ru": "Калифорния", "zh-CN": "加州" } } ], "traits": { "autonomous_system_number": 1239, "autonomous_system_organization": "Linkem IR WiMax Network", "connection_type": "Cable/DSL", "domain": "example.com", "ip_address": "1.2.3.4", "ip_risk_snapshot": 45.5, "is_anonymous": true, "is_anonymous_vpn": true, "is_anycast": true, "is_hosting_provider": true, "is_public_proxy": true, "is_residential_proxy": true, "is_tor_exit_node": true, "isp": "Linkem spa", "mobile_country_code": "310", "mobile_network_code": "004", "network": "1.2.3.0/24", "organization": "Linkem IR WiMax Network", "static_ip_score": 1.5, "user_count": 1, "user_type": "traveler" } }, "queries_remaining": 5000, "risk_score": 0.01, "warnings": [ { "code": "INPUT_INVALID", "input_pointer": "/shipping/city", "warning": "Encountered value at /shipping/city that does not meet the required constraints" } ], "billing_address": { "distance_to_ip_location": 100, "is_in_ip_country": true, "is_postal_in_city": true, "latitude": 37.545, "longitude": -122.421 }, "billing_phone": { "country": "US", "is_voip": true, "matches_postal": true, "network_operator": "Verizon/1", "number_type": "fixed" }, "credit_card": { "brand": "Visa", "country": "US", "is_business": true, "is_issued_in_billing_address_country": true, "is_prepaid": true, "is_virtual": true, "issuer": { "matches_provided_name": true, "matches_provided_phone_number": true, "name": "Bank of America", "phone_number": "800-732-9194" }, "type": "credit" }, "device": { "confidence": 99, "id": "7835b099-d385-4e5b-969e-7df26181d73b", "last_seen": "2016-06-08T14:16:38Z", "local_time": "2018-01-02T10:40:11-08:00" }, "email": { "domain": { "classification": "business", "first_seen": "2019-01-20", "risk": 1.23, "visit": { "has_redirect": true, "last_visited_on": "2025-11-15", "status": "live" }, "volume": 6.5 }, "first_seen": "2016-02-03", "is_disposable": false, "is_free": false, "is_high_risk": true }, "shipping_address": { "distance_to_billing_address": 22, "distance_to_ip_location": 15, "is_high_risk": true, "is_in_ip_country": true, "is_postal_in_city": true, "latitude": 37.632, "longitude": -122.313 }, "shipping_phone": { "country": "CA", "is_voip": true, "matches_postal": true, "network_operator": "Telus Mobility-SVR/2", "number_type": "mobile" }, "risk_score_reasons": [ { "multiplier": 45, "reasons": [ { "code": "ANONYMOUS_IP", "reason": "The Anonymous IP address raised the overall risk score" } ] }, { "multiplier": 1.6, "reasons": [ { "code": "ORG_DISTANCE_RISK", "reason": "The risk of the ISP combined with the distance between the billing address and IP address location raised the overall risk score" } ] }, { "multiplier": 0.34, "reasons": [ { "code": "PHONE_ACTIVITY", "reason": "minFraud network activity of the phone number lowered the overall risk score" } ] } ] } ``` ### Error Body Example ```json { "code": "INSUFFICIENT_FUNDS", "error": "You do not have sufficient funds to use this service." } ```