Clausum intelligence network

Clausum intelligence combines managed feeds and the collaborative network. Both apply during POST /api/v1/assess and POST /api/v1/assess/payout:

Layer	Contract	Who operates it	What you do
Managed feeds	CLM-ADD-INTEL	Clausum staff	Nothing — platform feeds and blocklists apply when entitled
CIN (collaborative network)	CLM-ADD-NET-C (consume) + opt-in contribute	Participating banks, PSPs, merchants	Publish signals; receive exact / aggregate peer hits in assess
CEG (Entity Graph)	Included with CIN consume (CEG Coverage)	Same network data, graph layer	Enable after CIN is stable — Entity Graph guide

CIN vs CEG: CIN is the base collaborative network (list hits). CEG is the premium / extended layer — 1-hop relationships between co-observed entities. Same SKU of consume; separate mode flag (graph_assess_mode). See Settings → Services for the integration index.

The network augments assess — it does not replace your local rules, blocklists, or the synchronous assess call. Prevention first.

Legal / compliance first? Read Collaborative network — trust & enrollment — enrollment-first path, privacy guarantees, and mutual commitments before API integration.

Who this guide is for

Segment	Typical role	Integration profile
Bank (`banco`)	Core banking, treasury, fraud ops	`financial_institution` — contribute + consume when contracted
PSP (`psp`)	Acquirer middleware, sub-merchant orchestration	`partner` — contribute aggregated signals; consume when contracted
Merchant	Optional peer contributor	`merchant` — contribute only unless staff enables consume

Segment plans: Bank · PSP · Merchant

How it fits your stack

Capability	Endpoint	Purpose
Real-time gate	`POST /api/v1/assess`	Pay-in decision before capture
Payout gate	`POST /api/v1/assess/payout`	Disbursement decision before release
Network publish	`POST /api/v1/network/intelligence`	Bulk shared signals for other participants
Webhooks / ingest	`clm_wh_*`	Post-payment events — not a substitute for assess

Quick start — bank (5 steps)

1. Create a server key

Dashboard → Connections → API keys — create clm_sk_* with:

assess — required to benefit from consumed signals
network:contribute — publish signals (or fraud:report for single reports)

See API keys.

2. Enable contribution

Banks use profile financial_institution. Contribution is toggled in the dashboard:

Intelligence (/dashboard/network) → Quick start panel (banks only) or Settings tab → enable Contribute to network

Consuming peer signals in assess is enabled by Clausum on your contract (CLM-ADD-NET-C). Contact your account manager — it is not self-serve via API.

3. Publish signals

Send confirmed fraud indicators from your core or fraud platform (up to 500 entries per request):

curl -s -X POST "${CLAUSUM_API_BASE}/api/v1/network/intelligence" \
  -H "Authorization: Bearer ${CLAUSUM_SECRET_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      {
        "list_type": "email",
        "value": "confirmed-fraud@example.com",
        "severity": "block",
        "reason_code": "confirmed_fraud",
        "reason_detail": "Internal case #12345",
        "confidence": 90,
        "source": "bank_feed"
      },
      {
        "list_type": "card_bin",
        "value": "411111",
        "severity": "flag",
        "reason_code": "card_testing",
        "source": "bank_feed"
      }
    ]
  }'

4. Protect pay-in and payout

Every payment or disbursement should call assess before money moves:

Pay-in: Real-time assessment
Payout: Payout assessment

When network consume is active, assess matches normalized fields against peer signals from contributors whose trust score meets your threshold.

5. Operate and revoke

Intelligence → My signals — review and revoke false positives
Intelligence → Participants — see contributing institutions (when consume is on)
Protection — compact status for managed + network layers

Quick start — PSP (5 steps)

1. Complete PSP onboarding

Register sub-merchants before live assess — PSP submerchants. Every pay-in assess must include submerchant_id when your registry is non-empty.

2. Create middleware keys

clm_sk_* on your PSP orchestration layer with assess + optional network:contribute. Never embed secret keys in sub-merchant frontends.

3. Assess before settlement

