Tool endpoints

GET /tools

Lists every verification tool and its current status for one supplier + person. This is the endpoint the admin UI renders as the underwriting checklist.

Requires a valid x-session-token; any source may call it.

Query parameter Notes

supplier_key

Required, UUID (regex-validated by FastAPI → 422 on a bad shape).

person_id

Required, UUID (regex-validated).

Behaviour:

  • ToolTable.get_tools_and_create_missing returns the supplier/person rows and creates any missing ones with status NOT_RUN. The auto-created set is ToolTable.SUPPORTED_TOOLS: AU10TIX, ENTRUST, THOMSON_REUTERS_CLEAR_ID, THOMSON_REUTERS_PERSONAL_BACKGROUND_REPORT.

  • Stale-pending detection: a tool that has been PENDING for more than TASK_TIMEOUT_IN_SECONDS (300 s) is reported as ERROR with error_message = "Task Timeout", and that transition is persisted back to ToolTable.

  • Each row gets a display name from ToolType[type].value, and the list is sorted by that name.

Response — List[Tool]:

[
  {
    "supplier_key": "9b1c4d3e-6f2a-4b8c-9d0e-1f2a3b4c5d6e",
    "person_id": "44f2a1b0-7c3d-4e5f-8a9b-0c1d2e3f4a5b",
    "type": "ENTRUST",
    "name": "Entrust Identity Verification",
    "status": "VERIFIED",
    "correlation_id": "b1f7d0c2-3f4e-4a1b-9c8d-2e5f6a7b8c9d",
    "updated_by": "automatic-uw-tool",
    "updated_at": "2026-08-12T09:15:12.001233",
    "created_by": "underwriter@payability.com",
    "created_at": "2026-08-12T08:52:44.918002"
  },
  {
    "supplier_key": "9b1c4d3e-6f2a-4b8c-9d0e-1f2a3b4c5d6e",
    "person_id": "44f2a1b0-7c3d-4e5f-8a9b-0c1d2e3f4a5b",
    "type": "THOMSON_REUTERS_CLEAR_ID",
    "name": "Thomson Reuters Clear ID (KYC Check)",
    "status": "NOT_RUN",
    "correlation_id": null,
    "updated_by": "automatic-uw-tool",
    "updated_at": "2026-08-12T09:20:03.774100",
    "created_by": "automatic-uw-tool",
    "created_at": "2026-08-12T09:20:03.774100"
  }
]

Every mutation (creation, timeout flip) also appends a TOOL row to ChangelogTable.

Systems touched: ToolTable, ChangelogTable.

Tool vocabulary

ToolType (storage key) Display name

THOMSON_REUTERS_CLEAR_ID

Thomson Reuters Clear ID (KYC Check)

THOMSON_REUTERS_PERSONAL_BACKGROUND_REPORT

Thomson Reuters Personal Background Report

AU10TIX

Au10tix

ENTRUST

Entrust Identity Verification
ToolStatus Meaning

NOT_RUN

The row exists but the process has never run.

PENDING

A request step (or an Entrust session) started; awaiting the async result. Older than 300 s is surfaced as ERROR.

ERROR

The task failed, or the pending window expired.

NOT_VERIFIED

A terminal negative verdict.

VERIFIED

A terminal positive verdict.

VERIFIED_ACCESS, VERIFIED_ADVANCE, VERIFIED_ACCESS_AND_ADVANCE

Tiered verdicts, personal background report only.

There is deliberately no tool for download_business_background_report.

See the Tool table for the stored item shape and its known scan-based access pattern.