Skip to main content

Disqualification

Endpoints for inspecting hard-disqualification rule activity. For the user-facing concept and configuration walkthrough, see the Hard Disqualification guide.

GET /scoring/disqualifications/match-counts​

Return the current match count for every active hard-disqualification rule in the active Organizational Unit. The Configure > Scoring > Disqualification tab uses this endpoint to render the per-rule counts shown next to each rule. It is also useful as a programmatic health check on your disqualification ruleset.

A rule's match count is the number of leads in the OU that are currently disqualified by that specific rule. A lead disqualified by two rules contributes to both counts.

Request​

No request body. Authentication and active OU context are taken from your credentials.

Response​

Status: 200 OK

{
  "match_counts": [
    {
      "rule_id": "8b2c1a5e-...",
      "dimension": "profile",
      "rule_name": "email equals \"\" AND phone equals \"\"",
      "match_count": 142
    },
    {
      "rule_id": "7d4f9c3a-...",
      "dimension": "profile",
      "rule_name": "email_domain in [gmail.com, yahoo.com]",
      "match_count": 38
    },
    {
      "rule_id": "2e1a8b6c-...",
      "dimension": "account",
      "rule_name": "account_status equals \"Competitor\"",
      "match_count": 6
    }
  ]
}

Response Fields​

FieldTypeDescription
match_counts[].rule_idstringRule identifier. Use this to look the rule up via the rule endpoints, or to navigate directly to the rule slideout in the UI.
match_counts[].dimensionstringEither profile or account. Engagement and deal dimensions are not supported for hard disqualification.
match_counts[].rule_namestringHuman-readable summary of the rule's conditions, synthesised from its property and operator. In V1 there is no separate user-editable name field on rules, so this string is what the UI displays.
match_countintegerNumber of leads in the OU currently disqualified by this rule.

Example​

curl -X GET "https://api.kenbun.io/scoring/disqualifications/match-counts" \
  -H "Authorization: Bearer <token>"

Common Errors​

StatusMeaningSolution
400Missing or malformed authentication contextConfirm your credentials and that you have an active OU selected.
401UnauthorizedVerify your API credentials.
500Server errorRetry. If the error persists, contact support.

Configuring Hard-Disqualification Rules​

Hard-disqualification rules are created and updated through the existing profile and account rule endpoints. Two fields on the rule POST and PUT bodies enable hard-disqualification behavior:

  • rule_type accepts either "add_points" (the default, normal scoring rule) or "hard_disqualify" (the rule disqualifies matching leads instead of scoring them).
  • conditions is a JSON object that captures compound AND/OR conditions for hard-disqualification rules. It is only honored when rule_type is "hard_disqualify". The shape supports a single flat group with two or more conditions and a group_operator of "AND" or "OR".

For the full POST and PUT request shapes, see the existing rule endpoints:

Conditions JSON Shape​

When rule_type is "hard_disqualify" and the rule uses compound conditions, the conditions field looks like:

{
  "group_operator": "AND",
  "conditions": [
    { "property": "email", "operator": "equals", "value": "" },
    { "property": "phone", "operator": "equals", "value": "" }
  ]
}

Single-condition hard-disqualification rules can omit the conditions field and use the rule's existing top-level property, operator, and value fields, exactly like an "add_points" rule.

Behavior After Save​

When a hard-disqualification rule is created or updated, kenbun re-evaluates it across the OU within seconds. Matching leads are flagged immediately. Their score values are preserved, but they are excluded from default lead and account lists, segment counts, and trigger evaluations. See the Hard Disqualification guide for the full behavior contract.

See Also​