{
  "amount": 150.00,
  "amount_unit": "major",
  "currency": "MXN",
  "submerchant_id": "uuid-from-registry",
  "order_id": "sm-8842-checkout-001",
  "email": "payer@example.com",
  "device": { "ip": "203.0.113.5" }
}

Your middleware enforces decision before settling funds to the sub-merchant. See PSP integration.

4. Optionally contribute aggregated signals

Publish BIN ranges, emails, or IPs observed across your portfolio (with legal approval):

curl -s -X POST "${CLAUSUM_API_BASE}/api/v1/network/intelligence" \
  -H "Authorization: Bearer ${CLAUSUM_SECRET_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [{
      "list_type": "ip_address",
      "value": "203.0.113.44",
      "severity": "review",
      "reason_code": "velocity_abuse",
      "source": "api"
    }]
  }'

Enable Contribute to network in Intelligence → Settings.

5. Route webhooks per sub-merchant

Outbound events include metadata for routing — Receiving webhooks. Pipe acquirer events via Event ingestion as a complement to assess.

API reference

Publish signals

POST /api/v1/network/intelligence
Authorization: Bearer clm_sk_...
Content-Type: application/json

Permissions: network:contribute or fraud:report (secret key only). Body: entries[] (max 500) or single list_type + value.

Field	Required	Description
`list_type`	Yes	Signal type (see table below)
`value`	Yes	Raw value — normalized server-side
`severity`	Recommended	`block`, `flag`, or `review`
`reason_code`	Recommended	Short machine code
`reason_detail`	Optional	Human note (not shown to other tenants)
`confidence`	Optional	0–100
`source`	Optional	`api`, `bank_feed`, `fraud_report`, …
`external_ref`	Optional	Stable id from your feed for idempotent batch jobs
`expires_at`	Optional	ISO timestamp

Response:

{
  "success": true,
  "accepted": 2,
  "skipped": 0,
  "errors": [],
  "list_types_supported": ["email", "email_domain", "ip_address", "..."]
}

Errors:

Code	Meaning
`NETWORK_CONTRIBUTE_DISABLED`	Enable contribution in Dashboard → Intelligence → Settings
`VALIDATION_ERROR`	Invalid `list_type`, empty batch, or >500 entries

Network stats (partner)

GET /api/v1/network/intelligence
Authorization: Bearer clm_sk_...

Permissions: network:signals:read, network:contribute, fraud:report, or assess. Returns your membership snapshot, contributed active count, and network pool size.

Dashboard membership (session)

GET /api/v1/network/membership
PATCH /api/v1/network/membership

Authenticated with dashboard session (browser cookie after sign-in), not partner keys. Tenants may PATCH:

Field	Description
`contribute_enabled`	Opt-in to publish signals
`contribute_list_types`	Allow-list of types to publish (`null` = all 28)
`consume_list_types`	Allow-list of types to match in assess (`null` = all)
`min_trust_score`	0–100 — ignore contributors below this trust level

consume_enabled and integration_profile are managed by Clausum based on organization type and contract (CLM-ADD-NET-C).

Revoke signals (dashboard session)

GET /api/v1/network/signals?page=1&limit=25
PATCH /api/v1/network/signals
{ "id": "entry-uuid" }

Sets is_active = false for your organization’s entry. Also available in Intelligence → My signals.

Supported signal types (28)

Full catalog with assess field mapping: see engineering reference NETWORK_SIGNAL_CATALOG.md in the repo.

Group	`list_type` values
Identity	`national_id`, `customer_name`, `customer_id`, `beneficiary_name`
Contact	`email`, `email_domain`, `phone`
Payment	`bank_account`, `card_bin`, `card_hash`, `card_last4_bin`, `swift_bic`, `routing_number`, `wallet_address`
Device / network	`ip_address`, `ip_range`, `device_fingerprint`, `user_agent`, `session_id`, `imei`, `asn`, `country`
Location	`billing_postal`, `shipping_postal`, `address_hash`
Commerce	`merchant_domain`, `submerchant_id`, `mcc`

Assess mapping highlights

