Business outcomes

A business outcome is your own fact about a case: this case was resolved without an escalation, CSAT was 4, handle time was 6m12s, the refund was reversed. It lives in your helpdesk, your CRM, or your warehouse — not in the trace — and it almost always arrives after the agent has finished running.

Neens accepts that fact, keys it to the case the agent actually handled, and keeps it as evidence alongside the trace. Nothing here is inferred: a judge’s opinion that an answer looked helpful is a score; the customer clicking 4 stars is an outcome. Only one of those is the business result, and this page is about the second one.

At a glance

The case grain

Neens keys every outcome to a case, which is conversation_id when the trace has one and the trace’s own id when it doesn’t — exactly the rollup you already see on the Sessions page (see Traces & sessions). A multi-turn conversation is one case, not one case per turn, so “handle time was 6m12s” attaches to the whole exchange rather than to a single model call.

When an outcome matches, Neens records both the case key (conversationId) and the case’s first trace (sessionId), so you can jump from the outcome straight into the conversation that produced it.

Choose a correlation type

correlationType tells Neens how to find the case your correlationKey refers to. There are three, and picking the right one is the single biggest lever on your match rate.

For external, Neens walks a list of dotted paths into each session’s metadata JSON and takes the first non-empty scalar it finds. Out of the box those paths are:

ticket_id · case_id · external_id · crm_id · attributes.ticket_id · tags.ticket_id

Change them per agent under the Data sources tab of Business KPIs, or with PUT /outcomes/settings (see Settings).

Push an outcome

export NEENS_BASE_URL="https://neens.example.com"   # your Neens origin
export NEENS_API_KEY="nk_live_..."                  # your agent API key

curl -sf -X POST "$NEENS_BASE_URL/api/outcomes" \
  -H "Authorization: Bearer $NEENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "zendesk_etl",
    "outcomes": [
      {
        "correlationKey": "ZD-10231",
        "correlationType": "external",
        "kind": "resolution",
        "value": true,
        "occurredAt": "2026-07-26T10:04:00Z",
        "metadata": {"queue": "billing"},
        "idempotencyKey": "zd-10231-resolution-v1",
        "externalId": "10231"
      },
      {
        "correlationKey": "ZD-10231",
        "correlationType": "external",
        "kind": "csat",
        "value": 4,
        "occurredAt": "2026-07-26T11:20:00Z",
        "idempotencyKey": "zd-10231-csat-v1"
      },
      {
        "correlationKey": "ZD-10231",
        "correlationType": "external",
        "kind": "resolution_time",
        "value": 372,
        "unit": "s",
        "occurredAt": "2026-07-26T10:04:00Z",
        "idempotencyKey": "zd-10231-rt-v1"
      }
    ]
  }'

import os
import requests
 
BASE = os.environ["NEENS_BASE_URL"]
KEY = os.environ["NEENS_API_KEY"]
 
payload = {
    "source": "zendesk_etl",
    "outcomes": [
        {
            "correlationKey": "ZD-10231",
            "correlationType": "external",
            "kind": "resolution",
            "value": True,
            "occurredAt": "2026-07-26T10:04:00Z",
            "metadata": {"queue": "billing"},
            "idempotencyKey": "zd-10231-resolution-v1",
            "externalId": "10231",
        },
        {
            "correlationKey": "ZD-10231",
            "correlationType": "external",
            "kind": "csat",
            "value": 4,
            "occurredAt": "2026-07-26T11:20:00Z",
            "idempotencyKey": "zd-10231-csat-v1",
        },
        {
            "correlationKey": "ZD-10231",
            "correlationType": "external",
            "kind": "resolution_time",
            "value": 372,
            "unit": "s",
            "occurredAt": "2026-07-26T10:04:00Z",
            "idempotencyKey": "zd-10231-rt-v1",
        },
    ],
}
 
