V1PortfolioAnalyzeRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/kokofinance-net/json-schema/kokofinance-net-v1-portfolio-analyze-request-schema.json",
  "title": "V1PortfolioAnalyzeRequest",
  "description": "Request for POST /api/v1/portfolio/analyze",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/kokofinance-net-openapi.json#/components/schemas/V1PortfolioAnalyzeRequest",
  "properties": {
    "cards": {
      "items": {
        "$ref": "#/$defs/CardInput"
      },
      "type": "array",
      "maxItems": 10,
      "minItems": 1,
      "title": "Cards",
      "description": "1-10 credit cards to analyze"
    },
    "analysis_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Analysis Type",
      "description": "Analysis type: general, fees, benefits, or usage",
      "default": "general"
    },
    "params": {
      "anyOf": [
        {
          "$ref": "#/$defs/ClientParameters"
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional spending and preference parameters"
    }
  },
  "type": "object",
  "required": [
    "cards"
  ],
  "$defs": {
    "CardInput": {
      "properties": {
        "card_name": {
          "type": "string",
          "title": "Card Name",
          "description": "Full card name"
        },
        "annual_fee": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Annual Fee",
          "description": "Annual fee override"
        },
        "card_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Card Id",
          "description": "Matched card ID if known"
        },
        "sign_on_bonus": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Sign On Bonus",
          "description": "Sign-on bonus amount"
        },
        "sign_on_bonus_type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Sign On Bonus Type",
          "description": "Sign-on bonus type (points or cashback)",
          "default": "points"
        }
      },
      "type": "object",
      "required": [
        "card_name"
      ],
      "title": "CardInput",
      "description": "Card in a portfolio"
    },
    "ClientParameters": {
      "properties": {
        "issuer_preferences": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/IssuerPreference"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Issuer Preferences"
        },
        "credit_tier": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^(poor|fair|good|excellent)$"
            },
            {
              "type": "null"
            }
          ],
          "title": "Credit Tier"
        },
        "spending": {
          "anyOf": [
            {
              "$ref": "#/$defs/SpendingInput"
            },
            {
              "type": "null"
            }
          ]
        },
        "point_balances": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/InlinePointBalance"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Point Balances",
          "description": "Point/miles balances for enrichment. API consumers provide these per-request."
        },
        "primary_goal": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^(travel|cashback|build_credit|business|balance_transfer)$"
            },
            {
              "type": "null"
            }
          ],
          "title": "Primary Goal"
        },
        "benefit_selections": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Benefit Selections",
          "description": "Individual benefit keys the user actually uses. Selected benefits count at 100%, unselected at 0%. If omitted, all benefits use the default 50% utilization. Common keys: uber, dining, travel, airline_fee, hotel_fhr, saks, clear_plus, digital_entertainment, admirals_club, global_entry, lyft, grubhub. Use GET /api/v1/benefit-categories for the full registry."
        },
        "benefit_categories_used": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Benefit Categories Used",
          "description": "Standard benefit categories the user uses (alternative to benefit_selections). Each category maps to one or more individual benefit keys. Valid values: dining_credit, travel_credit, hotel_credit, lounge_access, shopping_credit, entertainment_credit, business_credit, loyalty_bonus, other. Note: benefit_selections provides finer control."
        },
        "renewal_cancel_threshold": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Renewal Cancel Threshold",
          "description": "Net value below this → CANCEL_AND_REPLACE. Default: -100"
        },
        "renewal_keep_threshold": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Renewal Keep Threshold",
          "description": "Net value at or above this → RENEW. Default: 50"
        }
      },
      "type": "object",
      "title": "ClientParameters",
      "description": "Configurable parameters for B2B API consumption.\n\nThese parameters allow API clients (issuers, fintechs) to customize\nKoKo's analysis for their use case without changing core logic."
    },
    "InlinePointBalance": {
      "properties": {
        "program": {
          "type": "string",
          "title": "Program",
          "description": "Program key"
        },
        "balance": {
          "type": "integer",
          "title": "Balance",
          "description": "Point/miles balance"
        }
      },
      "type": "object",
      "required": [
        "program",
        "balance"
      ],
      "title": "InlinePointBalance",
      "description": "Point balance provided inline by API consumers (per-request, not stored)"
    },
    "IssuerPreference": {
      "properties": {
        "issuer": {
          "type": "string",
          "title": "Issuer",
          "description": "Card issuer name"
        },
        "weight": {
          "type": "number",
          "maximum": 3.0,
          "minimum": 0.1,
          "title": "Weight",
          "description": "1.0 = neutral, >1.0 = boost, <1.0 = de-boost",
          "default": 1.0
        }
      },
      "type": "object",
      "required": [
        "issuer"
      ],
      "title": "IssuerPreference",
      "description": "Boost or de-boost a specific issuer in recommendations"
    },
    "SpendingInput": {
      "properties": {
        "groceries": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Groceries",
          "description": "Monthly grocery spend"
        },
        "dining": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Dining",
          "description": "Monthly dining/restaurant spend"
        },
        "travel": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Travel",
          "description": "Monthly travel spend"
        },
        "gas": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Gas",
          "description": "Monthly gas/fuel spend"
        },
        "streaming": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Streaming",
          "description": "Monthly streaming services spend"
        },
        "shopping": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Shopping",
          "description": "Monthly general shopping spend"
        },
        "other": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Other",
          "description": "Monthly other spend"
        },
        "total_monthly": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Total Monthly",
          "description": "Total monthly spend override"
        }
      },
      "type": "object",
      "title": "SpendingInput",
      "description": "Monthly spending by category (dollars)"
    }
  }
}