API Reference

Base URL

https://api.churnpredict.io/v1

All endpoints require Bearer token authentication.

Get churn probability for a single customer.

Request Body

{
  "customer_id": "CUST-12345",
  "tenure": 12,
  "monthly_charges": 79.50,
  "total_charges": 954.00,
  "contract_type": "month-to-month",
  "payment_method": "electronic_check",
  "internet_service": "fiber_optic",
  "online_security": false,
  "tech_support": false,
  "streaming_tv": true,
  "streaming_movies": true,
  "support_tickets": 3
}

Response

{
  "customer_id": "CUST-12345",
  "churn_probability": 0.73,
  "risk_level": "high",
  "confidence_interval": [0.68, 0.78],
  "model_version": "xgboost-v2.3.1",
  "top_risk_factors": [
    {"feature": "contract_type", "impact": 0.28, "direction": "increases_risk"},
    {"feature": "tenure", "impact": 0.18, "direction": "increases_risk"},
    {"feature": "support_tickets", "impact": 0.12, "direction": "increases_risk"}
  ],
  "recommended_actions": [
    "offer_annual_contract_discount",
    "priority_support_escalation"
  ]
}

Score multiple customers in a single request (max 1000).

Request Body

{
  "customers": [
    {"customer_id": "CUST-001", "tenure": 12, ...},
    {"customer_id": "CUST-002", "tenure": 36, ...}
  ],
  "include_explanations": true
}

Get detailed SHAP explanation for a prediction.

Response

{
  "customer_id": "CUST-12345",
  "base_value": 0.265,
  "output_value": 0.73,
  "shap_values": {
    "contract_type": 0.28,
    "tenure": 0.18,
    "support_tickets": 0.12,
    "monthly_charges": 0.05,
    "payment_method": 0.03,
    "internet_service": -0.02,
    "online_security": -0.04
  },
  "feature_values": {
    "contract_type": "month-to-month",
    "tenure": 12,
    "support_tickets": 3
  }
}

Get cohort-level churn statistics.

Query Parameters

Parameter	Type	Description
dimension	string	Cohort dimension (contract, tenure, payment)
start_date	date	Analysis start date (YYYY-MM-DD)
end_date	date	Analysis end date (YYYY-MM-DD)

Get current model metadata and performance metrics.

Response

{
  "model_id": "xgboost-v2.3.1",
  "trained_at": "2024-01-15T08:30:00Z",
  "training_samples": 50432,
  "features_count": 21,
  "metrics": {
    "auc_roc": 0.89,
    "accuracy": 0.942,
    "precision": 0.873,
    "recall": 0.796,
    "f1_score": 0.833
  },
  "hyperparameters": {
    "n_estimators": 247,
    "max_depth": 7,
    "learning_rate": 0.08,
    "scale_pos_weight": 4
  }
}