resp = requests.post(
    f"{BASE}/api/outcomes",
    headers={"Authorization": f"Bearer {KEY}"},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
result = resp.json()
 
print(result["accepted"], "accepted,", result["matched"], "matched")
for bad in result["rejected"]:
    print("rejected", bad["index"], bad["correlationKey"], "-", bad["reason"])

{
  "accepted": 3,
  "created": 3,
  "revised": 0,
  "deduplicated": 0,
  "rejected": [],
  "matched": 3,
  "unmatched": 0,
  "ambiguous": 0,
  "outcomes": [
    {
      "id": "bo_ab12c3d45e6f7890",
      "seriesKey": "9f3c…",
      "projectId": "proj_x",
      "correlationType": "external",
      "correlationKey": "ZD-10231",
      "kind": "resolution",
      "kindLabel": "Resolved",
      "source": "zendesk_etl",
      "valueType": "boolean",
      "value": true,
      "unit": null,
      "occurredAt": "2026-07-26T10:04:00+00:00",
      "receivedAt": "2026-07-26T10:07:41.118932+00:00",
      "metadata": {"queue": "billing"},
      "revision": 1,
      "isCurrent": true,
      "supersededAt": null,
      "supersededBy": null,
      "matchState": "matched",
      "sessionId": "ses-1a2b3c",
      "conversationId": "conv-77f0",
      "matchedAt": "2026-07-26T10:07:41.118932+00:00",
      "matchAttempts": 1,
      "matchDetail": null,
      "matchDeadline": "2026-07-29T10:04:00+00:00",
      "connectionId": null,
      "externalId": "10231",
      "createdBy": "[email protected]",
      "createdAt": "2026-07-26T10:07:41.118932+00:00"
    }
  ]
}

Request fields

A top-level source applies to every record in the batch; a per-record source overrides it.

The outcome catalogue

GET /outcomes/kinds returns the platform catalogue plus the valid correlation types, match states and value types. These are the curated kinds the UI offers:

Idempotency and restatement

These are two different things, and the distinction is what keeps your history truthful.

Idempotency is “you already told me this”. Restatement is “you’ve changed your mind”.

A series is the identity of one fact about one case: (project, correlationType, correlationKey, kind, source). A series has one or more revisions, and exactly one of them is current. Nothing is ever overwritten and nothing is deleted — the superseded revision stays as evidence.

Neens decides which of the two happened in this order:

// REJECTED — one key, three different kinds. Append the kind instead ("zd-10231-csat").
[{"correlationKey": "ZD-10231", "kind": "resolution", "value": true,  "idempotencyKey": "zd-10231"},
 {"correlationKey": "ZD-10231", "kind": "csat",       "value": 4,     "idempotencyKey": "zd-10231"}]

So a reopened ticket looks like this — same key, same kind, same source, a different idempotency key:

curl -sf -X POST "$NEENS_BASE_URL/api/outcomes" \
  -H "Authorization: Bearer $NEENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "zendesk_etl",
    "correlationKey": "ZD-10231",
    "correlationType": "external",
    "kind": "resolution",
    "value": false,
    "occurredAt": "2026-07-27T09:15:00Z",
    "metadata": {"reopenReason": "customer replied: charge still on the statement"},
    "idempotencyKey": "zd-10231-resolution-v2"
  }'

In the UI, the Business outcomes section on the trace’s detail page marks that outcome Revised (rev 2) and expands its Revision history to show the value it used to hold. Over the API the whole series is readable:

curl -sf "$NEENS_BASE_URL/api/outcomes/bo_ab12c3d45e6f7890/revisions" \
  -H "Authorization: Bearer $NEENS_API_KEY"

{
  "seriesKey": "9f3c…",
  "total": 2,
  "revisions": [
    {"revision": 1, "value": true,  "isCurrent": false, "supersededAt": "2026-07-27T09:16:02+00:00", "supersededBy": "bo_7f9b46b1aebf4013", "…": "…"},
    {"revision": 2, "value": false, "isCurrent": true,  "supersededAt": null, "supersededBy": null, "…": "…"}
  ]
}

Late arrival: matched, parked, expired

An outcome routinely lands before its trace does — a helpdesk fires the moment a ticket closes, while the agent’s spans are still in flight. Neens never drops those.

Every record is correlated at write time, so a same-day outcome is matched immediately and never waits for a sweep. Whatever doesn’t match is parked, not discarded:

The match deadline is occurredAt + the match window (72 hours by default), which you can override per agent under the Data sources tab of Business KPIs. A background sweep periodically re-attempts the oldest parked rows first and stamps every attempt — so a permanently unmatchable row shows as “tried 40 times” rather than looking like a fresh arrival.

To run it now for the current agent, click Reconcile now on the Match coverage panel, or call the API (admin only):

