Back to Home

PredictivS API Integration Guide

Integrate Customer Churn Prediction API into Your Project

🚀 Quick Start

PredictivS API is a REST-based service that accepts and returns data in JSON format. To use the API, you first need to create an account and obtain an API token.

1. Create an Account

First, register and activate your account.

2. Get API Token

Log in and create a new token from Dashboard > API Tokens section.

# Store your token securely
export PREDICTIVS_API_TOKEN="your_api_token_here"

🔐 Authentication

All API requests are authenticated with Bearer token. You must send your token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Python Example

import requests

API_URL = "https://api.predictivs.com"  # Production URL
TOKEN = "your_api_token_here"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

response = requests.get(f"{API_URL}/health", headers=headers)
print(response.json())

JavaScript Example

const API_URL = "https://api.predictivs.com";
const TOKEN = "your_api_token_here";

const headers = {
    "Authorization": `Bearer ${TOKEN}`,
    "Content-Type": "application/json"
};

fetch(`${API_URL}/health`, { headers })
    .then(response => response.json())
    .then(data => console.log(data));

📱 Telecom Churn Prediction API

POST /telco/predict

Predict churn for telecom customers

Request Parameters

Parameter Type Required Description
customer_id string YES Unique customer identifier
gender string YES Gender (Male, Female)
senior_citizen integer YES Is senior citizen? (0: No, 1: Yes)
partner string YES Has partner? (Yes, No)
dependents string YES Has dependents? (Yes, No)
tenure integer YES Customer tenure (months)
phone_service string YES Phone service (Yes, No)
multiple_lines string YES Multiple lines (Yes, No, No phone service)
internet_service string YES Internet service (DSL, Fiber optic, No)
online_security string YES Online security (Yes, No, No internet service)
online_backup string YES Online backup (Yes, No, No internet service)
device_protection string YES Device protection (Yes, No, No internet service)
tech_support string YES Tech support (Yes, No, No internet service)
streaming_tv string YES Streaming TV (Yes, No, No internet service)
streaming_movies string YES Streaming movies (Yes, No, No internet service)
contract string YES Contract type (Month-to-month, One year, Two year)
paperless_billing string YES Paperless billing (Yes, No)
payment_method string YES Payment method (Electronic check, Mailed check, Bank transfer, Credit card)
monthly_charges float YES Monthly charges
total_charges float YES Total charges

Request Example

import requests

url = "https://api.predictivs.com/telco/predict"
headers = {
    "Authorization": "Bearer your_api_token_here",
    "Content-Type": "application/json"
}

data = {
    "customer_id": "7590-VHVEG",
    "gender": "Female",
    "senior_citizen": 0,
    "partner": "Yes",
    "dependents": "No",
    "tenure": 34,
    "phone_service": "Yes",
    "multiple_lines": "No",
    "internet_service": "DSL",
    "online_security": "No",
    "online_backup": "Yes",
    "device_protection": "No",
    "tech_support": "No",
    "streaming_tv": "No",
    "streaming_movies": "No",
    "contract": "Month-to-month",
    "paperless_billing": "Yes",
    "payment_method": "Electronic check",
    "monthly_charges": 65.6,
    "total_charges": 1889.5
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)

Response Example

{
    "customer_id": "7590-VHVEG",
    "churn_prediction": "No",
    "churn_probability": 0.23,
    "confidence": "High",
    "risk_level": "Low",
    "recommendation": "Customer is low risk. Maintain current services.",
    "timestamp": "2025-01-10T12:34:56.789Z"
}

🏦 Banking Churn Prediction API

POST /banking/predict

Predict churn for banking customers

Request Parameters

Parameter Type Required Description
customer_id string YES Unique customer identifier
credit_score integer YES Credit score (300-850)
geography string YES Geographic location (France, Spain, Germany, etc.)
gender string YES Gender (Male, Female)
age integer YES Age
tenure integer YES Years with bank
balance float YES Account balance
num_of_products integer YES Number of products (1-4)
has_cr_card integer YES Has credit card? (0: No, 1: Yes)
is_active_member integer YES Is active member? (0: No, 1: Yes)
estimated_salary float YES Estimated salary

Request Example

import requests

url = "https://api.predictivs.com/banking/predict"
headers = {
    "Authorization": "Bearer your_api_token_here",
    "Content-Type": "application/json"
}

data = {
    "customer_id": "15634602",
    "credit_score": 619,
    "geography": "France",
    "gender": "Female",
    "age": 42,
    "tenure": 2,
    "balance": 0.0,
    "num_of_products": 1,
    "has_cr_card": 1,
    "is_active_member": 1,
    "estimated_salary": 101348.88
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)

Response Example

{
    "customer_id": "15634602",
    "churn_prediction": "No",
    "churn_probability": 0.15,
    "confidence": "High",
    "risk_level": "Low",
    "recommendation": "Customer is loyal. Evaluate cross-sell opportunities.",
    "timestamp": "2025-01-10T12:34:56.789Z"
}

⚠️ Error Handling

HTTP Status Codes

Code Meaning Description
200 OK Request successful
400 Bad Request Invalid parameters
401 Unauthorized Invalid or missing token
403 Forbidden Unauthorized access or license issue
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error

Error Response Example

{
    "error": "Invalid token",
    "detail": "The provided API token is invalid or expired",
    "status_code": 401
}

📊 Rate Limits

Your API usage is limited based on your license type:

License Type Requests Per Minute Monthly Prediction Limit
Trial 10 100
Starter 60 5,000
Professional 300 50,000
Enterprise Unlimited Unlimited

✅ Best Practices

  • 🔒 Never store API tokens in source code, use environment variables
  • ⚡ Send requests in batches to avoid exceeding rate limits
  • 🔄 Implement exponential backoff for error situations
  • 📝 Log all requests and responses
  • 🎯 Use HTTPS in production environments
  • 💾 Cache responses to reduce API calls
  • 🔔 Use webhooks for rate limit notifications

💬 Support

For questions: