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/