Qualification Rules

See also: Qualification Rules REST API reference for request/response shapes, status codes, and error semantics.

Overview

A Qualification Rule is a configurable check that decides whether a customer may receive a particular Offer. Rules are evaluated inside the Filter stage of a Decision Flow. They come in two stages:

Stage	Behavior
qualification	Hard gate — if the rule fails the Offer is dropped from the candidate set.
fit	Soft penalty — if the rule fails the Offer’s score is multiplied by a decay factor (0.1 — 1.0) instead of being removed.

Rules are sorted by priority (highest first) and evaluated in order. The first hard-gate failure short-circuits — remaining rules for that Offer are skipped.

Rule Types

Kaireon ships five rule types. Each type has its own config shape and runtime evaluation logic.

Stage: qualification (hard gate)Checks that the customer belongs to all of the segments listed in requiredSegments (AND logic). If the customer is missing any of the required segments, the Offer is dropped.Config JSON

{
  "requiredSegments": ["premium", "high_value"]
}

Runtime behavior

Read requiredSegments from config.
Compare against the customer’s segment list (auto-resolved from enriched customer.segment field, or provided in the Recommend request).
If the customer is in all of the required segments, the rule passes.
If the customer is missing any required segment, the rule fails with a reason like Missing required segments: high_value.
An empty requiredSegments array is treated as a pass (no restriction).

Stage: qualification (hard gate)Compares a single customer attribute against an expected value using one of ten operators.Config JSON

{
  "attribute": "customer.credit_score",
  "operator": "gte",
  "value": 720
}

Supported operators

Operator	Meaning	Example
`eq`	Equals	`state eq "CA"`
`neq`	Not equals	`status neq "closed"`
`gt`	Greater than	`income gt 50000`
`gte`	Greater or equal	`credit_score gte 720`
`lt`	Less than	`age lt 65`
`lte`	Less or equal	`debt_ratio lte 0.4`
`in`	Value in list	`tier in ["gold","platinum"]`
`not_in`	Value not in list	`region not_in ["restricted"]`
`exists`	Attribute is present and non-empty	`email exists`
`not_exists`	Attribute is missing or empty	`legacy_id not_exists`

Runtime behavior

Look up attribute in the customer context (enriched attributes from the Enrich stage, or request-time attributes).
If the attribute is missing and operator is not exists/not_exists, the rule passes (skips the rule). This prevents rules from blocking offers when enrichment data is not available (e.g., legacy recommend path without an Enrich stage).
For exists/not_exists, a missing attribute is valid input (not an error).
Apply the operator. If the comparison is false, the rule fails with a reason containing the actual vs expected values.

Stage: qualification or fitSupports two modes for threshold checks:Mode 1: Model-based — requires a named propensity model’s score to meet a minimum threshold.

{
  "propensityModel": "cc_propensity_v3",
  "minScore": 40
}

Mode 2: Attribute-based — checks an enriched customer attribute against a threshold using a comparison operator. Useful for data-driven gates like churn risk or credit score.

{
  "attribute": "customer.churn_risk",
  "operator": "lt",
  "threshold": 0.8
}

Supported operators for attribute mode: gte, gt, lte, lt.Runtime behavior — qualification stage (model-based)

Look up propensityModel in the customer’s propensityScores map.
If no score exists for the model, the rule fails (No propensity score for model "cc_propensity_v3").
If the score is below minScore, the rule fails.

Runtime behavior — qualification stage (attribute-based)

Look up attribute in the enriched customer context.
If the attribute is missing, the rule fails.
Apply the operator comparison against threshold. If false, the rule fails with actual vs expected values.

Runtime behavior — fit stage

If no score/attribute exists, the multiplier is 1.0 (no penalty).
If the threshold is met, the multiplier is 1.0.
If below the threshold, the multiplier is score / threshold (linear decay, minimum 0.1).

Stage: qualification or fitVerifies that a customer-attribute representing “days since last activity” is within an acceptable window.Config JSON

{
  "attribute": "days_since_last_login",
  "maxDays": 30
}

