Ingestro Data Importer SDK: Quick Start Guide

Software teams rely on customer data to activate users and deliver value from day one. Ingestro gives you the infrastructure to import that data at scale—quickly and securely. This guide walks through the core steps to get Ingestro Data Import SDK running in your environment, along with best practices from real-world implementations.

1. Setting up the Importer

The Importer is the entry point. It's where you enter your license key, basic settings, and how users interact with it.

Basic setup

import { NuvoImporter } from "@getnuvo/importer-react";

export default function CustomerImporter() {
  const settings = {
    identifier: "customer-import",
    title: "Import Customers",
    columns: [ // Your TDM columns
      { key: "name", label: "Name" },
      { key: "email", label: "Email" },
    ],
  };

  return (
    <NuvoImporter
      licenseKey="YOUR_LICENSE_KEY"
      settings={settings}
      onResults={(data) => console.log("Imported:", data)}
      columnHooks={}
    />
  );
}

That's it! You've got your importer up and running.

From here, it's all about defining how your data should look and behave.

2. Defining a Target Data Model (TDM)

The TDM defines your output structure—the columns, data types, and validations that ensure you always get clean and consistent data.

Each column can include:

• label → Friendly name for users
• key → The field name your backend expects
• columnType → Data type (string, int, float, category, date, email, etc.)
• example → A sample value (visually helps the user)
• description → A short description on what kind of data the column holds
• alternativeMatches → Synonyms to make mapping easier (such as alternate names that you expect to receive in the files)
• validations → Rules like required, regex, or unique

Here’s an example:

[
  {
    label: "Customer Email",
    key: "customer_email",
    columnType: "email",
    example: "jane.doe@example.com",
    description: "The customer's primary email address used for contact.",
    alternativeMatches: ["Email Address", "Mail"],
    validations: [{ validate: "required" }],
  },
];

📘 Tip: Use our AI TDM generator to speed up the process of setting it up direcly from a file or prompting it with natural language.

3. Adding cleaning functions and validations

Cleaning Functions let you automatically fix or enrich data during the import process.

You can use them to standardize formats, clean data, or block invalid rows before users even hit “Complete import.”

Here’s an example:

columnHooks={{
  customer_email: (values) => {
    return values.map(([item, index]) => {
      const cleanedEmail = item?.toLowerCase().trim();
      return [
        {
          value: cleanedEmail,
          info: [
            {
              message: "Email addresses automatically converted to lowercase.",
              level: "info",
            },
          ],
        },
        index,
      ];
    });
  },
}}

You can also use the Step Handler to hook into each step (upload, mapping, review, etc.) and apply logic like:

• Validating required mappings
• Blocking progress until conditions are met
• Adding info messages or warnings

4. Dynamic Import—start anywhere

With ImporterSession, you can preload data and start the importer at a specific step (for example, at the Review Entries step, including preloaded rows).

await ImporterSession.upload({
  step: "review",
  data: [
    { name: "John Doe", email: "john@example.com" },
    { name: "Jane Smith", email: "jane@example.com" },
  ],
});

This option is perfect for custom workflows or when you already have partially processed data.

5. Styling and localization

Ingestro Data Importer SDK can fully match your brand and audience through white-label customization.

• tyling: Use global theme settings or override individual elements.
• Localization: Switch between supported languages (en, de, fr, pt, es, etc.) with one config line.

<NuvoImporter
  licenseKey="YOUR_LICENSE_KEY"
  settings={{
    identifier: "product_data",
    language: "de", // you can set the language for the UI
    columns: [
      { label: "Produkt-ID", key: "product_id" },
      { label: "Artikelname", key: "article_name" },
    ],
    style: { // directly change the styling of the Importer
      globals: {
        primaryColor: "#4CAF50",
        backgroundColor: "#f9f9f9",
        fontFamily: "Arial",
      },
    },
  }}
/>

Looks native, feels native.

6. Prompts

Give your users superpowers. With Prompts, they can transform or clean data more quickly and more efficiently using natural language commands—right inside the importer.

Examples:

• Replace all empty country fields with “Germany”
• Capitalize all first names
• Set discount to 0 where missing
• Everything runs locally, no data leaves the browser.

Best practices

• Always define identifier and columns in your settings (both are required).
• Use alternativeMatches for better auto-mapping.
• Keep validations helpful and specific, not overly strict.
• Add examples in your TDM so users immediately see what's expected.
• Use Cleaning Functions and Step Handler for custom logic.
• Keep your importer branded and localized—it builds trust.
• Try Prompts—they can save your users plenty of manual cleanup time.

Useful links

• Importer Settings
• TDM & Column Types
• Cleaning Functions
• Step Handler
• Dynamic Import
• Styling & Localization
• AI Prompts