Import and reconcile grants

CSV upload

Use the dashboard CSV template. Uploads are limited to 25 MiB and 100,000 rows. Required columns are email, benefit_key, and granted_at with timezone; add external_user_id and external_grant_id for stable matching. Review validation results and explicitly confirm the target environment.

Bulk API

Send up to 1,000 grants per request. Use a stable external grant ID and include claim_id when reconciling an existing authorization. Import jobs process bounded batches and tolerate duplicate delivery. The same external ID cannot refer to another recipient or benefit.

curl https://veltor.tech/v1/imports \
  -H "Authorization: Bearer $VELTOR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: outage_batch_123" \
  --data '{"grants":[{"external_grant_id":"grant_123","claim_id":"signup_customer_123","benefit":"signup_credits","subject":{"external_id":"customer_123","email":"alex@example.com"},"granted_at":"2026-01-01T12:00:00Z"}]}'

Fallback matching

Without an external grant ID, Veltor derives one from benefit, recipient, and exact grant timestamp. Changing a timestamp can create another record. Prefer your own durable grant IDs, especially when imports overlap live traffic.