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​