---
title: "Search for credit cards"
method: POST
path: "/api/v1/cards/search"
tags: ["Cards"]
---

# Search for credit cards

`POST /api/v1/cards/search`

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

Search the card database using structured filters. Returns ranked results based on spending alignment, fee value, and sign-on bonus. Deterministic ranking, <100ms.

## Headers

- `authorization` string, nullable

## Request body

- V1CardSearchRequest: Request for POST /search
  - `card_type` string, nullable: Card type filter: travel, cashback, balance_transfer, business, student, hotel, airline
  - `max_annual_fee` integer, nullable: Maximum annual fee in dollars (e.g. 200). Omit for no limit.
  - `issuer` string, nullable: Filter by issuer (e.g. 'Chase', 'American Express', 'Capital One')
  - `spending` object, nullable: Monthly spending by category for ranking (e.g. {"dining": 500, "travel": 300})
  - `max_results` integer, nullable: Maximum number of results (1-20, default 5)
  - `country` string, nullable: ISO 3166-1 alpha-2 country code (e.g. 'US', 'GB'). Defaults to 'US'.

## Response `200`

Ranked card recommendations matching filters

- unknown

## Other responses

- `401`: Invalid or missing API key
- `422`: Validation Error
- `429`: Rate limit exceeded

---

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