Historical Migration Mode

Import a large existing database (e.g. 150k contacts from a CRM export) without consuming your monthly plan quota. Day-to-day operations after migration still use your normal plan limits (Starter, Pro

When to use it

Scenario	Use migration mode?
One-time CSV/JSON import of historical PII	✅ Yes
Ongoing tokenization in production (forms, APIs)	❌ No — use a standard API key
GDPR full export when leaving Veilio	❌ No — export is already quota-free

How it works

1. Activate migration from the dashboard (/dashboard/onboarding → « Migration mode » card, or POST /api/onboarding/migration).
2. Veilio creates a one-shot budget on your subscription: migrationAllowance, migrationTokensUsed, migrationExpiresAt.
3. A dedicated API key with purpose = MIGRATION is generated (shown once).
4. Requests signed with this key (or dataset uploads with migration=true) consume the migration budget, not monthly tokens/requests.
5. When the budget is exhausted or expired, migration calls are rejected explicitly (no silent fallback to monthly quota).

Option A — Reusable script (veilio-migrate.mjs)

Download from your app (no login required):

curl -O https://app.veilio.xyz/veilio-migrate.mjs

Run on a CSV export:

export VEILIO_API_KEY="sk_..._MIGRATION_KEY"
export VEILIO_BASE_URL="https://app.veilio.xyz"

node veilio-migrate.mjs \
  --in customers.csv \
  --out customers.tokenized.csv \
  --columns email,phone,full_name \
  --types email=email,phone=phone \
  --entity-id-col customer_id \
  --retention-days 3650 \
  --batch 100 \
  --resume

Flag	Description
--columns	Comma-separated sensitive columns to tokenize
--types	Optional col=type mapping (email, phone, …)
--entity-id-col	Business id column kept in clear (for entityId / profile grouping)
--resume	Resume from last checkpoint after interruption
--dry-run	Parse only, no API calls

The script uses POST /api/tokenize/bulk with your migration key and backs off on HTTP 429.

Option B — Dataset upload (dashboard)

1. Create an organization (required for team sharing; optional for solo import).
2. Upload CSV/JSON from Datasets with migration mode enabled (migration=true on the upload API).
3. Cell count is debited from the migration budget after successful tokenization.

API behaviour with a migration key

Endpoint	Monthly quota	Migration budget
POST /tokenize, /bulk, /format	Skipped	Consumes tokens created
POST /flows/ingest	Skipped	Consumes tokens created
POST /detokenize (migration key)	Skipped	Not consumed (no new tokens)
POST /datasets with migration=true	Skipped	Consumes tokenized cells

Standard keys (purpose = STANDARD) always use monthly plan limits.

Check migration status

Authenticated dashboard or API:

GET /api/onboarding/migration

Response includes allowance, used, remaining, expiresAt, and active migration keys (prefix only).

Requirements

• Active paid plan (Starter, Pro, or Enterprise) — migration is not available on Freemium.
• Organization OWNER or DPO to activate.
• Plan your migrationAllowance to cover worst-case cell count (non-empty cells in the export).