The CLV API provides on-demand and batch computation of Customer Lifetime Value scores based on RFM (Recency, Frequency, Monetary) analysis of interaction summaries.
See the CLV feature page for business context, scoring methodology, and segment definitions. Base Path
/api/v1/customers/{customerId}/clv # Single customer
/api/v1/clv/compute # Batch compute
GET /api/v1/customers//clv
Returns the cached CLV record for a customer. If no cached record exists, computes CLV on-demand and caches the result.
Roles: admin, editor, viewer
Path Parameters
| Parameter | Type | Description |
|---|
customerId | string | Customer identifier |
Response 200
{
"customerId": "CUST-001",
"clvScore": 72,
"predictedRevenue": 1440.00,
"churnProbability": 0.119,
"rfmRecency": 5,
"rfmFrequency": 48,
"rfmMonetary": 360.00,
"segment": "high",
"computedAt": "2026-04-03T10:30:00.000Z",
"source": "cached"
}
Response Fields
| Field | Type | Description |
|---|
clvScore | integer | Composite CLV score (0-100) |
predictedRevenue | number | Projected revenue over 24-month lifespan |
churnProbability | number | Probability of churn (0.0-1.0) based on recency |
rfmRecency | integer | Days since last interaction |
rfmFrequency | integer | Total number of interactions (impressions) |
rfmMonetary | number | Total conversion value |
segment | string | Customer segment: high, medium, low, or at_risk |
computedAt | string | ISO 8601 timestamp of when the CLV was computed |
source | string | cached if returned from storage, computed if calculated on-demand |
Example
curl https://playground.kaireonai.com/api/v1/customers/CUST-001/clv \
-H "X-Tenant-Id: my-tenant" \
-H "Authorization: Bearer <token>"
POST /api/v1/customers//clv
Force recompute CLV for a specific customer. Always recalculates from current interaction summaries, ignoring any cached value.
Roles: admin, editor
Path Parameters
| Parameter | Type | Description |
|---|
customerId | string | Customer identifier |
Response 200
{
"customerId": "CUST-001",
"clvScore": 74,
"predictedRevenue": 1520.00,
"churnProbability": 0.119,
"rfmRecency": 5,
"rfmFrequency": 50,
"rfmMonetary": 380.00,
"segment": "high",
"computedAt": "2026-04-03T11:00:00.000Z",
"source": "recomputed"
}
Example
curl -X POST https://playground.kaireonai.com/api/v1/customers/CUST-001/clv \
-H "X-Tenant-Id: my-tenant" \
-H "Authorization: Bearer <token>"
POST /api/v1/clv/compute
Batch compute CLV for all customers in the tenant, or filtered to a specific segment. Processes customers in batches of 50 with parallel execution.
Roles: admin
Request Body
| Field | Type | Required | Description |
|---|
segment | string | No | Filter to recompute only customers in this segment. One of: high, medium, low, at_risk. Omit to recompute all. |
When a segment filter is provided, the batch includes customers currently in that segment plus any new customers without a CLV record. This ensures new customers are always scored.
Response 200
{
"success": true,
"computed": 342,
"errors": 0,
"segment": "all"
}
Response Fields
| Field | Type | Description |
|---|
success | boolean | Whether the batch completed |
computed | integer | Number of customers successfully computed |
errors | integer | Number of customers that failed computation |
segment | string | The segment filter used, or all |
Example
# Recompute all customers
curl -X POST https://playground.kaireonai.com/api/v1/clv/compute \
-H "X-Tenant-Id: my-tenant" \
-H "Content-Type: application/json"
# Recompute only at-risk customers
curl -X POST https://playground.kaireonai.com/api/v1/clv/compute \
-H "X-Tenant-Id: my-tenant" \
-H "Content-Type: application/json" \
-d '{ "segment": "at_risk" }'
Error Codes
| Status | Code | Description |
|---|
400 | Bad Request | Invalid segment value. Must be high, medium, low, or at_risk |
401 | Unauthorized | Missing or invalid authentication |
403 | Forbidden | Insufficient role for this operation |
500 | Server Error | Internal error during CLV computation |
See Also
