Card Recommendations API
Get personalized credit card recommendations based on spending history and preferences.
POST
/v1/recommendations/cardsPricing
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
| Field | Type | Required | Description |
|---|---|---|---|
user_id | string | Required | Unique identifier for the user |
transactions | array | Required | User transaction history (minimum 5 transactions recommended) |
transactions[].amount | number | Required | Transaction amount in INR |
transactions[].category | string | Required | Transaction category (food, travel, shopping, fuel, etc.) |
transactions[].merchant | string | Optional | Merchant name for merchant-specific rewards |
transactions[].timestamp | string (ISO 8601) | Required | Transaction timestamp |
user_cards | array | Optional | Cards the user already owns (to avoid duplicates) |
preferences | object | Optional | User preferences to influence ranking |
preferences.prioritize_cashback | boolean | Optional | Prioritize cashback cards in recommendations |
preferences.prioritize_travel | boolean | Optional | Prioritize travel cards in recommendations |
preferences.prioritize_lounge | boolean | Optional | Prioritize cards with lounge access |
preferences.max_annual_fee | number | Optional | Maximum acceptable annual fee |
options | object | Optional | Request options |
options.limit | number | Optional | Maximum number of recommendations (default: 5, max: 20) |
options.include_explanations | boolean | Optional | Include 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
| Code | HTTP Status | Description |
|---|---|---|
INVALID_REQUEST | 400 | Request body validation failed |
UNAUTHORIZED | 401 | Invalid or missing API key |
RATE_LIMITED | 429 | Rate limit exceeded |
INSUFFICIENT_CREDITS | 402 | Not enough credits for this request |