Runtime behavior — qualification stage

Read the named attribute from customer context.
If the attribute is missing, the rule passes (benefit of the doubt).
If the value exceeds maxDays, the rule fails.

Runtime behavior — fit stage

If the attribute is missing, the multiplier is 1.0.
If the value is within maxDays, the multiplier is 1.0.
If the value exceeds maxDays, the multiplier decays as maxDays / actualDays (minimum 0.1).

Stage: qualification (hard gate)Evaluates a Behavioral Metric value against a threshold. Use this to enforce business limits such as “no more than 10 impressions per month” or “at least 3 clicks before upgrade offer.”Config JSON

{
  "metricId": "monthly_impressions",
  "operator": "lte",
  "threshold": 10,
  "dimensionMapping": {
    "offerId": "$candidate.offerId"
  }
}

Supported operators: gt, gte, lt, lte, eqRuntime behavior

Build a lookup key from metricId + resolved dimensionMapping values. The special token $candidate.offerId is replaced with the current Offer’s ID.
Look up the metric value from the pre-loaded metric map. If no value is found, default to 0.
Apply the operator. If the condition triggers (evaluates to true), the rule fails and the Offer is dropped.

The operator semantics are inverted compared to attribute_condition: when the condition is met the Offer is disqualified. Think of it as defining the disqualification condition. For example, "operator": "gt", "threshold": 10 means “disqualify when impressions exceed 10.”

Stage: qualification (hard gate)Filters on offer-level fields (e.g., productType, margin, revenueValue, or custom fields defined in the offer’s metadata). This lets you write rules that target specific offer properties rather than customer attributes.Config JSON

{
  "attribute": "productType",
  "operator": "eq",
  "value": "credit_card"
}

Supported operatorsSame as attribute_condition: eq, neq, gt, gte, lt, lte, in, not_in, exists, not_exists.Runtime behavior

Look up attribute on the offer object. The engine checks top-level offer fields first, then falls back to metadata.customFieldValues.
If the attribute is missing and operator is not exists/not_exists, the rule passes (unknown field = don’t block).
For exists/not_exists, a missing attribute is valid input.
Apply the operator. If the comparison is false, the rule fails with a reason like Offer "productType" eq "credit_card" failed (actual: "loan").

Scopes

Every Qualification Rule has a scope that controls which Offers it applies to. Narrower scopes let you write rules that target specific parts of your catalog without affecting everything else.

Scope	`scopeId` resolves to	When it applies
`global`	(ignored)	Every Offer in the tenant
`segment`	Segment ID	Only when the customer belongs to the segment
`channel`	Channel ID	Only when the request targets that channel
`category`	Category ID	Only Offers in that Category
`subcategory`	SubCategory ID	Only Offers in that SubCategory
`offer`	Offer ID	Only that specific Offer
`placement`	Placement ID	Only when the request targets that placement

If a rule’s scope does not match the candidate Offer, the rule is skipped (treated as a pass).

When scopeId is null for a non-global scope, the rule applies to all entities at that scope level. For example, a rule with scope: "category" and scopeId: null applies to every Category.

Stages: Qualification vs Fit

	Qualification (hard gate)	Fit (soft penalty)
On failure	Offer removed from candidate set	Offer score multiplied by a decay factor
Typical rule types	`segment_required`, `attribute_condition`, `metric_condition`	`propensity_threshold`, `recency_check`
Multiplier range	N/A	0.1 — 1.0
Combination	First failure short-circuits	All fit multipliers are combined multiplicatively

When multiple fit rules apply to the same Offer, their multipliers are multiplied together. For example, if a propensity rule returns 0.8 and a recency rule returns 0.5, the final multiplier is 0.8 x 0.5 = 0.4.

Evaluation Order

During the Filter stage of a Decision Flow, rules are evaluated as follows:

