examples/hub_listing_docs.md

# RevAI — Hub Listing copy (paste into RapidAPI description / endpoint docs)

> Explainable churn prediction & lead scoring. Send your customer data — by
> spreadsheet, raw JSON, or a one-click Stripe connect — and get a risk score
> **with the reasons behind it**, plus optional custom models trained on your
> own data.

## Quick start (most users): /v1/predict/smart
Send rows with **whatever column names you already have** — we auto-map them.
All POSTs require `Content-Type: application/json`.

```
POST /v1/predict/smart
Content-Type: application/json

{"data":[
  {"account_id":"ACME","signup_date":"2024-01-10","last_seen":"2026-05-10",
   "plan":"Monthly","missed_payments":3,"nps":2}
],"model_type":"churn"}
```
Returns each row scored (0–100), a risk level, the **reasons**, and a
`field_mapping` report showing which of your columns mapped to which signal.

## Upload a spreadsheet: /v1/predict/csv  (multipart)
```
POST /v1/predict/csv      (multipart/form-data)
file=@customers.csv  model_type=churn
```

## Connect Stripe: /v1/connect/stripe
Paste a **restricted, read-only** Stripe key; we derive churn signals from
billing (tenure, payment delays, subscription status). Key is never stored.
```
POST /v1/connect/stripe
Content-Type: application/json
{"stripe_key":"rk_live_...","limit":100,"model_type":"churn"}
```

## Classic (exact fields): /v1/predict/churn and /v1/predict/lead
```
POST /v1/predict/churn
Content-Type: application/json
{"data":[{"customer_id":"C1","tenure_days":45,"days_since_last_login":18,
  "login_frequency_7d":1,"payment_delays_90d":2,"support_tickets_last_30d":4,
  "contract_type":"Month-to-Month","nps_score":3,"feature_adoption_score":45,
  "avg_session_minutes":8}]}
```
```
POST /v1/predict/lead
Content-Type: application/json
{"data":[{"lead_id":"L1","demo_requested":1,"budget_confirmed":1,
  "engagement_score":80,"source":"referral"}]}
```

## Train a custom model: /v1/train  (≥50 labeled rows)
```
POST /v1/train
Content-Type: application/json
{"data":[ /* ≥50 rows, each with features + a 0/1 label */ ],
 "target_column":"churned","model_type":"churn","model_name":"my-model"}
```
Then pass the returned `model_id` to any predict endpoint to use your model.

## Analyze a support call: /v1/analyze/call  (multipart)
```
POST /v1/analyze/call   (multipart/form-data)
file=@call.mp3   openai_api_key=sk-...    # you supply your own OpenAI key
```

---
**Common mistake:** a POST with no body returns `422 Field required`. That's
expected — the API needs your data. Always send the JSON body (and the
`Content-Type: application/json` header).