Getting Started
This page will guide you through the basic steps to install the csvbox.io CSV importer widget into your app and start accepting data from your users.

Overview

With csvbox.io you can add a production-ready import feature to your web app in just a few minutes.

Key Concepts

Here are a few important terms used throughout the application:
User: Any person who uses your application.
File: The spreadsheet file that the users want to upload to your application.
Users can upload .csv, .xlsx or .xls file formats.
Sheet or Template: It refers to the data modal that specifies the structure of the data you want to accept. You can add columns to the sheet and configure validation criteria via your csvbox.io dashboard.
Users will be able to match the headers of their file columns with the sheet columns and clean data before uploading.
Import: The entire process where the user invokes the csvbox.io importer to select the file, match columns, validate data, and submit the file is called Import.
Destination: It is the end location where the csvbox.io importer will push the data uploaded by the user.

Setup

It's easy to get started using csvbox.io importer. In this guide, we will use the bare minimum to get up and running with accepting files from your users.

1. Add a sheet

Sheets define the format of the data that you want to accept from the users.
Go to the 'Sheets' page in your dashboard. Add a sheet and specify columns. Configure the validation rules and data format for each column.
When users attempt to upload a file, the importer will validate the data for every column and inform the users if there are any errors. Users have to resolve the errors before submitting the file.
Under the 'Settings' tab, configure the destination where you want the data to be pushed. The destination could be an API endpoint, Amazon S3 bucket, MYSQL database, or any of the other options mentioned here.

2. Install Code

