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.
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 limitNo integer Maximum results per page. Default 25. cursorNo string Cursor for keyset pagination.
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" , "ruleType" : "segment_required" , "config" : { "segmentId" : "seg_gold" }, "priority" : 80 , "stage" : "qualification" , "createdAt" : "2026-03-10T12:00:00.000Z" , "updatedAt" : "2026-03-12T09:30:00.000Z" } ], "pagination" : { "total" : 15 , "limit" : 25 , "hasMore" : false , "nextCursor" : 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 nameYes string (1-255) Unique rule name. descriptionNo string Rule description. statusNo enum draft, active (default), paused, archived.scopeNo enum global (default), segment, channel, category, subcategory, offer, placement.scopeIdNo string | null ID of the scoped entity (required when scope is not global). ruleTypeYes enum One of: segment_required, attribute_condition, propensity_threshold, recency_check, metric_condition. configNo object Rule-type-specific configuration. priorityNo integer (0-100) Evaluation priority (higher = evaluated first). Default 50. stageNo enum qualification (default) or fit.
Rule types Type Description Config example segment_requiredCustomer must belong to a segment. { "segmentId": "seg_gold" }attribute_conditionCustomer attribute must match a condition. { "attribute": "age", "operator": "gte", "value": 18 }propensity_thresholdModel propensity score must exceed a threshold. { "modelId": "mod_01", "threshold": 0.3 }recency_checkCustomer must (or must not) have a recent interaction. { "outcomeType": "accepted", "withinDays": 30, "negate": true }metric_conditionA behavioral metric must meet a condition. { "metricKey": "open_rate", "operator": "gte", "value": 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.
Error codes Code Reason 400Validation error (missing name or ruleType). 409A qualification rule with that name already exists. 415Content-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 idYes 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}
Deletes a qualification rule by ID. The response includes warnings if the rule is still referenced by any Decision Flow.
Query parameters Parameter Required Type Description idYes string Rule ID to delete.
Response 200 { "deleted" : true , "warnings" : [ "Referenced by Decision Flow \" Credit Card NBA \" — it will skip this rule." ] }
Unlike most DELETE endpoints that return 204, this endpoint returns 200 with a body so it can communicate ghost-reference warnings.
Error codes Code Reason 400Missing id query parameter.
Role requirements Method Minimum role GET viewerPOST adminPUT adminDELETE admin
Qualification Rules Learn more about configuring qualification rules in the platform UI.
