V1CardValueRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/kokofinance-net/json-schema/kokofinance-net-v1-card-value-request-schema.json",
  "title": "V1CardValueRequest",
  "description": "Request for POST /api/v1/intelligence/value",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/kokofinance-net-openapi.json#/components/schemas/V1CardValueRequest",
  "properties": {
    "card_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Card Name",
      "description": "Card name to look up. If provided, uses actual card benefits from DB."
    },
    "annual_spending": {
      "type": "number",
      "title": "Annual Spending",
      "description": "Total annual spending on this card"
    },
    "annual_fee": {
      "type": "number",
      "title": "Annual Fee",
      "description": "Annual fee for the card"
    },
    "monthly_spending": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "number"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Monthly Spending",
      "description": "Per-category monthly spending"
    },
    "sign_on_bonus": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sign On Bonus",
      "description": "Sign-on bonus amount",
      "default": 0
    },
    "sign_on_bonus_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sign On Bonus Type",
      "description": "Sign-on bonus type (points or cashback)",
      "default": "points"
    },
    "params": {
      "anyOf": [
        {
          "$ref": "#/$defs/ClientParameters"
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional parameters"
    }
  },
  "type": "object",
  "required": [
    "annual_spending",
    "annual_fee"
  ],
  "$defs": {
    "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)"
    }
  }
}