Load all active Qualification Rules that match the flow’s filter mode (all, selected, or none).
Separate rules into qualification (hard gate) and fit (soft penalty) groups.
Sort each group by priority descending (highest priority first).
For each candidate Offer:
- Evaluate all qualification rules whose scope matches the candidate. First failure drops the Offer.
- Evaluate all fit rules whose scope matches the candidate. Accumulate the combined multiplier.
Surviving Offers proceed to the Scoring stage with their fit multiplier applied.

Decision Flow Filter Modes

Mode	Behavior
all	Every active Qualification Rule in the tenant is evaluated.
selected	Only the rules whose IDs are listed in `qualificationRuleIds` are evaluated.
none	Qualification is skipped entirely.

Setting the filter mode to none bypasses all Qualification Rules. Offers may be recommended to ineligible customers. Use with caution.

AND/OR Logic Trees

For advanced scenarios, Kaireon supports recursive AND/OR logic groups via a nested logic-group structure. This allows you to compose rules into arbitrarily nested boolean expressions.

{
  "operator": "AND",
  "ruleIds": ["rule_segment_premium", "rule_credit_720"],
  "groups": [
    {
      "operator": "OR",
      "ruleIds": ["rule_high_propensity", "rule_recent_login"]
    }
  ]
}

The example above evaluates as:

rule_segment_premium AND rule_credit_720 AND (rule_high_propensity OR rule_recent_login)

Vacuous truth rules:

An empty AND group (no ruleIds, no sub-groups) evaluates to true.
An empty OR group evaluates to false.

The evaluator walks the tree recursively: each group collects boolean results from its ruleIds (via the qualification engine) and its nested groups, then applies the group’s operator ("AND" = every result must be true; "OR" = at least one must be true).

Field Reference

All fields accepted by the POST /api/v1/qualification-rules endpoint:

Field	Type	Required	Default	Description
`name`	`string`	Yes	—	Unique display name for the rule.
`description`	`string`	No	`""`	Free-text description.
`status`	`enum`	No	`"active"`	One of `draft`, `active`, `paused`, `archived`. Only `active` rules are evaluated at decision time.
`scope`	`enum`	No	`"global"`	One of `global`, `segment`, `channel`, `category`, `subcategory`, `offer`, `placement`.
`scopeId`	`string \| null`	No	`null`	The ID of the entity the scope targets (e.g., a Category ID when `scope` is `category`). Null means “all entities at this scope level.”
`ruleType`	`enum`	Yes	—	One of `segment_required`, `attribute_condition`, `propensity_threshold`, `recency_check`, `metric_condition`, `offer_attribute`.
`config`	`object`	No	`{}`	Rule-type-specific configuration (see each rule type tab above).
`priority`	`integer`	No	`50`	0—100. Higher-priority rules are evaluated first.
`stage`	`enum`	No	`"qualification"`	One of `qualification` (hard gate) or `fit` (soft penalty).

Worked Example

Customer C-4821 requests a decision for the “Gold Card Upgrade” Offer. Three Qualification Rules are active.

Rule definitions

#	Name	Type	Scope	Config
1	Premium Segment Gate	`segment_required`	`global`	`{ "requiredSegments": ["premium"] }`
2	Min Credit Score	`attribute_condition`	`category:credit-cards`	`{ "attribute": "customer.credit_score", "operator": "gte", "value": 720 }`
3	Impression Cap	`metric_condition`	`global`	`{ "metricId": "monthly_impressions", "operator": "gt", "threshold": 10, "dimensionMapping": { "offerId": "$candidate.offerId" } }`

Pass scenario (credit_score = 745)

Customer context:

Segments: ["premium", "high_value"]
customer.credit_score: 745
monthly_impressions metric value: 8

Rule	Check	Result
1 — Premium Segment Gate	`"premium"` in segments?	Pass
2 — Min Credit Score	`745 >= 720`?	Pass
3 — Impression Cap	`8 > 10`? false — condition not triggered	Pass

The Offer survives and proceeds to scoring. Debug trace (abbreviated):

{
  "totalCandidates": 12,
  "afterQualification": 9,
  "qualificationReasons": []
}

