How to import CSV files in Strapi

5 min read
Learn how to build a CSV import feature in Strapi. Step-by-step guide for developers integrating spreadsheet uploads in SaaS applications.

How to Import CSV Data into Strapi Using CSVBox

Developers using Strapi for content or backend management often face the challenge of importing structured data—especially from spreadsheets. Whether you’re migrating existing records or building a tool for non-technical editors, enabling CSV import functionality streamlines operations by reducing manual work.

This tutorial walks you through how to integrate CSV file uploads into a Strapi application using CSVBox—a powerful widget that handles CSV validation, uploads, and webhooks with ease.

Why Add a CSV Import Feature to Strapi?

Strapi doesn’t natively support user-facing CSV uploads. This can be a bottleneck in scenarios such as:

  • Onboarding users who need to import data in bulk
  • Migrating legacy spreadsheets into Strapi collections
  • Empowering non-technical users to update content via files

Building a custom importer requires frontend UI, data validation, webhook handling, and security. CSVBox simplifies the entire workflow.

🔹 Real-world use cases:

  • A marketplace admin importing product catalogs
  • HR platforms ingesting candidate lists
  • SaaS teams allowing clients to upload customer or order data

What Is CSVBox and Why Use It?

CSVBox is a drop-in CSV import widget that helps you:

  • Validate spreadsheet structure before data is sent to your API
  • Set required columns and custom formats
  • Preview uploads with user feedback
  • Send structured JSON via secure webhook to your backend

👍 CSVBox saves 3–5 days of development time for each import feature you’d otherwise have to build manually.

Step-by-Step: How to Integrate CSV Import in Strapi

1. Create or Use an Existing Strapi Project

If you’re starting from scratch:

npx create-strapi-app my-project --quickstart
cd my-project
npm run develop

Ensure Strapi server is running at http://localhost:1337.

2. Create an Import Endpoint in Strapi

You’ll need a custom controller to receive the incoming data via webhook.

Generate a controller (e.g., upload):

yarn strapi generate:controller upload

Update src/api/upload/controllers/upload.js:

'use strict';

module.exports = {
  async import(ctx) {
    const { rows } = ctx.request.body;

    for (const row of rows) {
      await strapi.services['YOUR_COLLECTION_NAME'].create({
        data: row
      });
    }

    return { status: 'ok', imported: rows.length };
  }
};

🔁 Replace YOUR_COLLECTION_NAME with your actual collection name—e.g., products, users.

3. Add a Custom Route

Define a POST route in src/api/upload/routes/upload.js:

module.exports = {
  routes: [
    {
      method: 'POST',
      path: '/upload/import',
      handler: 'upload.import',
      config: { policies: [] }
    }
  ]
};

Restart the server to apply route changes.

✅ Pro Tip: Make sure this route is exposed to the public or your authenticated roles, depending on your auth strategy.

4. Configure CSVBox and Create a Widget

Head to the CSVBox Dashboard:

  1. Create a new widget (e.g., “User Import”)
  2. Define expected CSV columns (e.g., name, email, age)
  3. In the upload settings, set the webhook to:
http://localhost:1337/api/upload/import
  1. Use POST method and enable JSON payload delivery

CSVBox will now send validated spreadsheet data to your Strapi backend.

5. Embed CSVBox Into Your Frontend

You can launch the widget from any frontend—React, Vue, Svelte, or plain HTML.

Example using standard HTML/JS:

<script src="https://widget.csvbox.io/widget.js"></script>

<button onclick="launchCSVBox()">Import Users</button>

<script>
  function launchCSVBox() {
    CSVBox.show({
      licenseKey: "your-widget-license-key",
      user: {
        user_id: "123",
        name: "Admin User"
      }
    });
  }
</script>

📌 Replace licenseKey with the one shown in your CSVBox dashboard.

Backend Code Reference (Error-Handled)

Here’s a more robust controller with error handling:

module.exports = {
  async import(ctx) {
    const { rows } = ctx.request.body;

    try {
      for (const row of rows) {
        await strapi.entityService.create('api::product.product', {
          data: row
        });
      }
      return { status: 'success', imported: rows.length };
    } catch (error) {
      console.error('CSV Import Failed:', error);
      ctx.throw(500, 'Failed to process CSV data');
    }
  }
};

👀 Make sure roles have permission to access POST /upload/import under Settings → Roles & Permissions.

Troubleshooting Guide

Here are common issues and how to fix them:

❌ 403 Forbidden on Import

  • Check public or authenticated role permissions in Strapi admin.
  • Ensure CSVBox is pointing to the correct endpoint.

❗ Undefined rows in Payload

  • Confirm CSVBox is sending data as JSON.
  • Don’t forget to enable Webhook Payload in your widget settings.

🌐 CORS Errors

If embedding CSVBox from a different domain (e.g., frontend on localhost:3000):

Update your Strapi middleware in config/middlewares.js:

module.exports = [
  'strapi::body',
  {
    name: 'strapi::cors',
    config: {
      origin: ['http://localhost:3000'],
      credentials: true
    }
  }
];

CSVBox vs Manual CSV Upload: Key Advantages

✔️ Ready-made UI with drag-and-drop CSV uploading

✔️ Built-in column mapping and preview

✔️ Backend integration via JSON webhook

✔️ No need to write custom CSV parsers or file handlers

✔️ Secure submissions and audit tracking

CSVBox handles all the “boring but important” parts of CSV import.

Example Use Cases That Benefit from This Setup

  • SaaS dashboard where customers import user data
  • Internal CMS tools updating product listings
  • Admin panels managing city/state/country metadata
  • LMS platforms onboarding course enrollments via CSV

Whether you’re a solo founder or enterprise team, this workflow makes structured data import manageable and scalable.

Expand and Secure Your Import Feature

Ways to extend your CSV import:

  • 🛡️ Add JWT or token-based protection to your import route
  • 🧠 Normalize and transform data before saving
  • ⏱️ Throttle uploads to prevent spike loads
  • 🔀 Use separate widgets for each entity type (products, customers)

Explore the Strapi documentation and CSVBox guides for more advanced patterns.

Final Thoughts

A reliable CSV import pipeline is essential for running smooth content operations. With Strapi as your headless CMS and CSVBox as the import layer:

  • ✅ You empower users to bulk upload content safely
  • ✅ You avoid building and maintaining custom upload UIs
  • ✅ You reduce dev time and technical complexity

Whether you’re managing e-commerce data, CRM information, or editorial content, this integration offers a fast, user-friendly path to importing structured data into Strapi.

📘 See canonical guide: CSVBox → Strapi Integration

🔎 Need more help?

Explore:

  • CSV Validator Tools
  • Webhook Debuggers
  • JSON Formatter for Payload Inspection

Happy importing!

#frameworks

Related Posts