---
title: "Recommend Cards"
method: POST
path: "/api/v1/intelligence/recommend"
tags: ["Intelligence"]
---

# Recommend Cards

`POST /api/v1/intelligence/recommend`

## Request

- Base URL: `https://kokofinance.net` (the document declares no server; this is the origin it was published from)
- URL: `https://kokofinance.net/api/v1/intelligence/recommend`
- Auth: API key in header `X-API-Key`

Get card recommendations for a spending category.

fast mode:
  Mode A (portfolio_card_names provided): Ranks portfolio cards by
  reward value for the requested category. No AI narrative.
  Mode B (no portfolio_card_names): Ranks market cards by net value.

verbose mode:
  Mode A: Returns AI-generated headline, explanation, pro_tip,
  and alternative card narratives.
  Mode B: Same as fast (already deterministic, no AI needed).

## Query parameters

- `mode` 'fast' | 'verbose': Response mode for intelligence endpoints.

## Headers

- `authorization` string, nullable

## Request body

- V1RecommendRequest: Request for POST /api/v1/cards/recommend
  - `category` string, required: Spending category: dining, travel, groceries, gas, etc.
  - `amount` number, nullable: Monthly spend amount for this category
  - `portfolio_card_names` string[], nullable: If provided, recommend from portfolio instead of market
  - `params` ClientParameters: Configurable parameters for B2B API consumption. These parameters allow API clients (issuers, fintechs) to customize KoKo's analysis for their use case without changing core logic.
    - `issuer_preferences` IssuerPreference[], nullable
      - `issuer` string, required: Card issuer name
      - `weight` number: 1.0 = neutral, >1.0 = boost, <1.0 = de-boost
    - `credit_tier` string, nullable
    - `spending` SpendingInput: Monthly spending by category (dollars)
      - `groceries` number, nullable: Monthly grocery spend
      - `dining` number, nullable: Monthly dining/restaurant spend
      - `travel` number, nullable: Monthly travel spend
      - `gas` number, nullable: Monthly gas/fuel spend
      - `streaming` number, nullable: Monthly streaming services spend
      - `shopping` number, nullable: Monthly general shopping spend
      - `other` number, nullable: Monthly other spend
      - `total_monthly` number, nullable: Total monthly spend override
    - `point_balances` InlinePointBalance[], nullable: Point/miles balances for enrichment. API consumers provide these per-request.
      - `program` string, required: Program key
      - `balance` integer, required: Point/miles balance
    - `primary_goal` string, nullable
    - `benefit_selections` string[], nullable: 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` string[], nullable: 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` number, nullable: Net value below this → CANCEL_AND_REPLACE. Default: -100
    - `renewal_keep_threshold` number, nullable: Net value at or above this → RENEW. Default: 50

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kokofinance/apis/koko-finance-api.md) · [All operations](https://skmtc.dev/kokofinance/apis/koko-finance-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kokofinance/apis/koko-finance-api/revisions/a5f1170af4d4?raw)