Go to the 'Code' tab of the sheet and find the integration code. Place the code in your application at the location you want to display the import button.
Javascript
React
Angular
Vuejs
Sample code with basic usage:
1
<button class="btn btn-primary" data-csvbox disabled onclick="importer.openModal();">Import</button>
2
<script type="text/javascript" src="http://js.csvbox.io/embed/script"></script>
3
<script type="text/javascript">
4
function callback(result, data) {
5
if(result){
6
console.log("success");
7
console.log(data.row_success + " rows uploaded");
8
//custom code
9
}else{
10
console.log("fail");
11
//custom code
12
}
13
}
14
let importer = new CSVBoxImporter("z0ad8U7en2pFU0bT3z8o5UAUOi5BX6",{
15
}, callback);
16
17
importer.setUser({
18
user_id: "default123"
19
})
20
</script>
Copied!
Each sheet has a unique Licence Key. Find the Licence Key of the sheet on the 'Code' tab of the sheet page and pass it to the CSVBoxImporter function.
Install using npm:
1
npm install @csvbox/react
Copied!
This will give you access to the CSVBoxButton component having the basic functionality of our importer. Import the CSVBoxButton component to your project.
1
import { CSVBoxButton } from '@csvbox/react'
Copied!
Basic usage:
1
<CSVBoxButton
2
licenseKey="z0ad8U7en2pFU0bT3z8o5UAUOi5BX6"
3
user={{
4
user_id: "default123"
5
}}
6
onImport={(result, data) => {
7
if(result){
8
console.log("success");
9
console.log(data.row_success + " rows uploaded");
10
//custom code
11
}else{
12
console.log("fail");
13
//custom code
14
}
15
}}
16
render={(launch)=>{
17
return <button data-csvbox onClick={launch}>Upload file</button>;
18
}}
19
>
20
Import
21
</CSVBoxButton>
Copied!
Each sheet has a unique Licence Key. Find the Licence Key of the sheet on the Code section of the sheet page and attach it to the licenseKey property of the CSVBoxButton component.
The optional render property allows you to pass in your button to use in place of the standard csvbox element.
Install using npm:
1
npm install @csvbox/angular
Copied!
Import:
Add CSVBoxAngularModule to your module imports.
1
import { CSVBoxAngularModule } from "@csvbox/angular";
2
3
@NgModule({
4
...
5
imports: [
6
...
7
CSVBoxAngularModule
8
]
9
})
Copied!
Once you have this setup, in your app component file, you will be able to import and access theCSVBoxMethods module for use.
It will bring the csvbox-button component into your project. Example:
1
<csvbox-button [licenseKey]="licenseKey" [onImport]="onData.bind(this)" [user]="user">Import</csvbox-button>
Copied!
Basic usage:
1
import { CSVBoxMethods } from "@csvbox/angular"
2
3
@Component({
4
selector: 'app-root',
5
template: `
6
<csvbox-button
7
[licenseKey]="licenseKey"
8
[user]="user"
9
[onImport]="onData.bind(this)">
10
Import
11
</csvbox-button>
12
`
13
})
14
15
export class AppComponent implements CSVBoxMethods {
16
17
title = 'example';
18
licenseKey = 'YOUR_LICENSE_KEY_HERE';
19
user = { user_id: 'default123' };
20
21
onData(result: boolean, data: any) {
22
if(result) {
23
console.log("Sheet uploaded successfully");
24
console.log(data.row_success + " rows uploaded");
25
}else{
26
console.log("There was some problem uploading the sheet");
27
}
28
}
29
30
}
Copied!
Each sheet has a unique Licence Key. Find the Licence Key of the sheet on the Code section of the sheet page and attach it to the licenseKey property of the AppComponent.
Styling the button:
In order to style the <csvbox-button> from within your parent component, ensure that your parent component has ViewEncapsulation.None, pass down a class to <csvbox-button>, and now you will be able to style the button one-level down.
1
import { Component, ViewEncapsulation } from '@angular/core';
Copied!
1
@Component({
2
selector: 'app-root',
3
template: `
4
<csvbox-button
5
[licenseKey]="licenseKey"
6
[user]="user"
7
[dynamicColumns]="dynamicColumns"
8
[onImport]="onData.bind(this)"
9
class=“csvbox-btn”
10
>
11
Import
12
</csvbox-button>
13
`,
14
encapsulation: ViewEncapsulation.None,
15
styles: [`
16
.csvbox-btn button {
17
background: #007bff;
18
border-radius: 3px;
19
}
20
`],
21
export class AppComponent implements CSVBoxMethods {
22
//...
23
}
Copied!
Install using npm:
1
npm install @csvbox/vuejs
Copied!
This will give you access to the CSVBoxButton component. Import the CSVBoxButton component to your project.
1
import { CSVBoxButton } from '@csvbox/vuejs'
Copied!
Now just import the CSVBoxButton and include it in your Vue components, and you're ready to get started.
Basic usage:
1
<template>
2
<div id="app">
3
<CSVBoxButton
4
:licenseKey="licenseKey"
5
:user="user"
6
:onImport="onImport">
7
Upload File
8
</CSVBoxButton>
9
</div>
10
</template>
11
12
<script>
13
import { CSVBoxButton } from '@csvbox/vuejs';
14
15
export default {
16
name: 'App',
17
components: {
18
CSVBoxButton,
19
},
20
data: () => ({
21
licenseKey: 'z0ad8U7en2pFU0bT3z8o5UAUOi5BX6',
22
user: {
23
user_id: 'default123',
24
},
25
}),
26
methods: {
27
onImport: function (result, data) {
28
if(result){
29
console.log("success");
30
console.log(data.row_success + " rows uploaded");
31
//custom code
32
}else{
33
console.log("fail");
34
//custom code
35
}
36
}
37
},
38
}
39
</script>
Copied!
Each sheet has a unique Licence Key. Find the Licence Key of the sheet on the Code section of the sheet page and attach it to the licenseKey property of the CSVBoxButton component.

Referencing the user

You can configure custom user attributes in the installation code to identify the users in your platform and match them with their respective imports.
Javascript
React
Angular
Vuejs
Pass custom user attributes as input parameters to the setUsermethod. The custom user attributes will be pushed to your destination along with the uploaded data.
user_id is the only custom attribute that is mandatory. Apart from user_id, you can add up to 4 custom attributes in the<key>: <value>format. Example:
1
importer.setUser({
2
user_id: "1a2b3c4d5e6f",
3
team_id: "sales2",
4
isAuthenticated: "true",
5
permissionLevel: "admin",
7
})
Copied!
Pass custom user attributes as an object to the userproperty of the CSVBoxButton component. The custom user attributes will be pushed to your destination along with the uploaded data.
user_id is the only custom attribute that is mandatory. Apart from user_id, you can add up to 4 custom attributes in the <key>: <value>format. Example:
1
user={{
2
user_id: "1a2b3c4d5e6f",
3
team_id: "sales2",
4
isAuthenticated: "true",
5
permissionLevel: "admin",
7
}}
Copied!
Pass custom user attributes as an object to the userproperty of the AppComponent. The custom user attributes will be pushed to your destination along with the uploaded data.
user_id is the only custom attribute that is mandatory. Apart from user_id, you can add up to 4 custom attributes in the <key>: <value>format. Example:
1
user={
2
user_id: "1a2b3c4d5e6f",
3
team_id: "sales2",
4
isAuthenticated: "true",
5
permissionLevel: "admin",
7
}
Copied!
Pass custom user attributes as an object to the userproperty of the CSVBoxButton component. The custom user attributes will be pushed to your destination along with the uploaded data.
user_id is the only custom attribute that is mandatory. Apart from user_id, you can add up to 4 custom attributes in the <key>: <value>format. Example:
1
user: {
2
user_id: "1a2b3c4d5e6f",
3
team_id: "sales2",
4
isAuthenticated: "true",
5
permissionLevel: "admin",
7
},
Copied!

Callback function

Once the user uploads a file the importer will return the status of the import along with metadata describing the completed import. Data is returned via two variables: result and data.
  1. 1.
    result - It is of type boolean with the value true if the import is successful and false if the import fails.
  2. 2.
    data - It returns JSON data as shown below:
1
{
2
"import_id": 79418895,
3
"sheet_id": 575,
4
"sheet_name": "Products Import",
5
"destination_type": "webhook"
6
"row_count": 100,
7
"row_success": 98,
8
"row_fail": 2,
9
"import_status": "Partial",
10
"import_starttime": 87987897897,
11
"import_endtime": 90890890809,
12
"raw_file": "https://file-download-link",
13
"custom_fields": {
14
"user_id": "Z1001"
15
}
16
}
Copied!
You can write custom code to handle the success or failure conditions client side.
Javascript
React
Angular
Vuejs
The result and datavariables will be available in the callbackfunction that is triggered when the import is completed.
1
function callback(result, data) {
2
if(result){
3
console.log("success");
4
console.log(data.row_success + " rows uploaded");
5
//custom code
6
}else{
7
console.log("fail");
8
//custom code
9
}
10
}
Copied!
The onImport property provides access to the result and datavariables.
1
onImport={(result, data) => {
2
if(result){
3
console.log("success");
4
console.log(data.row_success + " rows uploaded");
5
//custom code
6
}else{
7
console.log("fail");
8
//custom code
9
}
10
}
11
}
Copied!
The onImport property provides access to the result and datavariables via the specified callback function.
1
onData(result: boolean, data: any) {
2
if(result) {
3
console.log("Sheet uploaded successfully");
4
console.log(data.row_success + " rows uploaded");
5
}else{
6
console.log("There was some problem uploading the sheet");
7
}
8
}
Copied!
The onImport property provides access to the result and datavariables.
1
onImport: function (result, data) {
2
if(result){
3
console.log("success");
4
console.log(data.row_success + " rows uploaded");
5
//custom code
6
}else{
7
console.log("fail");
8
//custom code
9
}
10
}
Copied!

3. Receive Data

Once the code is installed the users will be able to submit their files via the csvbox importer. The raw files uploaded by the users will be available on your dashboard's 'Import' page. The data will also be pushed to your app as per the destination type configuration of your sheet.

Sample JSON response for destination Webhook:

1
[
2
{
3
"import_id": 79418895,
4
"sheet_id": 55,
5
"sheet_name": "Products",
6
"row_number": 1,
7
"row_data": {
8
"Name": "TP-Link TL-WN822N Wireless N300 High Gain USB Adapter",
9
"SKU": "AS-100221",
10
"Price": "33.00",
11
"Quantity": "3",
12
"Image URL": "https://cdn.shopify.com/s/files/1/1491/9536/products/31jJOj1DS5L_070b4893-b7af-482f-8a15-d40f5e06760d.jpg?v=1521803806"
13
},
14
"custom_fields": {
15
"user_id": "1002"
16
}
17
},
18
{
19
"import_id": 79418895,
20
"sheet_id": 55,
21
"sheet_name": "Products",
22
"row_number": 2,
23
"row_data":{
24
"Name": "EPower Technology EP-600PM Power Supply 600W ATX12V 2.3 Single 120mm Cooling Fan Bare",
25
"SKU": "AS-103824",
26
"Price": "95.35",
27
"Quantity": "8",
28
"Image URL": "https://cdn.shopify.com/s/files/1/1491/9536/products/71pRC5VjF-L_8f840eb9-6a47-407f-999c-490f7814159d.jpg?v=1521803806"
29
},
30
"custom_fields": {
31
"user_id": "1002"
32
}
33
},
34
]
35
Copied!
All import data and RAW files will be retained for one month. You also have the option to delete them as soon as they are pushed to the destination.

Import Complete Webhook

Optionally, you can subscribe to the import complete event webhook via the sheet settings page. This webhook will fire when the csvbox completes the import process for any user. Here is some example JSON that could be sent to your webhook endpoint:
1
[
2
{
3
"import_id": 79418895,
4
"sheet_id": 575,
5
"sheet_name": "Products Import",
6
"destination_type": "webhook"
7
"row_count": 100,
8
"row_success": 98,
9
"row_fail": 2,
10
"import_status": "Partial",
11
"import_starttime": 87987897897,
12
"import_endtime": 90890890809,
13
"raw_file": "https://file-download-link",
14
"custom_fields": {
15
"user_id": "Z1001"
16
}
17
}
18
]
Copied!

Import Links

Use Import Links to accept files from your users without a website or an app. Create an import page in just a few clicks and share the link with your users—no code required. It is an alternative to the import button that can be set up by adding the integration code (mentioned above.)
After you have created a sheet go to the 'Code' tab on the Edit Sheet page. Below the integration code find the Import Link of the sheet. It will look something like this:
1
https://app.csvbox.io/upload/2gzJa5YO3QPLYK6Bj7Qmq5bpbFqXno?user_id=default123
Copied!
Simply share this link with your users to start collecting spreadsheets.
You can configure the query parameters in the link to identify and match the users with their respective imports. Add up to 5 query parameters with custom user attributes that help you identify the users in your platform. The custom user attributes will be pushed to your destination along with the uploaded data.
user_id is the only custom attribute that is mandatory. Apart from user_id, you can add up to 4 custom attributes in the&key=valueformat. Example:
1
https://app.csvbox.io/upload/2gzJa5YO3QPLYK6Bj7Qmq5bpbFqXno?user_id=1a2b3c4d5e6f&team_id=sales2&isAuthenticated=true&permissionLevel=admin&email=[email protected].com
Copied!
Last modified 1d ago