Do I need to connect a bank account to use enrichment?

Not for categorize, subscriptions, fraud-risk, or purchase-analysis: each accepts a transactions array instead of an access token, so you can send data you aggregated anywhere. Merchant intelligence only ever takes a query string. The products that read balances and long history — cash-flow forecasting, health score, financial summary, weekly report — need a connected item because the payload does not carry what they need.

What does the engine field mean?

It reports how the response was produced. rules means the deterministic engines alone; ai means schema-validated model output drove the answer; ai+rules means the deterministic layer produced the base result and the model enriched it. When a model was involved the response also carries its name. If the model layer is unreachable, endpoints degrade to rules rather than failing.

How deterministic is the rules layer?

526 ordered descriptor rules run first, most specific first: transaction-type descriptors such as payroll, interest, and card payments outrank merchant names, then known brands, then lower-confidence keyword fallbacks. Every result is normalized onto the 14-category taxonomy before it is returned, so the same descriptor always produces the same category with the same confidence.

How are recurring streams detected?

Transactions are grouped by merchant and direction, and a group is kept only when its intervals cluster within twenty percent of their median. That median maps to a cadence: weekly, biweekly, monthly, quarterly, or annual. A stream is flagged as a subscription when it is a steady-amount, roughly monthly charge in the subscription or entertainment categories. Detection runs over whatever transactions the connector returned, which is why it works on every connector rather than a privileged few.

How is enrichment billed?

Each /v1/ai/* call counts once against the API request meter and once against the AI request meter. A rules-only response is metered identically — the quota counts requests, not model tokens. The Free plan includes 1,000 AI requests a month, Startup 50,000, and Growth 500,000. /v1/recurring/get and /v1/categories/get are ordinary data endpoints and do not touch the AI meter.

What are the payload limits?

A transactions array carries up to 1,000 entries per call. Each entry needs an id, a description, and an amount; merchant, date, category, account_id, and datetime are optional and improve the result when present. Bodies are validated before anything runs, so a malformed entry returns invalid_request with the offending field named.

Transaction enrichment API

endpoints

What enrichment covers.

Four AI endpoints accept a raw payload; two ordinary data endpoints serve detected streams and the taxonomy itself.

POST/v1/ai/categorizeMap transactions onto the platform taxonomy with a confidence score each. Accepts a raw payload.
POST/v1/ai/merchantResolve one raw descriptor into a clean merchant name, category, and website. Takes only a query.
POST/v1/ai/subscriptionsFind paid subscriptions, price them annually, and flag the ones that look unused. Accepts a raw payload.
POST/v1/ai/fraud-riskScore transactions for duplicates, unfamiliar merchants, and out-of-pattern amounts. Accepts a raw payload.
POST/v1/recurring/getDetected recurring streams for a connected item: cadence, direction, average amount, next expected date.
POST/v1/categories/getThe full taxonomy — the exact strings every other surface uses.

requests

Send transactions, get labels back.

This request needs no connected account, no Link flow, and no item — just a key.

# No access_token: enrich transactions from any source.
curl https://connect.feels.money/v1/ai/categorize \
  -H "Authorization: Bearer $FEELCONNECT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactions": [
      { "id": "t1", "description": "SQ *BLUE BOTTLE COFFEE OAK", "amount": 6.75 },
      { "id": "t2", "description": "COMCAST CABLE COMM", "amount": 89.99 }
    ]
  }'

rules first

Deterministic by default, model-enhanced when useful.

The ordering matters more than the model: a categorizer that answers differently on Tuesday is not a categorizer.

526 ordered descriptor rules run first and first match wins. Transaction-type descriptors — payroll, interest charges, ATM fees, card payments, transfers — deliberately outrank merchant names, because PAYMENT TO VISA is a transfer no matter whose brand is in the string.
Every answer is normalized onto the taxonomy before it leaves, so a model that invents a category cannot leak one into your database.
The model is an enhancement, not a dependency. When it is unreachable the endpoints answer from rules alone and say so in engine. Nothing queues, nothing polls, and the request still returns in one round trip.
Recurring detection is not an AI call at all. Streams are computed on ingest from the transactions the connector returned, so /v1/recurring/get is a plain read against your normal request quota.

engine	What produced the response
rules	Deterministic engines only. Always available, always the same answer.
ai	Schema-validated model output drove the response.
ai+rules	Rules produced the base result and the model enriched it — narratives, edge cases, unfamiliar descriptors.

taxonomy

14 primary categories, 89 subcategories.

One vocabulary across the sandbox engine, the enrichment endpoints, stored transactions, and the dashboards. Fetch it at /v1/categories/get and store it beside your data.

Income
Salary · Freelance · Interest · Dividends · Refund · Bonus · Other Income
Transfer
Internal Transfer · External Transfer · Savings Transfer · Investment Contribution · Credit Card Payment · Loan Payment · Cash Withdrawal · Cash Deposit
Food & Drink
Restaurants · Fast Food · Coffee Shops · Bars & Nightlife · Delivery · Bakeries & Desserts
Groceries
Supermarket · Convenience Store · Specialty Foods · Warehouse Club · Farmers Market
Shopping
Clothing & Apparel · Electronics · Home Goods · Online Marketplace · Beauty & Personal Care · Books & Hobbies · Pets · Gifts
Entertainment
Streaming · Movies & Events · Music · Games · Concerts & Shows · News & Magazines
Travel
Flights · Hotels & Lodging · Car Rental · Vacation Packages · Travel Insurance
Transport
Rideshare · Public Transit · Fuel · Parking · Tolls · Auto Maintenance · Auto Payment
Housing
Rent · Mortgage · Home Insurance · Property Tax · Home Improvement · Furniture · HOA Fees
Utilities
Electricity · Water & Sewer · Gas · Internet · Mobile Phone · Trash & Recycling
Subscriptions
Software & SaaS · Cloud Storage · Memberships · Meal Kits · Box Subscriptions · Education & Courses
Health & Fitness
Gym & Fitness · Pharmacy · Doctor & Dental · Vision · Mental Health · Sports & Outdoors
Fees
Bank Fees · ATM Fees · Late Fees · Interest Charges · Foreign Transaction Fees · Service Charges
Other
Uncategorized · Charity & Donations · Education · Childcare · Taxes · Legal & Professional

recurring

How a stream is decided.

The detector is a pure function over transactions, so you can reason about why something was or was not called recurring.

Groups are formed per merchant and direction, then kept only when their intervals cluster within twenty percent of the median. Anything that does not fall in a band is not a stream.
Median interval between charges	Cadence assigned
5 to 9.5 days	`weekly`
11 to 20 days	`biweekly`
24 to 38 days	`monthly`
75 to 120 days	`quarterly`
300 to 430 days	`annual`

Each stream carries a merchant name, category, cadence, average and last amount, last and next expected date, a direction of outflow or inflow, and a status of active, paused, or ended. Inflow streams are how payroll shows up. The full shape is in the recurring reference.

faq

Questions developers actually ask.

keep reading

Descriptors in, merchants and categories out.