Partner connector configuration

Connector

One profile, many channels — webhooks, API, and CSV ingest attributed per trust context.

Audience: trust producers configuring ingest on PTI.

Outcomes

Register producer profile and enable trust contexts
Configure webhook URL, credentials, and event catalog
Send first live event and confirm processing in Pulse
Attribute usage by ingest channel and MTD TCU per context

Your connector is the single integration profile for your organization on TumiTrust Portable Trust Infrastructure (PTI). One partner ID, many trust contexts, multiple ingest channels — webhook, API, and CSV — all attributed for billing and Pulse visibility.

This guide describes what you configure in the hub and which APIs are available. For machine-readable schemas, use OpenAPI at tumitrust.com/api/docs/.

Before you start

Prerequisite	Where
Trust producer account	Trust producer registration
Institution hub access	`/institution/<your-slug>/dashboard/`
Partner ID assigned	Shown in Partner operations and Connector
At least one trust context enabled	Trust contexts for producers

Hub surfaces

Surface	In your hub	Purpose
Partner operations	Sidebar → Partner operations	Live health, ingest funnel, usage, event feed
Connector settings	Partner operations → Connector	Webhook URL, credentials, delivery, signal policy
Event catalog	Partner operations → Event catalog	Event types, trigger rules, impact preview
Data upload studio	Partner operations → Data upload	CSV bulk ingest with validation
Pulse	Sidebar → Trust intelligence (Pulse)	Context-scoped charts, Insight Studio

Architecture at a glance

Your platform                          TumiTrust PTI
─────────────                          ─────────────
 Webhook POST  ──────────────────────►  /api/v1/partner/webhooks/{partner_id}/
 API / connector sync ─────────────────►  /api/v1/partners/{partner_id}/connector/
 CSV upload (hub)  ───────────────────►  institution ingest APIs
        │                                        │
        └──────── trust events ─────────────────►│──► signals ──► scores ──► outcomes
                                                 └──► TCU meter (per context)

Every accepted event is recorded as a trust event, validated against your enabled contexts and event catalog, then processed into portable trust outcomes for the subjects you link.

Step 1 — Register your producer profile

After institution signup as a trust producer, complete onboarding:

Company — organization name and country
Partner — choose partner_id, producer type (commerce, lending, telecom, …)
Contexts — select every trust context you will emit from the documented context IDs (primaries you produce; lenses only when your contract covers direct emission)
Technical — optional webhook URL for your own callbacks
Plan — billing tier (sandbox tiers may waive TCU)

On completion, your tenant links to a partner profile with one or more enabled trust contexts.

API (session auth): POST /institution/<slug>/api/partner/register/
Body may include contexts[] and primary_context.

Step 2 — Configure trust contexts

One partner profile per organization supports multiple trust contexts.

Action	API
List contexts + ingest channel status + MTD TCU	`GET /institution/<slug>/api/partner/trust-contexts/`
Enable contexts, set primary, entity types	`PATCH /institution/<slug>/api/partner/trust-contexts/`

Each context row controls:

Which event types may target that context (via trigger rules)
Headline score selection (is_primary)
Ingest channels enabled: webhook, API, CSV (on the shared connector profile)

See Trust contexts for producers for the full context list and confirmation checklist.

Step 3 — Event catalog

Before traffic flows, define what you send:

Concept	Meaning
Event type	Stable slug (`order_completed`, `repayment_on_time`, …)
Trigger rule	Maps event → signal(s) and affected `context_ids`
Impact	Positive / negative / neutral (drives Pulse sentiment)
Sample payload	Documents expected JSON fields for integrators

Hub: Partner operations → Event catalog (edit, preview impact, sync to connector).

API:

Method	Path	Purpose
`GET`	`/institution/<slug>/api/partner-operations/event-catalog/`	Full catalog
`PATCH`	same	Update definitions and rules
`POST`	`…/event-catalog/preview/`	Dry-run impact for a sample payload
`POST`	`…/event-catalog/sync-connector/`	Push topics to connector profile

Confirmation: Run preview for each new event type before enabling in production. The preview shows affected contexts and signal paths without persisting data.

Step 4 — Connector profile (webhook & API)

Open Connector settings in the hub. Panels:

Ingest endpoint

Webhook URL (TumiTrust receives):
POST /api/v1/partner/webhooks/{partner_id}/
Authentication (canonical) — HMAC-SHA256 over the raw JSON body, hex digest in:
```
X-Partner-Signature: <hmac_sha256_hex(raw_body, webhook_secret)>
Content-Type: application/json
```
Legacy alias x-tumitrust-signature is accepted. Do not send a shared-secret header named X-TumiTrust-Webhook-Secret — that is not part of the contract.
Idempotency — send a stable idempotency_key per logical event; duplicates are acknowledged without double-charging processing where applicable
Integrator fan-out — post to the integrator partner_id and set X-Client-Partner-Id (or body client_partner_id). See Integrator guide.

Delivery & emit

