Getting Started

Getting Started

Add CSV and Excel imports to your application in under 10 minutes.

Rowporter is an embeddable data import widget that handles file parsing, column mapping, and validation. This guide will walk you through the complete setup process.

Prerequisites

Before you begin, make sure you have:

A Rowporter account (sign up free)
A web application where you want to add the import widget
Basic knowledge of HTML and JavaScript

Create an Import Template

A template defines the columns you expect in the imported data, along with their types and validation rules.

Dashboard → Templates → New Template

Or create via API:

Create Template via API

curl -X POST https://rowporter.com/api/v1/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contact Import",
    "columns": [
      {
        "key": "email",
        "name": "Email Address",
        "type": "email",
        "required": true,
        "description": "Contact email address"
      },
      {
        "key": "first_name",
        "name": "First Name",
        "type": "string",
        "required": true
      },
      {
        "key": "last_name",
        "name": "Last Name",
        "type": "string",
        "required": false
      },
      {
        "key": "phone",
        "name": "Phone Number",
        "type": "phone",
        "required": false
      },
      {
        "key": "company",
        "name": "Company",
        "type": "string",
        "required": false
      }
    ]
  }'

Column Types

stringnumberemaildatebooleanurlphone

Get Your API Key

API keys authenticate your requests and associate imports with your organization.

Dashboard → API Keys → Create Key

Your API key will look like this:

sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456

⚠️ Security Note

Keep your API key secret. Never expose it in client-side code or public repositories. For the embed widget, use template IDs instead of API keys.

Add the Widget to Your App

Choose one of the following integration methods:

Method A: Script Tag (Recommended)

index.html

<!-- Add the Rowporter SDK -->
<script src="https://rowporter.com/embed.js"></script>

<script>
  Rowporter.init({
    templateId: 'YOUR_TEMPLATE_ID',
    
    // Optional: Pass user info
    user: {
      id: 'user-123',
      email: 'user@example.com'
    },
    
    // Optional: Pass custom metadata
    metadata: {
      source: 'dashboard',
      campaign: 'onboarding'
    },
    
    // Callback when import completes
    onComplete: function(result) {
      console.log('Import completed!', result);
      
      // Send data to your backend
      fetch('/api/contacts/import', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(result.data)
      });
    },
    
    // Callback on error
    onError: function(error) {
      console.error('Import error:', error);
    }
  });
  
  // Safe button binding (handles DOM timing automatically)
  Rowporter.bindButton('#import-btn');
</script>

<!-- Your import button -->
<button id="import-btn">Import Contacts</button>

<!-- Or use the simplest approach: data attribute -->
<button data-rowporter-open>Import Contacts</button>

Method B: Inline Embed

inline-embed.html

<!-- Container for the widget -->
<div id="import-widget" style="width: 100%; height: 600px;"></div>

<script src="https://rowporter.com/embed.js"></script>
<script>
  Rowporter.init({
    templateId: 'YOUR_TEMPLATE_ID',
    modal: false,  // Disable modal mode
    container: '#import-widget',
    onComplete: function(result) {
      console.log('Import completed!', result);
    },
    onError: function(error) {
      console.error('Import error:', error);
    }
  });
</script>

Method C: React Component

ImportButton.tsx

import { useEffect, useRef } from 'react';

// Load the SDK
declare global {
  interface Window {
    Rowporter: any;
  }
}

function ImportButton() {
  const initialized = useRef(false);

  useEffect(() => {
    // Load the script
    const script = document.createElement('script');
    script.src = 'https://rowporter.com/embed.js';
    script.async = true;
    script.onload = () => {
      if (!initialized.current) {
        window.Rowporter.init({
          templateId: 'YOUR_TEMPLATE_ID',
          onComplete: (result) => {
            console.log('Import completed!', result);
            // Handle the imported data
          },
        });
        initialized.current = true;
      }
    };
    document.body.appendChild(script);

    return () => {
      if (window.Rowporter) {
        window.Rowporter.destroy();
      }
    };
  }, []);

  const handleClick = () => {
    if (window.Rowporter) {
      window.Rowporter.open();
    }
  };

  return (
    <button onClick={handleClick}>
      Import Data
    </button>
  );
}

export default ImportButton;

Configure Webhooks (Optional)

Receive import data directly on your backend via webhooks.

Dashboard → Settings → Webhooks

Configure your webhook URL:

https://your-app.com/api/webhooks/rowporter

Your endpoint will receive:

Webhook Payload

{
  "event": "import.completed",
  "importId": "imp_abc123",
  "templateId": "tpl_xyz789",
  "organizationId": "org_def456",
  "timestamp": "2024-01-15T10:30:00Z",
  "metadata": {
    "source": "dashboard",
    "campaign": "onboarding"
  },
  "data": {
    "rows": [
      { "email": "john@example.com", "first_name": "John", "last_name": "Doe" },
      { "email": "jane@example.com", "first_name": "Jane", "last_name": "Smith" }
    ],
    "rowCount": 2,
    "columns": ["email", "first_name", "last_name"]
  }
}