Skip to content
TruthVouch Docs

Bulk Import

Bulk Import lets you add dozens or hundreds of Truth Nuggets at once using CSV or JSON files. This is ideal for:

  • Initial setup with 50-500 facts
  • Migrating from other systems
  • Launching new products with pre-created facts
  • Regular batch updates

CSV Format

The easiest format. Create a CSV file with these columns:

ColumnRequiredFormatExample
factYesText”Founded in 2024”
categoryNoCompany/Products/Leadership/Financial/Technical/Legal/Competitive”Company”
confidenceNo0.0-1.0”0.95”
source_urlNoFull URL”https://your-site.com/about”
expires_atNoYYYY-MM-DD”2026-12-31”
tagsNoComma-separated”public,verified,2024-Q4”

CSV Example

fact,category,confidence,source_url,expires_at,tags
"Founded in 2024",Company,1.0,https://your-site.com/about,,public
"CEO: Sarah Chen",Leadership,0.95,https://your-site.com/team,,public
"Shield monitors 9+ AI engines",Products,0.95,https://your-site.com/products,,"public,marketing"
"Q4 2025 ARR: $8M",Financial,1.0,https://internal.company.com/financials,2026-03-31,confidential
"API response time <200ms p95",Technical,0.95,https://your-site.com/benchmarks,,verified

Download Template

  1. Go to Knowledge Base → Truth Nuggets
  2. Click Import → Download CSV Template
  3. Opens Excel/Google Sheets compatible template
  4. Fill in your facts
  5. Save as CSV

JSON Format

For programmatic imports or complex data:

[
  {
    "fact": "Founded in 2024",
    "category": "Company",
    "confidence": 1.0,
    "source_url": "https://your-site.com/about",
    "expires_at": null,
    "tags": ["public", "verified"]
  },
  {
    "fact": "Q4 2025 ARR: $8M",
    "category": "Financial",
    "confidence": 1.0,
    "source_url": "https://internal.company.com/financials",
    "expires_at": "2026-03-31",
    "tags": ["confidential", "time-sensitive"]
  }
]

Required fields: fact Optional fields: category, confidence, source_url, expires_at, tags

Importing Your File

Step 1: Prepare File

Ensure your CSV/JSON is valid:

  • No blank fact rows
  • Dates in YYYY-MM-DD format
  • Confidence between 0.0 and 1.0
  • Valid categories (or leave blank for “Uncategorized”)

Step 2: Open Importer

  1. Go to Knowledge Base → Truth Nuggets
  2. Click Import button
  3. Choose CSV or JSON

Step 3: Upload & Preview

  1. Select your file (or paste JSON)
  2. System validates format
  3. Preview shows first 10 rows and any errors

Examples of validation:

  • Missing required “fact” field → Error
  • Invalid confidence value → Shows in preview with warning
  • Unknown category → Defaults to “Uncategorized”

Step 4: Review & Adjust

See import summary:

  • Total nuggets: 47
  • Valid: 46
  • Warnings: 2 (invalid confidence values)
  • Errors: 0

Click Review Problems to fix specific rows, or proceed with auto-correction.

Step 5: Import

Click Import 46 Nuggets. System creates them all at once.

Progress bar shows import status. You can close the page; import completes in background.

Step 6: Verify

Once complete:

  • Email confirmation
  • Dashboard shows “47 nuggets created in last 24h”
  • View newly created nuggets filtered by import date

Batch Updating

Re-import to update existing nuggets. The system matches by exact fact text:

Original nugget:

Fact: "Founded in 2024"
Confidence: 1.0

Updated import:

Fact: "Founded in 2024"
Confidence: 0.95
Expires_at: "2026-01-01"

Result: Nugget updated (confidence lowered, expiry added). Alerts referencing the nugget use new confidence immediately.

Migration from Other Systems

From Existing Lists

If you have a spreadsheet of facts:

  1. Ensure columns match CSV format above
  2. Add category and confidence as needed
  3. Import via bulk uploader

From Competitor Products

Export facts from other tools (if available) and reformat to CSV:

  1. Export to CSV/JSON from source
  2. Map columns to TruthVouch format
  3. Fill missing confidence/source URLs (optional)
  4. Import

From Internal Wikis

Copy facts from Notion, Confluence, GitHub Wiki:

  1. Export as text or markdown
  2. Parse into CSV (fact per row)
  3. Add categories manually or in bulk
  4. Import

API-Based Import

For continuous integration with other systems, use the Trust API:

from truthvouch import TruthVouchClient


client = TruthVouchClient(api_key="your-key")


nuggets = [
    {
        "fact": "Founded in 2024",
        "category": "Company",
        "confidence": 1.0,
        "source_url": "https://your-site.com/about"
    },
    # ... more nuggets
]


client.knowledge_base.create_bulk(nuggets)

See Trust API docs for full details.

Troubleshooting

Import fails validation

Check:

  • CSV has “fact” column (required)
  • Dates are YYYY-MM-DD
  • Confidence values are between 0.0 and 1.0
  • No Unicode errors (save CSV as UTF-8)

Some rows import, some fail

System imports valid rows, skips invalid ones. Review error report for problematic rows.

Need to undo import

Import creates versioned snapshots. Go to Knowledge Base → Version History, select the commit before import, and click Restore. (Available in Professional+ tiers)

Duplicates created

If you re-import with exact same facts:

  • Old nuggets stay in history
  • New import creates new nuggets with same text
  • Use deduplication tool to merge: Knowledge Base → Tools → Find Duplicates

Best Practices

  1. Start small: Import 10-20 facts, verify quality, then bulk import rest
  2. Use source URLs: Every fact should link to where it came from
  3. Set confidence appropriately: Don’t mark estimates as 1.0
  4. Batch similar facts: Import all Products together, all Financial together
  5. Version your imports: Save CSV with date (facts_2026-03-01.csv)
  6. Schedule recurring: If facts change quarterly, schedule quarterly imports
  7. Add metadata: Use tags to track import source or review status

Next Steps