Skip to main content

Add explainable lead scoring to your Clay table

Call kenbun's scoring endpoint from a Clay HTTP API enrichment column so each contact or account row comes back with a lead score and the rule-level reasons behind it.

Most enrichment returns a number; this returns the score and the rules that fired to produce it, so the cell shows why a row scored the way it did, not just what it scored.

Prerequisites​

  • A kenbun Personal Access Token with the write:scoring scope. Create one under Settings → API Tokens.
  • A Clay workspace on a plan that includes HTTP API enrichment columns.

Add the enrichment column​

  1. In your table, add a new column and choose the HTTP API enrichment.

  2. Set the method to POST and the URL to:

    https://api.kenbun.io/scoring/score

  3. Add a header for authentication:

    Authorization: Bearer kbn_pat_your_token_here

    Add Content-Type: application/json if your column doesn't set it by default.

  4. In the request body, map your Clay columns into the JSON fields. Put person-level firmographics under profile and company-level attributes under account. Reference Clay columns with the column-merge syntax (for example {{Email}}):

    {
      "external_id": "clay-{{Email}}",
      "profile": {
        "email": "{{Email}}",
        "job_title": "{{Job Title}}",
        "country": "{{Country}}"
      },
      "account": {
        "domain": "{{Company Domain}}",
        "employee_count": "{{Employee Count}}",
        "industry": "{{Industry}}"
      }
    }

    Only the properties your scoring rules reference need to be sent. external_id is any stable identifier for the row; reusing the same value on a re-run keeps the lead consistent in kenbun.

  5. Run the column on a row to test the response.

Example response​

{
  "external_id": "clay-jordan@acme.io",
  "lead_id": "a1f2…",
  "dimensions_scored": ["profile", "account"],
  "profile": {
    "score": 18,
    "level": "Good Fit",
    "drivers": [
      { "property": "job_title", "condition": "contains", "value": "VP", "weight": 10, "matched": true },
      { "property": "country", "condition": "equals", "value": "US", "weight": 8, "matched": true }
    ]
  },
  "account": {
    "score": 12,
    "level": "Tier 2",
    "drivers": [
      { "property": "employee_count", "condition": "greater_than", "value": "100", "weight": 12, "matched": true }
    ]
  }
}

Map the response back into columns​

Each scored dimension returns its own block. Pull the fields you want into Clay columns:

  • profile.score and account.score — the numeric scores.
  • profile.level and account.level — the named tier for each score.
  • profile.drivers and account.drivers — one entry per rule, with the property, condition, weight, and a matched flag. The entries where matched is true are the reasons the score fired; concatenate their property values into a single column for a readable "why" cell.

With the score and reasons in columns, sort or filter your table by score and route high-fit rows into the rest of your Clay workflow.