curl -sf -X POST "$NEENS_BASE_URL/api/outcomes/reconcile" \
  -H "Authorization: Bearer $SESSION_TOKEN"

{"examined": 12, "matched": 4, "ambiguous": 1, "expired": 2, "stillUnmatched": 5}

Read the coverage panel

GET /outcomes/coverage is the surface this whole feature exists for. A containment rate computed off a 60%-matched set of outcomes is confidently wrong, and nothing else in the product would tell you.

curl -sf "$NEENS_BASE_URL/api/outcomes/coverage?since=2026-07-01" \
  -H "Authorization: Bearer $NEENS_API_KEY"

{
  "summary": {
    "total": 96, "matched": 86, "unmatched": 7, "ambiguous": 1, "expired": 2,
    "matchRate": 0.8958, "unresolvedRate": 0.1042
  },
  "byKind": [
    {"kind": "resolution", "total": 28, "matched": 18, "unmatched": 7, "ambiguous": 1, "expired": 2, "matchRate": 0.6429, "unresolvedRate": 0.3571}
  ],
  "bySource": [
    {"source": "zendesk_etl", "total": 78, "matched": 68, "…": "…"}
  ],
  "byCorrelationType": [
    {"correlationType": "conversation", "total": 66, "matched": 66, "matchRate": 1.0, "…": "…"}
  ],
  "recentUnmatched": [
    {"id": "bo_…", "kind": "resolution", "correlationKey": "ZD-77104", "correlationType": "external",
     "occurredAt": "2026-07-26T…", "matchAttempts": 3,
     "matchDetail": "external key 'ZD-77104' not found in any session's metadata"}
  ],
  "oldestUnmatchedAt": "2026-07-20T08:12:00+00:00"
}

Read it in this order:

1. summary.matchRate — the headline. Every downstream number is only as trustworthy as this.
2. byCorrelationType — usually where the problem is. A conversation row at 1.0 next to an external row at 0.55 tells you the correlation type, not the data, is wrong.
3. byKind / bySource — narrows it to one exporter or one fact.
4. recentUnmatched — up to 20 parked outcomes with the actual reason each one failed. This is the fastest path to a fix. The sample is redacted, so a ticket subject or a requester email in metadata never leaks into a shared screenshot.

Filter coverage with since, until, kind and source to check one exporter in isolation.

Why your match rate is not 100%

A brownfield deployment typically sits somewhere in the 85–95% range, and that’s fine — as long as you know why. Every parked outcome carries a matchDetail explaining itself; here is what each state means and what actually fixes it.

Fixed the cause? Parked rows are re-attempted automatically, or immediately with POST /outcomes/reconcile. Rows already marked expired are not retried — re-post them if they matter.

Agent settings

Both settings live on the Data sources tab of Business KPIs, under Correlation settings, as External key paths (one per line) and Match window (hours) — leave either blank to inherit the platform default. GET /outcomes/settings shows the effective configuration and the defaults it falls back to; PUT /outcomes/settings changes it (admin only).

curl -sf -X PUT "$NEENS_BASE_URL/api/outcomes/settings" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"externalKeyPaths": ["ticket_id", "attributes.zendesk_ticket"], "matchWindowHours": 168}'

Browse recorded outcomes

curl -sf -G "$NEENS_BASE_URL/api/outcomes" \
  -H "Authorization: Bearer $NEENS_API_KEY" \
  --data-urlencode "kind=csat" \
  --data-urlencode "matchState=matched" \
  --data-urlencode "limit=50"

GET /outcomes/{id} returns one outcome; GET /outcomes/{id}/revisions returns its whole series oldest → newest.

What’s next

• Connect your helpdesk — pull outcomes from Zendesk, Intercom, Salesforce or Jira Service Management on a schedule instead of pushing them.
• Business KPIs — turn these outcomes into containment rate, resolution time and cost per case, measured per case and badged with their provenance and coverage. Once a number is one you report on, promote it to a KPI: a target, a direction, an owner and a review cadence on top of the same measure. Because outcomes arrive late, every KPI value carries its coverage and an asOf — and a window with no decided cases reads unknown, never missed. Late arrivals are also why a KPI’s recorded daily history re-checks its most recent days: an outcome that lands on Thursday corrects the figure already recorded for Monday.
• Traces & sessions — the case grain outcomes are keyed to.
• Fix outcomes — the other outcome surface: whether a merged fix actually reduced a failure in production.