Card Recommendations API

Get personalized credit card recommendations based on spending history and preferences.

POST/v1/recommendations/cards

Pricing

This endpoint costs 10 credits base + ₹0.1 per card scored. A typical request scoring 50 cards costs 15 credits.

Example

POST /v1/recommendations/cards
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "user_id": "user-123",
  "transactions": [
    {
      "amount": 1200,
      "category": "food",
      "merchant": "Swiggy",
      "timestamp": "2024-01-15T10:00:00Z"
    },
    {
      "amount": 5000,
      "category": "travel",
      "merchant": "IRCTC",
      "timestamp": "2024-01-14T08:00:00Z"
    }
  ],
  "user_cards": [
    {
      "card_id": "existing-1",
      "bank_name": "ICICI",
      "card_name": "Amazon Pay"
    }
  ],
  "preferences": {
    "prioritize_cashback": true,
    "prioritize_travel": false,
    "prioritize_lounge": false,
    "max_annual_fee": 5000,
    "income_range": "medium"
  },
  "options": {
    "limit": 5,
    "include_explanations": true,
    "exclude_user_cards": true
  }
}

Request Schema

FieldTypeRequiredDescription
user_idstringRequiredUnique identifier for the user
transactionsarrayRequiredUser transaction history (minimum 5 transactions recommended)
transactions[].amountnumberRequiredTransaction amount in INR
transactions[].categorystringRequiredTransaction category (food, travel, shopping, fuel, etc.)
transactions[].merchantstringOptionalMerchant name for merchant-specific rewards
transactions[].timestampstring (ISO 8601)RequiredTransaction timestamp
user_cardsarrayOptionalCards the user already owns (to avoid duplicates)
preferencesobjectOptionalUser preferences to influence ranking
preferences.prioritize_cashbackbooleanOptionalPrioritize cashback cards in recommendations
preferences.prioritize_travelbooleanOptionalPrioritize travel cards in recommendations
preferences.prioritize_loungebooleanOptionalPrioritize cards with lounge access
preferences.max_annual_feenumberOptionalMaximum acceptable annual fee
optionsobjectOptionalRequest options
options.limitnumberOptionalMaximum number of recommendations (default: 5, max: 20)
options.include_explanationsbooleanOptionalInclude detailed reasoning (default: true)

Supported Categories

The API uses smart category matching. For example, "dining", "restaurant", and "food" are all treated as the same category.

food
dining
travel
shopping
fuel
groceries
entertainment
utilities
online
other

Scoring Algorithm

How recommendations are ranked and scored. Cards are scored across 7 dimensions with configurable weights:

Cashback

Cashback reward rates on user categories

25%

Rewards

Points/miles value

20%

Fee Efficiency

Annual fee vs projected value

15%

Benefits

General perks and benefits

15%

Lounge

Airport lounge access

10%

Milestone

Achievable milestone rewards

10%

Redemption

Points redemption value

5%

Error Codes

CodeHTTP StatusDescription
INVALID_REQUEST400Request body validation failed
UNAUTHORIZED401Invalid or missing API key
RATE_LIMITED429Rate limit exceeded
INSUFFICIENT_CREDITS402Not enough credits for this request