csvbox.io for CSVbox

Posted on May 22

Import Excel to GraphQL API

#api #excel #graphql #import

If your SaaS product team or development stack uses a GraphQL API, you’ll eventually face a common challenge: users want to upload Excel spreadsheets and push that data into your system. However, bridging the gap between semi-structured Excel files and structured GraphQL endpoints can be tricky.

This guide walks you through the process step by step — and then shows you how CSVBox makes Excel-to-GraphQL import seamless and user-friendly.

Introduction to the topic

Many systems today expose APIs for external integrations. GraphQL is increasingly preferred over REST because of its flexibility and powerful querying capabilities. But what happens when a user wants to import a dataset — often in Excel (XLS/XLSX or CSV) — into your GraphQL-powered application?

Maybe you're building:

An HR platform that lets recruiters bulk upload candidate profiles
A marketing dashboard that takes campaign data via spreadsheet
A no-code tool that connects user submissions to GraphQL endpoints

In all these scenarios, importing Excel via a GraphQL API becomes a critical integration. And while GraphQL offers querying expressiveness, it doesn't natively support file uploads or spreadsheet parsing.

That’s where an intermediary like CSVBox becomes invaluable.

Step-by-step: How to achieve the task

Here’s a step-by-step guide on how to import Excel data via a GraphQL API. We cover both the manual method and the streamlined CSVBox workflow.

1. Convert Excel to JSON or CSV

GraphQL APIs accept JSON input — but users won’t upload JSON; they’ll upload Excel.

You’ll need to:

Convert XLS/XLSX files to JSON or CSV (depending on your backend process).
Parse the spreadsheet rows into objects that match your GraphQL mutations.

You can use client-side libraries like:

npm install xlsx

Sample conversion code:

import * as XLSX from 'xlsx';

function excelToJson(file) {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = (e) => {
      const data = e.target.result;
      const workbook = XLSX.read(data, { type: 'binary' });
      const firstSheet = workbook.SheetNames[0];
      const excelRows = XLSX.utils.sheet_to_json(workbook.Sheets[firstSheet]);
      resolve(excelRows);
    };
    reader.onerror = reject;
    reader.readAsBinaryString(file);
  });
}

2. Prepare GraphQL Mutation

Assuming each row represents an Item, prepare a GraphQL mutation like:

mutation BulkCreateItems($input: [ItemInput!]!) {
  bulkCreateItems(input: $input) {
    id
    status
  }
}

You’ll need to match each spreadsheet row to the input schema expected by your GraphQL server.

3. Post Data to the GraphQL Endpoint

Use a tool like Apollo Client or fetch directly:

async function uploadData(rows) {
  const mutation = `
    mutation BulkCreateItems($input: [ItemInput!]!) {
      bulkCreateItems(input: $input) {
        id
      }
    }
  `;

  const response = await fetch('/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: mutation,
      variables: {
        input: rows,
      },
    }),
  });

  return response.json();
}

4. Add Validation & Feedback

You'll want to handle:

Field mismatches
Data type errors
Missing required fields

Provide row-level feedback to help users correct their Excel inputs.

Common challenges and how to fix them

❌ Poor Spreadsheet Formatting

Users may upload spreadsheets with:

Missing headers
Merged cells
Inconsistent data types

✅ Fix: Use a tool that validates the structure before uploading, including template guidance.

❌ Schema/Field Mismatches

Your GraphQL input schema expects firstName, lastName, email, but users upload First, Last, Mail.

✅ Fix: Implement mapping or schema enforcement on file upload, or use a schema definition interface.

❌ No Feedback on Errors

Users upload data and see... nothing. Silent failures are frustrating.

✅ Fix: Add row-level validation, live previews, and detailed error messages.

❌ Lack of Upload UI

Many devs build makeshift file uploaders that aren't user-friendly.

✅ Fix: Use a prebuilt, embeddable uploader that handles the entire UX + validation pipeline.

How CSVBox simplifies this process

CSVBox is a developer-first, embeddable Excel and CSV uploader that solves all of the above — and connects seamlessly to your GraphQL API.

Here’s how:

🧩 Step 1: Create a Widget

Using the CSVBox dashboard, you can define a data upload widget with:

Required fields
Validation rules
Field types
Sample templates

You don’t need to write spreadsheet parsing or mapping logic yourself.

🛠️ Step 2: Install the Widget on Your Site

Include the widget via script + HTML. Example:

<script src="https://js.csvbox.io/widget.js"></script>
<div
  id="csvbox-widget"
  data-csvbox-importer-id="your_importer_id"
  data-csvbox-user="john.doe@example.com"
></div>

More setup: CSVBox install guide

☁️ Step 3: Receive Clean JSON Data

CSVBox parses the file, validates it, and sends you structured JSON data asynchronously via webhook or API.

You can then use that to trigger your GraphQL mutation:

const cleanedData = receivedWebhook.payload;

fetch('/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: bulkCreateMutation,
    variables: { input: cleanedData },
  }),
});

Need help integrating with a GraphQL backend? Contact CSVBox support or view the GraphQL destination integration guide (custom).

✅ Key benefits for GraphQL users:

Drop-in Excel import UI
Schema enforcement at the UI level
Column validation + required fields
Clean data in JSON format
Compatible with any API backend, including GraphQL

Conclusion

Importing Excel to a GraphQL API is very doable — but prematurely building the file parsing, validation, mapping, and UI layer wastes time and increases bugs.

By using CSVBox, SaaS teams and no-code builders can focus on the API logic while providing an excellent import experience.

Whether you’re using GraphQL with Apollo, Hasura, or a custom backend, integrating with CSVBox ensures reliable, secure, and user-friendly Excel uploads — without writing all the brittle glue code.

FAQs

🔹 Can I use CSVBox with my GraphQL API?

Yes. CSVBox transforms spreadsheet data into JSON, which you can post to any GraphQL endpoint using your preferred client.

🔹 Does CSVBox support both Excel and CSV?

Yes. It supports .csv, .xls, and .xlsx file formats — no need to preprocess them yourself.

🔹 Can I define required fields and validate data types?

Absolutely. CSVBox lets you define your schema, field types (string, number, boolean), required fields, regex checks, and more — all via its dashboard.

🔹 How does CSVBox send the data to my app?

You can receive it via:

Webhooks (POST requests with JSON payloads)
API polling
Client-side event handlers

You can process the payload directly inside your app and use it for GraphQL uploads.

🔹 Is CSVBox embeddable?

Yes. Copy-paste the widget into your frontend. It works in React, Vue, or plain HTML environments.

Ready to streamline Excel import into your GraphQL-powered platform?

👉 Try CSVBox for free and watch data flow effortlessly into your API.

Explore it at https://csvbox.io

Canonical URL: https://csvbox.io/blog/import-excel-to-graphql-api

DEV Community