Skip to main content

Share Score Explanation

Generate a shareable link to a lead's score breakdown, or retrieve a previously shared explanation without a kenbun account. Share links are read-only and expire after 7 days, making them safe to forward to colleagues, executives, or partners who don't have kenbun access.

POST /leads/{id}/share-explain​

Creates a new shareable link for a lead's current score explanation. Only authenticated kenbun users can create share links.

When to Use This​

  • Briefing stakeholders: Share a lead's score breakdown with a sales manager or executive who doesn't log in to kenbun
  • Collaborating across teams: Send a score explanation to a colleague in another system without requiring them to create a kenbun account
  • Documenting a moment: Capture a point-in-time view of a lead's scoring for a handoff or a deal review

Request​

ParameterTypeRequiredDescription
idstringYesLead identifier (path parameter)

No request body is required.

Example:

curl -X POST "https://api.kenbun.io/leads/ld_abc123/share-explain" \
  -H "Authorization: Bearer <token>"

Response​

201 Created

FieldTypeDescription
tokenstringUnique token identifying this share
expires_attimestampWhen the link expires (7 days from creation)
share_urlstringThe full URL recipients can open in a browser — no login required

Example response:

{
  "token": "sxp_7f3k9mLqT2vNcWdXeYzA",
  "expires_at": "2026-04-12T14:23:00Z",
  "share_url": "https://app.kenbun.io/share/explain/sxp_7f3k9mLqT2vNcWdXeYzA"
}

Common Errors​

StatusMeaningSolution
401UnauthorizedCheck your API credentials
404Not FoundThe lead ID does not exist or is not accessible in your active OU

GET /public/score-explain/{token}​

Retrieves the score explanation for a previously shared link. This endpoint requires no authentication, making it suitable for recipient-facing integrations.

Request​

ParameterTypeRequiredDescription
tokenstringYesThe share token returned by POST /leads/{id}/share-explain (path parameter)

Example:

curl -X GET "https://api.kenbun.io/public/score-explain/sxp_7f3k9mLqT2vNcWdXeYzA"

Response​

200 OK — The share is valid and the explanation is returned.

The response mirrors the Score Explanation endpoint format, with the addition of identifying fields:

FieldTypeDescription
lead_namestringDisplay name of the lead
scoreintegerLead's current total score
top_driversarrayScoring rules that contributed most to the score, sorted by absolute contribution
top_drivers[].rule_idstringUnique identifier of the scoring rule
top_drivers[].event_typestringEvent type this rule scores
top_drivers[].countintegerNumber of events attributed to this rule
top_drivers[].weightintegerPoint value of the rule
top_drivers[].totalintegerTotal points contributed (count × weight)
top_drivers[].filter_labelstringHuman-readable attribute filter conditions, if any. Omitted when the rule has no filters.
snapshotarrayCurrent rule weights from active rulesets
decay_appliedintegerTotal decay points applied (negative value)
range_hoursintegerThe time window used for the explanation

Example response:

{
  "lead_name": "Jane Smith",
  "score": 87,
  "top_drivers": [
    {
      "rule_id": "rl_abc123",
      "event_type": "page_view",
      "count": 4,
      "weight": 10,
      "total": 40,
      "filter_label": "path contains /pricing"
    },
    {
      "rule_id": "rl_def456",
      "event_type": "email_click",
      "count": 3,
      "weight": 5,
      "total": 15
    }
  ],
  "snapshot": [
    { "event_type": "page_view", "weight": 10 },
    { "event_type": "email_click", "weight": 5 }
  ],
  "decay_applied": -6,
  "range_hours": 24
}

Common Errors​

StatusMeaningSolution
404Not FoundThe token does not exist — verify it was copied correctly
410GoneThe share link has expired (links expire after 7 days) — ask the sender to generate a new one

Notes​

  • Expiry: All share links expire automatically after 7 days from creation. Expired links return 410 Gone. Ask the sender to create a new link if you need access after expiry.
  • Read-only: Recipients can view the score explanation but cannot modify any kenbun data.
  • No account required: The GET /public/score-explain/{token} endpoint is publicly accessible. Do not share tokens with people who should not see the lead's score data.
  • OU-scoped creation: Only users with access to the relevant Organizational Unit can create share links for leads within it.
  • Score snapshot: The shared explanation reflects the lead's scoring data at the time each request is made — it is not frozen at the moment the link was created. The score and top drivers may update as the lead continues to engage.