Health Scores API Reference

Manage and monitor customer health scores through our API.

Overview

The Health Scores API allows you to update and retrieve customer health scores. Health scores are calculated based on multiple weighted factors that you can configure.

Score Range

Health scores range from 0.0 to 1.0, where 1.0 represents the healthiest state. Each factor score should also be between 0.0 and 1.0.

Update Customer Health Score

POST/api/customers/{customer_id}/health-score

Example Request

curl -X POST https://api.churnshield.ai/api/customers/cust_123/health-score \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "factors": {
      "usage": 0.8,
      "support": 0.9,
      "billing": 1.0
    }
  }'

Example Response

{
  "customer_id": "cust_123",
  "health_score": 0.85,
  "factors": {
    "usage": 0.8,
    "support": 0.9,
    "billing": 1.0
  },
  "updated_at": "2024-03-15T12:00:00Z"
}

Request Body

factors - Required. Object mapping factor names to scores (0.0 to 1.0).

Get Customer Health Score

GET/api/customers/{customer_id}/health-score

Example Request

curl https://api.churnshield.ai/api/customers/cust_123/health-score \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "customer_id": "cust_123",
  "health_score": 0.85,
  "factors": {
    "usage": 0.8,
    "support": 0.9,
    "billing": 1.0
  },
  "updated_at": "2024-03-15T12:00:00Z"
}

Configure Health Score Weights

PATCH/api/settings/health-score/weights

Example Request

curl -X PATCH https://api.churnshield.ai/api/settings/health-score/weights \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "weights": {
      "usage": 0.4,
      "support": 0.3,
      "billing": 0.3
    }
  }'

Example Response

{
  "weights": {
    "usage": 0.4,
    "support": 0.3,
    "billing": 0.3
  },
  "updated_at": "2024-03-15T12:00:00Z"
}

Request Body

weights - Required. Object mapping factor names to weights. Weights must sum to 1.0.