Sales, Marketing & Ad Tech
Customer Segmentation API
Your customers have segments in a slide deck and segments in their database, and the two have never been the same thing.
- CDP and marketing platforms
- E-commerce software
- Subscription businesses
- Retail analytics vendors
What your customers would see
example interfaceMockupIllustrative mockup of the interface we would build. Figures shown are examples, not results from a live deployment.
The problem this solves
Segmentation in most companies was defined once, by a workshop, and encoded as SQL filters nobody revisits. New customers are assigned to segments that described the base three years ago. The propensity scores sitting next to them came from a model whose author has left. The marketing team knows the segments are stale, works around them with ad-hoc queries, and the formal segmentation persists as a reporting artefact.
Behavioural segmentation computed from actual data is a well-worn problem with a few real difficulties. Clusters are unstable across runs unless the method accounts for it, which erodes trust the first time a customer moves segment for no visible reason. Segments that are statistically clean are frequently useless operationally — nobody can run a campaign for 'cluster 4'. And segment membership drifts as the base changes, so a definition fixed at launch slowly stops describing anyone.
There is also a line worth naming. Segmentation on observed behaviour — what someone bought, how often they return, which categories they browse — is ordinary commercial analytics. Segmentation that infers sensitive characteristics, or that uses proxies to reach them indirectly, is a different thing legally and ethically. The difference is not always obvious in a feature list, which is why it belongs in the design rather than in a policy document nobody reads.
Who buys this
CDP and marketing platforms, E-commerce software, Subscription businesses, Retail analytics vendors
What the API returns
What comes back
- Behavioural segments with stable identifiers and human-readable definitions
- Segment membership per customer with the attributes that placed them there
- Propensity scores for churn, repeat purchase and category expansion, each calibrated
- Value-based segmentation including predicted lifetime value with intervals
- Segment drift reporting, so a definition that no longer describes the base is visible
- Transition analysis: which segments customers move between and when
- Minimum cohort enforcement, so no segment is small enough to identify individuals
- Excluded-attribute documentation listing what the models may not use and why
Endpoints
| Method | Path | Returns |
|---|---|---|
| POST | /v1/segments/compute | Recompute segmentation across the customer base |
| GET | /v1/customers/{id}/segments | Segment membership with contributing attributes |
| GET | /v1/segments | Segment definitions, sizes and drift status |
| POST | /v1/propensity/score | Churn, repeat purchase and expansion propensities |
| GET | /v1/segments/{id}/transitions | Movement into and out of a segment |
| GET | /v1/governance/excluded-attributes | Attributes excluded from modelling, with reasons |
Request and response
illustrativeRequest
{
"dataset": "customers_active",
"features": ["purchase_recency", "frequency", "basket_composition",
"browse_category_mix", "channel_mix", "tenure"],
"n_segments": "auto",
"min_segment_size": 500,
"include_propensity": ["churn_90d", "repeat_purchase_30d"]
}Response
{
"computed_at": "2026-10-22T02:10:00Z",
"customers_segmented": 1842104,
"stability_vs_prior_run": 0.94,
"segments": [
{
"segment_id": "seg_core_replenishers",
"label": "Frequent single-category replenishers",
"size": 284118,
"definition": "Purchases every 3-5 weeks, 80%+ of spend in one category, low discount sensitivity",
"mean_order_value": 42.10,
"churn_90d_mean": 0.09,
"drift_vs_definition": 0.03
},
{
"segment_id": "seg_discount_entrants",
"label": "Promotion-acquired, single purchase",
"size": 511402,
"definition": "Acquired on promotion, one order, no repeat within 90 days",
"churn_90d_mean": 0.71,
"drift_vs_definition": 0.11,
"warning": "Definition drifting; recompute or redefine"
}
],
"propensity_calibration": {
"churn_90d": { "brier": 0.118, "calibration_error_max_decile": 0.021 }
},
"governance": {
"excluded_attributes": ["inferred_health", "inferred_ethnicity", "precise_location",
"inferred_religion", "inferred_sexual_orientation"],
"min_cohort_enforced": 500,
"lawful_basis_recorded_per_feature": true
}
}Where the data comes from
| Your transaction history | Orders, returns, basket composition and channel — the backbone of any honest behavioural segmentation |
| Your product and category taxonomy | So basket composition features reflect how your business thinks about its catalogue |
| First-party behavioural events | Browse, search and session data from your own properties, under your own consent notices |
| Subscription and account lifecycle data | Signup, upgrade, downgrade and cancellation events, which carry most of the churn signal in subscription models |
| Consent and preference records | Which customers consented to what, because a feature's availability for modelling depends on it and that has to be enforced in code rather than assumed |
| Deliberately excluded data | Inferred health, ethnicity, religion and sexual orientation; precise location; and purchased third-party attributes whose consent chain you cannot verify |
The intelligence layer
The difference between a demo and a service is mostly in this section. These are the parts that keep the answer trustworthy once real traffic is hitting it.
- Clustering with stability constraints and consistent initialisation, because a customer moving segment between runs for no behavioural reason destroys trust immediately
- Segment count chosen by both statistical criteria and operational usability — a technically optimal fourteen-segment solution that no campaign team can use is a failed deliverable
- Human-readable definitions generated per segment and validated against the cluster, so segments can be explained to a marketing team rather than referred to by number
- Propensity models kept separate from segmentation, because mixing clustering and prediction produces segments that are neither interpretable nor accurate
- Calibration on propensity outputs with per-decile error reporting, since these feed threshold decisions about who gets contacted
- Drift measurement against the original definition, with an explicit warning when a segment no longer describes its members
- Minimum cohort sizes enforced at compute time, so small segments cannot be used to single out individuals
- A feature-level governance register recording the lawful basis and consent requirement for every input, checked at compute time rather than documented separately
What it changes for the business
Segments that match the data
Recomputed behavioural segments replace definitions that described the customer base several years ago.
Scores that support thresholds
Calibrated propensity outputs let a campaign team choose a contact cutoff on expected precision rather than instinct.
Drift made visible
Explicit drift reporting means a stale segmentation gets fixed instead of quietly misdirecting spend.
Defensible data practice
A feature-level lawful basis register and enforced cohort minimums survive a DPA negotiation and a privacy review.
How it fits into your product
How it embeds
- Deployed inside your own environment in most engagements, since this works on first-party customer data that should not leave it
- Scheduled recomputation with stable segment identifiers across runs
- Segment membership written back into your CDP, CRM or campaign tool rather than held in a separate system
- Synchronous propensity scoring for real-time personalisation decisions
- Multi-tenant design for platforms running segmentation for many customers, with strict per-tenant separation
- Governance outputs exportable for privacy reviews and data protection impact assessments
Included in every build
- Authentication, scoped API keys and per-customer rate limiting
- Input validation with predictable, documented error responses
- Versioned endpoints so your integration never breaks without notice
- Request and response logging for audit and dispute resolution
- Latency, error-rate and usage monitoring with alerting
- OpenAPI specification, sandbox environment and client examples
- Backups, failover design and a documented recovery procedure
- An agreed support arrangement once the service is live
How we would build it
about 12 weeksDiscovery and data review
Weeks 1–2
We agree the exact question the API answers, review the sources you already hold, check what has to be licensed, and write down the response contract your developers will code against.
Architecture and prototype
Weeks 3–4
You get a written architecture plus a working endpoint on real data — narrow, but genuinely callable — so integration can be tested against something concrete rather than a document.
Production build
Weeks 5–10
Pipelines, models, storage, authentication, rate limiting, logging, tests and documentation. Security and observability are part of this phase, not a later one.
Integration and handover
Weeks 11–12
We support your engineers through their integration, run load tests at your expected volume, and agree how the service is monitored and supported once it is live.
Commercial models
There is no fixed price list, because the cost is driven by data complexity, integration count, model requirements, request volume and the support level you need. Scope is agreed in writing before development starts.
Fixed-scope prototype
A defined slice of the service, built and priced as one piece of work. The usual first step when the business case needs proving internally.
Fixed-price build
An agreed scope against a written architecture, delivered for an agreed price. Best when the requirements are already clear.
Build then retainer
We build the service, then operate and improve it under a monthly agreement covering monitoring, updates and model maintenance.
White-label product
The service runs under your brand, your domain and your pricing, with MLPivot invisible to your customers.
Questions buyers ask
What personal data may actually be used here?
Behavioural data you collected first-party, under a lawful basis you can point to, for a purpose compatible with how it was collected. That covers transactions, browse behaviour and account lifecycle, and it is enough for good segmentation. What it does not cover is inferring special category data, buying third-party attributes whose consent chain you cannot verify, or repurposing data collected for fulfilment into profiling without a basis for it. We build a feature-level register of basis and consent requirement, and the compute step enforces it rather than trusting a policy document.
Can you infer sensitive characteristics to improve targeting?
No, and we would decline to. Inferring health, ethnicity, religion or sexual orientation is unlawful in most relevant jurisdictions without explicit consent that a retailer will not have, and it is a bad idea independently of the law. Proxy routes to the same inference are the same problem wearing a disguise — we exclude the obvious proxies and document what was excluded and why, because that register is what a privacy reviewer actually wants to see.
Will customers keep moving between segments?
Some will, because their behaviour changed, and that is the system working. What should not happen is membership churning because the clustering is unstable, so we constrain for stability and report a run-over-run stability figure. If stability is poor on your data we would say so and look at the feature set rather than shipping something that reassigns a tenth of the base each month.
How many segments should we have?
Fewer than the statistics suggest. The binding constraint is how many distinct treatments your marketing team can actually build and maintain, which is usually five to eight. We would push back on a request for twenty, because the extra granularity does not get used and the segments become harder to explain and less stable.
Does the data have to leave our environment?
No, and we would recommend against it. This is first-party customer data and the usual deployment runs the whole pipeline inside your infrastructure, with segment memberships written back into your own tools. Nothing needs to cross a boundary for this to work.
Related blueprints
Lead Scoring API
Calibrated conversion probabilities and prioritisation for leads and opportunities, trained on your own outcomes rather than a generic model.
Buying Intent Intelligence API
Account-level signals that a company may be researching a category, with each signal's strength and basis stated rather than blended into a score.
Company Enrichment API
Industry, size, locations, technology and firmographic attributes resolved from a domain or company name, with change detection.
Want this built for your platform?
Tell us what your product does today and what you want another system to be able to ask it. We will come back with an approach, a scope and a price.