> ## Documentation Index
> Fetch the complete documentation index at: https://help.csvbox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Bubble

> Import customer CSV data to your Bubble app database with the CSVbox importer.

The Bubble.io destination pushes the CSV and Excel files your users upload directly into your Bubble app database. You configure the Bubble Data API, connect it to a CSVbox sheet, and add the CSVbox plugin to your app.

## Demo app

See how it works [here](https://csvbox-demo.bubbleapps.io/version-test).

## Configuring your Bubble app

<Note>
  You need to be on a [paid Bubble application plan](https://bubble.io/pricing/compare) to use the Bubble API, which is required to push external CSV data into the Bubble data store.
</Note>

### Data settings

Create or update a data type in your Bubble app where you want to push the CSV data. Make sure the data type is **Publicly visible**. Add custom fields to the data type as per your requirements.

<Frame>
  <img src="https://mintcdn.com/csvbox-io/gyjvlPdP5mzE2jo9/images/data-type.jpg?fit=max&auto=format&n=gyjvlPdP5mzE2jo9&q=85&s=9383e927b81dd4024756f477432fb781" alt="Bubble data type" width="759" height="672" data-path="images/data-type.jpg" />
</Frame>

<Warning>
  Manually add at least one object (row) to the data type.
</Warning>

<Frame>
  <img src="https://mintcdn.com/csvbox-io/Fn747PbJ5U7GCAW2/images/object.jpg?fit=max&auto=format&n=Fn747PbJ5U7GCAW2&q=85&s=0cff54dec3acbc137793608ca0eaaaa4" alt="Add object" width="1696" height="296" data-path="images/object.jpg" />
</Frame>

### API settings

<Steps>
  <Step title="Open Settings">
    Go to **Settings**.
  </Step>

  <Step title="Open the API page">
    Go to the **API** page.
  </Step>

  <Step title="Activate the Data API">
    Activate **Data API**.
  </Step>

  <Step title="Activate the API for your data type">
    Activate the API for the data type where you want to push the CSV data.
  </Step>

  <Step title="Generate the API Private Key">
    Generate and save the **API Private Key**.

    <Frame>
      <img src="https://mintcdn.com/csvbox-io/gyjvlPdP5mzE2jo9/images/api-settings.jpg?fit=max&auto=format&n=gyjvlPdP5mzE2jo9&q=85&s=847d956911094661c42cd9f57732fe01" alt="API settings" width="1101" height="635" data-path="images/api-settings.jpg" />
    </Frame>
  </Step>
</Steps>

## Setting up CSVbox

<Steps>
  <Step title="Log in to CSVbox">
    Log in to [csvbox.io](https://app.csvbox.io/login).
  </Step>

  <Step title="Add a sheet">
    <Frame>
      <img src="https://mintcdn.com/csvbox-io/gyjvlPdP5mzE2jo9/images/add-sheet.png?fit=max&auto=format&n=gyjvlPdP5mzE2jo9&q=85&s=69f7b40d5ca58b9ea1a6121227561873" alt="Add a sheet" width="371" height="159" data-path="images/add-sheet.png" />
    </Frame>
  </Step>

  <Step title="Add columns">
    Add columns to the sheet. The column names should match the column/object names for your data type in Bubble. Pay attention to upper and lower case letters in Bubble and match them in CSVbox.

    <Frame>
      <img src="https://mintcdn.com/csvbox-io/gyjvlPdP5mzE2jo9/images/add-columns.png?fit=max&auto=format&n=gyjvlPdP5mzE2jo9&q=85&s=32b2e1f3586aa0890240c0ce7241627e" alt="Add columns" width="640" height="696" data-path="images/add-columns.png" />
    </Frame>
  </Step>

  <Step title="Select Bubble.io as the destination">
    Under the **Settings** section, for the **Send Data To** setting, select **Bubble.io**.

    <Frame>
      <img src="https://mintcdn.com/csvbox-io/gyjvlPdP5mzE2jo9/images/bubble-io-settings.jpg?fit=max&auto=format&n=gyjvlPdP5mzE2jo9&q=85&s=48dc8766750447ce4b7ce94271b8ebd6" alt="Bubble.io data destination settings" width="701" height="1343" data-path="images/bubble-io-settings.jpg" />
    </Frame>

    Fill in the following fields:

    * **App Name**: the name of your Bubble.io app.
    * **Custom Domain Name**: if you have attached a custom domain name to your Bubble app, provide it here.
    * **Environment**: pick the environment where you want the CSV data to be sent, either TEST/DEVELOPMENT or PRODUCTION/LIVE.
    * **API Private Key**: the API token you generated while configuring the [API settings](/destinations/bubble-io#api-settings) in the Bubble app.
    * **Data Type**: the data type name where you want to push the CSV data.
  </Step>

  <Step title="Test the connection">
    Click **Test Connection**. It succeeds if all fields are filled in correctly.
  </Step>

  <Step title="Map columns">
    Click **Map Columns**. A modal opens where you can map the sheet columns to the object fields.

    <Frame>
      <img src="https://mintcdn.com/csvbox-io/Fn747PbJ5U7GCAW2/images/map-columns-2.jpg?fit=max&auto=format&n=Fn747PbJ5U7GCAW2&q=85&s=52324d9549544cb516b9d33a389de457" alt="Map sheet columns to Bubble data fields" width="521" height="631" data-path="images/map-columns-2.jpg" />
    </Frame>

    <Warning>
      The data fields from the Bubble database are available in the Map Column modal only if they have data in the first row. Add dummy data for each data field in the first row so that they appear in the Map Column modal.
    </Warning>
  </Step>

  <Step title="Save the sheet">
    Click **Save**.
  </Step>

  <Step title="Copy the Sheet License Key">
    Go to the **Code** section of the sheet and note down the **Sheet License Key**.

    <Frame>
      <img src="https://mintcdn.com/csvbox-io/Fn747PbJ5U7GCAW2/images/sheet-license-key.png?fit=max&auto=format&n=Fn747PbJ5U7GCAW2&q=85&s=16ff5b4d183d0522cf5a1f44337ead4b" alt="Sheet License Key" width="1065" height="187" data-path="images/sheet-license-key.png" />
    </Frame>
  </Step>
</Steps>

## Adding CSVbox to Bubble

<Steps>
  <Step title="Install the plugin">
    Install the [csvbox.io](https://bubble.io/plugin/csv--excel-importer-|-receive-json-1628686647935x372170116910546940) plugin in your Bubble app.
  </Step>

  <Step title="Add the CSVBox Button element">
    Drag the CSVBox Button element onto your web page.
  </Step>

  <Step title="Set the Sheet License Key">
    Paste the **Sheet License Key** value from the sheet **Code** page (saved above) into the **Sheet License Key** property of the CSVBox element.

    <Frame>
      <img src="https://mintcdn.com/csvbox-io/gyjvlPdP5mzE2jo9/images/bubble-app-csvbox-element.png?fit=max&auto=format&n=gyjvlPdP5mzE2jo9&q=85&s=0b1330a06cf3c8654de5d1ad1feb8648" alt="Bubble app CSVBox Button element" width="1280" height="577" data-path="images/bubble-app-csvbox-element.png" />
    </Frame>
  </Step>

  <Step title="Configure the button">
    Enter the import button label in the `button_text` property. Optionally, add CSS classes in the `button_classes` property to style the CSVbox import button.

    <Note>
      You can add custom user attributes (such as user\_id, user name, company name, etc.) as values to the `custom_attribute_XX` properties of the CSVBox Button element. More information on custom attributes is available [here](/getting-started/2-install-code#referencing-the-user).
    </Note>
  </Step>
</Steps>

The CSVbox import button is now available in your app. Your users can click the button to upload CSV files, and the data arrives in your Bubble database.

### Import events

The CSVBox Button element exposes two events that indicate the completion of the import process:

* **import\_success**: triggered when the CSV data is imported successfully into your Bubble database.
* **import\_fail**: triggered when the import fails completely or partially.

<Frame>
  <img src="https://mintcdn.com/csvbox-io/gyjvlPdP5mzE2jo9/images/bubble-events.png?fit=max&auto=format&n=gyjvlPdP5mzE2jo9&q=85&s=ca148525da3f87ab0f90ba9f8fc39218" alt="CSVBox Button element events" width="625" height="345" data-path="images/bubble-events.png" />
</Frame>

You can add relevant actions to process the import result events.

## Why does my upload fail with unknown errors?

Bubble.io databases are very picky. The column names you POST from the CSVbox importer must **exactly** match what is in your Bubble.io database.

Check the following:

* Make sure there are no extra columns in your CSVbox sheet that do not map to a field/attribute in your Bubble.io database object. Bubble does not accept extra columns that its database doesn't know about.
* The CSVbox sheet column names must **exactly** match the type names in your Bubble.io database object. Verify that capitalization and spaces are exactly the same as in your Bubble.io data type object.
* In your Bubble.io app settings, click **API** and make sure all checkboxes are checked for exposing the Data API, and for every database object you want to import into.

<Note>
  The maximum number of items that can be created in Bubble.io via a single bulk request is currently 1000.
</Note>

## Adding configuration options

<Note>
  Coming soon.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.