Assess field	Network `list_type`
`email`, `phone`, `customer_id`, `customer_name`	Same name
`payer_identity.document_number`	`national_id`
`payer_identity.imei`	`imei`
`beneficiary.clabe`, `iban`, `account_hash`, `origin.account_id`	`bank_account`
`beneficiary.name`	`beneficiary_name`
`device.ip`	`ip_address` (+ matches published `ip_range` CIDR)
`device.fingerprint`, `session_id`, `user_agent`, `asn`	Same name
`payment_method.card_bin`, `card_hash`	Same name
`merchant.domain`, `merchant.mcc`	`merchant_domain`, `mcc`
`submerchant_id`	`submerchant_id`

Escape hatch: send any catalog type via network_observations: [{ "list_type": "…", "value": "…" }] without waiting for new top-level assess fields.

{
  "amount": 150000,
  "currency": "MXN",
  "email": "payer@example.com",
  "payer_identity": { "document_number": "12345678-9" },
  "device": { "ip": "203.0.113.10" },
  "network_observations": [
    { "list_type": "bank_account", "value": "012180001234567890" }
  ]
}

Severity behavior: a peer signal with block can force decline during assess, similar to a local blocklist hit.

Entity Graph / CEG (`off` / `shadow` / `live`)

CEG is the premium extension of CIN — not a second product. When consume is enabled, assess can run a 1-hop relationship lookup over co-observed entities (e.g. bank account ↔ device ↔ email). It is incremental to exact match and aggregate — it does not replace them. Full checklist, CIN vs CEG table, and go-live path: Entity Graph (CEG).

`graph_assess_mode`	Effect
`off`	No graph lookup
`shadow` (default)	Returns `network_intelligence.graph` with weight 0; decision unchanged; compare via `shadow_would_decision`
`live`	Adds score; may force review / hard-block decline (≥2 independent sources required for hard-block)

Configure in Intelligence → Settings or Settings → Services → Entity Graph (dashboard session — not Partner API key).

graph_assess_mode is separate from CIN exact-match assess_mode (shadow / advisory / enforcement for peer list hits). Validate in shadow before enabling live on production traffic.

Never exposed: institution IDs, neighbor PII, reconstructable hashes. Lookup is 1 hop only, runs in parallel with exact CIN, fail-open ~400 ms.

Privacy and compliance

Data	Dashboard display	Cross-tenant matching
National ID, names, email, phone, bank accounts, fingerprints, card hashes	Safe masked labels only	Normalized / hashed
BIN, country, IP, IP range (CIDR), email domain, SWIFT, MCC	Plain labels	Plain normalized values

Contributor anonymity: other participants never see your institution name — only alias Participant INST-…. Clausum retains attribution internally for governance and trust scoring. Reason codes: use machine-readable reason_code (e.g. confirmed_fraud, mule_account). Optional reason_detail is stored for your org and Clausum ops — never returned to other tenants. Before contributing:

Confirm your legal / compliance team approves sharing each signal class (use contribute_list_types to restrict)
Document internal case IDs in reason_detail — not exposed to other tenants
Maintain a runbook to revoke false positives via Mis señales

Trust and consumption

Each contributor has a trust score (0–100). When consume is enabled, assess applies signals only from contributors at or above your min_trust_score (adjustable in Intelligence → Settings). Use consume_list_types to limit which signal classes you match during assess (e.g. identity + payment only, skip device signals). Dashboard Participantes lists anonymous contributor aliases with active contributions and whether they meet your threshold.

Bank integration patterns

Core banking / SPEI

Call assess synchronously in the authorization path before releasing funds:

Core receives transfer request
Middleware calls POST /api/v1/assess/payout
On decline → hold transfer, open case
On approve / review → follow your policy matrix (Assess resilience)

Pair with payout blocklists (flow_scope: payout) — Blocklists.

Fraud feed batch jobs

Schedule nightly or hourly jobs from your fraud warehouse:

Map internal tables → entries[]
Use stable external_ref per row for idempotent updates
Start with severity: review in UAT; promote to block after validation

Cases and regulatory workflow

Link high-severity network hits to Case management. Report fraud can complement bulk API for ad-hoc confirmations.

PSP integration patterns

Middleware owns orchestration

