---
title: "Market Compare Cards"
method: POST
path: "/api/v1/{country}/cards/compare"
tags: ["International"]
---

# Market Compare Cards

`POST /api/v1/{country}/cards/compare`

## 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/{country}/cards/compare`
- Auth: API key in header `X-API-Key`

Compare credit cards side-by-side in this market.

Cards are looked up within the specified market. Fast mode returns
deterministic value calculations; verbose mode includes AI narrative.

## Path parameters

- `country` string, required: ISO 3166-1 alpha-2 country code

## Query parameters

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

## Headers

- `authorization` string, nullable

## Request body

- V1CompareRequest: Request for POST /api/v1/intelligence/compare
  - `card_names` string[], required: 2-3 card names to compare
  - `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
  - `country` string, nullable: ISO 3166-1 alpha-2 country code (e.g. 'US', 'GB'). Scopes card lookup to that market.

## Response `200`

Successful Response

- APIResponse
  - `success` boolean, required
  - `data` unknown, required
  - `metadata` APIMetadata
    - `request_id` string
    - `api_version` string
    - `latency_ms` integer, nullable
    - `mode` string, nullable: Endpoint mode: 'fast' (deterministic, <100ms) or 'verbose' (includes AI narrative, 3-5s)
    - `timestamp` string
  - `error` string, nullable

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