No entries in qualificationReasons for this Offer because all three rules passed.

Fail scenario (credit_score = 680)

Same customer but with customer.credit_score = 680.

Rule	Check	Result
1 — Premium Segment Gate	`"premium"` in segments?	Pass
2 — Min Credit Score	`680 >= 720`?	Fail

Rule 2 fails. The engine short-circuits — Rule 3 is not evaluated. The Offer is dropped. Debug trace (abbreviated):

{
  "totalCandidates": 12,
  "afterQualification": 8,
  "qualificationReasons": [
    {
      "offerId": "offer_gold_card_upgrade",
      "creativeId": "",
      "reason": "Attribute \"customer.credit_score\" gte 720 failed (actual: 680)",
      "policyId": "qr_min_credit_score"
    }
  ]
}

API Quick Reference

Create a Qualification Rule

POST /api/v1/qualification-rules

{
  "name": "Premium Segment Gate",
  "ruleType": "segment_required",
  "scope": "global",
  "stage": "qualification",
  "priority": 80,
  "config": {
    "requiredSegments": ["premium"]
  }
}

Response: 201 Created with the full rule object including id, createdAt, and updatedAt.

List Qualification Rules

GET /api/v1/qualification-rules

Returns a paginated list sorted by priority (descending), then by creation date (descending). Supports cursor-based pagination via cursor and limit query parameters.

Update a Qualification Rule

PUT /api/v1/qualification-rules

Send the rule id plus any fields to update. Only provided fields are changed.

Delete a Qualification Rule

DELETE /api/v1/qualification-rules?id={ruleId}

Soft-deletes the rule (retains the record with a deletedAt timestamp). Returns { "deleted": true, "warnings": [...] }. If the rule is referenced by any Decision Flow’s draftConfig, the response includes a warnings array listing affected flows (ghost reference check). For complete request/response schemas, see the API Reference.

Contact Policies

Frequency caps and cooldown rules that limit how often a customer is contacted.

Decision Flows

Orchestrate Qualification Rules, scoring, and ranking into a complete decision pipeline.

Behavioral Metrics

Define the metrics used by metric_condition rules.

Composable Pipeline

The v2 pipeline includes a dedicated qualify node for inline qualification.

Get Started

Tutorials

Decisioning

Studio

Data Pipelines

AI & ML

Operations & Reporting

Governance & Security

Integrations

Reference

Qualification Rules

Overview

Rule Types

Scopes

Stages: Qualification vs Fit

Evaluation Order

Decision Flow Filter Modes

AND/OR Logic Trees

Field Reference

Worked Example

Rule definitions

Pass scenario (credit_score = 745)

Fail scenario (credit_score = 680)

API Quick Reference

Create a Qualification Rule

List Qualification Rules

Update a Qualification Rule

Delete a Qualification Rule

Contact Policies

Decision Flows

Behavioral Metrics

Composable Pipeline

Get Started

Tutorials

Decisioning

Studio

Data Pipelines

AI & ML

Operations & Reporting

Governance & Security

Integrations

Reference

Documentation Index

​Overview

​Rule Types

​Scopes

​Stages: Qualification vs Fit

​Evaluation Order

​Decision Flow Filter Modes

​AND/OR Logic Trees

​Field Reference

​Worked Example

​Rule definitions

​Pass scenario (credit_score = 745)

​Fail scenario (credit_score = 680)

​API Quick Reference

​Create a Qualification Rule

​List Qualification Rules

​Update a Qualification Rule

​Delete a Qualification Rule

​Related

Contact Policies

Decision Flows

Behavioral Metrics

Composable Pipeline

Overview

Rule Types

Scopes

Stages: Qualification vs Fit

Evaluation Order

Decision Flow Filter Modes

AND/OR Logic Trees

Field Reference

Worked Example

Rule definitions

Pass scenario (credit_score = 745)

Fail scenario (credit_score = 680)

API Quick Reference

Create a Qualification Rule

List Qualification Rules

Update a Qualification Rule

Delete a Qualification Rule

Related