In this section: Cards
Cards
Search the card catalog and get a card, comparison, or offer recommendation grounded in a member's own wallet.
get_best_card
Best card in the user's wallet for a spending category (dining, groceries, gas, travel, rent, ...) or a specific merchant -- pass at least one of category or merchant (a listed id; an unlisted business is merchant_label beside a category); amount (dollars) is optional.
| Scope | Quota |
|---|---|
miles:read | standard |
| Name | Type | Required | Description |
|---|---|---|---|
category | string | The one key that names what is being bought. Use other when no more specific key fits; registered merchant earning can still apply. | |
merchant | string | Use the listed merchant id, including a separate web-store or property id when shown (Grand Hyatt stay: hyatt; Costco gas: costco); other is for nonresidential premises or storage and still allows registered-merchant bonuses; residential payments use rent plus housing; null means the brand is not listed. | |
merchant_label | string | The business name as the person said it, only when merchant is null and the person named a business. Omit otherwise. | |
amount | number | Purchase amount in dollars; can change which card wins. Set only when stated; non-positive is absent. | |
international | boolean | Set to true when the purchase happens OUTSIDE the United States: the user names a foreign city or country ('in Tokyo', 'in Europe'), says abroad/overseas, or is on an international trip. Ranks by net return after foreign transaction fees and drops U.S.-only earning categories (Business Gold's 4X is 'U.S. purchases at restaurants' and earns nothing extra in Tokyo). Default false. Leave it off for domestic spending. | |
cards | string[] | Cards the user says they hold; ones the saved wallet lacks are ranked as held (stated_cards). | |
channel | string | How the purchase is made, when the person says so: online for a website or online order, in_app for a merchant's own app, mobile_wallet for Apple Pay or Google Pay, physical_card for the physical card, direct for booked directly with the airline or hotel. Omit otherwise. | |
portal | string | The booking portal the purchase goes through, when the person names one. Omit otherwise. | |
housing | string | With category rent: mortgage for a mortgage payment, rent for rent. Omit otherwise. | |
merchant_role | string | provider sells the category itself (restaurant, airline, hotel); reseller resells travel or experiences (day passes, tours); payment_platform is a payment app. Omit if unsure. | |
paid_through | string | Third-party payment platform named by the person. Keep the seller in merchant and name the payment platform here. Omit otherwise. | |
redemption_basis | string | The member's own stated way of redeeming, for this conversation. Omit unless the member said how they redeem. | |
categories | string[] | Every category key when one purchase spans several ('groceries and gas'), primary first. Omit for one. | |
purchase_kind | string | A trade no category names, when stated. Omit otherwise. | |
merchant_kinds | string[] | The venue, only when stated: a bar, nightclub, cafeteria, caterer, brewery or bakery, or a restaurant inside a hotel, casino or resort. A sushi bar, bar and grill or bakery-cafe is restaurant; a hotel brand alone is no venue. | |
time_windows | string[] | citi_nights when the person names Citi Nights or a Friday or Saturday night; never the current time. Omit otherwise. | |
stated_spend | object | Monthly USD amounts explicitly stated for the caller alone; omit another member or combined household spend. |
get_card_info
Full details for a credit card PRODUCT: fees, earning rates, credits, benefits, transfer partners, sign-up bonus.
| Scope | Quota |
|---|---|
miles:read | standard |
| Name | Type | Required | Description |
|---|---|---|---|
card_name | string | Catalog product name, fuzzy-matched ("Amex Plat" resolves). Send this or wallet_id, not both; wallet_id wins when both arrive. | |
wallet_id | string | A cc_N wallet entry id from get_wallet_cards; resolves to the product that entry holds. Takes only the cc_N shape: a product name here is refused, and an id with no entry is refused rather than fuzzy-matched. | |
as_of | string | Dataset date YYYY-MM-DD, today or later; null means today. A future date returns value, today, upcoming; today: current. | |
period | object | Dataset period [starts_on, ends_before); omit as_of. |
get_product_changes
Upgrade and downgrade paths for a wallet card -- the natural next question after analyze_keep_cancel. Wallet-aware: results reflect which products you already hold.
| Scope | Quota |
|---|---|
miles:read | standard |
| Name | Type | Required | Description |
|---|---|---|---|
card_name | string | required | Name of a card in the user's wallet to list upgrade and downgrade paths for. |
get_top_offers
Current top sign-up bonuses, optionally filtered by card type (personal/business), ranked by Miles's first-year value.
| Scope | Quota |
|---|---|
miles:read | standard |
| Name | Type | Required | Description |
|---|---|---|---|
card_type | string | Filter to "personal" or "business" cards; omit for both. | |
member | string | On a Household Profiles account, the household member to rank offers for; omit to keep any offer some member can apply for. A household member's name; a name matching no member is refused, not guessed. | |
annual_fee_max | number | Maximum recorded annual fee in dollars; 0 means no-fee offers only. Offers with unknown fees are excluded. | |
recent_denial_reason | string | A recent card denial the person states, by reason; every issuer then reads may_be_restricted, never open. | |
hard_inquiries_6m | integer | Hard inquiries in the last 6 months, when stated; read by issuer inquiry limits. | |
as_of | string | Dataset date YYYY-MM-DD, today or later; null means today. A future date returns value, today, upcoming; today: current. |
get_wallet_complement
Recommends NEW cards to get -- fills gaps in the wallet, not a keep/cancel review of cards already held. Finds orphaned points needing a companion card, weak spending categories, missing transfer ecosystems, and network gaps, then ranks up to 5 candidate cards with gap-fill reasons, ongoing value, and sign-up bonus. Each recommendation carries inline eligibility annotations (5/24, 6/24, Amex velocity limits) and portfolio rules (e.g. one Sapphire product at a time); results are filtered to the wallet's card type (personal/business) automatically.
| Scope | Quota |
|---|---|
miles:read | standard |
| Name | Type | Required | Description |
|---|---|---|---|
focus | string | "earning" narrows to category-multiplier gaps, "ecosystem" to new transfer-partner access; omit for a comprehensive analysis. | |
card_name | string | Find complements for one specific wallet card instead of the whole wallet. | |
check_eligibility | boolean | When true, drop cards the user cannot currently apply for instead of just annotating them. Already on by default whenever the wallet is non-empty. | |
member | string | On a Household Profiles account, the household member whose eligibility judges each candidate; omit to keep any candidate some member can apply for. A household member's name; a name matching no member is refused, not guessed. | |
preferred_programs | string[] | Loyalty programs the user has explicitly named as preferences, any spelling. A card that earns one, or transfers to one, is nudged up the ranking and says so in its gap-fill reasons: a tie-breaker, not a filter. Never infer these from the wallet; unrecognized names come back in preferred_programs_unmatched. | |
recent_denial_reason | string | A recent card denial the person states, by reason; every issuer then reads may_be_restricted, never open. | |
hard_inquiries_6m | integer | Hard inquiries in the last 6 months, when stated; read by issuer inquiry limits. |
search_cards
Search the 180+ card dataset by issuer, fees, rewards program, airline/hotel affiliation, or bonus spending categories.
| Scope | Quota |
|---|---|
miles:read | standard |
| Name | Type | Required | Description |
|---|---|---|---|
spending_categories | string[] | Bonus spending categories the card should earn well in, as a list of category names (e.g. ["dining", "groceries"]), not one comma-joined string. | |
issuer | string | Limit results to one issuer (e.g. "Chase", "Amex"). | |
card_type | string | Limit results to "Personal" or "Business" cards. | |
max_annual_fee | integer | Highest annual fee to include, in whole dollars; 0 means no-annual-fee cards only. | |
rewards_program | string | Limit results to cards earning one rewards program or currency (e.g. "Chase Ultimate Rewards"). Applied after the search, so the response notes when fewer than limit cards matched. | |
airline | string | Limit results to cards affiliated with one airline (e.g. "United"). | |
hotel | string | Limit results to cards affiliated with one hotel program (e.g. "Hyatt"). | |
has_signup_bonus | boolean | When true, keep only cards currently offering a sign-up bonus. | |
limit | integer | Maximum number of cards to return. Default 10. | |
member | string | On a Household Profiles account, the household member whose application eligibility filters the result; omit to keep any card some member can apply for. A household member's name; a name matching no member is refused, not guessed. | |
is_student | boolean | True only when the user said they are a student. Student cards are hidden otherwise. |