examples/README.md

# RevAI — POST request examples

All POST endpoints require header `Content-Type: application/json` (except
`/v1/analyze/call*`, which is multipart). Gateway also injects auth headers.

## /v1/predict/churn  (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}]}

## /v1/predict/lead  (JSON)
{"data":[{"lead_id":"L1","demo_requested":1,"budget_confirmed":1,"engagement_score":80,"source":"referral"}]}

## /v1/train  (JSON, >=50 rows)  -> see train_body.json
{"data":[ ...>=50 rows, each with feature cols + a 0/1 label col... ],
 "target_column":"churned","model_type":"churn","model_name":"my-model"}

## /v1/analyze/call  (multipart/form-data, NOT json)
Fields:
  file           = <audio file: .mp3 .wav .m4a .mp4 .ogg .webm>
  openai_api_key = sk-...   (caller supplies their own OpenAI key for Whisper)
curl example:
  curl -X POST https://revai1.p.rapidapi.com/v1/analyze/call \
    -H "X-RapidAPI-Host: revai1.p.rapidapi.com" \
    -H "X-RapidAPI-Key: <KEY>" \
    -F "file=@call.mp3" \
    -F "openai_api_key=sk-..."

## /v1/predict/csv  (multipart — upload a spreadsheet, no JSON needed)
The friction-killer. One column per signal, one row per customer/lead.
Fields:
  file       = your .csv export  (see sample_customers.csv)
  model_type = churn | lead       (default churn)
  model_id   = <optional trained model id>
curl:
  curl -X POST https://revai1.p.rapidapi.com/v1/predict/csv \
    -H "X-RapidAPI-Host: revai1.p.rapidapi.com" -H "X-RapidAPI-Key: <KEY>" \
    -F "file=@customers.csv" -F "model_type=churn"
Blank cells are fine (we use sensible defaults). Returns the same scored
JSON as /v1/predict/churn — score, risk level, and the reasons.

NOTE: RapidAPI's gateway only forwards endpoints you've DEFINED in the API.
Add /v1/predict/csv to the RapidAPI endpoint list or the gateway returns 404.

## /v1/connect/stripe  (JSON — paste a read-only Stripe key, auto-score customers)
No data prep at all. We pull the caller's recent Stripe customers and derive
churn signals from billing: tenure, payment delays (90d), subscription status
(past_due / canceled fire strong rules), contract type, monthly spend.
The key is used in-memory and NEVER stored. RevAI pays Stripe nothing.
Body:
  {"stripe_key":"rk_live_...", "limit":100, "model_type":"churn", "model_id":null}
curl:
  curl -X POST https://revai1.p.rapidapi.com/v1/connect/stripe \
    -H "X-RapidAPI-Host: revai1.p.rapidapi.com" -H "X-RapidAPI-Key: <KEY>" \
    -H "Content-Type: application/json" \
    -d '{"stripe_key":"rk_live_...","limit":100}'
Tell customers to use a RESTRICTED key (read-only: Customers, Invoices,
Subscriptions). Returns the same scored JSON as /v1/predict/churn.

NOTE: like every endpoint, add /v1/connect/stripe to your RapidAPI endpoint
list or the gateway returns 404.

## /v1/predict/smart  (JSON — UNIVERSAL connector, send ANY column names)
The real friction-killer. You don't need our exact field names. Send your rows
as-is; we auto-detect columns (last_seen -> days_since_last_login, signup_date
-> tenure_days, plan -> contract_type, ...) and even derive durations from
dates. Response includes a `field_mapping` report (matched / missing / ignored)
so it's fully transparent.
Body:
  {"data":[{"account_id":"ACME","signup_date":"2024-01-10","last_seen":"2026-05-10",
            "plan":"Monthly","missed_payments":3,"nps":2}],
   "model_type":"churn",
   "mapping": {"tenure_days":"signup_date"}   // OPTIONAL explicit overrides
  }
Auto-derives: signup/created dates -> tenure_days; last-login dates ->
days_since_last_login; pipeline-entry dates -> days_in_pipeline.
This is the recommended entry point for most customers — it makes Stripe/CSV/
HubSpot/raw exports all "just work".