CSV data upload studio

Bulk ingest

Validate → confirm → batch — historical rows with the same event catalog and TCU rules as webhooks.

Audience: partner teams importing historical activity via CSV.

Outcomes

Select one context per batch and download a partner-specific template
Validate rows and see estimated TCU before confirm
Track batch status and open Pulse filtered by batch_id
Attribute ingest to ingest_channel=csv in billing breakdowns

The Data upload studio is TumiTrust’s bulk ingest path for trust producers. It mirrors the rigor of webhook ingest — same event catalog, same context rules, same TCU meter — with a guided validate → confirm → ingest flow so operations teams can backfill or migrate data without guessing.

Hub path: /institution/<slug>/partner-operations/ingest/
Sidebar: Operations → Data upload

When to use CSV vs webhook

Channel	Best for
Webhook	Real-time order, repayment, verification events
API / connector sync	Scheduled pulls from your systems
CSV upload	Historical backfill, one-off migrations, ops batches, integration testing

Every CSV row becomes a trust event tagged with source=csv, a batch_id, and a context_id — visible in Pulse ingest funnels and billing breakdowns.

The five-step studio

 ① Context          ② Upload           ③ Map & validate      ④ Ingest           ⑤ Results
 pick trust    →   drag-drop CSV   →   column map +       →   background       →   batch status
 context           UTF-8 header       error table            processing         Pulse deep-link

Step 1 — Select producer trust context

Choose one enabled context per batch from your partner profile — any of the documented trust contexts you have enabled (e.g. merchant, lending, mobility). Cards show primary badge and entity type.

After you pick a context, the studio shows a CSV template panel with:

Column headers for that context (required columns highlighted)
Allowed event_type values from your catalog
A live preview of example rows
Download CSV template — file name {partner_id}-{context_id}-trust-events-template.csv

Templates are generated per partner and context from your event catalog (not a single static file). A minimal three-column reference is also available in the studio.

Template CSV: GET /institution/<slug>/api/partner-operations/ingest/template/?context=<id>
Template JSON (columns + preview): same URL with &format=json

Step 2 — Upload CSV

Drag-and-drop or file picker
UTF-8 with header row required
Typical size limits are shown in the upload studio for your plan; split very large files into multiple batches

Step 3 — Map columns & validate (dry-run)

Click Validate & preview. The studio calls:

POST /institution/<slug>/api/partner-operations/ingest/preview/
(multipart: context_id, file, optional column_map JSON)

You see:

Panel	Content
KPI strip	Valid rows, errors, estimated TCU for this batch
Column mapping	Map `event_type`, `partner_entity_id`, `occurred_at` to your file headers
Event histogram	Count per `event_type` among valid rows
Error table	Row number, field, message
Sample rows	First valid rows before commit

Re-validate after changing column mapping — no data is written until you confirm.

Column map example (form field column_map):

{
  "event_type": "EventType",
  "partner_entity_id": "StoreId",
  "occurred_at": "Timestamp"
}

Step 4 — Confirm ingest

Click Confirm ingest. The studio:

Re-runs validation server-side
Creates an ingest batch record
Queues async processing
Shows a progress bar

API: POST /institution/<slug>/api/partner-operations/ingest/csv/
Returns batch_id, task_id, tcu_estimate, and pulse_filter_url.

Step 5 — Results & confirmation

When the batch completes:

Status	Meaning
`completed`	All valid rows ingested
`partial`	Some rows failed; see error report
`failed`	No rows ingested
`processing`	Still running — poll job API

Poll batch:

GET /institution/<slug>/api/partner-operations/ingest/jobs/<batch_id>/

Response includes ingested_count, duplicate_count, error_count, tcu_accrued, and errors[].

Open Pulse — link filters Insight Studio to source=csv and batch_id for audit.

CSV format

Required columns

Column	Description
`event_type`	Must exist in your event catalog for the chosen context
`partner_entity_id`	Your stable subject key (store id, subscriber id, …)
`occurred_at`	ISO-8601 timestamp (UTC recommended)

Optional payload columns

Additional columns become JSON payload fields (e.g. order_value, currency). The template generator includes keys from your catalog sample payloads for the selected context.

Example

event_type,partner_entity_id,occurred_at,order_value,currency
order_completed,store-1001,2026-06-25T10:00:00Z,29.99,USD
repayment_on_time,merchant-acct-88,2026-06-24T15:30:00Z,150.00,USD

TCU and billing

CSV ingest consumes Trust Compute Units (TCU) per successfully ingested row (ingest operation), attributed to:

partner_id
context_id
ingest_channel=csv
batch_id (metadata)

The studio shows estimated TCU before confirm; the batch job returns actual TCU accrued after processing. Period totals and per-context breakdowns appear in Partner operations and:

GET /institution/<slug>/api/partner-operations/billing/tcu/
GET /institution/<slug>/api/partner-operations/billing/tcu/breakdown/

Batch history

The studio lists recent ingest batches (time, context, status, rows, TCU). Refresh via:

GET /institution/<slug>/api/partner-operations/ingest/batches/

Use batch IDs in support tickets — not raw PII from CSV files.

Idempotency & duplicates

Each row receives a unique idempotency key so duplicate uploads in the same batch are skipped.

Re-uploading the same logical event in a new batch may create a duplicate acknowledgment if the same business key was already processed via webhook. Design backfills to use consistent partner_entity_id + event_type + occurred_at semantics.

Error handling playbook

Symptom	Likely cause	Fix
Unknown `event_type`	Catalog gap	Add event + trigger rule; sync connector
Context rejected	Context disabled	Enable via trust-contexts API
Invalid `occurred_at`	Format	Use ISO-8601
Zero valid rows	Header mismatch	Use column mapping + re-validate
Partial batch	Mixed good/bad rows	Fix errors; upload corrected rows in new batch

Security & compliance (public guidance)

Upload only data you are contractually permitted to share with TumiTrust
Use institution session auth — do not embed API keys in browser extensions
Rotate credentials if a CSV with secrets was attached to a ticket
Prefer webhook ingest for ongoing real-time flows; CSV for batch boundaries

API summary

Method	Path	Purpose
`GET`	`…/ingest/template/?context=`	Download CSV template
`GET`	`…/ingest/template/?context=&format=json`	Template columns + preview (JSON)
`POST`	`…/ingest/preview/`	Dry-run validation
`POST`	`…/ingest/csv/`	Confirm ingest
`GET`	`…/ingest/jobs/<batch_id>/`	Batch status
`GET`	`…/ingest/batches/`	Recent batches

Outcomes​

When to use CSV vs webhook​

The five-step studio​

Step 1 — Select producer trust context​

Step 2 — Upload CSV​

Step 3 — Map columns & validate (dry-run)​

Step 4 — Confirm ingest​

Step 5 — Results & confirmation​

CSV format​

Required columns​

Optional payload columns​

Example​

TCU and billing​

Batch history​

Idempotency & duplicates​

Error handling playbook​

Security & compliance (public guidance)​

API summary​

Related​