---
title: "Analyze credit card portfolio"
method: POST
path: "/api/v1/portfolio/analyze"
tags: ["Portfolio"]
---

# Analyze credit card portfolio

`POST /api/v1/portfolio/analyze`

## 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/portfolio/analyze`
- Auth: API key in header `X-API-Key`

Portfolio analysis with card-by-card value breakdowns and decisions. Use ?mode=fast for deterministic-only (<100ms) or ?mode=verbose for AI narrative (3-5s).

## Query parameters

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

## Headers

- `authorization` string, nullable

## Request body

- V1PortfolioAnalyzeRequest: Request for POST /api/v1/portfolio/analyze
  - `cards` CardInput[], required: 1-10 credit cards to analyze
    - `card_name` string, required: Full card name
    - `annual_fee` integer, nullable: Annual fee override
    - `card_id` integer, nullable: Matched card ID if known
    - `sign_on_bonus` integer, nullable: Sign-on bonus amount
    - `sign_on_bonus_type` string, nullable: Sign-on bonus type (points or cashback)
  - `analysis_type` string, nullable: Analysis type: general, fees, benefits, or usage
  - `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`

Portfolio analysis with card-by-card breakdown

- unknown

## Other responses

- `401`: Invalid or missing API key
- `422`: Validation Error
- `429`: Rate limit exceeded (60 requests/minute)

---

[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)