---
title: Lead Scoring Polling v1
description: Contract profile for polling Lead Scoring run status and DotB-Omni integration.
status: draft
tags:
  - lead-scoring
  - polling
  - integration
---

# Lead Scoring Polling v1

## Authority and release

This document defines polling semantics and security handling for inspecting scoring run
status. Exact JSON shapes, constraints, and golden response payloads are generated
deterministically from released Pydantic models and committed at
`contracts/lead-scoring-polling/v1/`.

Generate the contract pack with `uv run generate-polling-contract`; verify it with
`uv run generate-polling-contract --check`. `contract.json` identifies the standalone
pre-release contract pack version (`contract_pack_version: 0.1.0`), which targets the
HTTP API v1 major route (`/v1/scoring-runs/{run_id}`). DotB-Omni must pin the pack by
AI Platform Git commit when implementation begins and run its consumer tests against
these committed artifacts. Do not recreate response schemas or status payload fixtures in
Omni.

This pack is a pre-release baseline. The approved Customer Pilot specification remains
the authority for product behavior and ownership. Polling is an inspection and fallback
mechanism for internal callers and simple consumers alongside asynchronous webhook events.

## Endpoint and transport

Lead Scoring exposes `GET /v1/scoring-runs/{run_id}` with strict tenant scoping.

### Request headers

| Header | Type | Description |
|---|---|---|
| `Authorization` | `string` | `Bearer <service-token>` for authenticated service caller |
| `X-Tenant-Id` | `string` | Tenant identifier for scoped tenant isolation query |

### Path parameters

| Parameter | Type | Constraints | Description |
|---|---|---|---|
| `run_id` | `string` | `min_length=1`, `max_length=36` | Unique scoring run identifier |

## Status lifecycle

A scoring run progresses through the following runtime states, independent of the
underlying scoring mode (`light_ai`, `medium_ai`, `heavy_ai`, `rules_only_fallback`, or `rule_only`):

- `pending`: Run is admitted and persisted, awaiting worker execution.
- `running`: Worker has claimed the run and execution is in progress.
- `completed`: Execution finished successfully with calculated scores and combined confidence meeting or exceeding threshold.
- `review_required`: Execution completed but requires Human-In-The-Loop review (e.g. combined confidence below threshold or degraded rules-only fallback).
- `failed`: Terminal execution failure (e.g. `error_code=worker_interrupted`, `retryable=true`).
- `superseded`: Run was superseded by a child run created via re-evaluation.

## Response schemas and fixtures

The response shape is strictly defined by `scoring-run-response.schema.json`. Every
persisted run includes a fully materialized `effective_config` (`ScoringConfig`) and
`confidence_threshold`. Committed fixtures in `contracts/lead-scoring-polling/v1/fixtures/`
represent normative wire payloads for each active runtime status:

- `fixtures/pending.json`: Initial state before execution starts.
- `fixtures/running.json`: In-progress execution state.
- `fixtures/completed.json`: Successful run with full scores and AI metadata.
- `fixtures/review_required.json`: Degraded or low-confidence run needing review.
- `fixtures/failed.json`: Interrupted or failed run with error code and retry flag.
- `fixtures/superseded.json`: Superseded parent run after re-evaluation.

## HTTP response status codes

| HTTP Status | Description | Schema |
|---|---|---|
| `200 OK` | Scoring run metadata and current status | `scoring-run-response.schema.json` |
| `401 Unauthorized` | Invalid or missing Bearer service token | `error-response.schema.json` |
| `403 Forbidden` | Caller not authorized for tenant | `error-response.schema.json` |
| `404 Not Found` | Scoring run not found for tenant | `error-response.schema.json` |
| `422 Unprocessable Content` | Validation error for missing/invalid required headers or path parameters | `error-response.schema.json` |

## Consumer implementation boundary

DotB-Omni and internal callers use this endpoint to poll run status when webhook delivery
is unavailable, to reconcile run state after reconnection, or to verify execution progress
in internal tooling. Polling must always supply both `Authorization` and `X-Tenant-Id`
headers matching the tenant context of the requested run.