Qualification Rules API

Qualification rules define conditions that offers must satisfy before they can be recommended to a customer. Rules are evaluated during the qualification stage of a Decision Flow and can be scoped globally or to a specific segment, channel, category, sub-category, offer, or placement.

See the Qualification Rules feature page for UI guidance and conceptual overview.

Base path

/api/v1/qualification-rules

List qualification rules

GET /api/v1/qualification-rules

Returns a paginated list of qualification rules, ordered by priority (highest first), then creation date (newest first).

Query parameters

Parameter	Required	Type	Description
`limit`	No	integer	Maximum results per page. Default `25`.
`cursor`	No	string	Cursor for keyset pagination.
`includeDeleted`	No	boolean	Include soft-deleted records. Default `false`.

Response `200`

{
  "data": [
    {
      "id": "qr_001",
      "tenantId": "t_001",
      "name": "Gold Tier Required",
      "description": "Only show to gold tier or above.",
      "status": "active",
      "scope": "segment",
      "scopeId": "seg_gold",
      "scopes": [{ "id": "qs_001", "qualificationRuleId": "qr_001", "scope": "global", "scopeId": null, "createdAt": "2026-03-10T12:00:00.000Z" }],
      "ruleType": "segment_required",
      "config": { "requiredSegments": ["gold", "platinum"] },
      "priority": 80,
      "stage": "qualification",
      "version": 1,
      "deletedAt": null,
      "createdAt": "2026-03-10T12:00:00.000Z",
      "updatedAt": "2026-03-12T09:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 15,
    "limit": 25,
    "hasMore": false,
    "cursor": null
  }
}

Create a qualification rule

POST /api/v1/qualification-rules

Creates a new qualification rule. Requires the admin role.

Request body

Field	Required	Type	Description
`name`	Yes	string (1-255)	Unique rule name.
`description`	No	string	Rule description.
`status`	No	enum	`draft`, `active` (default), `paused`, `archived`.
`scope`	No	enum	`global` (default), `segment`, `channel`, `category`, `subcategory`, `offer`, `placement`.
`scopeId`	No	string \| null	ID of the scoped entity (required when scope is not `global`).
`ruleType`	Yes	enum	One of: `segment_required`, `attribute_condition`, `propensity_threshold`, `recency_check`, `metric_condition`.
`config`	No	object	Rule-type-specific configuration.
`priority`	No	integer (0-100)	Evaluation priority (higher = evaluated first). Default `50`.
`stage`	No	enum	`qualification` (default) or `fit`.
`scopes`	No	array	Array of scope assignments. Each item: `{ scope: "global"\|"category"\|"subcategory"\|"channel"\|"offer"\|"creative", scopeId: "entity-UUID" }`. When provided, overrides the legacy `scope`/`scopeId` fields. A rule can have multiple scope assignments simultaneously.

Rule types

Type	Description	Config example
`segment_required`	Customer must be in any of the listed segments (OR logic).	`{ "requiredSegments": ["premium", "vip"] }`
`attribute_condition`	Customer attribute must match a condition. Supports `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `exists`, `not_exists`.	`{ "attribute": "customer.age", "operator": "gte", "value": 18 }`
`propensity_threshold`	Model score or enriched attribute must exceed a threshold.	Model: `{ "propensityModel": "mod_01", "minScore": 0.3 }` or Attribute: `{ "attribute": "customer.churn_risk", "operator": "lt", "threshold": 0.8 }`
`recency_check`	Customer attribute representing days since last activity must be within a window.	`{ "attribute": "customer.last_purchase_days", "maxDays": 90 }`
`metric_condition`	A behavioral metric must meet a condition.	`{ "metricId": "open_rate", "operator": "gte", "threshold": 0.1 }`

Example request

{
  "name": "Minimum Age 18",
  "ruleType": "attribute_condition",
  "scope": "global",
  "config": {
    "attribute": "age",
    "operator": "gte",
    "value": 18
  },
  "priority": 90,
  "stage": "qualification"
}

Response `201`

Returns the created qualification rule object.

Validation

All fields are validated via Zod schemas:

name: 1-255 characters, must be unique per tenant.
ruleType: Must be one of the five enum values.
scope: Must be one of the seven enum values.
priority: Integer, 0-100.
stage: Must be qualification or fit.

Error codes

Code	Reason
`400`	Validation error (missing name or ruleType, invalid scope/priority).
`409`	A qualification rule with that name already exists.
`415`	`Content-Type` is not `application/json`.

Update a qualification rule

PUT /api/v1/qualification-rules

Updates an existing qualification rule. Only provided fields are changed. Requires the admin role.

Request body

All fields from the create schema are accepted as optional, plus:

Field	Required	Type	Description
`id`	Yes	string	The rule ID to update.

Example request

{
  "id": "qr_001",
  "priority": 95,
  "status": "paused"
}

Response `200`

Returns the updated qualification rule object.

Delete a qualification rule

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

Soft-deletes a qualification rule by ID. The record is marked as deleted but retained in the database for audit purposes. The response includes warnings if the rule is still referenced by any Decision Flow’s draftConfig.

Query parameters

Parameter	Required	Type	Description
`id`	Yes	string	Rule ID to delete.

Response `200`

{
  "deleted": true,
  "warnings": [
    "Referenced by decision flow \"Credit Card NBA\" — it will skip this rule."
  ]
}

This endpoint uses soft-delete — the record is not physically removed from the database. It is excluded from GET results by default. To include soft-deleted records, pass ?includeDeleted=true on the GET request.

Unlike most DELETE endpoints that return 204, this endpoint returns 200 with a body so it can communicate ghost-reference warnings. The API checks all Decision Flows in the tenant for references to this rule ID in their draftConfig.stages.filter.qualificationRuleIds array.

Error codes

Code	Reason
`400`	Missing `id` query parameter, or soft-delete failed.

Role requirements

Method	Minimum role
GET	`viewer`
POST	`admin`
PUT	`admin`
DELETE	`admin`

Soft-delete and audit

Qualification rules use soft-delete with audit snapshots. When a rule is deleted:

The deletedAt timestamp is set (record is retained).
An audit snapshot is captured with the full state before deletion.
Ghost reference warnings are returned if the rule is still referenced by any Decision Flow.

Updates also create audit snapshots via auditedUpdate, incrementing the rowVersion on each change. This provides a full change history for compliance and debugging. To include soft-deleted rules in GET responses, add ?includeDeleted=true to the query string.

Multi-scope rules are evaluated differently: global-scoped rules are evaluated in the Decision Flow’s Qualify node, while entity-scoped rules (offer, category, channel, creative) are automatically evaluated per-candidate during the recommend pipeline.