Clausum does not call Stripe, Mercado Pago, or your acquirer. Your PSP layer:

Receives payment attempt from sub-merchant checkout
Calls assess with submerchant_id
Branches on decision before capture

See architecture diagram in PSP integration.

Multi-tenant signal contribution

When contributing portfolio-level signals:

Avoid sub-merchant PII in reason_detail
Prefer BIN, IP, and velocity patterns over raw emails when possible
Separate sandbox and production keys per environment

Institutional add-ons

PSPs with treasury or disbursement products should also evaluate Payout assessment and Regulatory screening when on CLM-MOD-INST.

Managed feeds (CLM-ADD-INTEL)

When entitled, Clausum-operated threat feeds apply automatically during assess — no API setup. Check status in Dashboard → Protection (Intelligence Clausum strip). Staff syncs feeds on the platform side; tenants see signal counts and last sync time only. This layer is independent of the collaborative network — you may have one, both, or neither depending on contract.

Go-live checklists

Bank

SQL 044 + 144 + 145 applied in Supabase
Server key with assess + network:contribute
Contribution enabled in Intelligence → Settings; contribute_list_types agreed with legal
min_trust_score and optional consume_list_types configured
CLM-ADD-NET-C confirmed with account manager if consuming peer signals
Payout assess wired before SPEI/wire release (Bank integration)
UAT: publish test signal from staging org → verify assess match
Runbook for revoking false positives in Mis señales
Certification sign-off on cert.clausum.ai when provided

PSP

All active sub-merchants registered with stable external_id
Every assess includes submerchant_id when registry is non-empty
Middleware enforces decision before acquirer capture
Optional: contribution enabled + legal sign-off for aggregated signals
Webhook routing tested per sub-merchant
Sandbox UAT on sandbox.clausum.ai before production

Troubleshooting

Symptom	Check
`403 NETWORK_CONTRIBUTE_DISABLED`	Enable Contribute to network in Intelligence settings
Peer signals never match	Confirm CLM-ADD-NET-C active; check trust threshold with account manager
`401` on network API	Use `clm_sk_` with `network:contribute`, not `clm_wh_`
Assess works but no network layer	Consumption is contract-gated — managed intel and local rules still apply
Duplicate signals	Use consistent normalization; revoke old entry in Mis señales

Bank integration

Payout-first institutional plan

PSP integration

Sub-merchant routing plan

Real-time assess

Pay-in API

Payout assess

Disbursement API

API keys

Permissions and prefixes

Capabilities

Module catalog by segment

Support: api@clausum.ai

​Who this guide is for

​How it fits your stack

​Quick start — bank (5 steps)

​Quick start — PSP (5 steps)

​API reference

​Publish signals

​Network stats (partner)

​Dashboard membership (session)

​Revoke signals (dashboard session)

​Supported signal types (28)

​Assess mapping highlights

​Entity Graph / CEG (off / shadow / live)

​Privacy and compliance

​Trust and consumption

​Bank integration patterns

​Core banking / SPEI

​Fraud feed batch jobs

​Cases and regulatory workflow

​PSP integration patterns

​Middleware owns orchestration

​Multi-tenant signal contribution

​Institutional add-ons

​Managed feeds (CLM-ADD-INTEL)

​Go-live checklists

​Bank

​PSP

​Troubleshooting

​Related guides

Bank integration

PSP integration

Real-time assess

Payout assess

API keys

Capabilities

Who this guide is for

How it fits your stack

Quick start — bank (5 steps)

Quick start — PSP (5 steps)

API reference

Publish signals

Network stats (partner)

Dashboard membership (session)

Revoke signals (dashboard session)

Supported signal types (28)

Assess mapping highlights

Entity Graph / CEG (`off` / `shadow` / `live`)

Privacy and compliance

Trust and consumption

Bank integration patterns

Core banking / SPEI

Fraud feed batch jobs

Cases and regulatory workflow

PSP integration patterns

Middleware owns orchestration

Multi-tenant signal contribution

Institutional add-ons

Managed feeds (CLM-ADD-INTEL)

Go-live checklists

Bank

PSP

Troubleshooting

Related guides