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.

4.3 KiB Raw Blame History