Outbound channels when trust outcomes are ready (webhooks back to your platform, optional writeback). Configure emit channels in the connector profile via:

GET/PATCH /api/v1/partners/{partner_id}/connector/

Signal policy

Per context, which signal sources are allowed (partner events, verification, native user contributions). Policy is enforced when events are processed — misaligned sources are rejected or down-ranked per your configuration.

Credentials

Secrets are write-only in the hub (masked previews only). Rotate via connector PATCH; never commit secrets to tickets or docs.

Step 5 — Send your first event (webhook)

Minimal canonical shape:

{
  "event_type": "order_completed",
  "partner_entity_id": "store-abc-123",
  "occurred_at": "2026-06-25T12:00:00Z",
  "payload": {
    "order_value": 42.50,
    "currency": "USD"
  },
  "idempotency_key": "your-unique-key-per-event"
}

Optional rail fields (indexed for Pulse filters): channel (ussd|sms|app|…), program (agency|fisp|…).

Sign and POST (Python sketch):

import hmac, hashlib, json, requests

body = json.dumps(event, separators=(",", ":"), ensure_ascii=False).encode()
sig = hmac.new(webhook_secret.encode(), body, hashlib.sha256).hexdigest()
requests.post(
    f"{BASE}/api/v1/partner/webhooks/{partner_id}/",
    data=body,
    headers={
        "Content-Type": "application/json",
        "X-Partner-Signature": sig,
    },
    timeout=30,
)

Sign the exact bytes you send. Re-serializing after signing will fail verification.

Confirm success:

Partner operations — Activity today increments; connector health stays green
Pulse → Insight Studio — event appears with context and pipeline status
Metrics poll — GET /institution/<slug>/api/partner-operations/metrics/ shows ingest breakdown by channel

HTTP responses: 2xx with event id on accept; 4xx with validation detail on reject (unknown context, disabled event type, etc.).

Step 6 — Health & operations

Signal	Where to look
Connector down	Partner operations → Data connection status
Failed events	Pulse Insight Studio → status filter Failed
TCU burn	Partner operations TCU ring; CSV upload guide for batch attribution
Per-context load	Pulse context switcher; billing TCU breakdown API

Poll endpoint (session): GET /institution/<slug>/api/partner-operations/metrics/

Embeds & screening

Partners typically place these in their LOS / CRM — not inside the TumiTrust console.

Surface	URL / API	Notes
Trust card (iframe)	`GET /embed/v1/{partner_id}/{context_id}/{entity_id}/`	Public frame; use canonical context ids (`lending`, `agricultural`, …). Frame is clickjacking-exempt for partner origins.
Curated showcase	`GET /embed/demo/{slug}/`	Demo studio presets (e.g. Wirepick bank/agri).
Screening token	`POST /api/v1/partner/embed/screening/{partner_id}/token/`	Auth: `X-Partner-API-Key`. Returns `embed_token`.
Screening iframe	`GET /embed/v1/screening/{partner_id}/?embed_token=…`	Mint token server-side; never put partner secrets in the browser.

context_id must match an enabled trust context. Prefer the ids from Trust contexts for producers — e.g. agricultural, not agriculture.

Explain / decision APIs (keyed): GET /api/v1/pti/explain/{pti_id}/ with X-Partner-API-Key.

API quick reference (producer)

Job	Endpoint
Ingest (webhook)	`POST /api/v1/partner/webhooks/{partner_id}/` · header `X-Partner-Signature`
Connector config	`GET/PATCH /api/v1/partners/{partner_id}/connector/`
Event definitions	`GET/PATCH /api/v1/partners/{partner_id}/events/`
Explain score	`GET /api/v1/pti/explain/{pti_id}/` · `X-Partner-API-Key`
Trust card embed	`GET /embed/v1/{partner_id}/{context_id}/{entity_id}/`
Screening token	`POST /api/v1/partner/embed/screening/{partner_id}/token/`
Trust contexts (hub)	`GET/PATCH /institution/<slug>/api/partner/trust-contexts/`
Billing TCU	`GET /institution/<slug>/api/partner-operations/billing/tcu/`

Full API reference: OpenAPI at tumitrust.com/api/docs/.

Checklist — production readiness

Partner ID and enabled contexts configured in Partner Operations
Event catalog complete; preview run for each event type
Webhook credentials stored securely; signature verification enabled
Idempotency keys implemented on your sender
Primary context set for headline scores
TCU quota and billing details configured in Billing
CSV path tested in sandbox if you use bulk backfill (CSV guide)
Pulse Insight Studio reviewed with your team

Outcomes​

Before you start​

Hub surfaces​

Architecture at a glance​

Step 1 — Register your producer profile​

Step 2 — Configure trust contexts​

Step 3 — Event catalog​

Step 4 — Connector profile (webhook & API)​

Ingest endpoint​

Delivery & emit​

Signal policy​

Credentials​

Step 5 — Send your first event (webhook)​

Step 6 — Health & operations​

Embeds & screening​

API quick reference (producer)​

Checklist — production readiness​

Related guides​