# Authentication
Source: https://developer.dromo.io/api-reference/authentication

Authenticate Dromo REST API requests with frontend or backend API keys and keep privileged credentials secure.

## Overview

The Dromo API uses API keys to authenticate requests. You can view and manage your API keys in the [Dromo Dashboard](https://dashboard.dromo.io).

<Warning>
  **Keep your backend API keys secure!**

  * Never expose them in client-side code
  * Store them securely in environment variables
</Warning>

## Authentication Methods

To send an authorized API call, include your backend API key in the `X-Dromo-License-Key` header.

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-Dromo-License-Key: YOUR_API_KEY" \
        https://app.dromo.io/api/v1/schemas
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.dromo.io/api/v1/schemas', {
    headers: {
      'X-Dromo-License-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  });
  ```
</CodeGroup>


# Create a new headless import
Source: https://developer.dromo.io/api-reference/headless/create-a-new-headless-import

/api-reference/openapi.json post /headless/imports/
Starts a headless import from an uploaded file or data payload using a saved or inline schema.



# Delete headless import
Source: https://developer.dromo.io/api-reference/headless/delete-headless-import

/api-reference/openapi.json delete /headless/imports/{id}/
Permanently deletes a headless import identified by ID.



# Get presigned download URL for headless import data
Source: https://developer.dromo.io/api-reference/headless/get-presigned-download-url-for-headless-import-data

/api-reference/openapi.json get /headless/imports/{id}/url/
Creates a temporary presigned URL for downloading the processed data from a successful headless import.



# List headless imports
Source: https://developer.dromo.io/api-reference/headless/list-headless-imports

/api-reference/openapi.json get /headless/imports/
Returns a paginated list of headless imports for the authenticated Dromo organization.



# Retrieve headless import
Source: https://developer.dromo.io/api-reference/headless/retrieve-headless-import

/api-reference/openapi.json get /headless/imports/{id}/
Returns the current status and available result or review information for a headless import by ID.



# Create a new import schema
Source: https://developer.dromo.io/api-reference/import-schemas/create-a-new-import-schema

/api-reference/openapi.json post /schemas/
Creates a saved import schema with fields, settings, and optional hooks for reuse in Dromo imports.



# Delete an import schema
Source: https://developer.dromo.io/api-reference/import-schemas/delete-an-import-schema

/api-reference/openapi.json delete /schemas/{id}/
Permanently deletes a saved import schema identified by ID.



# Get all import schemas
Source: https://developer.dromo.io/api-reference/import-schemas/get-all-import-schemas

/api-reference/openapi.json get /schemas/
Returns all saved import schemas available to the authenticated Dromo organization.



# Get an import schema
Source: https://developer.dromo.io/api-reference/import-schemas/get-an-import-schema

/api-reference/openapi.json get /schemas/{id}/
Returns one saved import schema by ID, including its fields, settings, and hooks.



# Update an import schema
Source: https://developer.dromo.io/api-reference/import-schemas/update-an-import-schema

/api-reference/openapi.json put /schemas/{id}/
Replaces the fields, settings, and hooks of an existing saved import schema identified by ID.



# Create a session
Source: https://developer.dromo.io/api-reference/sessions/create-a-session

/api-reference/sessions-openapi.json post /auth/
Creates a new partial-import session and mints the initial hydration token to pass to the widget. Requires your **backend** license key — never call this client-side.



# Delete a session
Source: https://developer.dromo.io/api-reference/sessions/delete-a-session

/api-reference/sessions-openapi.json delete /{sessionId}/
Permanently deletes the session and its saved state. All hydration tokens for this session are immediately invalidated — subsequent widget calls with the old `hydrationId` return 403. Idempotent: returns `{"success": true}` even if the session was already deleted.



# Resume a session (re-issue hydrationId)
Source: https://developer.dromo.io/api-reference/sessions/resume-a-session-re-issue-hydrationid

/api-reference/sessions-openapi.json post /{sessionId}/auth/
Issues a fresh `hydrationId` for an existing session. Call this server-side when the user returns after their previous token has expired. The new token must belong to the same org as the session.



# Create SFTP connector
Source: https://developer.dromo.io/api-reference/sftp-connectors/create-sftp-connector

/api-reference/openapi.json post /headless/sftp/connectors/
Creates an automated SFTP connector that imports files using configured credentials and schema settings.



# Delete SFTP connector
Source: https://developer.dromo.io/api-reference/sftp-connectors/delete-sftp-connector

/api-reference/openapi.json delete /headless/sftp/connectors/{id}/
Deletes an automated SFTP connector identified by ID.



# List SFTP connectors
Source: https://developer.dromo.io/api-reference/sftp-connectors/list-sftp-connectors

/api-reference/openapi.json get /headless/sftp/connectors/
Returns the automated SFTP import connectors configured for the authenticated Dromo organization.



# Retrieve SFTP connector
Source: https://developer.dromo.io/api-reference/sftp-connectors/retrieve-sftp-connector

/api-reference/openapi.json get /headless/sftp/connectors/{id}/
Returns one automated SFTP connector and its import configuration by ID.



# Update SFTP connector
Source: https://developer.dromo.io/api-reference/sftp-connectors/update-sftp-connector

/api-reference/openapi.json put /headless/sftp/connectors/{id}/
Updates an existing automated SFTP connector identified by ID.



# Create SFTP credentials
Source: https://developer.dromo.io/api-reference/sftp-credentials/create-sftp-credentials

/api-reference/openapi.json post /headless/sftp/credentials/
Creates an SFTP credential configuration for connecting Dromo to an SFTP server.



# Delete SFTP credentials
Source: https://developer.dromo.io/api-reference/sftp-credentials/delete-sftp-credentials

/api-reference/openapi.json delete /headless/sftp/credentials/{id}/
Deletes an SFTP credential configuration identified by ID.



# List SFTP credentials
Source: https://developer.dromo.io/api-reference/sftp-credentials/list-sftp-credentials

/api-reference/openapi.json get /headless/sftp/credentials/
Returns the SFTP credential configurations available to the authenticated Dromo organization.



# Retrieve SFTP credentials
Source: https://developer.dromo.io/api-reference/sftp-credentials/retrieve-sftp-credentials

/api-reference/openapi.json get /headless/sftp/credentials/{id}/
Returns one SFTP credential configuration by ID without exposing secret credential values.



# Test SFTP connection
Source: https://developer.dromo.io/api-reference/sftp-credentials/test-sftp-connection

/api-reference/openapi.json post /headless/sftp/credentials/{id}/test_connection/
Tests whether Dromo can connect to the SFTP server using the selected credential configuration.



# Update SFTP credentials
Source: https://developer.dromo.io/api-reference/sftp-credentials/update-sftp-credentials

/api-reference/openapi.json put /headless/sftp/credentials/{id}/
Updates an existing SFTP credential configuration identified by ID.



# Delete an upload permanently
Source: https://developer.dromo.io/api-reference/uploads/delete-an-upload-permanently

/api-reference/openapi.json post /upload/{id}/delete/
Permanently deletes a completed upload and its stored data from Dromo.



# Get all uploads
Source: https://developer.dromo.io/api-reference/uploads/get-all-uploads

/api-reference/openapi.json get /uploads/
Lists completed Dromo uploads for the authenticated organization, optionally filtered by a start and end date.



# Get presigned download URL for upload data
Source: https://developer.dromo.io/api-reference/uploads/get-presigned-download-url-for-upload-data

/api-reference/openapi.json get /upload/{id}/url/
Creates a temporary presigned URL for securely downloading the data from a completed upload.



# Get upload metadata
Source: https://developer.dromo.io/api-reference/uploads/get-upload-metadata

/api-reference/openapi.json get /upload/{id}/metadata/
Returns metadata for a completed Dromo upload, including information about its schema, user, and results.



# Changelog
Source: https://developer.dromo.io/changelog

Review Dromo product releases, new SDK and API capabilities, behavior changes, accessibility improvements, and bug fixes.

<Update label="September 2026" description="Upcoming">
  ## Optional Bulk Fix Step

  * **`skipBulkFixStep`**: Set to `true` to always skip the Bulk Fix step, regardless of whether select, multi-select, or date values would normally cause it to appear.

  See [`skipBulkFixStep`](/reference/settings/settings#skipbulkfixstep) in the Settings reference for configuration details.
</Update>

<Update label="August 2026" description="v3.13.0">
  ## Batch Row Hooks for Large Imports

  Large imports can now be transformed in bounded chunks during initialization, avoiding the need to pass the entire dataset to one bulk callback.

  * **`registerBatchRowHook()`**: Register a JavaScript SDK callback that receives one slice of rows and its one-based batch number
  * **`batchRowHooks`**: Supply the same initialization-only callbacks through the React prop or Angular input
  * **`batchRowHookBatchSize`**: Set the maximum rows per callback invocation with a positive integer; defaults to `2000`

  See the [Batch row hooks reference](/reference/hooks#batch-row-hooks) for callback signatures and examples.
</Update>

<Update label="July 2026" description="v3.13.0">
  ## Dr.Dromo Enters Limited Beta

  Meet **Dr.Dromo**, Dromo's AI assistant for designing and refining import workflows. Describe the outcome you need in plain language, and Dr.Dromo can help turn it into a reviewable Dromo schema.

  During the beta, Dr.Dromo can:

  * Generate import schemas from natural-language prompts, sample files, or existing configurations
  * Update fields, validation rules, settings, and hooks directly in Schema Studio
  * Provide product and implementation guidance grounded in Dromo's developer documentation
  * Present every proposed change for review before it is applied

  Dr.Dromo is currently available to a limited group of customers while we gather feedback and expand its capabilities. To request early access, contact [Dromo Support](mailto:support@dromo.io) or start a conversation using the support chat in the dashboard.

  ## Session Hydration Security

  Sessions now support a short-lived signed **`hydrationId`** token as a more secure alternative to passing the raw `sessionId` UUID in API URLs. The `sessionId`-based approach remains supported — `hydrationId` is an opt-in improvement that limits the impact of a leaked credential by scoping access to a short-lived token.

  * **`hydrationId`**: A signed token returned on session create; pass it to the widget instead of the raw `sessionId`
  * **`expiresAt`**: Token expiration timestamp returned by the Sessions API; configure the lifetime with the `expires_in` request field
  * **`sessionId`**: Unchanged long-lived identifier — store it server-side to re-issue a fresh `hydrationId` whenever needed

  See the [Session Saving & Restoration Guide](/guides/saving-progress) for the full security model and endpoint reference.
</Update>

<Update label="June 2026" description="v3.13.0">
  ## Error Navigator Style Overrides & Custom AI Transform Prompts

  * **`styleOverrides.errorNavigator`**: New style override object for the Error Navigator panel. Customize `errorColor`, `warningColor`, `accentColor`, `errorIconUrl`, and `warningIconUrl`. See the [Style Overrides reference](/reference/settings/style-overrides#param-error-navigator) for details.
  * **`reviewStep.transformDataPrompts`**: Pass a `string[]` of custom prompt suggestions to display in the AI Transform Data modal, replacing the default localized prompts. See [`transformDataPrompts`](/reference/settings/settings#param-transform-data-prompts).
</Update>

<Update label="May 2026" description="v3.12.0">
  ## Inline Schema Imports for Headless API

  The [create headless import endpoint](/api-reference/headless/create-a-new-headless-import) now supports defining schemas inline at import time, without requiring a saved schema in the dashboard.

  * **`fields`**: Pass field definitions directly in the request body instead of a `schema_id` — useful for dynamically generated schemas
  * **`settings` and `hooks` overrides**: Provide `settings` or `hooks` alongside a `schema_id` to merge one-off overrides for a specific import without modifying the saved schema
  * **Documentation**: [Headless Quickstart — Inline Schema Imports](/getting-started/headless#inline-schema-imports)

  ## Error Navigator & onUserEvent Callback

  ### Error Navigator

  * **`reviewStep.enableNavigatingErrors`**: A new boolean setting (default `false`) adds an error navigation panel to the Review Step. When enabled, row headers with validation errors display a red circular info icon — clicking it opens the panel anchored to that row's first error.
  * **Navigator panel**: Slides in from the right of the table and lists all validation errors as cards (row number, column name, error message). A column dropdown filters the list; Prev/Next buttons and `Alt+↑` / `Alt+↓` keyboard shortcuts step through errors in order, scrolling the table to each cell. Clicking any card jumps directly to that cell.
  * **Inline fix actions**: The active error card exposes two actions:
    * **Clear** — removes the invalid value; for multi-select fields, removes only invalid tokens.
    * **Replace** — sets a new value; shows a valid-options dropdown for select/multi-select fields, free text for all others; for multi-select, appends the chosen value to existing valid ones.
  * **Stateful panel**: Closing the panel (X) resets state and the column filter.

  See [`reviewStep.enableNavigatingErrors`](/reference/settings/settings#param-enable-navigating-errors) in the Settings reference for full details.

  ### onUserEvent Callback

  * **`onUserEvent()`**: Register a callback on any `DromoUploader` instance to receive real-time notifications when the user interacts with tracked UI controls. Fires on every button click across all import steps — upload, header selection, column matching, value matching, and review.
  * **`BUTTON_CLICK` event**: The initial event type emitted, with a payload containing `buttonName` (the specific control clicked) and `step` (the active import step). Over 30 named button values are covered, from `UPLOAD_DATA` and `DOWNLOAD_TEMPLATE` to `FIND_AND_REPLACE_CONFIRM`, `TRANSFORM_DATA_CONFIRM`, and exit/alert modal actions.
  * **Safe by default**: Errors thrown inside the callback are caught and logged as a warning — they never crash the importer or interrupt the user's flow.

  See the [onUserEvent Reference](/reference/on-user-event) for the full event type definitions, payload shapes, and button name reference.
</Update>

<Update label="April 2026" description="v3.10.0">
  ## Custom Steps

  ### New Features

  * **`registerCustomStep()`**: Inject your own UI into the Dromo import flow at any point — after `HEADER_SELECT`, `COLUMN_MATCH`, or `SELECT_MATCH`.
  * **Iframe mode**: Custom steps render a hosted `<iframe>` inside Dromo's standard modal. The page drives navigation by posting `DROMO_NEXT` or `DROMO_BACK` to `window.parent`.
  * **`onMessage` callback**: The iframe can post `DROMO_MESSAGE` with an arbitrary payload to trigger a callback with the uploader instance — use it to call `addField`, `addRows`, and more.
  * **Multiple steps**: Register multiple custom steps at the same position — they are presented in registration order.

  See the [Building a Custom Step UI](/guides/custom-steps) guide for full details and examples.
</Update>

<Update label="March 2026" description="v3.9.0">
  ## XML Import, AI Hook Generator & Schema Studio Settings

  ### New Features

  * **XML File Import**: Dromo now supports client-side parsing of XML files. Configure via `xmlParsingOptions` with support for force array tags, header aliases, custom data sources, and auto plural heuristics. No backend processing required.
  * **AI-Powered Hook Generator**: A new `HookGeneratorModal` with a "Generate" button (sparkle wand icon) lets users generate hook code from a plain-language prompt. Available across all hook editors — Column hooks, Row hooks, Bulk row hooks, and Step hooks.
  * **Schema Studio Settings Panels**: Three new settings sections added to Schema Studio: General, Localization, and Step Customization.

  ### Improvements

  * **Button Style Overrides**: Extended style override schema with new properties for `primaryButton`, `secondaryButton`, and `tertiaryButton`:
    * **`disabledBackgroundColor`**: Sets the background color of a button when it is disabled
    * **`disabledTextColor`**: Sets the text color of a button when it is disabled
    * **`padding`**: Controls button padding (default: `8px 12px`)
  * **Style System Updates**: Updated `ErrorFilterButton` and `ModalHeader` styling for better customizability.
</Update>

<Update label="February 2026" description="v3.8.0">
  ## Text Overrides

  New customization options

  ### New Features

  * **Text Overrides for UI**: Developers can now override in-importer modal text via `textOverrides.ui`. Supported keys: `COLUMN_MATCH_SUBTITLE`, `BULK_FIX_SUBTITLE`

  ### Bug Fixes

  * **Column Matching**: Fixed incorrect labels and missing cross/remove symbol in column match and select match cards
  * **Percentage Numbers**: Fixed parsing and formatting of percentage-formatted number values
  * **Select Field Options**: Fixed an issue where select options were not resolving correctly during data actions
</Update>

<Update label="January 2026" description="v3.7.0">
  ## Session Restore & Accessibility Improvements

  Session restore support, WCAG accessibility enhancements, and critical bug fixes.

  ### New Features

  * **Restore User Session**: Added session restore support with `sessionId` setting; session ID is now returned via the step hook callback
  * **Progress Auto-Save**: New `savePartialSession` setting enables automatic saving of user progress throughout the import flow
  * **Accessibility Fixes**: WCAG improvements across the Column Match and Empty Field card components
  * **Documentation**: [Session Settings Reference](https://developer.dromo.io/reference/settings/settings#savepartialsession)

  ### Bug Fixes

  * **Find & Replace Modal**: Fixed broken modal interactions and select behavior in the Find & Replace flow
  * **Date Parsing**: Multiple fixes for bulk date fixing and edge cases in date parsing
  * **Multi-Select Dropdown**: Fixed multi-select renderer opening multiple dropdowns simultaneously
  * **Keyboard Tabbing**: Fixed tab navigation inside modals
</Update>

<Update label="December 2025" description="v3.6.0">
  ## Multi-Select Field Type & SFTP API Integration

  New multi-select field type for handling multiple selections, plus powerful SFTP APIs for automated file imports.

  ### Multi-Select Field Type

  * **Multiple Value Selection**: New `multi-select` field type allows users to choose multiple values from predefined options
  * **Array Output**: Results returned as `string[]` containing selected option values
  * **Custom Delimiters**: Configure custom delimiters (`,`, `;`, `|`, etc.) for parsing input data
  * **Value Trimming**: Automatic whitespace trimming for cleaner data processing
  * **Many-to-One Mapping**: Map multiple source columns to a single multi-select field with `manyToOne` support
  * **Validation**: Automatic validation of selected values against predefined options with duplicate detection
  * **Flexible Matching**: Support for `alternateMatches` for fuzzy value mapping
  * **Documentation**: [Multi-Select Field Type Reference](https://developer.dromo.io/reference/fields/field-types#multi-select)

  ### SFTP API Integration

  New public APIs for programmatic SFTP integration.

  * **SFTP Credentials API** (`/api/v1/headless/sftp/credentials/`): Full CRUD for SFTP credentials with key-based and password authentication, connection testing, and encrypted storage
  * **SFTP Connectors API** (`/api/v1/headless/sftp/connectors/`): Full CRUD for SFTP connectors with scheduled imports, configurable directory paths, and file regex patterns
  * **Authentication**: Authenticate SFTP API requests with a backend license key in the `X-Dromo-License-Key` header
  * **Documentation**: [SFTP API Reference](https://developer.dromo.io/api-reference/sftp-credentials/list-sftp-credentials)
</Update>

<Update label="November 2025" description="v3.5.0">
  ## Enhanced Style Override Configuration

  New style override configuration options for comprehensive color customization of the Dromo uploader.

  * **Complete Color Control**: Configure text, backgrounds, interactive elements, status colors, borders, and dividers
  * **Full Appearance Customization**: Enhanced color settings to fully customize the Dromo uploader
  * **Custom Color Schemes**: Define your own brand colors for any theme
  * **Light and Dark Examples**: Build a light or dark appearance from individual style override keys using the documented examples
  * **Seamless Experience**: Consistent styling across all import steps and components
  * **Documentation**: [Style Overrides Reference](https://developer.dromo.io/guides/custom-styling)
</Update>

<Update label="October 2025" description="v3.4.0">
  ## Advanced Customization & Enhanced Data Handling

  Major improvements to styling capabilities and import flexibility.

  ### Complete Visual Customization

  * **Data Table Styling**: Full control over table headers, row numbers, cell selection, and interactive elements
  * **Modal Overlay Control**: Customize backdrop appearance with color and opacity settings
  * **Global Styling Enhancements**: New color options for success states, warnings, and backdrop blur effects

  ### Custom Template Downloads

  * **Override Template URLs**: Provide your own custom template files instead of auto-generated CSV
  * **Seamless Integration**: Custom templates download with the same user experience

  ### Smarter Date Processing

  * **Mixed Format Detection**: Automatically handle multiple date formats in the same column
  * **Enhanced International Support**: Better detection of international date formats
  * **Complex Scenario Handling**: Advanced logic for ambiguous and mixed format datasets
  * **Improved Luxon Integration**: Better parsing for various date format standards
</Update>

<Update label="July 2025" description="v3.3.2">
  ## Smarter Date Handling & Improved Reliability

  Enhanced date processing and more reliable import experience.

  ### Automatic Date Detection & Fixing

  * **Smart Date Recognition**: Automatically detects and fixes date format issues across your entire dataset
  * **Bulk Date Correction**: Fix multiple date columns at once instead of row by row
  * **Better Format Support**: Handles more date formats automatically without manual intervention
  * **Reduced Manual Work**: Less time spent manually correcting date formatting errors
  * **Autofix Control**: New `autofix` parameter for date fields lets you control whether format fixes are applied automatically or require user approval

  ### More Reliable Imports

  * **Fewer Import Failures**: Improved stability means fewer interrupted imports
  * **Better Error Recovery**: Imports continue smoothly even when encountering data issues
  * **Cleaner Experience**: Reduced unexpected errors during the import process
</Update>

<Update label="June 2025" description="v3.3.1">
  ## Faster Uploads & Smoother Experience

  Improved upload performance and streamlined user experience.

  ### Upload Improvements

  * **Faster File Uploads**: Significantly improved upload speeds, especially for large files
  * **More Reliable Uploads**: Reduced upload failures and timeouts
  * **Better Progress Tracking**: Clearer visibility into upload progress and status

  ### Streamlined Experience

  * **Smoother Workflow**: Removed unnecessary barriers that could interrupt your import process
  * **Faster Processing**: Quicker data processing means less waiting time
  * **Enhanced Reliability**: More consistent performance across all import operations
</Update>

<Update label="May 2025" description="v3.3.0">
  ## Better Performance with Large Datasets

  Dramatically improved performance when working with large amounts of data and options.

  ### Faster Dropdown Performance

  * **Handle Thousands of Options**: Select fields with thousands of options now load instantly
  * **Smooth Scrolling**: No more lag when browsing through large lists of choices
  * **Responsive Interface**: UI stays fast and responsive even with complex datasets

  ### Streamlined Workflows

  * **Skip Unnecessary Steps**: Automatically bypasses empty field matching to save time
  * **Cleaner Interface**: Improved layout prevents data from being cut off or hidden
  * **Better Error Displays**: Clearer presentation of issues that need your attention
</Update>

<Update label="February 2025" description="API Update">
  ## DEPRECATION of api/v1/upload/\<id>/data/ endpoint

  Dromo is deprecating the `api/v1/upload/<id>/data/` endpoint due to a partial outage caused by endpoint abuse.

  ### What's Changing

  * **Deprecated Endpoint**: `api/v1/upload/<id>/data/`
  * **New Endpoint**: `api/v1/upload/<id>/url/` - returns a URL with the data
  * **Impact**: Users currently using the deprecated endpoint will see a 410 error

  ### Migration Required

  Most users will not need to take action. However, if you're currently using the deprecated endpoint, you must migrate to the new endpoint.

  **Documentation**: [API Reference](https://developer.dromo.io/api#tag/uploads/operation/getUploadUrl)
</Update>

<Update label="October 2024" description="v3.2.1">
  ## More Field Types & Smarter Validation

  Expanded support for different data types and more intelligent validation.

  ### New Data Types

  * **Percentage Fields**: Properly handle and format percentage data
  * **Currency Fields**: Support for different currencies with proper formatting
  * **Phone Numbers**: Validate and format phone numbers from different countries
  * **URLs**: Ensure web addresses are properly formatted and valid
  * **Advanced Text**: Better handling of complex text patterns and formats

  ### Smarter Validation

  * **Context-Aware Rules**: Validation that considers relationships between different fields
  * **Automatic Type Detection**: Dromo can guess the right field type based on your data
  * **Better Error Messages**: More helpful explanations when validation fails
  * **Flexible Rules**: Set up validation that adapts based on other field values
</Update>

<Update label="October 2024" description="v3.2.0">
  ## Custom File Parsers & AI Transformations

  Major expansion of file processing capabilities with custom parsers and AI-powered data transformations.

  ### Custom File Parsers

  * **Support for Custom Formats**: Process PDFs, images, fixed-width formats, XML, and any file type with extractable tabular data
  * **Industry-Leading Parsing**: Builds on Dromo's existing CSV, text-delimited, and Excel support
  * **Documentation**: [Custom File Parsers Guide](https://developer.dromo.io/custom-file-parsers)
  * **Example**: [PDF Import Guide](https://developer.dromo.io/guides/importing-a-pdf)

  ### AI User Transformations

  * **Bulk Data Editing**: Users can now edit import data using plain language AI
  * **Transform Data Button**: New feature in the Review Step
  * **Setting**: Enable with `reviewStep.enableUserTransformations = true`
  * **Guide**: [Using Transform Data](https://developer.dromo.io/guides/using-transform-data)

  ### Automatic Date Format Fixing

  * Enhanced date parsing and automatic format correction
  * Improved handling of various date formats across different file types
</Update>

<Update label="August 2024" description="v3.1.0">
  ## Enhanced Review Experience

  Significant improvements to the data review process with new search capabilities and customization options.

  ### Search on Review Step

  Users can now easily search and filter data during the Review Step using the new search icon.

  <img alt="Search functionality in review step" />

  ### Submission Dialog Customization

  * **Override Confirmation Dialog**: Customize submission confirmation messages
  * **Technical Implementation**: Use `REVIEW_STEP_PRE_SUBMIT` step hook with `setConfirmationMessage` method
  * **Enhanced UX**: Create tailored user interaction experiences

  ### UI Improvements

  * **Redesigned Table Info Messages**: Enhanced tooltips with improved visual design
  * **Multiple Messages Support**: Display multiple message levels (error, warning, info) per cell
  * **HTML Markup Support**: Basic HTML markup support in info messages
  * **Documentation**: [Working with Info Messages](https://developer.dromo.io/hooks#working-with-info-messages)
</Update>

<Update label="June 2024" description="v3.0.5">
  ## Advanced Schema Configuration & Developer Tools

  Powerful new tools for advanced users and developers to have more control over import configuration.

  ### Code Editor for Schema Studio

  * **JSON Editing**: Direct JSON editing for schema settings and fields
  * **Code Completion**: Instant code completion and validation
  * **Hook Writing**: Write row, column, and step hooks directly in Schema Studio
  * **Toggle Feature**: "Edit JSON" option for power users

  ### Enhanced Configuration Options

  * **Step Skipping**: New options to streamline imports
    * "Always use first row for headers" (`matchingStep.headerRowOverride = 0`)
    * "Remember mapped headers and values" (`autoMapHeaders = true`)
  * **Initial File Setting**: Pass files directly with `initialFile` setting (similar to `initialData`)
  * **Import Management**: Delete imports directly from dashboard with trash icon

  ### Row and Submission Control

  * **Empty Submission Control**: New `allowEmptySubmit` setting to prevent empty imports
  * **Row Manipulation Settings**:
    * `reviewStep.allowAddingRows` - Control user ability to add rows
    * `reviewStep.allowRemovingRows` - Control user ability to remove rows
  * **Documentation**: [Settings Reference](https://developer.dromo.io/settings)
</Update>

<Update label="May 2024" description="v3.0.0">
  ## Advanced Data Mapping & Column Handling

  Enhanced data mapping capabilities with more granular control over field mapping and data processing.

  ### Enhanced Field Mapping

  * **Select Field Limits**: `maxMappableSelectFields` setting to control option mapping UI
  * **Unmapped Column Access**: `passThroughUnmappedColumns` setting to preserve all original data
  * **Help Text Configuration**: Add guidance with `matchValuesStep.helpText`

  ### Data Processing Improvements

  * **Complete Data Preservation**: Access all columns from original file via `$unmapped` key
  * **Flexible Mapping Control**: Override default limits for complex datasets
  * **Better User Guidance**: Enhanced help text for value matching steps

  Example unmapped data structure:

  ```json theme={null}
  {
      "$unmapped": {
          "1": "Phillips",
          "3": "(124) 246-3980",
          "4": "United States"
      },
      "firstName": "Michael",
      "email": "jason@moxie.xyz"
  }
  ```
</Update>

<Update label="December 2023" description="v2.8.2">
  ## Faster Processing & Better Reliability

  Significant improvements to import speed and overall platform reliability.

  ### Faster Imports

  * **Quicker Large File Processing**: Import large datasets much faster than before
  * **Reduced Wait Times**: Less time spent waiting for imports to complete
  * **Better Memory Usage**: Handle bigger files without performance issues
  * **Improved Response Times**: Faster navigation and interaction throughout the platform

  ### Enhanced Reliability

  * **Fewer Errors**: More robust system that handles edge cases better
  * **Better Uptime**: Improved platform stability and availability
  * **Stronger Security**: Enhanced protection for your data and imports
</Update>

<Update label="November 2023" description="v2.8.1">
  ## Smarter Validation & Better User Experience

  More intelligent data validation and improved interface design.

  ### Enhanced Data Validation

  * **Context-Aware Validation**: Validation rules that consider relationships between fields
  * **Cross-Row Consistency**: Ensure data consistency across your entire dataset
  * **Clearer Error Messages**: Better explanations of what needs to be fixed
  * **Faster Validation**: Quicker validation processing for large imports

  ### Improved Interface

  * **Better Error Display**: Clearer presentation of issues that need attention
  * **Smoother Navigation**: More intuitive flow between import steps
  * **Mobile-Friendly**: Better experience on phones and tablets
  * **Helpful Loading States**: Know exactly what's happening during processing
</Update>

<Update label="November 2023" description="v2.8.0">
  ## Authentication & Advanced Data Features

  New authentication options and powerful data manipulation features.

  ### Google Sign-In

  * **Simplified Login**: Sign in to the dashboard with your Google account
  * **Reduced Account Management**: One less account to keep track of

  ### Many-to-One Field Mapping

  * **Multiple Column Mapping**: Map multiple file columns to a single schema field
  * **Array Results**: Results returned as arrays when `manyToOne` is enabled
  * **Use Cases**: Map "primary email" and "secondary email" to single "email" field
  * **Guide**: [Using manyToOne](https://developer.dromo.io/guides/using-manyToOne)

  ### Find and Replace

  * **Bulk Error Correction**: Quick correction of errors across datasets
  * **Flexible Matching**: Case-sensitive options and substring matching
  * **Scope Control**: Apply to specific columns or entire import dataset
  * **Review Step Integration**: Accessible from review step toolbar
</Update>

<Update label="October 2023" description="v2.7.0">
  ## Enhanced File Handling & Import Management

  Improved file processing and new import management capabilities.

  ### File Processing Improvements

  * **Improved Excel Date Parsing**: More reliable date parsing regardless of locale-specific formatting
  * **Original File Access**: Download original uploaded files via `raw_upload.download_url`
  * **Better Data Integrity**: Compare original and transformed files

  ### Import Management

  * **Hosted Imports**: Create public links directly from Schema Studio dashboard
  * **No-Code Solution**: Share import links without writing code
  * **Simplified Sharing**: Third option alongside embedding and API methods

  ### User Management

  * **Dashboard User Roles**: Specify user roles when inviting team members
    * **Admins**: Full access including user management and billing
    * **Users**: Access to schemas and imports, limited admin functions
</Update>

<Update label="July 2023" description="v2.1.0">
  ## Announcing the Headless API

  We're excited to announce the launch of our **Headless API** as a premium Dromo Pro add-on! This powerful new feature enables developers to integrate Dromo's data import capabilities directly into their applications.

  ### Key Features

  * **Saved Schema API**: Programmatically manage and retrieve your import schemas
  * **Enhanced API Documentation**: Comprehensive guides and examples
  * **Zapier Integration**: Connect Dromo with thousands of other apps
  * **Improved Schema Studio**: Better tools for schema management
  * **New Website**: Fresh design and improved user experience
</Update>

<Update label="May 2023" description="v2.0.5">
  ## Enhanced User Experience & Multilingual Support

  ### New Features

  * **Multilingual Support**: Dromo now supports 30+ languages for a global user experience
  * **Enhanced Error Filtering**: Better tools to identify and resolve data issues
  * **Schema-based Column Matching**: Smarter automatic column detection
  * **Programmatic Row Management**: More control over data processing

  ### Improvements

  * More customization options across the platform
  * Streamlined user workflows
  * Better error messaging and guidance
</Update>

<Update label="April 2023" description="v2.0.0">
  ## Version 2 - Complete Platform Redesign

  We've completely rebuilt Dromo from the ground up with a focus on simplicity and power.

  ### Major Updates

  * **Complete UI Redesign**: Fresh, modern interface that's easier to navigate
  * **Streamlined Header Row Selection**: Simplified process for identifying data headers
  * **Simplified Column Matching**: Intuitive drag-and-drop column mapping
  * **New Data Wizard**: Step-by-step guidance through the import process
  * **Rich Error Export**: Detailed error reports with actionable insights
  * **Excel Parsing in Private Mode**: Enhanced security for sensitive data processing

  ### Under the Hood

  * Improved performance and reliability
  * Better error handling and user feedback
  * Enhanced data validation capabilities
</Update>

<Update label="March 2023" description="v1.9.0">
  ## Schema Builder Enhancements & Broader File Support

  ### Schema Builder Improvements

  * Enhanced settings and configuration options
  * Better field management capabilities
  * Improved validation rules setup

  ### File Type Expansion

  * Support for additional file formats
  * Better parsing accuracy across different file types
  * Enhanced encoding detection

  ### Developer Experience

  * New field mapping requirements for better data accuracy
  * Preparation and foundation work for Version 2
  * Improved API responses and error handling
</Update>

<Update label="February 2023" description="v1.8.0">
  ## Schema Builder Launch & Major Feature Additions

  ### 🎉 Schema Builder

  Introducing our powerful **Schema Builder** - create and manage import schemas with a visual interface.

  * **Drag & Drop Interface**: Build schemas visually
  * **Field Validation**: Set up complex validation rules
  * **Preview Mode**: Test your schemas before deployment

  ### Bring Your Own Storage (BYOS)

  * **Custom Storage Integration**: Use your own cloud storage solutions
  * **Data Sovereignty**: Keep your data where you need it
  * **Enterprise Security**: Enhanced security for sensitive data

  ### Advanced Features

  * **Hidden Fields**: Include fields in processing without displaying them to users
  * **Field Removal**: Dynamically remove unnecessary fields during import
  * **Dynamic Select Options**: Create dropdown fields with dynamic option lists
  * **Improved AI Column Matching**: Smarter automatic field detection and mapping

  ### Developer Tools

  * Enhanced API capabilities
  * Better webhook support
  * Improved error handling and logging
</Update>

<Update label="June 2022" description="v1.7.0">
  ## Automatic Column Matching & Enhanced Validation

  ### Smart Automation

  * **Automatic Column Matching**: Column mapping is now automatically skipped if all headers exactly match the schema field names
  * Skip the mapping step entirely when your data structure is consistent

  ### Enhanced Validation

  * **Custom Select Field Validation**: Added `invalidValueMessage` for select fields
  * Better error messaging for validation failures
  * More granular control over validation rules

    <img alt="Custom validation messages" />

  ### User Experience

  * **Simplified Sign-up Flow**: Streamlined registration process - just email and password
  * Faster onboarding for new users
  * Reduced friction in the user journey

  ### Bug Fixes

  * **Column Labeling**: Fixed issues with column labeling beyond 26 columns (AA, AB, AC...)
  * **Character Encoding**: Enhanced detection and handling of different character encodings
  * Improved overall stability and performance
</Update>

<Update label="August 2022" description="v1.7.2">
  ## Faster Processing & Better Data Quality

  Significant improvements to import speed and data accuracy detection.

  ### Performance Improvements

  * **Faster Large File Imports**: Process big files much quicker
  * **More Efficient Processing**: Handle complex datasets without slowdowns
  * **Better Progress Tracking**: See exactly how your import is progressing

  ### Enhanced Data Quality

  * **Smarter Duplicate Detection**: Automatically identify potential duplicate records
  * **Data Consistency Checks**: Spot inconsistencies across your dataset
  * **Quality Insights**: Get automatic feedback on your data quality
  * **Better Error Highlighting**: Easily spot and fix data issues

  ### Improved Workflow

  * **Bulk Operations**: Fix multiple issues at once instead of one by one
  * **Clearer Status Updates**: Always know what's happening with your import
</Update>

<Update label="July 2022" description="v1.7.1">
  ## Enhanced Security & Enterprise Features

  Stronger security and new enterprise capabilities.

  ### Improved Security

  * **Better Data Protection**: Enhanced encryption and security measures
  * **Stronger Access Controls**: More control over who can access what
  * **Complete Activity Tracking**: Full audit trail of all actions taken
  * **Reliable Authentication**: More secure and stable login system

  ### Enterprise Features

  * **Single Sign-On**: Use your company's existing login system
  * **Custom Domains**: Use your own domain for the import experience
  * **Advanced Monitoring**: Better visibility into system performance and usage

  ### API Improvements

  * **More Reliable Webhooks**: Better delivery of real-time notifications
  * **Faster Response Times**: Quicker API responses for better integration performance
  * **Enhanced Documentation**: More examples and clearer guidance for developers
</Update>

<Update label="June 2022" description="v1.6.5">
  ## Enhanced Data Processing & Invalid Data Management

  ### Invalid Data Behavior Configuration

  Introducing the new `invalidDataBehavior` configuration option - "More options for dealing with unresolved errors" - with three modes:

  * **`REMOVE_INVALID_ROWS`** (default): Automatically filter out rows with validation errors
  * **`INCLUDE_INVALID_ROWS`**: Include invalid rows in the final dataset with error flags
  * **`BLOCK_SUBMIT`**: Prevent submission until all validation errors are resolved

  ### API Enhancements

  * **Filename in Callbacks**: The original filename is now available in the `onResults` callback
  * Better metadata tracking for imported files
  * Enhanced error reporting in API responses

  ### Data Processing

  * **Smart Column Handling**: Empty columns are automatically dropped during import
  * Reduced noise in your final dataset
  * Better performance with large files containing empty columns

  ### Developer Experience

  * More flexible error handling options
  * Better integration with existing validation workflows
  * Enhanced debugging capabilities
</Update>

<Update label="March 2022" description="v1.6.0">
  ## Redesigned Interface & Real-time Validation

  Major visual improvements and instant validation feedback.

  ### New Look and Feel

  * **Modern Interface**: Fresh, cleaner design that's easier to use
  * **Mobile-Friendly**: Better experience on all device sizes
  * **Improved Accessibility**: More accessible for users with disabilities
  * **Smoother Navigation**: Easier movement between import steps

  ### Instant Validation

  * **Real-time Feedback**: See validation errors immediately as you work
  * **Custom Business Rules**: Set up validation that matches your specific needs
  * **Bulk Validation**: Check multiple records at once for efficiency
  * **Reusable Rules**: Save validation templates for repeated use

  ### Better Performance

  * **Faster Loading**: Large datasets display quicker
  * **Smoother Experience**: No more waiting for the interface to catch up
</Update>

<Update label="January 2022" description="v1.5.5">
  ## Better Integrations & Export Options

  Expanded ways to connect Dromo with other tools and export your data.

  ### Enhanced Integrations

  * **More App Connections**: Connect with popular business applications
  * **Reliable Webhooks**: More dependable real-time notifications
  * **Better Error Messages**: Clearer feedback when integrations have issues
  * **Flexible API Options**: More control over how you integrate with Dromo

  ### Improved Export Options

  * **Multiple File Formats**: Export as CSV, Excel, JSON, and more
  * **Automated Exports**: Schedule exports to run automatically
  * **Custom Export Templates**: Create reusable export formats
  * **Bulk Export**: Export multiple imports at once

  ### Developer Experience

  * **Better SDKs**: Improved libraries for different programming languages
  * **Testing Tools**: Easier ways to test your integrations
  * **Comprehensive Documentation**: More examples and clearer guidance
</Update>

<Update label="November 2021" description="v1.5.0">
  ## Expanded File Support & Streamlined Experience

  Better support for different file types and a simpler import process.

  ### More File Types Supported

  * **Broader Format Support**: Handle more file formats and character encodings
  * **Better Error Detection**: Catch and explain file issues more clearly
  * **Advanced Data Transformation**: More ways to clean and modify your data during import
  * **Stronger Validation**: Better checking to ensure your data meets requirements

  ### Simplified Workflow

  * **Fewer Steps**: Streamlined import process gets you to results faster
  * **Better Progress Visibility**: Always know how your import is progressing
  * **Improved Error Recovery**: Easier ways to fix issues when they occur
  * **Contextual Help**: Get guidance right when and where you need it

  ### Enhanced Performance

  * **Faster Processing**: Quicker handling of your data imports
  * **Handle Larger Files**: Better support for big datasets
  * **More Reliable**: Fewer failed imports and better error handling
</Update>


# FAQs
Source: https://developer.dromo.io/faqs

Find answers to common questions about Dromo's spreadsheet importer, security, supported files, integrations, billing, and product capabilities.

## Company[​](#company "Direct link to Company")

### What is Dromo's mission?[​](#what-is-dromos-mission "Direct link to What is Dromo's mission?")

Dromo exists to deliver shockingly pleasant **data file importing** software to fast-paced teams on a budget.

### What does "Dromo" mean?[​](#what-does-dromo-mean "Direct link to What does \"Dromo\" mean?")

Dromo is a Greek word meaning "road," and holds a particular significance in the data industry. Often, we hear the euphemism of a "data pipeline", suggesting a seamless, direct journey for data from its source to its destination. In reality, data travels more often along a meandering road, filled with potholes, bumps, and twists.

In many organizations, this road is always under construction. New on-ramps and exits emerge all the time, making the route unpredictable. At times, it leads somewhere useful, but frequently it dead ends.

Dromo honors the winding road that your data must travel in order to become useful, and we're here to help you navigate it.

### Who's behind Dromo?[​](#whos-behind-dromo "Direct link to Who's behind Dromo?")

Dromo is backed by a constellation of over **three dozen** diverse investors and operators with expertise building exceptional companies like Discord, Vercel, Shopify, Palantir, Meta, and Salesforce.

### Do you provide support?[​](#do-you-provide-support "Direct link to Do you provide support?")

Yes! But don't take our word for it. Here's what one of our customers had to say:

> "I have worked with a lot of different vendors over the years, and the timeliness and helpfulness of the Dromo team in response to our questions has got to be the best I've ever experienced."

If you encounter any problems or have any questions, please reach out to our [support team](mailto:contact@dromo.io) or start a conversation using the chat app (in the lower right-hand corner of any page). We're here to help! We also offer same-day Slack support for customers on an enterprise plan.

### Where is Dromo based?[​](#where-is-dromo-based "Direct link to Where is Dromo based?")

Dromo is a Delaware C corporation based in San Francisco. We support customers on six continents and over 30 languages (see the full list [here](/reference/settings/settings#locale)).

### Where can I find updates about the product?[​](#where-can-i-find-updates-about-the-product "Direct link to Where can I find updates about the product?")

We publish regular updates [here](https://developer.dromo.io/changelog).

### How can I monitor Dromo's uptime and availability?[​](#how-can-i-monitor-dromos-uptime-and-availability "Direct link to How can I monitor Dromo's uptime and availability?")

We publish these stats 24/7 [here](https://status.dromo.io/).

## Features and functionality[​](#features-and-functionality "Direct link to Features and functionality")

### What are the steps of the import process?[​](#what-are-the-steps-of-the-import-process "Direct link to What are the steps of the import process?")

Typically, the import flow starts with the user uploading a file. Then, they match their columns to the fields you expect (or the importer does this automatically on their behalf). Then, they have the option to perform bulk transformations on the data. Finally, they review and correct any remaining errors.

### Does an end user have to upload a file to use Dromo?[​](#does-an-end-user-have-to-upload-a-file-to-use-dromo "Direct link to Does an end user have to upload a file to use Dromo?")

No. A user has the option to skip uploading a file and enter their data manually (copying and pasting is supported) as long as the [`manualInputDisabled`](/reference/settings/settings#manualinputonly) flag is not set.

You may also launch an import programmatically using the Headless API (this feature is a premium add-on). If there are any errors during the import process (for example, a column cannot be matched automatically or a data validation fails) you are provided a URL where you can direct your user to fix the issues. If there are no errors, the import succeeds automatically and the user does not need to be involved.

### What file types does the importer support?[​](#what-file-types-does-the-importer-support "Direct link to What file types does the importer support?")

The importer handles CSV, XLS, XLSX, and TSV files out of the box.

We can also support spreadsheets in all the legacy Excel formats (Excel 2007+, Excel 97-2004, Excel 2.0-5.0), Lotus 1-2-3, Quattro Pro, Works, OpenDocument, Uniform Office Format, and Numbers, as well as DIF files, HTML tables, and RTF tables. Please [contact us](mailto:contact@dromo.io) if you need additional file type support.

### Do you support JSON files?[​](#do-you-support-json-files "Direct link to Do you support JSON files?")

Yes, but a user cannot upload the file directly to Dromo. You must parse the file and provide the contents to Dromo via the [`initialData`](/reference/settings/settings#initialdata) setting.

### What is the maximum row count / file size that can be imported?[​](#what-is-the-maximum-row-count--file-size-that-can-be-imported "Direct link to What is the maximum row count / file size that can be imported?")

Any in-browser importer is ultimately constrained by the resources of the user's browser, but Dromo can typically handle files with several hundred thousand rows without problems.

For maximum performance with very large files (e.g., 1 million+ rows), we recommend using Dromo Headless, which processes files on an optimized server. There is no limit to the row count or file size that Dromo Headless can handle.

### Can you match a user's columns to fields in my database?[​](#can-you-match-a-users-columns-to-fields-in-my-database "Direct link to Can you match a user's columns to fields in my database?")

Yes, the Dromo importer provides an intuitive mapping interface that allows your user to match their columns to the fields you require. We harness OpenAI to assist users in the mapping process.

### Can you remember mappings from one import to the next?[​](#can-you-remember-mappings-from-one-import-to-the-next "Direct link to Can you remember mappings from one import to the next?")

Yes, you can achieve this with the [`autoMapHeaders`](/reference/settings/settings#automapheaders) setting. When enabled, the importer will remember mappings of prior imports that used the same `importIdentifier`.

### What happens if there are errors during the import process?[​](#what-happens-if-there-are-errors-during-the-import-process "Direct link to What happens if there are errors during the import process?")

At the end of an import, the user is shown a familiar workbook interface, which highlights and annotates any remaining issues in the data. From here, they can quickly isolate, diagnose, and correct any errors.

### What happens if you cannot finish an import in one session?[​](#what-happens-if-you-cannot-finish-an-import-in-one-session "Direct link to What happens if you cannot finish an import in one session?")

From the review screen, the user may download the current state of the import as an Excel file, complete with error annotations. The user then has the option to fix those errors offline. Whenever they re-upload that file, the importer will pick up where they left off.

### What does a finished import look like?[​](#what-does-a-finished-import-look-like "Direct link to What does a finished import look like?")

Dromo returns a JSON object containing the final data. Now that it has been validated and cleaned, you can move it to the next stage of your data pipeline (e.g., upsert it into a database) with confidence. Dromo also returns a separate JSON object containing metadata about the import, such as any identifying user data you provided prior to the import and stats about the import itself (e.g., the total number of rows).

### How do I handle the results of an import?[​](#how-do-i-handle-the-results-of-an-import "Direct link to How do I handle the results of an import?")

The results and metadata objects are both sent to your application via the [`onResults`](/reference/results) callback. If you elect to enable the [`backendSyncMode`](/reference/settings/settings#backendsyncmode) setting, the data will also be stored on your behalf. In that case, you may access the original version of the file and final results (in CSV or JSON format) via the Imports tab of the [Dashboard](https://dashboard.dromo.io), or you may access the final results and metadata via the [API](/api-reference).

### How will I know when a user has finished an import?[​](#how-will-i-know-when-a-user-has-finished-an-import "Direct link to How will I know when a user has finished an import?")

You may either handle the the [`onResults`](/reference/results) callback directly in your application, or you may use a [webhook](/reference/webhooks). In that case, Dromo will send a POST request to any address you specify in the [`webhookUrl`](/reference/settings/settings#webhookurl) setting whenever an import is completed.

## Customization[​](#customization "Direct link to Customization")

### Do you have a white-label option?[​](#do-you-have-a-white-label-option "Direct link to Do you have a white-label option?")

Dromo is exclusively white-label. We believe you should have total control over your end users' import experience, so we do not include Dromo branding anywhere in the importer.

### Can I customize the styling?[​](#can-i-customize-the-styling "Direct link to Can I customize the styling?")

Yes, you can customize the look-and-feel of the importer using the [`styleOverrides`](/reference/settings/settings#styleoverrides) setting.

### Can I customize the error messages and help text that my users see?[​](#can-i-customize-the-error-messages-and-help-text-that-my-users-see "Direct link to Can I customize the error messages and help text that my users see?")

Yes. In Dromo Pro, error messages for built-in [validators](/reference/fields/field-validators) can be customized by providing an `errorMessage` in the JavaScript SDK. You may also write [custom messages](/reference/hooks#working-with-info-messages), including error messages, to any cell using row or column hooks.

You may customize the help text at each step (i.e., Upload Step, Matching Step, and Review Step) by providing the appropriate [`helpText`](/reference/settings/settings#helptext) setting.

## Security[​](#security "Direct link to Security")

### What is Private Mode?[​](#what-is-private-mode "Direct link to What is Private Mode?")

In Private Mode, the data file uploaded by the end user is processed entirely in the context of their web browser, and the results are shared back to your application directly. To enable Private Mode, set [`backendSyncMode`](/reference/settings/settings#backendsyncmode) to `DISABLED`. The Dromo Pro SDK enables Private Mode by default.

### How does Dromo protect end user data?[​](#how-does-dromo-protect-end-user-data "Direct link to How does Dromo protect end user data?")

Dromo believes the best way to protect your end user data is to never have access to it in the first place. To that end, we offer numerous options for operating Dromo without end user data ever transiting our servers or networks.

By default, the embedded Dromo Pro SDK runs in [Private Mode](/faqs#what-is-private-mode).

If you set [`backendSyncMode`](/reference/settings/settings#backendsyncmode) to `MAPPINGS_ONLY`, then information about column headers will be shared with Dromo (this is required to enable certain advanced features like AI-assisted column mapping and remembering mappings from prior imports), but the rest of the file is not shared with Dromo.

If you choose to disable Private Mode (i.e., by setting `backendSyncMode` to `FULL_DATA`) but want to store imports in your own infrastructure, you can enable the premium Bring Your Own Storage feature.

NB: When using the Headless API (instead of an embedded importer), Dromo processes end user data on a server.

Should you store or otherwise share end user data with Dromo, we will process it solely to the extent reasonably required for the delivery of our service. For more information on how we treat end user data, read [here](https://dromo.io/legal/terms#end-user-data).

### Are you SOC 2 certified?[​](#are-you-soc-2-certified "Direct link to Are you SOC 2 certified?")

Yes. We can make our security report available under MNDA.

### Do you offer BAAs for HIPAA compliance?[​](#do-you-offer-baas-for-hipaa-compliance "Direct link to Do you offer BAAs for HIPAA compliance?")

Yes. Where possible we use the standard BAA [template](https://www.hhs.gov/sites/default/files/model-business-associate-agreement.pdf) from HHS.

If your end users might be importing PHI (protected health information) about themselves or others, we strongly encourage you to not share or store that data with any third party unnecessarily, including Dromo! Instead, we recommend you either 1) exclusively run Dromo Pro in [Private Mode](/faqs#what-is-private-mode), 2) enable the Bring Your Own Storage option (requires an enterprise plan), or 3) deploy Dromo on-prem.

### How long does Dromo retain imported data?[​](#how-long-does-dromo-retain-imported-data "Direct link to How long does Dromo retain imported data?")

Dromo retains imported data according to your organization's configured retention period. You can manage this period in the Organization section of the [Dromo Dashboard](https://dashboard.dromo.io). Retention is indefinite by default, and custom retention periods are configurable.

### Does Dromo support single sign-on (SSO)?[​](#does-dromo-support-single-sign-on-sso "Direct link to Does Dromo support single sign-on (SSO)?")

Yes. Dromo supports Google SSO today, and support for additional identity providers is in progress.

### Are you GDPR compliant?[​](#are-you-gdpr-compliant "Direct link to Are you GDPR compliant?")

Yes, but with respect to European data subjects, we recommend the same best practices for GDPR compliance as we do for HIPAA compliance (see above), so that no third party needs to process or control your end user data unnecessarily.

We offer Standard Contractual Clauses (SCCs) for controller-to-processor (Module 2) and processor-to-processor (Module 3) arrangements, where necessary. To request a copy, please [contact us](mailto:privacy@dromo.io). Indicate if you require Module 2 or Module 3 and an international data transfer addendum (for transfers out of the UK).

### What is "Bring Your Own Storage"?[​](#what-is-bring-your-own-storage "Direct link to What is \"Bring Your Own Storage\"?")

When you enable the Bring Your Own Storage (BYOS) feature, your data is persisted directly from the user's browser to your storage layer (such as AWS S3 or GCP Cloud Storage, in a bucket owned by you). When BYOS is enabled for an embedded importer, Dromo does not have any access to user data at any point in the import process, but the import results are available to you in your cloud.

The purpose of BYOS is to provide similar security benefits as a fully self-hosted solution at a fraction of the cost and with minimal additional overhead to manage.

This is a premium add-on. To learn more, [contact us](mailto:contact@dromo.io) by email or [get a quote](https://dromo.io/get-a-quote).

### Do you offer a self-hosted solution?[​](#do-you-offer-a-self-hosted-solution "Direct link to Do you offer a self-hosted solution?")

You may choose to self-host your user data by enabling the premium "Bring Your Own Storage" feature.

Dromo also offers a fully self-hosted solution, where you can deploy our full stack in your cloud using Kubernetes.

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

### I'm trying to use NextJS and running into issues. What do I do?[​](#im-trying-to-use-nextjs-and-running-into-issues-what-do-i-do "Direct link to I'm trying to use NextJS and running into issues. What do I do?")

Dromo must be used as a client component. To use Dromo in NextJS, make sure to add `'use client'` to the top of the file with the Dromo importer.


# Angular Quickstart
Source: https://developer.dromo.io/getting-started/angular

Install the Dromo Angular SDK, define fields and settings, launch the spreadsheet importer, and handle completed import results.

<Note>
  Are you looking for a framework other than Angular? Check the Getting Started
  guides in the sidebar.
</Note>

## Step By Step Guide

Our SDK for Angular currently supports Angular versions 13-17. Have a look at our [live example](https://codesandbox.io/s/dromo-developer-demo-angular-wbxuzt?file=/src/app/dromo-importer/dromo-importer.component.ts) for inspiration.

<Steps>
  <Step title="Installation">
    To install the Dromo Angular SDK in your application, just install the NPM package `dromo-uploader-angular`.

    <CodeGroup>`bash Terminal npm install dromo-uploader-angular `</CodeGroup>

    Then, add the `DromoUploaderModule` to your imports.

    <CodeGroup>
      ```typescript app.module.ts theme={null}
      // app.module.ts
      import { NgModule } from '@angular/core';
      import { BrowserModule } from '@angular/platform-browser';
      import { DromoUploaderModule } from 'dromo-uploader-angular';
      import { AppComponent } from './app.component'; // Assuming AppComponent is in app.component.ts

      @NgModule({
      declarations: [AppComponent],
      imports: [BrowserModule, DromoUploaderModule],
      providers: [],
      bootstrap: [AppComponent]
      })
      export class AppModule {}

      ```
    </CodeGroup>
  </Step>

  <Step title="Usage">
    The `DromoUploaderModule` provides the `lib-dromo-uploader` component. You can create a wrapper component to provide its configuration.
    Below are examples of how you might set up your component: one for a full manual configuration, and another using a schema defined in Dromo's Schema Studio.

    <CodeGroup>
      ```typescript "my-uploader.component.ts (Manual Setup)" theme={null}
      // my-uploader.component.ts
      import { Component } from '@angular/core';
      import {
        DromoMethods,
        IColumnHook,
        IColumnHookInput,
        IRowDeleteHook,
        IRowHook,
        IStepHook,
        IUploadStepData,
        IBatchRowHook,
        IBulkRowHook,
        IBeforeFinishCallback
      } from 'dromo-uploader-angular';

      @Component({
        selector: 'my-uploader',
        template: `
          <lib-dromo-uploader
            [licenseKey]="licenseKey"
            [user]="user"
            [fields]="fields"
            [settings]="settings"
            [rowHooks]="rowHooks"
            [columnHooks]="columnHooks"
            [stepHooks]="stepHooks"
            [rowDeleteHooks]="rowDeleteHooks"
            [styles]="styles"
            [class]="class"
            class="dromo-importer"
            [onCancel]="onCancel"
            [onResults]="onResults"
            [beforeFinish]="beforeFinish"
            [batchRowHooks]="batchRowHooks"
            [bulkRowHooks]="bulkRowHooks"
          >
            Import with Dromo!
          </lib-dromo-uploader>
        `,
      })
      export class MyUploader implements DromoMethods {
        licenseKey = 'YOUR_LICENSE_KEY_HERE';
        user = { id: 'angular tester' };
        fields = [
          { label: 'first name', key: 'first_name' },
          { label: 'email address', key: 'email' }
        ];
        settings = {
          importIdentifier: 'angular imports',
          developmentMode: true
        };
        rowHooks: IRowHook[] = [
          (record) => {
            const newRecord = { ...record };
            newRecord.row['first_name'].value = record.row['first_name'].value + '!!!';
            return newRecord;
          }
        ];
        rowDeleteHooks: IRowDeleteHook[] = [(record) => alert(`deleted ${record.index}`)];
        columnHooks: IColumnHook[] = [
          {
            fieldName: 'email',
            callback: (values: IColumnHookInput[]) => {
              console.log('COLUMN HOOK', values);
              return values.map(({ value, index }) => ({ value: index + value, index }));
            }
          }
        ];
        stepHooks: IStepHook[] = [
          {
            type: 'UPLOAD_STEP',
            callback: (uploader, data) => {
              console.log(
                'STEP HOOK',
                `Filename: ${(data as IUploadStepData).filename}`
              );
            }
          }
        ];
        onCancel = () => alert('Something I said?');
        onResults = (data: any[], metaData: any) => {
          alert(`Submitted ${data.length} records`);
          console.table(data);
          console.log('MetaData', metaData);
        };
        bulkRowHooks: IBulkRowHook[] = [
          (data, _mode) => {
            console.log('in the bulk row hook!');
            return data;
          }
        ];
        batchRowHooks: IBatchRowHook[] = [
          (batch, batchNumber) => {
            console.log(`Processing batch ${batchNumber}`);
            return batch;
          }
        ];
        beforeFinish: IBeforeFinishCallback = (data, metaData, _instance) => {
          console.log(`${data.length} total rows!`);
          if (metaData.rowsWithError.length > 10) {
            return { cancel: true, message: 'More than ten errors, fix them first!' };
          }
          return undefined;
        };
        class = 'dromo-button';
        styles = {
          'background-color': 'rgb(0, 123, 255)',
          border: '1px solid rgb(0, 123, 255)',
          'border-radius': '0.25rem',
          color: 'white',
          padding: '15px',
          'text-align': 'center',
          'text-decoration': 'none',
          display: 'inline-block',
          'font-size': '16px',
          'box-shadow': '5px 5px 5px 0px #7F7F7F'
        };
      }
      ```

      ```typescript "my-uploader.component.ts (Schema Studio)" theme={null}
      // my-uploader.component.ts
      import { Component } from "@angular/core";
      import {
        IUser,
        IBeforeFinishCallback,
        DromoSavedSchemaMethods,
      } from "dromo-uploader-angular";

      @Component({
        selector: "app-dromo-importer",
        template: `
          <lib-dromo-uploader
            [licenseKey]="licenseKey"
            [schemaId]="schemaId"
            [user]="user"
            [styles]="styles"
            [class]="class"
            [onCancel]="onCancel"
            [onResults]="onResults"
            [beforeFinish]="beforeFinish"
            [developmentMode]="developmentMode"
            class="dromo-importer"
          >
            Import with Dromo!
          </lib-dromo-uploader>
        `,
        styleUrls: ["./dromo-importer.component.css"],
      })
      export class DromoImporterComponent implements DromoSavedSchemaMethods {
        schemaId = "00000000-0000-0000-0000-000000000000";
        licenseKey = "<YOUR LICENSE KEY>";
        user: IUser = { id: "angular tester" };
        developmentMode = true;
        onCancel = () => alert("Something I said?");
        onResults = (data: any[], metaData: any) => {
          alert(`Submitted ${data.length} records`);
          console.table(data);
          console.log("MetaData", metaData);
        };
        beforeFinish: IBeforeFinishCallback = (data, metaData, _instance) => {
          console.log(`${data.length} total rows!`);
          if (metaData.rowsWithError.length > 2) {
            return { cancel: true, message: "More than two errors, fix them first!" };
          }
          return undefined;
        };
        class = "dromo-button";
        styles = {
          "background-color": "rgb(0, 123, 255)",
          border: "1px solid rgb(0, 123, 255)",
          "border-radius": "0.25rem",
          color: "white",
          padding: "15px",
          "text-align": "center",
          "text-decoration": "none",
          display: "inline-block",
          "font-size": "16px",
          "box-shadow": "5px 5px 5px 0px #7F7F7F",
        };
      }
      ```
    </CodeGroup>
  </Step>
</Steps>


# Embedded Importers
Source: https://developer.dromo.io/getting-started/embedded

Choose an embedded Dromo SDK, launch the importer in your application, and understand when to use embedded or headless imports.

An embedded Dromo importer runs inside your web application and guides users through uploading, matching, cleaning, and reviewing their data. Your application configures the import and receives the cleaned results when the user finishes.

## Choose an SDK

<CardGroup>
  <Card title="JavaScript" icon="js" href="/getting-started/javascript">
    Use the core SDK in any browser application.
  </Card>

  <Card title="React" icon="react" href="/getting-started/react">
    Use the Dromo component and React props.
  </Card>

  <Card title="Angular" icon="angular" href="/getting-started/angular">
    Use the Angular component, inputs, and outputs.
  </Card>
</CardGroup>

All three integrations use the same fields, settings, hooks, and result model. The React and Angular packages wrap the JavaScript SDK with framework-native components.

## How an embedded import works

<Steps>
  <Step title="Configure the importer">
    Provide a frontend license key, [fields](/reference/fields/fields), [settings](/reference/settings/settings), and user metadata. You can also use a saved schema from Schema Studio.
  </Step>

  <Step title="Open it in your application">
    The SDK displays Dromo in an iframe within a modal or inline container. Users upload a file and resolve mapping or validation issues without leaving your application.
  </Step>

  <Step title="Receive cleaned results">
    Handle the [`onResults` callback](/reference/results) to send the validated data to your application. You can optionally sync imports to Dromo and receive webhooks.
  </Step>
</Steps>

## Embedded or headless?

|                    | Embedded                                 | Headless                                        |
| ------------------ | ---------------------------------------- | ----------------------------------------------- |
| Best for           | User-guided imports in a web application | Automated or server-driven imports              |
| Initial processing | In the user's browser by default         | On Dromo's servers                              |
| Resolving issues   | Directly in the embedded importer        | Through a review URL when human input is needed |
| Integration        | JavaScript, React, or Angular SDK        | REST API                                        |

Use an embedded importer when users should see and control the import flow. Use the [Headless API](/getting-started/headless) when imports should begin from your backend or run without an initial user interface.

<Note>
  Embedded imports can run in [Private Mode](/faqs#what-is-private-mode), where end-user file data remains in the browser.
</Note>


# Headless Quickstart
Source: https://developer.dromo.io/getting-started/headless

The Headless API allows you to import CSVs and spreadsheet files via an API

With Headless, you can send a file or JSON payload to Dromo and specify a [schema](/#defining-a-schema) that defines the desired shape and constraints of the final data file.

If the import is successful, Dromo returns cleaned data in JSON format, just like an embedded import. If there are issues (e.g., missing columns or validation errors), Dromo provides a URL for users to resolve them via the embedded interface.

## Prerequisite[​](#prerequisite "Direct link to Activation")

The Headless API is a premium add-on to the [Dromo Enterprise Plan](https://dromo.io/pricing), [get in touch](mailto:support@dromo.io) and we can get you ready to go!

These limits help ensure service stability. For high-volume use cases, we recommend using webhooks instead of polling to avoid hitting rate limits.

## Using the Headless Importer[​](#using-the-headless-importer "Direct link to Using the Headless Importer")

A headless import can be run either on a file or a JSON object. The steps below walk through the procedure for either type of import.

You will need a schema to guide the import — either a saved schema referenced by `schema_id`, or an inline schema defined with `fields` in the request body. For more information about saved schemas, check out the [Schema Studio Guide](/guides/schema-builder) or the [Saved Schema API](/guides/saved-schema-api).

### Importing a File

<Steps>
  <Step title="Create a New Headless Import">
    The import process starts by creating a new headless import record. You will use this record ID to check the status of the import and retrieve the results.

    To create a headless import, use the [create headless import endpoint](/api-reference/headless/create-a-new-headless-import).

    You must provide two things when creating the import:

    * The ID of the saved schema you want to use
    * The original filename of the file you want to import

    Here is an example request:

    ```sh theme={null}
    curl \
      -H "Content-Type: application/json" \
      -H "X-Dromo-License-Key: your-backend-key" \
      -X POST \  'https://app.dromo.io/api/v1/headless/imports/' \
      -d '{"schema_id": "4eefe3fe-7181-4562-aa28-8cfe1c5bdf1b", "original_filename": "data.csv"}'
    ```

    <Note>Each headless import allows you to import only one file.</Note>
  </Step>

  <Step title="Upload the File">
    Once you've created the import record, Dromo will return an ID and a URL (in the `"upload"` field) where you can upload the file. Store the ID for later use (you need it to fetch the import status and results).

    To upload the file, make a PUT request to the URL, with the file as the body. Note that the upload URL is only valid for 30 minutes, so only create the import record when you are ready to upload the file.

    Here is an example request for uploading the file:

    ```sh theme={null}
    curl \
      -X PUT \'https://dromo-headless-imports-prod.s3.us-west-2.amazonaws.com/.....' \
      --data-binary "@/path/to/data.csv"
    ```
  </Step>

  <Step title="Wait for the Import to Run">
    Dromo will automatically begin the import process once the upload is complete.
  </Step>
</Steps>

### Importing a JSON Object

<Steps>
  <Step title="Create a New Headless Import">
    The import process starts by creating a new headless import record. You will use this record to check the status of the import and retrieve the results.

    To create a headless import, use the [create headless import endpoint](/api-reference/headless/create-a-new-headless-import).

    You must provide two things when creating the import:

    * The ID of the saved schema you want to use
    * The complete JSON data

    Here is an example request:

    ```sh theme={null}
    curl \
      -H "Content-Type: application/json" \
      -H "X-Dromo-License-Key: your-backend-key" \
      -X POST \  'https://app.dromo.io/api/v1/headless/imports/' \
      -d '{    "schema_id": "4eefe3fe-7181-4562-aa28-8cfe1c5bdf1b",    "initial_data": '[{"product": "widget1", "transaction": "foo123"}, {"product": "widget2", "transaction": "foo456"}]'  }'
    ```
  </Step>

  <Step title="Wait for the Import to Run">
    Dromo will automatically begin the import process once the upload is complete.
  </Step>
</Steps>

## Inline Schema Imports

Instead of referencing a saved schema via `schema_id`, you can define the schema inline at import time by passing `fields` directly in the request body. This is useful when you want to generate the schema dynamically or avoid managing saved schemas in the dashboard.

`schema_id` and `fields` are mutually exclusive — you must provide one or the other.

### Importing with an Inline Schema

Pass `fields` (required), `settings` (optional), and `hooks` (optional) in place of `schema_id`. Use `original_filename` when importing a file, or `initial_data` when importing JSON directly:

```sh theme={null}
curl \
  -H "Content-Type: application/json" \
  -H "X-Dromo-License-Key: your-backend-key" \
  -X POST \
  'https://app.dromo.io/api/v1/headless/imports/' \
  -d '{
    "fields": [
      { "key": "first_name", "type": "string", "label": "First Name", "validators": [] },
      { "key": "last_name", "type": "string", "label": "Last Name", "validators": [] }
    ],
    "initial_data": [
      { "first_name": "Zeph", "last_name": "paul.zeph@gmail.com" }
    ],
    "hooks": {
      "rowHooks": [
        "(record, mode) => { return { row: { first_name: { value: \"Updated from row hook\" } } }; }"
      ]
    }
  }'
```

The `fields` array accepts the same field definitions as a saved schema. See the [Field Object Reference](/reference/fields/fields) for the full list of options.

### Overriding Settings or Hooks on a Saved Schema

If you provide a `schema_id` alongside `settings` or `hooks`, Dromo will merge them on top of the saved schema for that specific import — without modifying the schema itself. This is useful for one-off overrides like changing validation behavior or injecting runtime hooks.

```sh theme={null}
curl \
  -H "Content-Type: application/json" \
  -H "X-Dromo-License-Key: your-backend-key" \
  -X POST \
  'https://app.dromo.io/api/v1/headless/imports/' \
  -d '{
    "schema_id": "4eefe3fe-7181-4562-aa28-8cfe1c5bdf1b",
    "settings": {
      "allowInvalidSubmit": true
    },
    "original_filename": "data.csv"
  }'
```

<Note>
  When overriding, `settings` and `hooks` are merged on top of the saved schema's values. Any keys you provide will overwrite the corresponding keys on the saved schema; keys you omit are left unchanged.
</Note>

## Handling Import Results[​](#handling-import-results "Direct link to Handling Import Results")

You can query for the current import status using the [retrieve headless import endpoint](/api-reference/headless/retrieve-headless-import). The import status will be one of the following:

* `AWAITING_UPLOAD`: The import record has been created, but the import file has not yet been uploaded.
* `PENDING`: The import file has been received, and the import process will begin shortly.
* `RUNNING`: The import process is currently running.
* `SUCCESSFUL`: The import was successful and the result data is ready to be retrieved.
* `NEEDS_REVIEW`: The import could not be completed due to data validation errors, and requires human attention.
* `FAILED`: The import encountered a fatal error, and cannot be processed.

### Successful import[​](#successful-import "Direct link to Successful import")

If the import data did not have any issues, the import will be in the `SUCCESSFUL` state.

You can be notified when an import completes in two ways:

1. **Dashboard-configured webhooks (RECOMMENDED)**:

   The recommended approach is to configure webhooks in the Dromo dashboard under the Webhooks section. This method provides several advantages:

   * More reliable delivery with retry mechanisms
   * Detailed event information
   * Easier configuration and management
   * Better security

   For detailed information on setting up and using dashboard webhooks, see the [Webhooks documentation](/reference/webhooks).

   These webhooks will receive detailed information about the completed import:

```sh theme={null}
{  "event": "import_completed",  "data": {    "id": "911224fa-c609-46d2-a278-bc2250d2be91",    "filename": "contacts (8).csv",    "user": null,    "created_date": "2025-02-25T17:07:03.769925Z",    "import_type": "HEADLESS",    "status": "SUCCESSFUL",    "num_data_rows": 92,    "development_mode": false,    "has_data": true  }}
```

After receiving this webhook notification, use the import ID from the payload to retrieve the presigned URL for downloading the data:

```sh theme={null}
curl \
  -H "X-Dromo-License-Key: your-backend-key" \
  -X GET \  'https://app.dromo.io/api/v1/headless/imports/{id}/url/'
```

The response will contain a presigned URL that you can use to download the data:

```sh theme={null}
{  "presigned_url": "https://dromo-user-imports.s3.us-west-2.amazonaws.com/..."}
```

2. **Legacy webhookUrl (DEPRECATED)**:

   If you define a [legacy webhookUrl](/reference/settings/settings#webhookurl) in your schema, it will still fire when the import completes successfully, but this method is deprecated and may be removed in the future.

**Alternative: Polling for completion**

If you prefer not to use webhooks, you can poll the [retrieve headless import endpoint](/api-reference/headless/retrieve-headless-import) to check the status:

```sh theme={null}
curl \
  -H "X-Dromo-License-Key: your-backend-key" \
  -X GET \  'https://app.dromo.io/api/v1/headless/imports/{id}/'
```

Once the status shows `SUCCESSFUL`, you can then retrieve the presigned URL using the [headless import URL endpoint](/api-reference/headless/get-presigned-download-url-for-headless-import-data):

```sh theme={null}
curl \
  -H "X-Dromo-License-Key: your-backend-key" \
  -X GET \  'https://app.dromo.io/api/v1/headless/imports/{id}/url/'
```

<Warning>
  Remember that polling is subject to rate limits (12 requests per minute per
  import). For production systems with many imports, webhooks are strongly
  recommended to avoid hitting these limits.
</Warning>

### Import needs review[​](#import-needs-review "Direct link to Import needs review")

If the import has issues that need manual review, the import will be in the `NEEDS_REVIEW` state.

This can happen for several reasons:

* The header row could not be determined
* The columns could not be mapped automatically
* There are failing data validations, and [invalidDataBehavior](/reference/settings/settings#invaliddatabehavior) is set to `BLOCK_SUBMIT`

When an import is in the `NEEDS_REVIEW` state, the data returned by the [retrieve headless import endpoint](/api-reference/headless/retrieve-headless-import) will include a `"review_url"` field. This is a URL which you can navigate to in a browser to resolve the import issues using Dromo's import UI.

After resolving the issues and completing the import, the import will transition to the `SUCCESSFUL` state.

### Import failed[​](#import-failed "Direct link to Import failed")

An import will enter the `FAILED` state if it has an unrecoverable error.

Some examples of unrecoverable errors are:

* The import file was corrupted and could not be parsed
* The import file was completely empty
* A custom hook threw an unhandled exception

Failed imports do not have results and also do not have a review URL.

## Rate Limits[​](#rate-limits "Direct link to Rate Limits")

The Headless API has the following rate limits:

* **Creating headless imports**: 20 requests per minute
* **Polling import status**: 12 requests per minute per import


# JavaScript Quickstart
Source: https://developer.dromo.io/getting-started/javascript

Add Dromo to a JavaScript application, configure an import schema, launch the uploader, and receive cleaned spreadsheet data.

<Note>
  Are you looking for a framework-specific SDK? Check the Getting Started guides
  in the sidebar.
</Note>

## Step By Step Guide

This guide will walk you through the essential steps to integrate the Dromo Uploader into your JavaScript application.

<Steps>
  <Step title="Installation">
    There are two ways to add the Dromo JavaScript SDK to your codebase:

    #### Using CDN

    You can source the SDK directly from our CDN:

    <CodeGroup>
      ```html "HTML (CDN)" theme={null}
      <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/dromo-uploader-js/dist/DromoUploader.js"></script>
      ```
    </CodeGroup>

    #### Using NPM package

    Alternatively, you can install the NPM package into your application:

    <CodeGroup>
      ```bash Terminal theme={null}
      npm install dromo-uploader-js
      ```
    </CodeGroup>

    Then import it into your project:

    <CodeGroup>
      ```javascript JavaScript theme={null}
      import DromoUploader from "dromo-uploader-js";
      ```
    </CodeGroup>
  </Step>

  <Step title="Initialize the Uploader">
    Create an instance of `DromoUploader`. You'll need your Dromo front-end license key, and to define your fields, settings, and user metadata.

    <CodeGroup>
      ```javascript JavaScript theme={null}
      const licenseKey = "YOUR_FRONTEND_LICENSE_KEY"; // Get this from the Dromo dashboard
      const fields = [
        { label: "Name", key: "name" },
        { label: "Email", key: "email_address" }
        // Define other fields as needed
      ];
      const settings = {
        importIdentifier: "MyContactsImport", // A descriptive name for this import type
        developmentMode: true // Set to false in production
      };
      const user = {
        id: "unique_user_id_123",
        name: "Jane Doe",
        email: "jane@example.com"
        // Add other user metadata as needed
      };

      const dromo = new DromoUploader(licenseKey, fields, settings, user);
      ```
    </CodeGroup>

    For full details on constructor parameters, see the [DromoUploader SDK Reference](/reference/dromo-uploader-sdk).
  </Step>

  <Step title="Register Callbacks (Optional)">
    You can register callbacks to handle events like data processing or when results are ready.

    <CodeGroup>
      ```javascript JavaScript theme={null}
      dromo.onResults((data, metadata) => {
        console.log("Imported Data:", data);
        console.log("Import Metadata:", metadata);
        // Process the data here
        return "Import successful! Thanks!"; // Optional message to show to the user
      });

      // For other available callbacks like row hooks, column hooks, etc.,
      // refer to the [DromoUploader SDK Reference](/reference/dromo-uploader-sdk) and [Hooks documentation](/hooks).
      ```
    </CodeGroup>
  </Step>

  <Step title="Open the Uploader">
    Call `dromo.open()` to launch the Dromo import interface.

    <CodeGroup>
      ```javascript JavaScript theme={null}
      dromo.open();
      ```
    </CodeGroup>
  </Step>
</Steps>

## Basic Example

To use the example below, replace `"FRONTEND_API_KEY"` with your frontend license key from [the Dromo dashboard](https://dashboard.dromo.io/).

<CodeGroup>
  ```javascript "HTML (Full Example)" theme={null}
  <script type="text/javascript">
    const license = "FRONTEND_API_KEY";
    const fields = [
      {
        label: "Name",
        key: "name"
      },
      {
        label: "Email",
        key: "email_address"
      }
    ];
    const settings = {
      importIdentifier: "Contacts",
      developmentMode: true
    };
    const user = {
      id: "1",
      name: "Jane Doe",
      email: "jane@dromo.io",
      companyId: "Dromo",
      companyName: "12345"
    };
    const dromo = new DromoUploader(license, fields, settings, user);
    dromo.onResults(function (response, metadata) {
      // Do something with the data here
      return "Done!";
    });
  </script>
  <div id="root">
    <button onclick="dromo.open()">Open Dromo</button>
  </div>
  ```
</CodeGroup>


# React Quickstart
Source: https://developer.dromo.io/getting-started/react

Install the Dromo React SDK, configure the DromoUploader component, define schema fields, and process import results.

<Note>
  Are you looking for a framework other than React? Check the Getting Started
  guides in the sidebar.
</Note>

## Step By Step Guide

This guide will walk you through integrating the Dromo Uploader into your React application.

<Steps>
  <Step title="Installation">
    Install the Dromo React SDK NPM package:

    <CodeGroup>
      ```bash Terminal theme={null}
      npm install dromo-uploader-react
      ```
    </CodeGroup>

    Next, import the `DromoUploader` component in your file:

    <CodeGroup>
      ```javascript JavaScript theme={null}
      import DromoUploader from "dromo-uploader-react";
      ```
    </CodeGroup>
  </Step>

  <Step title="Basic Usage">
    Add the `<DromoUploader />` component to your app. You'll need to provide your `licenseKey` and configure `fields`, `settings`, `user` props, and an `onResults` callback.

    <CodeGroup>
      ```jsx "JSX (Basic Usage)" theme={null}
      <DromoUploader
        licenseKey="YOUR_FRONTEND_LICENSE_KEY" // Get this from the Dromo dashboard
        fields={[
          { label: "Name", key: "name" },
          { label: "Email", key: "email_address" },
        ]}
        settings={{
          importIdentifier: "ContactsUpload",
          developmentMode: true,
        }}
        user={{
          id: "user_123",
          name: "Jane Doe",
          email: "jane@example.com",
        }}
        onResults={(response, metadata) => {
          console.log("Imported Data:", response);
          console.log("Import Metadata:", metadata);
          // Process the data here
        }}
      >
        Launch Dromo Importer
      </DromoUploader>
      ```
    </CodeGroup>

    This will render a button that says "Launch Dromo Importer". Clicking it will open the Dromo modal.
    For a full list of props and detailed explanations, see the [`<DromoUploader />` Component Props Reference](/reference/react-dromo-uploader).
  </Step>

  <Step title="Opening the Uploader">
    There are two primary ways to control when the Dromo modal opens:

    #### 1. Using Children as a Trigger

    If you provide children to the `<DromoUploader />` component (like the "Launch Dromo Importer" button in the example above), these children will be rendered, and clicking them will open the Dromo modal.

    <CodeGroup>
      ```jsx "JSX (Children Trigger)" theme={null}
      <DromoUploader
        licenseKey="YOUR_FRONTEND_LICENSE_KEY" // Add other essential props
        onResults={(data, metadata) => console.log(data)} // Example callback
      >
        <button>Upload Data</button>
      </DromoUploader>
      ```
    </CodeGroup>

    #### 2. Using the `open` Prop (v2.0.9+)

    Alternatively, you can omit children and control the modal's visibility programmatically using the `open` prop (boolean).

    <CodeGroup>
      ```jsx "JSX (Open Prop)" theme={null}
      // In your component state
      // const [isImporterOpen, setIsImporterOpen] = useState(false);

      <DromoUploader
        licenseKey="YOUR_FRONTEND_LICENSE_KEY" // Add other essential props
        open={isImporterOpen} // Control with your component's state
        onCancel={() => setIsImporterOpen(false)} // Recommended to handle modal close
        onResults={(data, metadata) => console.log(data)} // Example callback
      />
      // <button onClick={() => setIsImporterOpen(true)}>Open Programmatic Uploader</button>
      ```
    </CodeGroup>

    See more about the `open` prop in the [`<DromoUploader />` Component Props Reference](/reference/react-dromo-uploader).
  </Step>
</Steps>

## Using a Saved Schema

You can use a schema created in Dromo's Schema Studio by providing its ID via the `schemaId` prop. This simplifies the props you need to pass, as fields, most settings, and hooks will be loaded from your saved schema.

<CodeGroup>
  ```jsx "JSX (Saved Schema)" theme={null}
  <DromoUploader
    licenseKey="YOUR_LICENSE_KEY"
    schemaId="YOUR_SCHEMA_ID_FROM_DASHBOARD"
    user={{ id: "user_123" }}
    // Optionally override importIdentifier or developmentMode from saved schema:
    // settings={{ importIdentifier: "OverrideName", developmentMode: false }}
    onResults={(response, metadata) => {
      console.log("Data with saved schema:", response);
    }}
  >
    Upload with Saved Schema
  </DromoUploader>
  ```
</CodeGroup>

Learn more about [creating schemas in the Schema Studio](/guides/schema-builder).

## Walkthrough Video[​](#walkthrough-video "Direct link to Walkthrough video")

<iframe title="Walkthrough video" />

Want a more detailed walkthrough? Jeff will escort you step-by-step through the process.


# Accessing Unmapped Columns
Source: https://developer.dromo.io/guides/accessing-unmapped-columns

How to capture and process columns that weren't mapped to your schema fields.

When users upload files that contain more columns than are defined in your schema, you might want to access those unmapped columns for additional processing. Dromo provides a straightforward way to capture this data.

## Setup Required

### 1. Enable passthrough in settings

First, enable the `passThroughUnmappedColumns` setting in your Dromo configuration:

```javascript theme={null}
const settings = {
  passThroughUnmappedColumns: true,
  // ... other settings
};
```

<Note>
  When enabled, each row in your results will include a special `$unmapped` property containing the unmapped column data.
</Note>

### 2. Update your resultsCallback

Modify your results callback to process both mapped and unmapped data:

```javascript theme={null}
const config = {
  // ... other config
  resultsCallback: (data, metadata) => {
    // Process your normal mapped data
    console.table(data);

    // Extract unmapped columns with proper header names
    const unmappedData = data.map(row => {
      if (row.$unmapped && metadata.rawHeaders) {
        const unmappedWithHeaders = {};
        Object.entries(row.$unmapped).forEach(([index, value]) => {
          const headerName = metadata.rawHeaders[parseInt(index)];
          if (headerName) {
            unmappedWithHeaders[headerName] = value;
          }
        });
        return unmappedWithHeaders;
      }
      return {};
    });

    console.log("Unmapped columns:", unmappedData);

    // Process both datasets as needed
    processMainData(data);
    processUnmappedData(unmappedData);
  }
};
```

## How It Works

### Data Structure

When `passThroughUnmappedColumns` is enabled:

* **`$unmapped` property**: Added to each row containing unmapped column values
* **Format**: `{ "0": "value1", "2": "value2" }` (column index → value)
* **`metadata.rawHeaders`**: Array containing original file headers in order
* **Header mapping**: Convert column indexes to actual column names using `rawHeaders[index]`

### Example Walkthrough

#### Original CSV File

```csv theme={null}
Name,Email,Phone,Department,Notes,Start Date
John Doe,john@example.com,555-1234,Engineering,New hire,2024-01-15
Jane Smith,jane@example.com,555-5678,Marketing,Manager,2024-02-01
```

#### Schema Definition

Let's say your schema only maps two fields:

```javascript theme={null}
const schema = [
  { key: "name", label: "Full Name" },
  { key: "email", label: "Email Address" }
];
```

#### Processed Results

With `passThroughUnmappedColumns: true`, you'll receive:

```javascript theme={null}
// Main data (mapped columns)
[
  {
    name: "John Doe",
    email: "john@example.com",
    $unmapped: { "2": "555-1234", "3": "Engineering", "4": "New hire", "5": "2024-01-15" }
  },
  {
    name: "Jane Smith",
    email: "jane@example.com",
    $unmapped: { "2": "555-5678", "3": "Marketing", "4": "Manager", "5": "2024-02-01" }
  }
]

// metadata.rawHeaders
["Name", "Email", "Phone", "Department", "Notes", "Start Date"]
```

#### Converted Unmapped Data

After processing with header names:

```javascript theme={null}
[
  {
    "Phone": "555-1234",
    "Department": "Engineering",
    "Notes": "New hire",
    "Start Date": "2024-01-15"
  },
  {
    "Phone": "555-5678",
    "Department": "Marketing",
    "Notes": "Manager",
    "Start Date": "2024-02-01"
  }
]
```

## Common Use Cases

### Audit Trail

Store unmapped columns for compliance or auditing purposes:

```javascript theme={null}
function storeAuditData(mainData, unmappedData) {
  mainData.forEach((row, index) => {
    const auditRecord = {
      processedData: row,
      additionalColumns: unmappedData[index],
      timestamp: new Date(),
      uploadId: getCurrentUploadId()
    };

    saveToAuditLog(auditRecord);
  });
}
```

### Dynamic Field Processing

Process specific unmapped columns based on their header names:

```javascript theme={null}
function processUnmappedColumns(unmappedData) {
  return unmappedData.map(row => {
    const processed = {};

    Object.entries(row).forEach(([header, value]) => {
      // Handle phone numbers
      if (header.toLowerCase().includes('phone')) {
        processed.phoneNumber = formatPhoneNumber(value);
      }

      // Handle dates
      if (header.toLowerCase().includes('date')) {
        processed.dates = processed.dates || [];
        processed.dates.push({
          field: header,
          value: parseDate(value)
        });
      }

      // Store everything else as metadata
      processed.metadata = processed.metadata || {};
      processed.metadata[header] = value;
    });

    return processed;
  });
}
```

### Flexible Schema Extension

Allow users to map additional fields in a second pass:

```javascript theme={null}
function enableSecondaryMapping(unmappedData) {
  const availableColumns = Object.keys(unmappedData[0] || {});

  // Present UI for mapping additional fields
  const secondaryMappingOptions = availableColumns.map(header => ({
    original: header,
    suggested: suggestFieldMapping(header),
    values: unmappedData.slice(0, 3).map(row => row[header]) // Preview values
  }));

  return secondaryMappingOptions;
}
```

## Best Practices

### Performance Considerations

For large datasets, consider processing unmapped data asynchronously, since you can't know how many unmapped columns there will be:

```javascript theme={null}
resultsCallback: async (data, metadata) => {
  // Process main data immediately
  await processMainData(data);

  // Queue unmapped data processing
  if (hasUnmappedColumns(data, metadata)) {
    queueUnmappedProcessing(data, metadata);
  }
}
```

### Data Validation

Validate unmapped data before processing:

```javascript theme={null}
function validateUnmappedData(unmappedData) {
  return unmappedData.filter(row => {
    return Object.values(row).some(value =>
      value !== null &&
      value !== undefined &&
      value.toString().trim() !== ''
    );
  });
}
```

This feature gives you complete flexibility to handle any data structure your users might upload, while maintaining a clean separation between your core schema and additional data capture.


# Bring Your Own Storage
Source: https://developer.dromo.io/guides/bring-your-own-storage

Send Dromo import files and results directly to your AWS, Google Cloud, or Azure storage bucket with Bring Your Own Storage.

Bring Your Own Storage (BYOS) allows import data to be sent from the Dromo JS widget in your user's browser directly to your cloud storage bucket, without Dromo ever having access to the data.

<Info>
  BYOS is only available on the Enterprise Plan.
</Info>

<img alt="Bring Your Own Storage Diagram" />

## BYOS Requirements and Setup[​](#byos-requirements-and-setup "Direct link to BYOS Requirements and Setup")

BYOS supports AWS S3, GCP Cloud Storage, and Azure Blob Storage. You will need to have configuration access to prepare your storage layer for receiving data from Dromo. Dromo will need **write-only** access, which will be used to generate pre-signed upload URLS used by the Dromo importer widget.

The Dromo Solution Engineering team will guide you through the setup process.

## Using BYOS[​](#using-byos "Direct link to Using BYOS")

Once configured, ensure [`settings: backendSycMode`](/reference/settings/settings#backendsyncmode) is set to `"FULL_DATA"`. All your imports will automatically be uploaded to the bucket associated with the account the API key belongs to. The raw import file will also be saved to your bucket.

After the import is completed, Dromo's backend will send any configured webhooks for the import. You can also retrieve the metadata for any import using the [Get Upload Metadata API endpoint](/api-reference#tag/uploads/operation/getUploadMetadata).


# Building a Custom Step UI
Source: https://developer.dromo.io/guides/custom-steps

Inject your own UI into the Dromo import flow between any two built-in steps using iframes and postMessage.

Custom steps let you insert your own UI into the Dromo import flow — between any two built-in steps — without breaking the standard modal experience. Your page loads inside an `<iframe>` embedded in Dromo's modal chrome, and communicates back via `postMessage`.

## The import flow

The default step order is:

```
UPLOAD → HEADER_SELECT → COLUMN_MATCH → SELECT_MATCH → REVIEW
```

Custom steps can be inserted **after** any of these steps (except `REVIEW`):

| `insertAfter`     | Inserted after                             |
| ----------------- | ------------------------------------------ |
| `"HEADER_SELECT"` | Header row detection                       |
| `"COLUMN_MATCH"`  | Column mapping                             |
| `"SELECT_MATCH"`  | Select field matching — just before Review |

***

## Quick start

Register a custom step before calling `open()`. The `url` is the page Dromo will load inside the iframe.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import DromoUploader from "dromo-uploader-js";

  const dromo = new DromoUploader(licenseKey, fields, settings, user);

  dromo.registerCustomStep({
    id: "terms",
    insertAfter: "SELECT_MATCH",
    label: "Terms & Conditions",
    url: "https://your-app.com/dromo-custom-step.html",
  });

  dromo.open();
  ```

  ```jsx React theme={null}
  import { DromoUploader } from "dromo-uploader-react";

  <DromoUploader
    licenseKey={licenseKey}
    fields={fields}
    settings={settings}
    user={user}
    customSteps={[
      {
        id: "terms",
        insertAfter: "SELECT_MATCH",
        label: "Terms & Conditions",
        url: "https://your-app.com/dromo-custom-step.html",
      },
    ]}
    onResults={(data, metadata) => console.log(data)}
  >
    Import
  </DromoUploader>
  ```

  ```typescript Angular theme={null}
  // component.ts
  customSteps: ICustomStepConfig[] = [
    {
      id: "terms",
      insertAfter: "SELECT_MATCH",
      label: "Terms & Conditions",
      url: "https://your-app.com/dromo-custom-step.html",
    },
  ];
  ```

  ```html Angular template theme={null}
  <lib-dromo-uploader [customSteps]="customSteps" ...>
    Import with Dromo!
  </lib-dromo-uploader>
  ```
</CodeGroup>

***

## Driving navigation from the iframe

Your iframe page posts messages to `window.parent` to control navigation.

| Message                                   | Effect                           |
| ----------------------------------------- | -------------------------------- |
| `{ type: "DROMO_NEXT" }`                  | Advance to the next step         |
| `{ type: "DROMO_BACK" }`                  | Return to the previous step      |
| `{ type: "DROMO_MESSAGE", payload: any }` | Trigger the `onMessage` callback |

```javascript theme={null}
// Advance to the next step
window.parent.postMessage({ type: "DROMO_NEXT" }, "*");

// Go back
window.parent.postMessage({ type: "DROMO_BACK" }, "*");

// Send data to onMessage, then advance
window.parent.postMessage({ type: "DROMO_MESSAGE", payload: { accepted: true } }, "*");
window.parent.postMessage({ type: "DROMO_NEXT" }, "*");
```

***

## Modifying the schema from a custom step

Use the `onMessage` callback to mutate the import schema in response to what the user does in your iframe. It receives the same uploader instance as step hooks, giving you access to `addField`, `removeField`, `addRows`, and more.

```typescript theme={null}
dromo.registerCustomStep({
  id: "add-fields",
  insertAfter: "SELECT_MATCH",
  label: "Add Fields",
  url: "https://your-app.com/add-fields.html",
  onMessage: async (uploader, payload) => {
    const { fields } = payload as { fields: Array<{ label: string; key: string; type: string }> };
    for (const field of fields) {
      await uploader.addField(field as any);
    }
  },
});
```

The iframe sends the payload:

```javascript theme={null}
window.parent.postMessage(
  { type: "DROMO_MESSAGE", payload: { fields: [{ label: "Department", key: "department", type: "string" }] } },
  "*"
);
window.parent.postMessage({ type: "DROMO_NEXT" }, "*");
```

***

## Multiple custom steps

Register multiple steps at the same `insertAfter` position — they are presented in registration order:

```typescript theme={null}
dromo.registerCustomStep({ id: "consent",   insertAfter: "COLUMN_MATCH", url: "/consent.html" });
dromo.registerCustomStep({ id: "data-type", insertAfter: "COLUMN_MATCH", url: "/data-type.html" });
// Flow: … → COLUMN_MATCH → consent → data-type → SELECT_MATCH → REVIEW
```

***

## Full example: dynamic field builder

The example below is a self-contained iframe page that lets the user define extra fields before Review, then sends them back via `onMessage`.

### Step registration

```typescript theme={null}
dromo.registerCustomStep({
  id: "add-fields",
  insertAfter: "SELECT_MATCH",
  label: "Add Fields",
  url: "https://your-app.com/add-fields.html",
  onMessage: async (uploader, payload) => {
    const { fields } = payload as {
      fields: Array<{
        label: string;
        key: string;
        type: string;
        selectOptions?: { label: string; value: string }[];
      }>;
    };
    for (const field of fields) {
      await uploader.addField(field as any);
    }
  },
});
```

### Iframe page (`add-fields.html`)

```html theme={null}
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Add Fields</title>
  <style>
    body { font-family: sans-serif; margin: 0; padding: 32px 24px; background: #f9fafb; }
    h2   { margin: 0 0 4px; font-size: 18px; }
    .subtitle { margin: 0 0 24px; color: #6b7280; font-size: 14px; }
    .card { background: #fff; border: 1px solid #e5e7eb; border-radius: 8px; padding: 16px; margin-bottom: 16px; }
    .row  { display: flex; gap: 8px; }
    .col  { display: flex; flex-direction: column; gap: 4px; flex: 1; }
    label { font-size: 12px; color: #6b7280; font-weight: 500; }
    input, select { padding: 7px 10px; border: 1px solid #d1d5db; border-radius: 6px; font-size: 14px; width: 100%; }
    .btn { padding: 8px 16px; border-radius: 6px; font-size: 14px; font-weight: 600; cursor: pointer; border: none; }
    .btn:disabled { opacity: 0.4; cursor: default; }
    .btn-primary   { background: #4f46e5; color: #fff; }
    .btn-secondary { background: #fff; border: 1px solid #d1d5db; color: #374151; }
    .btn-sm { padding: 6px 12px; font-size: 13px; }
    #fields-list { list-style: none; margin: 0 0 8px; padding: 0; display: flex; flex-direction: column; gap: 6px; }
    #fields-list li { display: flex; justify-content: space-between; align-items: center; padding: 8px 12px; background: #fff; border: 1px solid #e5e7eb; border-radius: 6px; font-size: 13px; }
    #fields-list li button { background: none; border: none; cursor: pointer; color: #9ca3af; }
    #fields-empty { font-size: 13px; color: #9ca3af; font-style: italic; }
    .nav { display: flex; gap: 12px; margin-top: 24px; }
  </style>
</head>
<body>
  <h2 id="title">Add Custom Fields</h2>
  <p class="subtitle">Define extra fields to add to the import schema, then click Continue.</p>

  <div class="card">
    <div class="row">
      <div class="col">
        <label for="field-label">Label</label>
        <input id="field-label" type="text" placeholder="e.g. Department" />
      </div>
      <div class="col" style="max-width:140px">
        <label for="field-type">Type</label>
        <select id="field-type">
          <option value="string">String</option>
          <option value="select">Select</option>
        </select>
      </div>
    </div>
    <div style="margin-top:12px">
      <button id="add-field-btn" class="btn btn-primary btn-sm" onclick="addField()" disabled>
        Add field
      </button>
    </div>
  </div>

  <div class="card">
    <p id="fields-empty">No fields added yet.</p>
    <ul id="fields-list"></ul>
  </div>

  <div class="nav">
    <button class="btn btn-secondary"
      onclick="window.parent.postMessage({ type: 'DROMO_BACK' }, '*')">
      Back
    </button>
    <button class="btn btn-primary" onclick="onContinue()">Continue</button>
  </div>

  <script>
    const pendingFields = [];

    function refreshAddBtn() {
      document.getElementById("add-field-btn").disabled =
        !document.getElementById("field-label").value.trim();
    }

    function addField() {
      const lbl = document.getElementById("field-label").value.trim();
      if (!lbl) return;
      pendingFields.push({
        label: lbl,
        key: lbl.toLowerCase().replace(/\s+/g, "_"),
        type: document.getElementById("field-type").value,
      });
      document.getElementById("field-label").value = "";
      renderFields();
      refreshAddBtn();
    }

    function removeField(i) {
      pendingFields.splice(i, 1);
      renderFields();
    }

    function renderFields() {
      const list  = document.getElementById("fields-list");
      const empty = document.getElementById("fields-empty");
      list.innerHTML = "";
      empty.style.display = pendingFields.length ? "none" : "block";
      pendingFields.forEach((f, i) => {
        const li = document.createElement("li");
        li.innerHTML = `<span><strong>${f.label}</strong> — ${f.type}</span>
          <button onclick="removeField(${i})">✕</button>`;
        list.appendChild(li);
      });
    }

    function onContinue() {
      window.parent.postMessage(
        { type: "DROMO_MESSAGE", payload: { fields: pendingFields } },
        "*"
      );
      window.parent.postMessage({ type: "DROMO_NEXT" }, "*");
    }

    document.getElementById("field-label").addEventListener("input", refreshAddBtn);
    document.getElementById("field-label").addEventListener("keydown", (e) => {
      if (e.key === "Enter") addField();
    });
  </script>
</body>
</html>
```

**What happens when the user clicks Continue:**

<Steps>
  <Step title="Send data">
    The iframe posts `DROMO_MESSAGE` with `{ fields: [...] }` to `window.parent`.
  </Step>

  <Step title="onMessage callback runs">
    Dromo calls `onMessage(uploader, payload)`. The callback iterates the fields and calls `uploader.addField()` for each one.
  </Step>

  <Step title="Advance">
    The iframe posts `DROMO_NEXT`. Dromo moves to the next step (Review).
  </Step>
</Steps>

<Info>
  For a complete configuration reference, see the [Custom Steps reference](/reference/custom-steps).
</Info>


# Customizing Styles
Source: https://developer.dromo.io/guides/custom-styling

Customize the Dromo Uploader's colors, typography, buttons, steps, modals, and other visual elements with style overrides.

<Info>
  For more detail about possible style overrides, see the [Reference](/reference/settings/style-overrides) page.
</Info>

You can customize styles for almost all the visual elements throughout the Dromo Uploader, allowing you to seamlessly integrate the uploader with your application's design system and brand identity.

<img alt="Upload screen" />

<img alt="Set header screen" />

<img alt="Matching screen" />

<img alt="Clean data screen" />

<img alt="Review screen" />

## Basic Example

In this example, we change the text color to dark gray, the primary button to blue, and the secondary button to red. This demonstrates the fundamental approach to customizing Dromo's appearance.

```js theme={null}
const settings = {
  styleOverrides: {
    global: {
      textColor: "#394b59",
      customFontURL: "https://fonts.googleapis.com/css2?family=Open+Sans&display=swap",
      customFontFamily: "'Open Sans', sans-serif"
    },
    primaryButton: {
      borderRadius: "0.25rem",
      backgroundColor: "#1a4a7a",
      textColor: "#ffffff",
      border: "1px solid #1a4a7a",
      hoverBackgroundColor: "#006bef",
      hoverTextColor: "#ffffff",
      hoverBorder: "1px solid #006bef"
    },
    secondaryButton: {
      borderRadius: "0.25rem",
      backgroundColor: "#b0276b",
      textColor: "#ffffff",
      border: "1px solid #b0276b",
      hoverBackgroundColor: "#5c656d",
      hoverTextColor: "#ffffff",
      hoverBorder: "1px solid #5c656d"
    }
  }
}
```

## Global Styling

The `global` section controls application-wide styles that affect multiple components throughout the uploader. These settings provide a foundation for your design system and ensure visual consistency across all screens.

### Text Colors

Control the color hierarchy for text throughout the application:

* **`textColor`** - Default text color for body text and general content
* **`primaryTextColor`** - Emphasized text such as headings, labels, and important information
* **`secondaryTextColor`** - De-emphasized text like descriptions, hints, and supplementary information

### Status Colors

Define colors for conveying state and feedback to users:

* **`successColor`** - Indicates successful operations, valid data, and positive states
* **`warningColor`** - Highlights warnings, potential issues, and cautionary information

### Typography

Integrate your brand's typography:

* **`customFontURL`** - URL to load custom fonts (e.g., Google Fonts, Adobe Fonts, or self-hosted fonts)
* **`customFontFamily`** - CSS font-family declaration to apply the custom font

<Info>
  When using custom fonts, ensure the font URL is accessible and supports CORS. The font will be loaded asynchronously to avoid blocking the uploader initialization.
</Info>

### Container Styling

Control the appearance of modal containers and panels:

* **`backgroundColor`** - Background color for the main uploader container
* **`borderRadius`** - Corner radius for rounded elements (e.g., "8px", "0.5rem")
* **`borderWidth`** - Thickness of borders throughout the application
* **`borderColor`** - Default border color for dividers and containers
* **`borderStyle`** - Border style (e.g., "solid", "dashed", "dotted")

### Visual Effects

* **`backdropBlur`** - Boolean to enable/disable the blur effect on the modal backdrop. When enabled, the background behind the modal will have a frosted glass effect.

```js theme={null}
const settings = {
  styleOverrides: {
    global: {
      // Text color hierarchy
      textColor: "#1f2937",           // Body text
      primaryTextColor: "#374151",     // Headings and labels
      secondaryTextColor: "#6b7280",   // Descriptions and hints

      // Status colors for feedback
      successColor: "#10b981",         // Green for success states
      warningColor: "#f59e0b",         // Amber for warnings

      // Custom brand font
      customFontURL: "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap",
      customFontFamily: "'Inter', sans-serif",

      // Container appearance
      backgroundColor: "#ffffff",
      borderRadius: "8px",
      borderWidth: "1px",
      borderColor: "#e5e7eb",
      borderStyle: "solid",

      // Visual effects
      backdropBlur: true               // Enable backdrop blur
    }
  }
}
```

## Button Styling

Dromo uses three button types throughout the interface: primary (main actions), secondary (alternative actions), and tertiary (subtle actions). Each button type can be fully customized with normal and hover states.

### Primary Buttons

Primary buttons are used for the main call-to-action on each screen (e.g., "Continue", "Submit", "Finish"). These should be the most visually prominent buttons.

**Use cases:**

* Advancing to the next step in the workflow
* Submitting final data
* Confirming important actions

### Secondary Buttons

Secondary buttons provide alternative or less critical actions (e.g., "Back", "Skip", "Cancel").

**Use cases:**

* Navigating back to previous steps
* Canceling or closing modals
* Secondary actions that complement the primary action

### Tertiary Buttons

Tertiary buttons are the most subtle option, typically used for optional actions or inline controls.

**Use cases:**

* "View details" or "Show more" links
* Inline editing actions
* Optional helper actions

### Button Properties

Each button type supports the following properties:

* **`borderRadius`** - Corner radius (e.g., "0.375rem", "4px")
* **`backgroundColor`** - Fill color
* **`textColor`** - Text/label color
* **`border`** - Border style (e.g., "1px solid #3b82f6")
* **`hoverBackgroundColor`** - Fill color on mouse hover
* **`hoverTextColor`** - Text color on mouse hover
* **`hoverBorder`** - Border style on mouse hover
* **`disabledBackgroundColor`** - Fill color when the button is disabled (default: `#e5e7eb`)
* **`disabledTextColor`** - Text color when the button is disabled (default: `#6b7280`)
* **`padding`** - Button padding (default: `8px 12px`)

<Warning>
  If you specify a `backgroundColor` but not a `hoverBackgroundColor`, Dromo will automatically use the same color for the hover state. For better UX, explicitly define hover states that are slightly darker or lighter than the normal state.
</Warning>

```js theme={null}
const settings = {
  styleOverrides: {
    primaryButton: {
      borderRadius: "0.375rem",
      backgroundColor: "#3b82f6",          // Blue background
      textColor: "#ffffff",                // White text
      border: "1px solid #3b82f6",         // Matching border
      hoverBackgroundColor: "#2563eb",     // Darker blue on hover
      hoverTextColor: "#ffffff",
      hoverBorder: "1px solid #2563eb"
    },
    secondaryButton: {
      borderRadius: "0.375rem",
      backgroundColor: "#f3f4f6",          // Light gray background
      textColor: "#374151",                // Dark text
      border: "1px solid #d1d5db",         // Gray border
      hoverBackgroundColor: "#e5e7eb",     // Slightly darker gray on hover
      hoverTextColor: "#1f2937",           // Darker text on hover
      hoverBorder: "1px solid #9ca3af"
    },
    tertiaryButton: {
      borderRadius: "0.375rem",
      backgroundColor: "transparent",       // No background
      textColor: "#3b82f6",                // Blue text
      border: "1px solid transparent",     // No border
      hoverBackgroundColor: "#eff6ff",     // Light blue background on hover
      hoverTextColor: "#2563eb",           // Darker blue text on hover
      hoverBorder: "1px solid #3b82f6"     // Blue border on hover
    }
  }
}
```

## Table Styling

The data table (powered by Handsontable) is the core interface where users view, edit, and validate their data. Extensive styling options allow you to match your application's design while maintaining usability.

### Column Headers

Headers identify each column and show field names from your schema.

* **`headerBackgroundColor`** - Background color for column headers
* **`headerTextColor`** - Text color for column headers
* **`headerFontWeight`** - Font weight (e.g., "400", "500", "600", "700", "bold")

### Active & Highlighted Headers

When users interact with columns (selecting, mapping, or hovering), headers can change appearance to provide visual feedback.

* **`headerActiveBackgroundColor`** - Background when the column is currently active/selected
* **`headerActiveTextColor`** - Text color when active
* **`headerHighlightedBackgroundColor`** - Background when the column is highlighted (e.g., during drag operations)
* **`headerHighlightedTextColor`** - Text color when highlighted

**Use case:** During the column matching step, when a user selects a column to map to a schema field, the active header styling helps them identify which column they're working with.

### Row Headers

The leftmost column displays row numbers to help users reference specific data rows.

* **`rowHeaderBackgroundColor`** - Background color for the row number column
* **`rowHeaderTextColor`** - Text color for row numbers

### Corner Header

The top-left cell where the row header and column header intersect.

* **`cornerHeaderBackgroundColor`** - Background color for the corner cell

### Cell Styling

Basic styling for data cells in the table.

* **`cellBackgroundColor`** - Default background for all cells
* **`cellTextColor`** - Default text color for cell content
* **`cellHoverBackgroundColor`** - Background when hovering over a cell
* **`cellHoverTextColor`** - Text color when hovering

### Alternating Rows

Improve readability with zebra-striping (alternating row colors).

* **`oddRowBackgroundColor`** - Background color for odd-numbered rows

<Tip>
  Use a subtle color difference between even and odd rows (e.g., white and light gray) to help users track data across columns without being distracting.
</Tip>

### Selection Styling

Visual feedback when users select cells or rows.

* **`cellSelectionBorderColor`** - Border color around selected cells
* **`cellSelectionBackgroundColor`** - Background color for selected cells (use semi-transparent colors like "rgba(59, 130, 246, 0.1)")
* **`rowSelectedBackgroundColor`** - Background color for entire selected rows
* **`rowSelectedBorderColor`** - Border color for selected rows

### Borders & Dividers

Control the table's grid lines and borders.

* **`borderColor`** - Main border color for the table's outer edges
* **`dividerColor`** - Color for grid lines between rows and columns

### Cell States

Cells can display validation states using different colors to communicate errors, warnings, or informational messages.

**Error States** (validation failures, required fields missing):

* **`errorCellBackgroundColor`** - Background for cells with errors
* **`errorCellHoverBackgroundColor`** - Background when hovering over error cells

**Warning States** (potential issues, data that needs attention):

* **`warningCellBackgroundColor`** - Background for cells with warnings
* **`warningCellHoverBackgroundColor`** - Background when hovering over warning cells

**Info States** (suggestions, transformations, helpful information):

* **`infoCellBackgroundColor`** - Background for cells with informational messages
* **`infoCellHoverBackgroundColor`** - Background when hovering over info cells

<Info>
  Use distinct but harmonious colors for different states. For example, light red for errors, light yellow for warnings, and light blue for info. Ensure sufficient contrast for accessibility.
</Info>

### Read-Only Cells

Some cells may be locked from editing based on your field configuration.

* **`readOnlyCellBackgroundColor`** - Background for non-editable cells
* **`readOnlyCellTextColor`** - Text color for read-only content

### Accent Color

A general-purpose accent color used for various interactive elements in the table.

* **`accentColor`** - Primary accent color for controls, highlights, and interactive elements

```js theme={null}
const settings = {
  styleOverrides: {
    dataTable: {
      // Column headers
      headerBackgroundColor: "#f9fafb",
      headerTextColor: "#111827",
      headerFontWeight: "600",

      // Active/highlighted headers (interaction feedback)
      headerActiveBackgroundColor: "#eff6ff",
      headerActiveTextColor: "#1e40af",
      headerHighlightedBackgroundColor: "#dbeafe",
      headerHighlightedTextColor: "#1e3a8a",

      // Row numbers (left column)
      rowHeaderBackgroundColor: "#f9fafb",
      rowHeaderTextColor: "#6b7280",

      // Top-left corner cell
      cornerHeaderBackgroundColor: "#f3f4f6",

      // Cell styling
      cellBackgroundColor: "#ffffff",
      cellTextColor: "#1f2937",
      cellHoverBackgroundColor: "#f9fafb",
      cellHoverTextColor: "#111827",

      // Alternating row colors (zebra striping)
      oddRowBackgroundColor: "#f9fafb",

      // Selection styling
      cellSelectionBorderColor: "#3b82f6",
      cellSelectionBackgroundColor: "rgba(59, 130, 246, 0.1)",
      rowSelectedBackgroundColor: "rgba(59, 130, 246, 0.08)",
      rowSelectedBorderColor: "#3b82f6",

      // Borders and grid lines
      borderColor: "#e5e7eb",
      dividerColor: "#e5e7eb",

      // Cell validation states
      errorCellBackgroundColor: "#fef2f2",
      errorCellHoverBackgroundColor: "#fee2e2",
      warningCellBackgroundColor: "#fffbeb",
      warningCellHoverBackgroundColor: "#fef3c7",
      infoCellBackgroundColor: "#eff6ff",
      infoCellHoverBackgroundColor: "#dbeafe",

      // Read-only cells
      readOnlyCellBackgroundColor: "#f9fafb",
      readOnlyCellTextColor: "#6b7280",

      // General accent color
      accentColor: "#3b82f6"
    }
  }
}
```

## Card Styling

Cards are used throughout Dromo for displaying field mappings, data enhancement options, and review summaries. Card styling helps organize information into digestible sections.

### Card Properties

* **`backgroundColor`** - Background color for individual cards
* **`containerBackgroundColor`** - Background color for the area containing multiple cards
* **`borderColor`** - Border color around cards
* **`borderWidth`** - Thickness of card borders
* **`borderRadius`** - Corner radius for rounded cards
* **`textColor`** - Default text color within cards
* **`expandedBackgroundColor`** - Background color when a card is expanded (for cards with collapsible content)
* **`iconColor`** - Color for icons displayed within cards

**Use cases:**

* Column matching screen: Each field in your schema is displayed as a card
* Data enhancement screen: Suggested fixes and transformations appear in cards
* Review screen: Summary information is organized in cards

```js theme={null}
const settings = {
  styleOverrides: {
    card: {
      backgroundColor: "#ffffff",
      containerBackgroundColor: "#f9fafb",
      borderColor: "#e5e7eb",
      borderWidth: "1px",
      borderRadius: "0.5rem",
      textColor: "#1f2937",
      expandedBackgroundColor: "#ffffff",
      iconColor: "#6b7280"
    }
  }
}
```

## Dropdown Styling

Dropdown menus (select components) are used for field mapping, choosing data types, and selecting transformation options.

### Dropdown Properties

* **`backgroundColor`** - Background color of the closed dropdown
* **`borderColor`** - Border color around the dropdown
* **`textColor`** - Text color for the selected value
* **`errorBorderColor`** - Border color when the control is in an error state
* **`menuBackgroundColor`** - Background color of the opened dropdown menu
* **`optionHoverBackgroundColor`** - Background color when hovering over an option
* **`optionSelectedBackgroundColor`** - Background color for the currently selected option

**Use cases:**

* Selecting which schema field a column maps to
* Choosing date formats during data transformation
* Selecting validation rules

```js theme={null}
const settings = {
  styleOverrides: {
    dropdown: {
      backgroundColor: "#ffffff",
      borderColor: "#d1d5db",
      textColor: "#374151",
      errorBorderColor: "#dc2626",
      menuBackgroundColor: "#ffffff",
      optionHoverBackgroundColor: "#f3f4f6",
      optionSelectedBackgroundColor: "#eff6ff"
    }
  }
}
```

## Additional UI Elements

### Dropzone (File Upload Area)

The dropzone is the drag-and-drop area on the upload screen where users can drop files or click to browse.

#### Properties

* **`borderWidth`** - Thickness of the dropzone border (number, e.g., 2)
* **`borderRadius`** - Corner radius (number, e.g., 8)
* **`borderColor`** - Border color
* **`borderStyle`** - Border style (e.g., "dashed", "solid", "dotted")
* **`backgroundColor`** - Background color
* **`color`** - Text color for the dropzone message
* **`outline`** - CSS outline property (e.g., "none", "2px solid blue")
* **`activeBorderColor`** - Border color while a file is being dragged over the dropzone
* **`acceptBorderColor`** - Border color when the dragged file is accepted
* **`rejectBorderColor`** - Border color when the dragged file is rejected

<Tip>
  A dashed border is commonly used for dropzones to visually distinguish them as interactive upload areas. Consider using your brand's accent color for the border when a file is being dragged over the dropzone.
</Tip>

```js theme={null}
const settings = {
  styleOverrides: {
    dropzone: {
      borderWidth: 2,
      borderRadius: 8,
      borderColor: "#d1d5db",
      borderStyle: "dashed",
      backgroundColor: "#f9fafb",
      color: "#374151",
      outline: "none",
      activeBorderColor: "#3b82f6",
      acceptBorderColor: "#10b981",
      rejectBorderColor: "#ef4444"
    }
  }
}
```

### Help Text

Help text appears throughout the interface to provide guidance, tips, and contextual information to users.

#### Properties

* **`textColor`** - Color of help text
* **`backgroundColor`** - Background color for help text sections (if applicable)

**Use cases:**

* Instructions on the upload screen
* Field descriptions during column matching
* Tips for fixing data errors

```js theme={null}
const settings = {
  styleOverrides: {
    helpText: {
      textColor: "#6b7280",
      backgroundColor: "#f9fafb"
    }
  }
}
```

### Stepper Bar (Progress Indicator)

The stepper bar displays the user's progress through the multi-step upload workflow (Upload → Set Headers → Match Columns → Clean Data → Review).

#### Properties

* **`completeColor`** - Color for completed steps
* **`incompleteColor`** - Color for steps not yet reached
* **`currentColor`** - Color for the current step
* **`fontSize`** - Font size for step labels
* **`completeFontWeight`** - Font weight for completed step labels
* **`incompleteFontWeight`** - Font weight for incomplete step labels
* **`currentFontWeight`** - Font weight for the current step label
* **`backgroundColor`** - Background color of the stepper bar
* **`borderBottom`** - Border at the bottom of the stepper bar

<Info>
  Use distinct colors that clearly communicate progress. A common pattern is green for completed, gray for incomplete, and blue for the current step.
</Info>

```js theme={null}
const settings = {
  styleOverrides: {
    stepperBar: {
      completeColor: "#10b981",        // Green for completed
      incompleteColor: "#d1d5db",      // Gray for not started
      currentColor: "#3b82f6",         // Blue for current step
      fontSize: "0.875rem",
      completeFontWeight: "600",       // Bold completed steps
      incompleteFontWeight: "400",     // Normal weight for future steps
      currentFontWeight: "600",        // Bold current step
      backgroundColor: "#ffffff",
      borderBottom: "1px solid #e5e7eb"
    }
  }
}
```

### Modal Overlay

The semi-transparent overlay that appears behind the uploader modal, covering the parent application.

#### Properties

* **`backgroundColor`** - Color of the overlay (typically black or dark gray)
* **`opacity`** - Opacity value from "0" to "100" (string)

<Warning>
  Be careful with opacity values. Too low (below 30) may not provide enough visual separation from the background. Too high (above 70) may make the overlay too dark and imposing.
</Warning>

```js theme={null}
const settings = {
  styleOverrides: {
    modalOverlay: {
      backgroundColor: "#000000",
      opacity: "50"                    // 50% opacity
    }
  }
}
```

### Error Navigator

The Error Navigator is available when [`reviewStep.enableNavigatingErrors`](/reference/settings/settings#enablenavigatingerrors) is enabled. Its colors and icons can be customized independently from the data table.

* **`errorColor`** - Color of error indicators, messages, and the error count
* **`warningColor`** - Color of warning indicators and messages
* **`accentColor`** - Color of primary actions and the active column filter
* **`errorIconUrl`** - URL of a custom error icon, or `null` for the default
* **`warningIconUrl`** - URL of a custom warning icon, or `null` for the default

```js theme={null}
const settings = {
  styleOverrides: {
    errorNavigator: {
      errorColor: "#b91c1c",
      warningColor: "#d97706",
      accentColor: "#6366f1",
      errorIconUrl: "https://cdn.example.com/error-icon.svg",
      warningIconUrl: null
    }
  }
}
```

## Complete Examples

### Light Theme Example

Here's a comprehensive example that demonstrates how to combine multiple style overrides to create a cohesive, branded experience. This example uses a blue and gray color palette typical of modern SaaS applications.

```js theme={null}
const settings = {
  styleOverrides: {
    // Global application styles
    global: {
      textColor: "#1f2937",
      primaryTextColor: "#111827",
      secondaryTextColor: "#6b7280",
      successColor: "#10b981",
      warningColor: "#f59e0b",
      customFontURL: "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap",
      customFontFamily: "'Inter', sans-serif",
      borderRadius: "0.5rem",
      backgroundColor: "#ffffff",
      borderColor: "#e5e7eb",
      backdropBlur: true
    },

    // Button styles
    primaryButton: {
      backgroundColor: "#3b82f6",
      textColor: "#ffffff",
      borderRadius: "0.375rem",
      hoverBackgroundColor: "#2563eb"
    },
    secondaryButton: {
      backgroundColor: "#f3f4f6",
      textColor: "#374151",
      borderRadius: "0.375rem",
      hoverBackgroundColor: "#e5e7eb"
    },
    tertiaryButton: {
      backgroundColor: "transparent",
      textColor: "#3b82f6",
      borderRadius: "0.375rem",
      hoverBackgroundColor: "#eff6ff"
    },

    // Data table
    dataTable: {
      headerBackgroundColor: "#f9fafb",
      headerTextColor: "#111827",
      headerFontWeight: "600",
      headerActiveBackgroundColor: "#eff6ff",
      cellBackgroundColor: "#ffffff",
      oddRowBackgroundColor: "#f9fafb",
      cellSelectionBorderColor: "#3b82f6",
      cellSelectionBackgroundColor: "rgba(59, 130, 246, 0.1)",
      errorCellBackgroundColor: "#fef2f2",
      warningCellBackgroundColor: "#fffbeb",
      infoCellBackgroundColor: "#eff6ff",
      readOnlyCellBackgroundColor: "#f9fafb",
      accentColor: "#3b82f6"
    },

    // Cards
    card: {
      backgroundColor: "#ffffff",
      containerBackgroundColor: "#f9fafb",
      borderColor: "#e5e7eb",
      borderRadius: "0.5rem",
      textColor: "#1f2937"
    },

    // Dropdowns
    dropdown: {
      backgroundColor: "#ffffff",
      borderColor: "#d1d5db",
      textColor: "#374151",
      optionHoverBackgroundColor: "#f3f4f6"
    },

    // File upload dropzone
    dropzone: {
      borderWidth: 2,
      borderRadius: 8,
      borderColor: "#d1d5db",
      borderStyle: "dashed",
      backgroundColor: "#f9fafb"
    },

    // Progress stepper
    stepperBar: {
      completeColor: "#10b981",
      currentColor: "#3b82f6",
      incompleteColor: "#d1d5db",
      completeFontWeight: "600",
      currentFontWeight: "600"
    },

    // Modal overlay
    modalOverlay: {
      backgroundColor: "#000000",
      opacity: "50"
    }
  }
}
```

### Dark Mode Example

Create a modern dark theme for applications that support dark mode or prefer a darker aesthetic. This example uses dark grays and blues with carefully adjusted contrast ratios for readability.

```js theme={null}
const settings = {
  styleOverrides: {
    // Global dark theme styles
    global: {
      backgroundColor: "#1a1a1a",
      primaryTextColor: "#f9fafb",
      secondaryTextColor: "#9ca3af",
      textColor: "#e5e7eb",
      successColor: "#10b981",
      warningColor: "#f59e0b",
      borderColor: "#374151",
      borderRadius: "8px",
      backdropBlur: true
    },

    // Dark mode cards
    card: {
      backgroundColor: "#1f2937",
      containerBackgroundColor: "#111827",
      borderColor: "#374151",
      borderWidth: "1px",
      borderRadius: "0.75rem",
      textColor: "#f9fafb",
      expandedBackgroundColor: "#111827",
      iconColor: "#9ca3af"
    },

    // Dark mode data table
    dataTable: {
      // Headers
      headerBackgroundColor: "#111827",
      headerTextColor: "#f9fafb",
      headerFontWeight: "500",
      headerActiveBackgroundColor: "#1e3a8a",
      headerActiveTextColor: "#ffffff",
      headerHighlightedBackgroundColor: "#1e40af",
      headerHighlightedTextColor: "#ffffff",

      // Row headers
      rowHeaderBackgroundColor: "#111827",
      rowHeaderTextColor: "#f9fafb",
      cornerHeaderBackgroundColor: "#111827",

      // Cells
      cellBackgroundColor: "#1f2937",
      cellTextColor: "#e5e7eb",
      cellHoverBackgroundColor: "#374151",
      cellHoverTextColor: "#f9fafb",
      oddRowBackgroundColor: "#374151",

      // Selection
      cellSelectionBorderColor: "#3b82f6",
      cellSelectionBackgroundColor: "rgba(59, 130, 246, 0.1)",
      rowSelectedBackgroundColor: "rgba(59, 130, 246, 0.3)",
      rowSelectedBorderColor: "#3b82f6",

      // Borders
      borderColor: "#374151",
      dividerColor: "#4b5563",

      // Cell states
      errorCellBackgroundColor: "#7f1d1d",
      errorCellHoverBackgroundColor: "#991b1b",
      warningCellBackgroundColor: "#713f12",
      warningCellHoverBackgroundColor: "#854d0e",
      infoCellBackgroundColor: "#1e3a8a",
      infoCellHoverBackgroundColor: "#1e40af",

      // Read-only
      readOnlyCellBackgroundColor: "#374151",
      readOnlyCellTextColor: "#9ca3af",

      accentColor: "#3b82f6"
    },

    // Dark mode buttons
    primaryButton: {
      backgroundColor: "#3b82f6",
      textColor: "#ffffff",
      borderRadius: "0.375rem",
      hoverBackgroundColor: "#2563eb",
      hoverTextColor: "#ffffff"
    },
    secondaryButton: {
      backgroundColor: "#374151",
      textColor: "#f9fafb",
      border: "1px solid #4b5563",
      borderRadius: "0.375rem",
      hoverBackgroundColor: "#4b5563",
      hoverTextColor: "#f9fafb"
    },
    tertiaryButton: {
      backgroundColor: "transparent",
      textColor: "#3b82f6",
      border: "1px solid transparent",
      borderRadius: "0.375rem",
      hoverBackgroundColor: "#1f2937",
      hoverTextColor: "#60a5fa"
    },

    // Dark mode dropdowns
    dropdown: {
      backgroundColor: "#1f2937",
      borderColor: "#374151",
      textColor: "#f9fafb",
      menuBackgroundColor: "#1f2937",
      optionHoverBackgroundColor: "#374151",
      optionSelectedBackgroundColor: "#4b5563"
    },

    // Dark mode dropzone
    dropzone: {
      borderWidth: 2,
      borderRadius: 8,
      backgroundColor: "#1f2937",
      borderColor: "#4b5563",
      borderStyle: "dashed",
      color: "#f9fafb"
    },

    // Dark mode stepper
    stepperBar: {
      backgroundColor: "#111827",
      borderBottom: "1px solid #374151",
      currentColor: "#3b82f6",
      completeColor: "#10b981",
      incompleteColor: "#6b7280",
      completeFontWeight: "600",
      currentFontWeight: "600"
    },

    // Dark mode overlay
    modalOverlay: {
      backgroundColor: "#000000",
      opacity: "75"
    }
  }
}
```

<Tip>
  When implementing dark mode, pay special attention to contrast ratios. Dark backgrounds require lighter text colors, and selection/highlight colors often need higher opacity to be visible. Test your dark theme with actual content to ensure readability.
</Tip>


# Processing Import Results in Your Application
Source: https://developer.dromo.io/guides/handling-results

Process completed Dromo import data and metadata in the browser, send results to your backend, or receive them through webhooks.

<Info>
  For more information on the onResults callback, see the [Reference](/reference/results#the-onresults-callback) documentation.
</Info>

Here we show how to handle results directly in the browser, using Google Firebase as an example (unlike an RDBMS like Postgres, Firebase allows for direct browser connections). To handle results on a server, either send the `onResults` data to an API you control or subscribe to a [webhook](/reference/webhooks).

This example assumes you have installed the [Firebase SDK](https://firebase.google.com/docs/web/setup).

<CodeGroup>
  ```javascript theme={null}
  import { initializeApp } from 'firebase/app';
  import { getFirestore } from 'firebase/firestore';
  import { addDoc, collection } from 'firebase/firestore';

  const firebaseConfig = {
    ...
  };

  const app = initializeApp(firebaseConfig);
  const db = getFirestore(app);

  ```
</CodeGroup>

The `onResults` callback returns an array of objects, where each object represents a record. The callback also receives a `metadata` object containing information about the import process.

<CodeGroup>
  ```javascript theme={null}
  dromo.onResults(function (data, metadata) {
    console.log('Import metadata:', metadata);

    // Loop through each item in the data array and add it as a document in Firebase
    data.forEach(async (record) => {
      try {
        const docRef = await addDoc(collection(db, 'collectionName'), record);
        console.log(`Document written with ID: ${docRef.id}`);
      } catch (e) {
        console.error('Error adding document: ', e);
      }
    })
  });
  ```
</CodeGroup>

## Working with Metadata

The `metadata` object contains useful information about the import:

```javascript theme={null}
dromo.onResults(function (data, metadata) {
  console.log('Total rows processed:', metadata.totalRows);
  console.log('Valid rows:', metadata.validRows);
  console.log('Invalid rows:', metadata.invalidRows);
  console.log('Original headers:', metadata.rawHeaders);
});
```

## Handling Unmapped Columns

If you've enabled the `passThroughUnmappedColumns` setting, your data will include unmapped columns that weren't part of your schema:

```javascript theme={null}
dromo.onResults(function (data, metadata) {
  data.forEach(async (record) => {
    // Process main mapped data
    const mappedData = { ...record };
    delete mappedData.$unmapped;

    // Handle unmapped columns separately if they exist
    if (record.$unmapped && metadata.rawHeaders) {
      const unmappedData = {};
      Object.entries(record.$unmapped).forEach(([index, value]) => {
        const headerName = metadata.rawHeaders[parseInt(index)];
        if (headerName) {
          unmappedData[headerName] = value;
        }
      });

      // Store unmapped data in a separate collection or field
      console.log('Unmapped data:', unmappedData);
    }

    // Save to Firebase
    await addDoc(collection(db, 'collectionName'), mappedData);
  });
});
```

<Note>
  For a comprehensive guide on working with unmapped columns, see the [Accessing Unmapped Columns guide](/guides/accessing-unmapped-columns).
</Note>


# Importing a PDF table with a Custom Parser
Source: https://developer.dromo.io/guides/importing-a-pdf

Build a custom Dromo file parser that extracts tabular data from PDF uploads with PDFTables and PapaParse.

## Overview

In this guide, we'll build a [custom file parser](/reference/custom-file-parsers) to support PDF uploads using the PDFTables API to extract tables from PDFs.

## Getting Started

For our example we're importing users from a table in a PDF document.

<img alt="PDF Contents" />

We'll rely on [PDFTables](https://pdftables.com/) API to parse the PDF into a CSV string. Once we have a CSV string, we'll use an additional external library, [PapaParse](https://www.papaparse.com/), to parse the CSV string into a two dimensional array of data for Dromo to receive.

<Info>
  To use this demo you'll need to get your own [paid API key from PDFTables](https://pdftables.com/pricing).
</Info>

## Adding the Custom Parser to Dromo

Dromo provides an [interface for implementing custom file parsing](/reference/custom-file-parsers). We need to specify the file extension(s) and the parsing logic that will be used to parse the file.

<CodeGroup>
  ```javascript JavaScript theme={null}
  ...
  const dromo = new DromoUploader("FRONTEND_API_KEY", fields, settings, user);

  dromo.registerFileParser({
    extensions: ["pdf"],
    parseFile: async (buffer, fileName) => {
      ...
    },
  });
  ```

  ```jsx React theme={null}
  ...
  <DromoUploader
    fileParsers={[
      {
        extensions: ["pdf"],
        parseFile: async (buffer, fileName) => {
          ...
        },
      },
    ]}>
    Import Users
  </DromoUploader>
  ```
</CodeGroup>

## Implementing PDF Parsing Logic

Dromo passes a `buffer: ArrayBuffer` and `fileName: string` to the `parseFile` callback. We will use the buffer to create a file that we can `POST` to the PDFTables API.

<CodeGroup>
  ```javascript theme={null}
  async (buffer, fileName) => {
    const myPDFTablesAPIKey = "<YOUR PDF TABLED API KEY>";
    const url = `https://pdftables.com/api?key=${myPDFTablesAPIKey}&format=csv`;
    const formData = new FormData();
    formData.append("file", new Blob([buffer]), fileName);
    
    const response = await fetch(url, {
      method: "POST",
      body: formData,
    });
    
    // text data response is a CSV string
    const data = await response.text();
    ...
  };
  ```
</CodeGroup>

If successful, the `response.text()` will contain a CSV string. Like this:

<CodeGroup>
  ```text theme={null}
  'my_filename,,,\nFirst,Last,Email,Food\nMichael,Phillips,jason@moxie.xyz,Apple\nMohit,Kukreja,info@hub.inc,Banana\nMark,Walz,vengat@klenty.com,Orange\nTonya,,team@buyerassist.io,Apple\nBen,Cohen,bad email,Banana\n,Simonyan,hello@markaaz.com,Orange\nSagar,Sagiraju,,Apple\nR2,Bewley,preena@klenty.com,Banana\nRuairi,Galavan,Info test,Orange\nAdam,Zelinski,info@medisponsor.com,Apple\nAnais,Mares,info@arrowxyz.com,Banana\nLucia,Lu,support@data-lead.com,Orange\nVishu,Gopal,admin@uptics.io,Strawberry\n1,,,\n'
  ```
</CodeGroup>

We need to convert this in to a two dimensional array. We'll use [PapaParse](https://www.papaparse.com/), a free package, to convert the string to the desired format.

<CodeGroup>
  ```javascript theme={null}
  import Papa from "papaparse";
  ...

  // text data response is a CSV string
  const data = await response.text();
  // 'names email select,,,\nFirst,Last,Email,Food\nMichael,Phillips...'

  const lines = Papa.parse(data).data as string[][];
  // [['names email select', '', '', ''], ['First', 'Last', 'Email', 'Food'], ['Michael', 'Phillips', 'jason@moxie.xyz', 'Apple']...]
  ...
  ```
</CodeGroup>

Ensure that every line in the two dimensional array is the same length, then return the data.

<CodeGroup>
  ```javascript theme={null}
  const maxLen = Math.max(...lines.map((row) => row.length));
  const result = lines.map((row) => {
    const padding = Array(maxLen - row.length).fill("");
    return [...row, ...padding];
  });

  return result;
  ```
</CodeGroup>

We're done! Let's try it in Dromo and see how it works.

Open the Dromo importer and observe the file extensions now include 'pdf'.

<img alt="extensions include pdf image" />

Drag and drop your PDF test file. Your data should be properly parsed and loaded.

<img alt="parsed pdf data" />

## Full Complete Demo

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Using PapaParse https://www.papaparse.com/ to parse the CSV string
  import Papa from "papaparse";

  const fields = [
    {
      label: "Email",
      key: "email",
      type: "email",
    },
    {
      label: "First Name",
      key: "firstName",
    },
    {
      label: "Last Name",
      key: "lastName",
    },
    {
      label: "Food",
      key: "food",
      type: "select",
      selectOptions: [
        { label: "Apple", value: "Apple" },
        { label: "Banana", value: "Banana" },
        { label: "Orange", value: "Orange" },
        { label: "Strawberry", value: "Strawberry" },
      ],
    },
  ];

  const settings = {
    importIdentifier: "Custom Parser Example",
  };

  const user = {
    id: "12345",
  };

  const dromo = new DromoUploader("FRONTEND_API_KEY", fields, settings, user);

  dromo.registerFileParser({
    extensions: ["pdf"],
    parseFile: async (buffer, fileName) => {
      const myPDFTablesAPIKey = "<YOUR PDF TABLED API KEY>";
      const url = `https://pdftables.com/api?key=${myPDFTablesAPIKey}&format=csv`;
      const formData = new FormData();
      formData.append("file", new Blob([buffer]), fileName);
      
      const response = await fetch(url, {
        method: "POST",
        body: formData,
      });
      
      // text data response is a CSV string
      const data = await response.text();
      const lines = Papa.parse(data).data as string[][];
      
      // Pad the lines to ensure they're all the same length
      const maxLen = Math.max(...lines.map((row) => row.length));
      const result = lines.map((row) => {
        const padding = Array(maxLen - row.length).fill("");
        return [...row, ...padding];
      });
      
      return result;
    },
  });
  ```

  ```jsx React theme={null}
  // Using PapaParse https://www.papaparse.com/ to parse the CSV string
  import Papa from "papaparse";
  ...

  <DromoUploader
    licenseKey={"FRONTEND_API_KEY"}
    user={{ id: "12345" }}
    fields={[
      {
        label: "Email",
        key: "email",
        type: "email",
      },
      {
        label: "First Name",
        key: "firstName",
      },
      {
        label: "Last Name",
        key: "lastName",
      },
      {
        label: "Food",
        key: "food",
        type: "select",
        selectOptions: [
          { label: "Apple", value: "Apple" },
          { label: "Banana", value: "Banana" },
          { label: "Orange", value: "Orange" },
          { label: "Strawberry", value: "Strawberry" },
        ],
      },
    ]}
    settings={{
      importIdentifier: "Custom Parser Example",
    }}
    fileParsers={[
      {
        extensions: ["pdf"],
        parseFile: async (buffer, fileName) => {
          const myPDFTablesAPIKey = "<YOUR PDF TABLED API KEY>";
          const url = `https://pdftables.com/api?key=${myPDFTablesAPIKey}&format=csv`;
          const formData = new FormData();
          formData.append("file", new Blob([buffer]), fileName);
          
          const response = await fetch(url, {
            method: "POST",
            body: formData,
          });
          
          // text data response is a CSV string
          const data = await response.text();
          const lines = Papa.parse(data).data as string[][];
          
          // Pad the lines to ensure they're all the same length
          const maxLen = Math.max(...lines.map((row) => row.length));
          const result = lines.map((row) => {
            const padding = Array(maxLen - row.length).fill("");
            return [...row, ...padding];
          });
          
          return result;
        },
      },
    ]}>
    Import Users
  </DromoUploader>
  ```
</CodeGroup>


# Using the Saved Schema API
Source: https://developer.dromo.io/guides/saved-schema-api

Create, update, and delete saved schemas with correctly shaped names, fields, settings, validators, and serialized hook callbacks.

Working with the API lets you create and manage reusable import schemas. Saved schemas support the serializable fields, settings, and hooks defined by the Saved Schema API.

## The API

Dromo provides a standard REST API for working with schemas. The API provides standard CRUD operations for saved schemas.

You can view the full Saved Schema API reference [here](/api-reference/import-schemas).

## Saved Schema Structure

Schemas have the following fields:

<ResponseField name="id" type="string">
  Schemas are automatically assigned a UUID when they are created.
</ResponseField>

<ResponseField name="name" type="string">
  Schemas must have a unique name within your organization.

  Schema names are displayed in the Dromo dashboard.
</ResponseField>

<ResponseField name="settings" type="Settings">
  Saved schemas accept the serializable settings defined by the API schema. This includes the `uploadStep`, `matchingStep`, `matchValuesStep`, and `reviewStep` objects and `autoMapHeaders`.

  Some browser-runtime settings are not accepted by the saved-schema serializer. These currently include `initialFile`, `savePartialSession`, `textOverrides`, `allowEmptySubmit`, and `batchRowHookBatchSize`.

  See [Settings](/reference/settings/settings) for the full browser SDK settings reference.
</ResponseField>

<ResponseField name="fields" type="Field[]">
  Schemas have an array of fields which also accept the same full set of options as the browser SDK.

  See [Field Object Reference](/fields#field-object-reference) for more details.
</ResponseField>

<ResponseField name="hooks" type="object">
  You can define the serializable [hooks](/reference/hooks) listed below using the Saved Schema API. Batch row hooks are currently available only through embedded SDK integrations and cannot be stored in a saved schema or used by a headless import.

  The hook function JavaScript source is passed as a string, which must evaluate to a valid JavaScript function. See the [defining hooks section](#defining-hooks) for examples.

  All hooks are optional.

  <Expandable title="Hook Properties">
    <ResponseField name="rowHooks" type="string[]">
      An array of strings defining valid JavaScript [standard row hooks](/reference/hooks#standard-row-hooks).
    </ResponseField>

    <ResponseField name="bulkRowHooks" type="string[]">
      An array of strings defining valid JavaScript [bulk row hooks](/reference/hooks#bulk-row-hooks).
    </ResponseField>

    <ResponseField name="rowDeleteHooks" type="string[]">
      An array of strings defining valid JavaScript [row delete hooks](/reference/hooks#row-delete-hooks).
    </ResponseField>

    <ResponseField name="columnHooks" type="object[]">
      An array of objects defining [column hooks](/reference/hooks#column-hooks).

      Each column hook has a `fieldName` specifying which column the hook will run on, and a `callback` defining a valid JavaScript column hook function.

      <Expandable title="Column Hook Object">
        <ResponseField name="fieldName" type="string">
          The field name this hook applies to.
        </ResponseField>

        <ResponseField name="callback" type="string">
          Valid JavaScript column hook function.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="stepHooks" type="object[]">
      An array of objects defining [step hooks](/reference/hooks#step-hooks).

      Each step hook has a supported `type` and a `callback` defining a valid JavaScript step hook function.

      <Expandable title="Step Hook Object">
        <ResponseField name="type" type="string">
          One of: `"UPLOAD_STEP"`, `"REVIEW_STEP"`, `"REVIEW_STEP_POST_HOOKS"`, or `"REVIEW_STEP_PRE_SUBMIT"`.
        </ResponseField>

        <ResponseField name="callback" type="string">
          Valid JavaScript step hook function.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="beforeFinishCallback" type="string">
      A string defining a valid JavaScript [before finish callback](/reference/results#the-beforefinish-callback).
    </ResponseField>

    <ResponseField name="fileParsers" type="object[]">
      An array of [custom file parser](/reference/custom-file-parsers) objects. Each object contains an `extensions` string array and a serialized `parseFile` callback.
    </ResponseField>
  </Expandable>
</ResponseField>

## Defining hooks

Hook functions are defined using strings containing JavaScript source code. The code is evaluated in the end user's browser for standard imports, and using Node.js 18 for headless imports.

All types of function declarations are accepted:

* Anonymous function expression: `function(a, b) { return a + b; }`
* Named function expression: `function sum(a, b) { return a + b; }`
* Arrow function: `(a, b) => { return a + b; }`

<AccordionGroup>
  <Accordion title="Row hook example">
    To define a row hook, you could pass the following to the API's `hooks` parameter:

    <CodeGroup>
      ```javascript theme={null}
      {
        "rowHooks": [
          (record, mode) => {
            record.row.zipCode.value = record.row.zipCode.value.padStart(5, '0');
            return record;
          }
        ]
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Step hook example">
    To define a step hook, you could pass the following to the API's `hooks` parameter:

    <CodeGroup>
      ```javascript theme={null}
      {
        "stepHooks": [
          {
            type: "REVIEW_STEP",
            callback: (instance) => {
              instance.addField({ label: 'Full Name', key: 'fullName' });
            }
          }
        ]
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## Using saved schemas

Saved schemas can be used [in the browser](/guides/schema-builder) or using the [Headless API](/getting-started/headless).

You can also use the [Saved Schema API](/api-reference/import-schemas) to programmatically create and manage schemas.


# Saving & Restoring Session Progress
Source: https://developer.dromo.io/guides/saving-progress

Save an in-progress Dromo import, restore it later across devices, and securely manage session and hydration tokens.

Dromo's session auto-save feature lets users pick up an import exactly where they left off — even after navigating away, closing the browser, or returning days later. Sessions are stored server-side and can be restored across any device.

## How it works

When `savePartialSession` is enabled, Dromo continuously saves the user's progress in the background — capturing the active stage, column mappings, transformations, and the uploaded file. Progress is debounced and flushed automatically; no extra code is required.

To enable auto-save:

```javascript theme={null}
const importer = new DromoUploader("YOUR_LICENSE_KEY", fields, {
  backendSyncMode: "FULL_DATA",
  savePartialSession: true,
  importIdentifier: "contacts-import-v1",
});
```

<Note>
  `savePartialSession` requires `backendSyncMode: "FULL_DATA"` and a consistent
  `importIdentifier` to group sessions for the same import type.
</Note>

***

## Security model — the hydrationId

Sessions use a two-token model to prevent a leaked credential from granting permanent access:

| Token         | Lifespan                                        | Purpose                                                                               |
| ------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------- |
| `sessionId`   | Long-lived (7-day session TTL)                  | Backend session identifier — persist this durably; used to resume or delete a session |
| `hydrationId` | Short-lived (configurable TTL, default 6 hours) | Access token — passed to the widget to start or resume a session                      |

When a session is created, both tokens are returned. Pass the `hydrationId` to the widget. Store the `sessionId` server-side so you can mint a fresh `hydrationId` whenever the user returns.

<Warning>
  All session endpoints require your **backend** license key (`is_for_backend_api=True`). Never call these from client-side code.
</Warning>

***

## Starting a session

Call `POST /api/widget/session/v2/auth/` from your backend. The response includes a `sessionId` to store and a `hydrationId` to pass to the widget.

```bash theme={null}
curl --request POST \
  --url https://app.dromo.io/api/widget/session/v2/auth/ \
  --header 'X-DROMO-LICENSE-KEY: YOUR_BACKEND_LICENSE_KEY'
```

Optionally provide an `import_identifier` and a custom token TTL:

```bash theme={null}
curl --request POST \
  --url https://app.dromo.io/api/widget/session/v2/auth/ \
  --header 'X-DROMO-LICENSE-KEY: YOUR_BACKEND_LICENSE_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "import_identifier": "user_import_v1",
    "expires_in": 3600
  }'
```

| Field               | Required | Description                                                                                               |
| ------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `import_identifier` | No       | A label for your own bookkeeping (e.g. schema name, import type). Not used for lookups. Defaults to `""`. |
| `expires_in`        | No       | Hydration token TTL in seconds. Defaults to `21600` (6 hours).                                            |

**Response:**

```json theme={null}
{
  "sessionId":   "1b6acf28-8748-4120-8d7a-4b7846d5e487",
  "hydrationId": "<signed-token>",
  "expiresAt":   "2026-08-26T18:00:00Z"
}
```

Store both values:

* **`sessionId`** — persist this server-side. It is needed to resume or delete the session later.
* **`hydrationId`** — pass this to the widget to begin the session.

***

## Restoring a session

When the user returns to resume an import, mint a fresh `hydrationId` from your backend using the stored `sessionId`, then pass it to the widget.

### Step 1 — Re-issue a hydrationId

```bash theme={null}
curl --request POST \
  --url https://app.dromo.io/api/widget/session/v2/SESSION_ID/auth/ \
  --header 'X-DROMO-LICENSE-KEY: YOUR_BACKEND_LICENSE_KEY'
```

Optionally set a custom TTL:

```bash theme={null}
curl --request POST \
  --url https://app.dromo.io/api/widget/session/v2/SESSION_ID/auth/ \
  --header 'X-DROMO-LICENSE-KEY: YOUR_BACKEND_LICENSE_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "expires_in": 3600 }'
```

| Field              | Required | Description                                                                                                 |
| ------------------ | -------- | ----------------------------------------------------------------------------------------------------------- |
| `SESSION_ID` (URL) | Yes      | UUID of the session to resume. Returns 404 if the session doesn't exist or hasn't been saved within 7 days. |
| `expires_in`       | No       | New token TTL in seconds. Defaults to `21600` (6 hours).                                                    |

**Response:**

```json theme={null}
{
  "sessionId":   "1b6acf28-8748-4120-8d7a-4b7846d5e487",
  "hydrationId": "<signed-token>",
  "expiresAt":   "2026-08-26T18:00:00Z"
}
```

### Step 2 — Pass to the widget

```javascript theme={null}
const importer = new DromoUploader("YOUR_LICENSE_KEY", fields, {
  backendSyncMode: "FULL_DATA",
  savePartialSession: true,
  importIdentifier: "contacts-import-v1",
  hydrationId: freshHydrationId,
});
```

The widget uses the `hydrationId` to fetch the saved state and resume from where the user left off.

***

## Deleting a session

Sessions are automatically cleared when an import completes. To delete manually, send a `DELETE` request with the session's UUID and your **backend** license key:

```bash theme={null}
curl --request DELETE \
  --url https://app.dromo.io/api/widget/session/v2/SESSION_ID/ \
  --header 'X-DROMO-LICENSE-KEY: YOUR_BACKEND_LICENSE_KEY'
```

| Field              | Required | Description                    |
| ------------------ | -------- | ------------------------------ |
| `SESSION_ID` (URL) | Yes      | UUID of the session to delete. |

**Response:**

```json theme={null}
{ "success": true }
```

All hydration tokens for the session are immediately invalidated — any subsequent widget calls with the old `hydrationId` return 403. This call is idempotent and returns `success: true` even if the session was already deleted.

***

## Error reference

| Error                     | Meaning                                                      | Action                                                                   |
| ------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------ |
| `404` on resume or delete | Session not found or not saved within 7 days                 | Start a new session                                                      |
| `403` on widget call      | `hydrationId` invalidated (session deleted or token expired) | Re-issue a `hydrationId` via the resume endpoint, or start a new session |

***

## Full endpoint reference

All endpoints require `X-DROMO-LICENSE-KEY` (backend license key).

| Method   | Endpoint                                   | Description                                                                |
| -------- | ------------------------------------------ | -------------------------------------------------------------------------- |
| `POST`   | `/api/widget/session/v2/auth/`             | Create a new session. Returns `sessionId`, `hydrationId`, and `expiresAt`. |
| `POST`   | `/api/widget/session/v2/{sessionId}/auth/` | Re-issue a `hydrationId` for an existing session.                          |
| `DELETE` | `/api/widget/session/v2/{sessionId}/`      | Delete a session and invalidate all its tokens. Idempotent.                |


# Using Schema Studio
Source: https://developer.dromo.io/guides/schema-builder

Create, configure, test, and manage Dromo import schemas visually with Schema Studio in the Dromo dashboard.

Dromo's Schema Studio streamlines creating a schema, so you can start working with Dromo.

## Creating a Schema[​](#creating-a-schema "Direct link to Creating a Schema")

<Check>
  [Click here to get started with Schema Studio now!](https://dashboard.dromo.io/public/schemas/create)
</Check>

Once you've [logged into](https://dashboard.dromo.io/auth/login) your Dromo account, you can access Schema Studio from your [Dromo dashboard](https://dashboard.dromo.io/schemas). Here, you can create a new schema or update any schemas you've previously created. Click **Create Schema**:

<img alt="Navigate to Schema Studio" />

<Steps>
  <Step title="Add a Name">
    <img alt="Adding a schema name" />
  </Step>

  <Step title="Customize your importer">
    Next, you can customize the importer your end-user interacts with:

    <img alt="Customizing the general settings of your Dromo importer" />

    You can optionally configure the importer's:

    * title
    * behavior for [invalid data](/reference/settings/settings#invaliddatabehavior)
    * a [webhook URL](/reference/webhooks) where new submissions are sent
    * ability to let users add [custom fields](/reference/settings/settings#allowcustomfields)
    * private mode settings

    <Info>
      Private mode lets you to control whether user data is sent or persisted through Dromo's servers. Private mode is only available on the [Dromo Pro plan](https://dromo.io/pricing).
    </Info>

    You can also optionally customize your importer's appearance with custom colors. You can preview your Dromo importer's appearance by clicking **Test now** in the footer:

    <img alt="Use the Test Now button to see your importer" />
  </Step>

  <Step title="Add fields to your schema">
    Next, you'll define your schema's fields. You can think of a schema's [fields](/reference/fields) like columns in a spreadsheet.

    If you are importing your user-collected data into a database, you'll want your data to be in the shape your database table expects. This means your schema's fields usually match the columns in your database. For example, let's say you have a client database table with two columns for clients' names and emails. Your schema would have two fields to match your database table; one for our clients' names and a second for their emails.

    You can add fields in two ways:

    1. Importing a CSV and letting Schema Studio automatically detect the field and types.
    2. Manually clicking the **Add field** button.

       <img alt="Use an existing file or manually add fields" />

    Once you've added a new field, clicking on the name of that field enables you to customize or delete it. You can customize a field's:

    * Label: The column name your users see in the importer.
    * Key: The field's unique identifier is this field's key in the JSON results.
    * Description: A description for this field that your users will see in the importer.
    * Type: The [type](/reference/fields/field-types) of data your user should input (e.g., email, date, text, etc.).

      <img alt="The options to customize a field" />

    Additionally, you can use [**validators**](/reference/fields/field-validators) to enforce rules for the data a user is allowed to import. You can choose to make a field required, unique, follow a particular [Regex](https://en.wikipedia.org/wiki/Regular_expression) pattern, or any combination of the above:

    <img alt="The validators you can add to a field" />

    You can try out your importer settings and fields in real-time using the **Test now** button on the footer on the screen:

    <img alt="Click test now to try our your schema" />

    Once you've customized your schema, click **Save schema**. You'll be redirected to the main Schema Studio page, where you can see your new schema:

    <img alt="New schema added to total list" />
  </Step>
</Steps>

## Using Schemas

To start using a schema in your application, click on the angled brackets icon in the Schemas Tab in the Dashboard:

<img alt="Schema icons" />

Copy and paste the pop-up code block into your own website's code and you're done! 🎉 You should be able to test the flow now.

<Info>
  You can see your user's imports from the [**Imports** Tab](https://dashboard.dromo.io/imports) in your Dromo dashboard.
</Info>

However, to integrate into your application, you will still need to handle the data, which you can do via the [`onResult` callback](/reference/results).

<CodeGroup>
  ```javascript JavaScript theme={null}
  dromo.onResults((response, metadata) => {
    // Connect to our database
    db.connect();
    // create new entries in our database using the user's imported data
    db.uploadData(response);
  });
  ```

  ```jsx React theme={null}
  <DromoUploader
    ...
    onResults={(response, metadata) =>
      // Connect to our database
      db.connect();
      // create new entries in our database using the user's imported data
      db.uploadData(response);
    }
  ></DromoUploader>
  ```
</CodeGroup>

## Advanced Usage

### Assigning User Metadata

Currently, your importer doesn't know *who* is using it to upload information. If a user uploads data, there is no associated metadata for that user, so all user-related fields are left blank:

<img alt="No set user for an Import" />

However, you can add more context to an upload by setting user metadata about the end user to associate with an import:

<CodeGroup>
  ```javascript theme={null}
  const dromo = new DromoUploader("YOUR_LICENSE_KEY", "YOUR_SCHEMA_ID");

  // Create a user object to associate imports to
  const user = {
    id: '1',
    name: 'Jane Doe',
    email: 'jane@dromo.io',
    companyId: '12345',
    companyName: 'Dromo'
  };

  // Associate the above user to this import
  dromo.setUser(user);
  ```
</CodeGroup>

### Development Mode[​](#development-mode "Direct link to Development mode")

The `DromoUploader` offers a "development mode" for testing import flows or iterating on finishing touches. Dromo doesn't charge you for data you import in development mode, but you are restricted to only importing 100 rows for any given file.

<Info>
  Your importer runs in development mode by default if you do **not** have an active Dromo subscription. To run Dromo in production, upgrade [to one of our pricing plans](https://dromo.io/pricing).
</Info>

You can switch your `DromoUploader` into development mode using the `setDevelopmentMode` method, like so:

<CodeGroup>
  ```javascript theme={null}
  <script type="text/javascript">
    const dromo = new DromoUploader("YOUR_LICENSE_KEY", "YOUR_SCHEMA_ID");
    dromo.setDevelopmentMode(true);
  </script>
  ```
</CodeGroup>

The importer now shows a development mode banner, and all incoming imports are now flagged as development imports and you don't get charged for them!

<img alt="Development Mode" />


# Concatenating and Splitting Fields via addField
Source: https://developer.dromo.io/guides/using-addField

Use step hooks, addField, removeField, and row hooks to dynamically concatenate, split, add, or remove fields during an import.

This guide demonstrates how to use step hooks to add or remove fields midway through an import.

<Info>
  For more information on the `instance.addField` method, see the [Reference](/reference/hooks#instanceaddfield) documentation. For more information on the `instance.removeField` method, see the [Reference](/reference/hooks#instanceremovefield) documentation.
</Info>

<CodeGroup>
  ```javascript JavaScript theme={null}
  dromo.registerStepHook("REVIEW_STEP", function (instance, data) {
    instance.addField({
      label: "Full Name",
      key: "fullName",
    });
  });

  dromo.registerStepHook("REVIEW_STEP_POST_HOOKS", function (instance, data) {
    instance.removeField("firstName");
    instance.removeField("lastName");
  });

  dromo.registerRowHook(function (data, mode) {
    let out: IRowHookOutput = { row: { ...data.row } };
    if (data.row.firstName && data.row.lastName && mode === "init") {
      out.row.fullName = {
        value: data.row.firstName.value + " " + data.row.lastName.value,
        info: [
          {
            message: "combined first and last name into full name",
            level: "info",
          },
        ],
      };
    }
    return out;
  });
  ```

  ```jsx React theme={null}
  <DromoUploader
    licenseKey="FRONTEND_API_KEY"
    ...
    stepHooks={[
      {
        type: "REVIEW_STEP",
        callback: (instance, _data) => {
          instance.addField({
            label: "Full Name",
            key: "fullName",
          })
        }
      },
      {
        type: "REVIEW_STEP_POST_HOOKS",
        callback: (instance, _data) => {
          instance.removeField("firstName");
          instance.removeField("lastName");
        }
      }
    ]}
    rowHooks={[
      (data: IRowHookInput, mode: string) => {
        let out: IRowHookOutput = { row: { ...data.row } };
        if (data.row.firstName && data.row.lastName && mode === 'init') {
          out.row.fullName = {
            value: data.row.firstName.value + " " + data.row.lastName.value,
            info: [
              {
                message: "combined first and last name into full name",
                level: "info"
              }
            ]
          }
        }
        return out
      }
    ]}>
    Launch Dromo
  </DromoUploader>
  ```
</CodeGroup>


# Mapping Multiple Columns to a Single Field
Source: https://developer.dromo.io/guides/using-manyToOne

Configure manyToOne fields to map a variable number of uploaded spreadsheet columns into a single Dromo schema field.

This guide demonstrates how to use field setting to map multiple columns to a single field.

<Info>
  For more detail about the `manyToOne` setting, see the [field object reference](/reference/fields/fields#field-object-reference).
</Info>

Suppose we're collecting tax information: `email`, `primary_earnings`, and optional `additional_earnings`. Users upload spreadsheets with these columns, though the number of `additional_earnings` columns may vary. We'll map them all to a single `additional_earnings` field and validate all earnings as USD currency.

## Field Configuration

Adding the property `manyToOne` with the value `true` enables many to one mapping.

<CodeGroup>
  ```javascript JavaScript theme={null}
  export const fields = [
    {
      label: 'Email',
      key: 'email',
      type: 'email'
    },
    {
      label: 'Primary Earnings',
      key: 'primary_earnings',
      type: ['number', 'usd'],
    },
    {
      label: 'Additional Earnings',
      key: 'additional_earnings',
      type: ['number', 'usd'],
      manyToOne: true,
    },
  ];
  ```

  ```jsx React theme={null}
  <DromoUploader
    fields={[
      {
        label: 'Email',
        key: 'email',
        type: 'email'
      },
      {
        label: 'Primary Earnings',
        key: 'primary_earnings',
        type: ['number', 'usd'],
      },
      {
        label: 'Additional Earnings',
        key: 'additional_earnings',
        type: ['number', 'usd'],
        manyToOne: true,
      },
    ]}
    ...>
    Import Earnings
  </DromoUploader>
  ```
</CodeGroup>

With this setting enabled, a user will be able to choose multiple columns and match them to the field without error.

<img alt="many to one column mapping" />

## Data Review Screen

With multiple columns mapped to one field, all the columns will have the label with a number indicating their order.

Note that validations defined in a `manyToOne` field apply to all mapped columns.

<img alt="data review screen with many to one" />

## Results

Upon successful import, the [results and metadata](/reference/results#the-onresults-callback) include all the values from the mapped columns and metadata indicating how the columns were mapped to the target schema.

### Result Data

Each value from a `manyToOne` column appear in an array that is the value for the `manyToOne` field's key.

<CodeGroup>
  ```json theme={null}
  [
    {
      "email": "tumvu@comowa.fk",
      "primary_earnings": 8954.08,
      "additional_earnings": [
        66.66,
        88.88
      ]
    },
    {
      "email": "hovawu@goiv.io",
      "primary_earnings": 446.02,
      "additional_earnings": [
        6478.45,
        7435.89
      ]
    },
    {
      "email": "idmup@te.au",
      "primary_earnings": 2175.84,
      "additional_earnings": [
        7949.13,
        1998.52
      ]
    }
    ...
  ]
  ```
</CodeGroup>

### Result Metadata

The result metadata indicates which columns from the source file were mapped to which columns.

<CodeGroup>
  ```json theme={null}
  {
    "id": null,
    "filename": "earnings.csv",
    "importIdentifier": "earnings",
    "user": {
      "id": "testUser"
    },
    "rowsWithError": [],
    "rawHeaders": [
      "email",
      "salary",
      "gifts",
      "bonuses"
    ],
    "fields": {
      "email": {
        "fileHeaderIndex": 0,
        "fileHeader": "email",
        "isCustom": false,
        "manyToOne": false
      },
      "primary_earnings": {
        "fileHeaderIndex": 1,
        "fileHeader": "salary",
        "isCustom": false,
        "manyToOne": false
      },
      "additional_earnings": {
        "fileHeader": null,
        "fileHeaders": [
          "gifts",
          "bonuses"
        ],
        "fileHeaderIndex": null,
        "fileHeaderIndexes": [
          2,
          3
        ],
        "isCustom": false,
        "manyToOne": true
      }
    },
    "errors": []
  }
  ```
</CodeGroup>

## Hooks

### Row Hook

`manyToOne` fields can have their values changed and their info messages and validations set in [row hooks](/reference/hooks#row-hooks).

<CodeGroup>
  ```javascript JavaScript theme={null}
  dromo.registerRowHook(function (record) {
    if (record.index !== 2) return record;
    record.row.additional_earnings.manyToOne![0].value = 42.0;
    record.row.additional_earnings.manyToOne![1].info = [
      { level: "error", message: "Invalid additional earning" },
    ];
    return record;
  });
  ```

  ```jsx React theme={null}
  <DromoUploader
    ...
    rowHooks={[
      (record) => {
        if (record.index !== 2) return record;
        record.row.additional_earnings.manyToOne![0].value = 42.0;
        record.row.additional_earnings.manyToOne![1].info = [
          { level: "error", message: "Invalid additional earning" },
        ];
        return record;
      }
    ]}
    ...>
    Import Earnings
  </DromoUploader>
  ```
</CodeGroup>

### Column Hooks

For `manyToOne` fields, a [column hook](/reference/hooks#column-hooks) callback registered for a `manyToOne` field will be invoked once for every mapped column.

<CodeGroup>
  ```javascript JavaScript theme={null}
  dromo.registerColumnHook("additional_earnings", (values) => {
    // Cap additional earnings at $5,000
    return values.map((v) => {
      if (v.value > 5000) {
        return {
          ...v,
          value: 5000,
          info: [{ level: "info", message: "capped at $5000" }],
        };
      } else return v;
    });
  });
  ```

  ```jsx React theme={null}
  <DromoUploader
    ...
    columnHooks={[{
      fieldName: "additional_earnings",
      callback: (values) => {
        // Cap additional earnings at $5,000
        return values.map((v) => {
          if (v.value > 5000) {
            return {
              ...v,
              value: 5000,
              info: [{ level: "info", message: "capped at $5000" }],
            };
          } else return v;
        });
      }
    }]}
    ...>
    Import Earnings
  </DromoUploader>
  ```
</CodeGroup>

### Step Hooks

[Step hooks](/reference/hooks#step-hooks) `REVIEW_STEP` and `REVIEW_STEP_POST_HOOKS` can be used to inspect column mapping at run time to see which columns were mapped to `manyToOne` fields.

The full data object supplied as an argument to the step hook will resemble this:

<CodeGroup>
  ```json theme={null}
  {
    "fields": {
      "email": {
        "fileHeaderIndex": 0,
        "fileHeader": "email",
        "isCustom": false,
        "manyToOne": false
      },
      "primary_earnings": {
        "fileHeaderIndex": 1,
        "fileHeader": "salary",
        "isCustom": false,
        "manyToOne": false
      },
      "additional_earnings": {
        "fileHeader": null,
        "fileHeaders": [
          "gifts",
          "bonuses"
        ],
        "fileHeaderIndex": null,
        "fileHeaderIndexes": [
          2,
          3
        ],
        "isCustom": false,
        "manyToOne": true
      }
    },
    "rawHeaders": [
      "email",
      "salary",
      "gifts",
      "bonuses"
    ],
    "headerMapping": {
      "email": "email",
      "salary": "primary_earnings",
      "gifts": "additional_earnings",
      "bonuses": "additional_earnings"
    }
  }
  ```
</CodeGroup>

So in code:

<CodeGroup>
  ```javascript JavaScript theme={null}
  ...
  dromo.registerStepHook("REVIEW_STEP", (_uploader, data) => {
    console.log("manyToOne file headers", data.fields.additional_earnings.fileHeaders);
    // ["gifts", "bonuses"]
    console.log("manyToOne file indexes", data.fields.additional_earnings.fileHeaderIndexes);
    // [2, 3]
  });
  ...
  ```

  ```jsx React theme={null}
  <DromoUploader
    ...
    stepHooks={[
      {
        type: "REVIEW_STEP",
        callback: (_instance, data) => {
          console.log("manyToOne file headers", data.fields.additional_earnings.fileHeaders);
          // ["gifts", "bonuses"]
          console.log("manyToOne file indexes", data.fields.additional_earnings.fileHeaderIndexes);
          // [2, 3]
        }
      }
    ]}
    ...>
    Import Earnings
  </DromoUploader>
  ```
</CodeGroup>


# AI Editing with User Transformations
Source: https://developer.dromo.io/guides/using-transform-data

Enable Transform Data so users can describe, preview, and apply AI-generated bulk data edits from Dromo's review step.

## Overview

Dromo's Transform Data feature allows your users to create bulk transformations from natural language and execute them on the dataset. The feature is available on the Pro plan.

<Check>
  Enable Transform Data with the [`reviewStep.enableUserTransformations` setting](/reference/settings/settings#enableusertransformations).
</Check>

With `enableUserTransformations` enabled, you will see a "Transform Data" button on the Data Review step.

<img alt="Transform data button" />

Click this button to open the Transform Data modal. You will be prompted for what you would like to do to your data.

<img alt="Transform data prompt" />

Transform Data takes a user's request and turns it in to a transformation that can be applied to the data. If the request was successfully able to produce a transformation, the result is previewed to the user so they can optionally accept or reject it.

<img alt="Data Change Preview" />

The feature can edit values and remove rows. It cannot add rows.

<img alt="Remove low value rows" />

## Best Practices

### Include context about inputs

The AI building the transformation function never has access to the import data, so including context about both the input and output is often helpful.

For example, given a column containing dates formatted like "Jul-8-1999" where you wish to convert them to "07/08/1999," you should request "Change the date format from 'Jul-8-1999' to MM-DD-YYYY." A request unlikely to succeed would be "Change the dates to US format" because the AI does not have access to the current format.

<img alt="date-example" />

### Only apply transformations to one row at a time

A transformation only has access to an individual row. If you need to perform an operation that requires knowledge of other rows or information outside of the table, the transformation will not succeed.

<img alt="failed prompt" />

### Keep expectations realistic

Transform data performs best when it is given a simple, well-scoped task. Changing values based on simple criteria, adjusting date and time formats, and removing rows based on simple conditions are all great uses for the transform data feature.

## Privacy

Dromo sends the request to OpenAI along with some information about the schema, but absolutely no user data is transmitted as part of this process.


# Using Field Types
Source: https://developer.dromo.io/guides/using-types

Choose and configure Dromo field types to validate, transform, format, and consistently output imported spreadsheet data.

Dromo's field types define how a field accepts, transforms, validates, and outputs data. They ensure consistent data types across a field (e.g., `number` for numeric values, `string` for text). Field types cover categories like numbers, text, dates, and times.

### Selecting the Best Type

By default, if you don't specify a type for a field, it uses the [`string` type](/reference/fields/field-types#string%E2%80%8B). For example, below, we create a field for collecting email addresses:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const fields = [
    {
      label: 'Email Address',
      key: 'emailAddress'
    }
  ];

  const settings = {
    importIdentifier: 'Field types example'
  };

  const user = {
    id: '12345'
  };

  const dromo = new DromoUploader('FRONTEND_API_KEY', fields, settings, user);
  ```

  ```jsx React theme={null}
  <DromoUploader
    licenseKey={'FRONTEND_API_KEY'}
    user={{ id: '12345' }}
    fields={[
      {
        label: 'Email Address',
        key: 'emailAddress'
      }
    ]}
    settings={{
      importIdentifier: 'Field types example'
    }}>
    Import data
  </DromoUploader>
  ```
</CodeGroup>

Because we didn't specify a *type* in the above "Email Address" field, it uses the default `string` type.

However, if we update the "Email address" field to use the [`email` type](/reference/fields/field-types#email%E2%80%8B), that field gains the advantage of Dromo's built-in email address validation:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const fields = [
    {
      label: 'Email',
      key: 'email',
      type: 'email'
    }
  ];
  ```

  ```jsx React theme={null}
  <DromoUploader
    licenseKey={'FRONTEND_API_KEY'}
    user={{ id: '12345' }}
    fields={[
      {
        label: 'Email Address',
        key: 'emailAddress',
        type: 'email'
      }
    ]}>
  ```
</CodeGroup>

<Check>
  Selecting the ideal type for each field is essential to honing your Dromo workflow. [See all field types.](/reference/fields/field-types)
</Check>

### Configuring Field Types

Certain field types offer different configuration options, enabling you to customize how data is validated, displayed to the user, and output.

For example, we want a field that tracks prices in USD. We can add a "Price" field using the ["usd" preset](/reference/fields/field-types#number%E2%80%8B):

<CodeGroup>
  ```javascript theme={null}
  const fields = [
    {
      label: 'Price',
      key: 'price',
      type: ['number', { preset: 'usd' }]
    }
  ];
  ```
</CodeGroup>

 

<Accordion title="💡 Click to learn more about Presets">
  Dromo provides many preset options for formatting standard `number`, `date`, `time`, and `datetime` formats. Presets work by automatically filling preset values into the configuration options for a field type.

  You can manually configure the options for a number type:

  <CodeGroup>
    ```javascript theme={null}
    type: [
      "number",
      {
        round: <integer>,
        displayFormat: <format object>,
        outputFormat: <format object>
      }
    ]
    ```
  </CodeGroup>

  Or you can use a preset, which configures options for you. Under the hood, the "usd" preset inputs the following options:

  <CodeGroup>
    ```javascript theme={null}
    {
      round: 2,
      displayFormat: {
        mantissa: 2,
        thousandSeparated: true,
        output: "currency",
        average: false,
        spaceSeparatedCurrency: true,
        currencyPosition: "prefix",
        currencySymbol: "$"
      }
    }
    ```
  </CodeGroup>

  To learn more about configuring your types without presets, see [customizing numbers](/reference/fields/field-types#number%E2%80%8B) or [customizing dates, times, and datetimes](/reference/fields/field-types#datetime%E2%80%8B).
</Accordion>

The "usd" preset ensures that this `number` field parses, validates, displays, and outputs values in dollars. Therefore, if a user attempts to insert a value that *can't* be parsed into USD (i.e., another currency), Dromo throws a validation error:

<img alt="Validation error for inputting invalid currency" />

<Note>
  For numbers (and a few other field types) the display format is not what the field outputs. If you want to change how a field is output, the `outputFormat` configuration option enables you to do so. For example, if you want to convert a number into USD, you can use the ["usd" preset](/reference/fields/field-types#number%E2%80%8B) alongside an `outputFormat` option.

  <Expandable title="See code example">
    <CodeGroup>
      ```javascript theme={null}
      {
        label: 'Price',
        key: 'price',
        type: [
          'number',
          {
            preset: 'usd',
            outputFormat: {
              mantissa: 2,
              thousandSeparated: true,
              output: 'currency',
              average: false,
              spaceSeparatedCurrency: true,
              currencyPosition: 'prefix',
              currencySymbol: '$'
            }
          }
        ]
      }
      ```
    </CodeGroup>
  </Expandable>
</Note>


# Validating with External Data
Source: https://developer.dromo.io/guides/validate-external-data

Use asynchronous Dromo row hooks to validate imported values against an external API or another remote data source.

The following example demonstrates how to use row hooks to validate data against an external API.

<Info>
  For more information on row hooks, see the [Row Hooks](/reference/hooks#row-hooks) documentation.
</Info>

Although it's not required to use `async`/`await` with hooks, we recommend you use it with an external API call.

<CodeGroup>
  ```javascript JavaScript theme={null}
  export const fields = [
    {
      label: 'Email',
      key: 'email'
    }
  ];

  let hasFetchedData = false;
  let serverResults;

  dromo.registerRowHook(async function (record) {
    const newRecord = record;
    if (!hasFetchedData) {
      await fetch('https://my-json-server.typicode.com/dromoio/docs-email-api/leads', {
        method: 'GET'
      })
        .then((response) => response.json())
        .then(function (json) {
          serverResults = json.map((record) => {
            return record['email'];
          });
          hasFetchedData = true;
        });
    }
    if (serverResults.includes(newRecord.row['email'].value)) {
      newRecord.row['email'].info = [
        {
          message: 'Duplicate record. This user is already in the database.',
          level: 'error'
        }
      ];
    }
    return newRecord;
  });
  ```

  ```jsx React theme={null}
  let hasFetchedData = false;
  let serverResults;

  <DromoUploader
    licenseKey={"FRONTEND_API_KEY"}
    user={{ id: "12345" }}
    fields={[
      {
        label: "Email",
        key: "email",
      },
    ]}
    settings={{
      importIdentifier: "Row Hooks Example",
    }}
    rowHooks={[
      async (record) => {
        const newRecord = record;
        if (!hasFetchedData) {
          await fetch('https://my-json-server.typicode.com/dromoio/docs-email-api/leads', {
            method: 'GET'
          })
            .then((response) => response.json())
            .then(function (json) {
              serverResults = json.map((record) => {
                return record['email'];
              });
              hasFetchedData = true;
            });
        }
        if (serverResults.includes(newRecord.row['email'].value)) {
          newRecord.row['email'].info = [
            {
              message: 'Duplicate record. This user is already in the database.',
              level: 'error'
            }
          ];
        }
        return newRecord;
      }
    ]}>
    Import Contacts
  </DromoUploader>
  ```
</CodeGroup>


# Validating Multiple Rows at Once
Source: https://developer.dromo.io/guides/validate-multiple-rows

Validate requirements across an entire Dromo import and block completion with the beforeFinish callback and table-level errors.

Row hooks are great for validating a single row, but what if you want to validate multiple rows at once? For example, you want to make sure that the user has imported at least 20 rows. In this case, you can use the beforeFinish callback.

This function will run every time the user clicks the "Finish" button. If it returns an object with the `cancel` property set to `true`, the user will be reverted to the data review screen, and the `message` will be displayed as a table-level error.

<Info>
  For more information on the beforeFinish callback, see the [Reference](/reference/results#the-beforefinish-callback) documentation.
</Info>

<CodeGroup>
  ```javascript JavaScript theme={null}
  dromo.beforeFinish(function (data, metadata, instance) {
    if (data.length < 20) {
      return { cancel: true, message: "You must import at least 20 rows" }
    }
  });
  ```

  ```jsx React theme={null}
  <DromoUploader
    ...
    beforeFinish={(data, metadata, instance) => {
      if (data.length < 20) {
        return { cancel: true, message: "You must import at least 20 rows" }
      }
    }}>
    Launch Dromo
  </DromoUploader>
  ```
</CodeGroup>


# Zapier Integration
Source: https://developer.dromo.io/guides/zapier-integration

Connect Dromo imports to Zapier workflows using result-file and imported-row triggers for notifications, storage, and CRM automation.

Dromo's Zapier integration allows you to connect your imports with thousands of web services with a few mouse clicks. You can enable email or Slack notifications for new imports, copy import results to Google Drive, or automatically add imported records to your CRM, to name a few."

## How to Use Zapier with Dromo

You can create [Zaps](https://help.zapier.com/hc/en-us/articles/8496309697421-Create-Zaps) to perform actions based on Dromo triggers.

Dromo offers two event triggers: "New Results File" and "New Data Row Imported".

"New Results File" will trigger every time a file is imported for a selected schema. This trigger is useful when you want to notify a service when an import is completed, for example to send a Slack message or store the results file.

"New Data Row Imported" will trigger for every individual row in an import. This trigger is useful when adding data directly to an existing database like a spreadsheet or CRM.

## Dromo Zap Templates

You can manually [create a new Zap](https://zapier.com/resources/guides/quick-start/create-zap) or use one of Dromo's pre-configured Zap templates. These are available from the integrations menu in the Schema Editor.

<img alt="Schema Integrations Image" />

If you manually create a Zap, you can add a Dromo trigger by searching for the "Dromo" app in the menu. Once you've selected the Dromo app, you can choose the event to subscribe to.

## Step by Step Example: Dromo Slack Notifications

In this example, we will configure Zapier to send us a Slack message each time a new import is completed.

To follow along, you will need a [Dromo account](https://dashboard.dromo.io/), a [Zapier account](https://zapier.com), and a [Slack account](https://slack.com/) with permissions to add new apps.

<Info>
  Zapier triggers only operate in Production Mode and require a paid Dromo subscription or active free trial.
</Info>

The Dromo Zapier triggers are scoped to a specific saved schema. If you don't have one already, you will need to [create a schema](/guides/schema-builder) using the Schema Studio to try out your Zap with. It is also helpful to have at least one completed import using your schema so you can test that your Zap will work as expected.

<img alt="Schema Studio" />

Open the Schema Integrations Menu and click "Use this Zap" under the "Send Slack Messages for New Dromo Imports" template.

<img alt="Schema Integrations Image" />

A new draft Zap will open in Zapier.

Expand the Dromo trigger, where you can configure how your Zap will run. First, you will need to connect your Dromo account. Then, select the schema you want notifications for in the "Trigger" section.

<img alt="Dromo Trigger" />

Under the "Test" section, click "Test Trigger". Zapier will retrieve a recent import from your schema. Click "Continue with selected record".

<img alt="Sample File" />

Next, we will configure the Slack action. For this example, we'll configure Zapier to send ourselves a DM, so we'll choose the "Send Direct Message" event. Click continue and connect your Slack account.

Then, set "To Username" to yourself. For the message text, we'll configure the Zap to send us a DM with the result filename and a link to download the results.

<img alt="Slack config" />

Test the action, you should receive a Slack message with the ID as text and a working link to download the file!

<img alt="Slack message" />

Click publish, and your Zap is now live! Try importing some files with Dromo in production mode. You should see a new Slack message for each import.


# Custom File Parsers
Source: https://developer.dromo.io/reference/custom-file-parsers

Custom file parsers allow you to parse any file format by giving you control of the parsing logic. Dromo natively supports common CSV and Excel formats, but with custom file parsers you can enable your users to import PDF, XML, HTML, or any other file type when you implement the file parsing.

<Check>
  For a PDF importing example, see our [guide on importing a PDF using the PDFTables API](/guides/importing-a-pdf).
</Check>

At a high level, custom parsers are a function you define which is called with the file contents and returns the parsed file as arrays of strings.

You define which file extensions your parser should be used for, and if a user uploads a matching file, your file parsing function will be called instead of Dromo's native file parsers.

Custom parsers are invoked immediately when the user selects a file. Additionally, if a user goes to the Data Review step and then backtracks to a previous step, the file is re-parsed, so the custom parser will be called again to get a fresh, unedited copy of the file data.

Custom parser functions receive two arguments, the file buffer and the filename.

<ResponseField name="buffer" type="ArrayBuffer">
  An ArrayBuffer containing the raw binary content of the uploaded file
</ResponseField>

<ResponseField name="fileName" type="string">
  The filename of the file selected by the user
</ResponseField>

File parsers must return a 2-dimensional array of strings.

File parsers may return the value async, wrapped in a promise.

<ResponseField name="data" type="string[][]">
  Parsed data to be imported. The data must be an array with a length of at least 1, with each row being an array of strings. Each row must be the same length.
</ResponseField>

<Accordion title="Custom File Parsing Example">
  In this example we're parsing a fixed width file with stock prices. Each stock symbol is 4 characters and the price is the following 6 characters.

  ```
  AAPL023367GOOG016968TSLA025952
  ```

  <CodeGroup>
    ```javascript JavaScript theme={null}
    const fields = [
      {
        label: "Stock Symbol",
        key: "stock_symbol",
      },
      {
        label: "Stock Price",
        key: "stock_price",
      },
    ];

    const settings = {
      importIdentifier: "Custom Parser Example",
    };

    const user = {
      id: "12345",
    };

    const dromo = new DromoUploader("FRONTEND_API_KEY", fields, settings, user);

    dromo.registerFileParser({
      extensions: ["txt"],
      parseFile: async (buffer, fileName) => {
        const stockData = new TextDecoder().decode(buffer);
        const headers = ["Stock Symbol", "Stock Price"];
        const data: string[][] = stockData
          .split("\n")
          .map((line) => [line.slice(0, 4), line.slice(4, -1)]);
        return [headers, ...data];
      },
    });
    ```

    ```jsx React theme={null}
    <DromoUploader
      licenseKey={"FRONTEND_API_KEY"}
      user={{ id: "12345" }}
      fields={[
        {
          label: "Stock Symbol",
          key: "stock_symbol",
        },
        {
          label: "Stock Price",
          key: "stock_price",
        },
      ]}
      settings={{
        importIdentifier: "Custom Parser Example",
      }}
      fileParsers={[
        {
          extensions: ["txt"],
          parseFile: (buffer, _fileName) => {
            const stockData = new TextDecoder().decode(buffer);
            const headers = ["Stock Symbol", "Stock Price"];
            const data: string[][] = stockData
              .split("\n")
              .map((line) => [line.slice(0, 4), line.slice(4, -1)]);
            return [headers, ...data];
          },
        },
      ]}>
      Import Users
    </DromoUploader>
    ```
  </CodeGroup>
</Accordion>


# Custom Steps
Source: https://developer.dromo.io/reference/custom-steps

Reference for the custom step configuration and the postMessage API for injecting custom UI into the Dromo import flow.

Custom steps allow you to insert your own UI between any two built-in steps in the Dromo import flow. See the [Custom Steps guide](/guides/custom-steps) for a walkthrough and examples.

## Configuration

<ResponseField name="id" type="string">
  Unique identifier for this step. Used as a fallback label in the stepper progress bar if `label` is omitted.
</ResponseField>

<ResponseField name="insertAfter" type="&#x22;HEADER_SELECT&#x22; | &#x22;COLUMN_MATCH&#x22; | &#x22;SELECT_MATCH&#x22;">
  Which built-in step this custom step is inserted after.

  | Value             | Inserted after                            |
  | ----------------- | ----------------------------------------- |
  | `"HEADER_SELECT"` | Header row detection                      |
  | `"COLUMN_MATCH"`  | Column mapping                            |
  | `"SELECT_MATCH"`  | Select field matching, just before Review |
</ResponseField>

<ResponseField name="label" type="string">
  Text shown in the stepper progress bar. Defaults to `id` if omitted.
</ResponseField>

<ResponseField name="url" type="string">
  URL of the page to render inside an `<iframe>` within Dromo's modal.
</ResponseField>

<ResponseField name="onMessage" type="(uploader, payload: unknown) => void | Promise<void>">
  Called when the iframe posts `{ type: "DROMO_MESSAGE", payload }`. The `uploader` argument exposes the same mutation methods available in [step hooks](/reference/hooks#the-dromo-uploader-instance).

  All uploader methods return `Promise<void>` — await them when order matters.
</ResponseField>

***

## Registering custom steps

### JavaScript / TypeScript

```typescript theme={null}
dromo.registerCustomStep(config): void
```

Call `registerCustomStep` on the `DromoUploader` instance before `open()`. Multiple calls at the same `insertAfter` position are presented in registration order.

### React

Pass an array of config objects to the `customSteps` prop:

```tsx theme={null}
<DromoUploader
  customSteps={[
    {
      id: "terms",
      insertAfter: "SELECT_MATCH",
      label: "Terms & Conditions",
      url: "https://your-app.com/terms-step.html",
    },
  ]}
  {/* other required props */}
>
  Import
</DromoUploader>
```

### Angular

Bind a config array to the `[customSteps]` input on `lib-dromo-uploader`:

```typescript theme={null}
customSteps = [
  {
    id: "terms",
    insertAfter: "SELECT_MATCH",
    label: "Terms & Conditions",
    url: "https://your-app.com/terms-step.html",
  },
];
```

```html theme={null}
<lib-dromo-uploader [customSteps]="customSteps" ...>
  Import with Dromo!
</lib-dromo-uploader>
```

***

## postMessage API

Your iframe page communicates with Dromo by posting messages to `window.parent`.

### Navigation messages

<ResponseField name="{ type: &#x22;DROMO_NEXT&#x22; }">
  Advance to the next step.
</ResponseField>

<ResponseField name="{ type: &#x22;DROMO_BACK&#x22; }">
  Return to the previous step.
</ResponseField>

<ResponseField name="{ type: &#x22;DROMO_MESSAGE&#x22;, payload: any }">
  Trigger the `onMessage` callback with the uploader instance and `payload`. Does not automatically navigate — post `DROMO_NEXT` separately when ready.
</ResponseField>

***

## Uploader methods in `onMessage`

The `uploader` instance passed to `onMessage` exposes the following methods. These are the same mutation methods available in [step hooks](/reference/hooks#the-dromo-uploader-instance).

<ResponseField name="addField(field, position?) => Promise<void>">
  Dynamically add a field to the import schema. See [`instance.addField`](/reference/hooks#instanceaddfield).
</ResponseField>

<ResponseField name="removeField(key) => Promise<void>">
  Remove a field from the schema. See [`instance.removeField`](/reference/hooks#instanceremovefield).
</ResponseField>

<ResponseField name="addRows(rows) => Promise<string[]>">
  Inject rows into the dataset. Returns the IDs of the added rows. See [`instance.addRows`](/reference/hooks#instanceaddrows).
</ResponseField>

<ResponseField name="removeRows(ids) => Promise<void>">
  Remove rows from the dataset by ID. See [`instance.removeRows`](/reference/hooks#instanceremoverows).
</ResponseField>

<ResponseField name="setUser(user) => Promise<void>">
  Update the current user associated with the import.
</ResponseField>


# DromoUploader SDK Reference
Source: https://developer.dromo.io/reference/dromo-uploader-sdk

Detailed reference for the DromoUploader JavaScript SDK instance, its constructor, and configuration methods.

## DromoUploader Instance

To begin an import, you first need to create an instance of the `DromoUploader`:

```javascript theme={null}
const dromo = new DromoUploader(licenseKey, fields, settings, user);
```

### Constructor

The `DromoUploader` constructor takes 4 parameters:

<ResponseField name="licenseKey" type="string">
  Your Dromo front-end license key, which can be found in [the Dromo dashboard](https://dashboard.dromo.io/).
</ResponseField>

<ResponseField name="fields" type="Field[]" href="/fields">
  An array of fields which comprise your import schema.
</ResponseField>

<ResponseField name="settings" type="Settings" href="/settings">
  Settings to change the behavior of the Dromo importer.
</ResponseField>

<ResponseField name="user" type="User" href="/users">
  Metadata about the end user to associate with the import.
</ResponseField>

### Configuration Methods

Once you have an instance, you can register callbacks and configure its behavior using the following methods. You can register callbacks for [running hooks](/reference/hooks) and [receiving results](/reference/results).

<ResponseField name="registerColumnHook(fieldKey: string, callback: ColumnHookFn) => void">
  Used to register a [column hook](/reference/hooks#column-hooks) callback on the field with the given field key.
</ResponseField>

<ResponseField name="registerRowHook(callback: RowHookFn) => void">
  Used to register a standard [row hook](/reference/hooks#standard-row-hooks) callback.
</ResponseField>

<ResponseField name="registerBulkRowHook(callback: BulkRowHookFn) => void">
  Used to register a [bulk row hook](/reference/hooks#bulk-row-hooks) callback.
</ResponseField>

<ResponseField name="registerBatchRowHook(callback: BatchRowHookFn) => void">
  Registers an initialization-only [batch row hook](/reference/hooks#batch-row-hooks). The callback receives one bounded slice of rows and its one-based batch number. Configure the maximum slice size with [`batchRowHookBatchSize`](/reference/settings/settings#batchrowhookbatchsize).
</ResponseField>

<ResponseField name="registerStepHook(stepHookType: &#x22;UPLOAD_STEP&#x22; | &#x22;REVIEW_STEP&#x22; | &#x22;REVIEW_STEP_POST_HOOKS&#x22; | &#x22;REVIEW_STEP_PRE_SUBMIT&#x22;, callback: StepHookFn) => void">
  Used to register a [step hook](/reference/hooks#column-hooks) callback of the given type.
</ResponseField>

<ResponseField name="registerFileParser(parser: { extensions: string[], parseFile: ParseFileFn }) => void">
  Registers a [custom file parser](/reference/custom-file-parsers) for one or more file extensions.
</ResponseField>

<ResponseField name="registerRowDeleteHook(callback: RowDeleteHookFn) => void">
  Used to register a [row delete hook](/reference/hooks#row-delete-hooks) callback.
</ResponseField>

<ResponseField name="registerCustomStep(config) => void">
  Registers a [custom step](/reference/custom-steps) to be inserted into the import flow. Call before `open()`. Multiple steps at the same `insertAfter` position are presented in registration order.
</ResponseField>

<ResponseField name="beforeFinish(callback: BeforeFinishCallbackFn) => void">
  Used to register a [beforeFinish callback](/reference/results#the-beforefinish-callback).
</ResponseField>

<ResponseField name="onResults(callback: OnResultsCallbackFn) => void">
  Used to register an [onResults callback](/reference/results#the-onresults-callback).
</ResponseField>

<ResponseField name="onCancel() => void">
  Called when the user exits the Dromo Uploader without completing the import.
</ResponseField>

<ResponseField name="onUserEvent(callback: (event: IUserEvent) => void) => void">
  Registers a callback that fires whenever the user interacts with a tracked UI control inside the importer (e.g. button clicks). Useful for analytics, audit logging, and conditional UI reactions. Only one callback can be registered per instance — calling this a second time replaces the first. Not invoked in headless mode. See the [onUserEvent reference](/reference/on-user-event) for event types, payload shapes, and the full button name reference.
</ResponseField>

**Example of registering callbacks:**

```javascript theme={null}
dromo.registerColumnHook('zipCode', (colData) => {  
  return colData.map((zipCode) => {
    return { ...zipCode, value: zipCode.value.padStart(5, '0') };  
  });
});
dromo.onResults((data, metadata) => {  
  console.log(data);
});
```

### Starting the Import

With Dromo fully configured, call `open()` on the uploader instance to start the import process.

<ResponseField name="open() => void">
  Opens the Dromo Uploader interface to begin the import process.
</ResponseField>

```javascript theme={null}
dromo.open();
```


# Field Types
Source: https://developer.dromo.io/reference/fields/field-types

Dromo supports a variety of field types, each with their own unique properties and behaviors. This section describes the different types of fields available and their usage.

## Usage

<Note>
  The field type is set by passing a `type` parameter in the field object. This can be a string referring to one of the field types, explained below. Alternatively, some field types can take additional options controlling their behavior and format. In this case, you can provide the `type` parameter with a 2-element array, where the first element is the type name and the second element is any options that field type takes.
</Note>

Here is an example of a few different valid field type configurations:

```json theme={null}
{
  "fields": [
    {
      "label": "Email address",
      "key": "email",
      "type": "email"
    },
    {
      "label": "Subscription fee",
      "key": "subscriptionFee",
      "type": ["number", "eur"]
    },
    {
      "label": "Subscribed since",
      "key": "subscriptionStart",
      "type": ["date", { "locale": "de-DE" }]
    }
  ]
}
```

## Types

### String[​](#string "Direct link to String")

<div>
  > `type: "string"`

  By default (if no field type is specified), all fields in Dromo have the `string` type. This is the simplest field type, and does not do any validation or transformation of the data – the data is output as a string exactly as it was entered.

  The string type does not take any options.
</div>

### Number[​](#number "Direct link to Number")

<div>
  > `type: "number"`
  > `type: ["number", <preset name string>]`

  ```json theme={null}
  {
    "type": ["number", {
      "preset": "<preset name string>",
      "round": "<integer>",
      "displayFormat": "<format object>",
      "outputFormat": "<format object>",
      "min": "<number>",
      "max": "<number>"
    }]
  }
  ```

  #### For all kinds of numeric values[​](#for-all-kinds-of-numeric-values "Direct link to For all kinds of numeric values")

  The field type parses many common number formats and displays the number in a user-friendly format.

  If the input data is unable to be parsed as a number, a validation error is added to the cell.

  Unless an output format is specified, the number is output to the result JSON as a number.

  #### Presets[​](#presets "Direct link to Presets")

  The number type has several presets available to handle the most common number formats. You can use a preset by passing the name of the preset with the field type, such as `type: ["number", "usd"]`.

  Here are all of the presets that Dromo provides:

  | Preset Name                                      | Source value     | Display value          |
  | ------------------------------------------------ | ---------------- | ---------------------- |
  | `default`(used if no display settings are given) | 1234567.1234567  | 1,234,567.1234567      |
  | `percent`                                        | 0.12340.56       | 12.34%56%              |
  | `plain`                                          | 1234567.123      | 1234567.123            |
  | `usd`                                            | 1234.567-3456.78 | $1,234.57-$3,456.78    |
  | `usd_accounting`                                 | 1234.567-3456.78 | $ 1,234.57$ (3,456.78) |
  | `eur`                                            | 1234.567-3456.78 | 1,234.57 €-3,456.78 €  |
  | `gbp`                                            | 1234.567-3456.78 | £ 1,234.57- £3,456.78  |
  | `decimal_0` *or*`integer`                        | 234.567          | 235                    |
  | `decimal_1`                                      | 234.567123       | 234.6123.0             |
  | `decimal_2`                                      | 234.567123       | 234.57123.00           |
  | `decimal_3`                                      | 234.5678123      | 234.568123.000         |
  | `decimal_4`                                      | 234.56789123     | 234.5679123.0000       |
  | `percent_0`                                      | 0.1256           | 13%                    |
  | `percent_1`                                      | 0.12560.34       | 12.6%34.0%             |
  | `percent_2`                                      | 0.125670.34      | 12.57%34.00%           |
  | `percent_3`                                      | 0.1234560.34     | 12.346%34.000%         |
  | `percent_4`                                      | 0.123456780.34   | 12.3457%34.0000%       |

  #### Custom configuration[​](#custom-configuration "Direct link to Custom configuration")

  If none of the presets meet your needs, you can define your own rounding, display format and output format behavior.

  The `round` setting takes an integer which defines how many digits after the decimal point the value will be rounded to. Negative values will round to digits before the decimal.

  The `displayFormat` and `outputFormat` settings can be used for creating your own custom formats. The `displayFormat` is used for displaying the number to the user on the review screen. The `outputFormat`, if set, will determine how the number is output in the result JSON, as a string.

  For more information on using `displayFormat` and `outputFormat`, see the [number formatting section](/reference/fields/field-types#number%E2%80%8B).

  #### Validating minimum and maximum[​](#validating-minimum-and-maximum "Direct link to Validating minimum and maximum")

  You can validate that the number falls within a given range using the `min` and `max` settings.

  The `min` and `max` settings are optional and you can specify none, one or both. If a given number falls below the `min` or above the `max`, a validation error will be added to the field.
</div>

### Date[​](#date "Direct link to Date")

<div>
  > `type: "date"`

  ```json theme={null}
  {
    "type": ["date", {
      "locale": "<locale string>",
      "displayFormat": "<format string>",
      "outputFormat": "<format string>",
      "autofix": "<boolean>"
    }]
  }
  ```

  #### For handling date values (with no time)[​](#for-handling-date-values-with-no-time "Direct link to For handling date values (with no time)")

  The date type parses dates in several formats including:

  * **ISO-8601** (e.g., `2024-03-27`, `2024-03-27T10:30`)
  * **RFC-2822** (e.g., `27 Mar 2024`)
  * **Common date formats** (e.g., `03/27/2024`, `27/03/2024`, `27.03.2024`)
  * **Two-digit years** (e.g., `03/27/24` → `2024-03-27`)
  * **Unpadded dates** (e.g., `3/7/2024` → `2024-03-07`)
  * **Various separator styles** (dots, slashes, dashes)

    If a time is also given, it is allowed but ignored. If an input date cannot be parsed, a validation error will be added to the cell.

    When using a date field, Dromo's enhanced date detection will analyze the imported data and suggest appropriate formatting fixes during the Bulk Fix step. The system uses heuristic-based detection to identify various date patterns and recommend the most likely correct interpretation.

    <img alt="Suggesting date fixes during the bulk edit step" />

  #### Automatic Date Fixing[​](#automatic-date-fixing "Direct link to Automatic Date Fixing")

  You can control whether date format fixes are applied automatically or require user approval using the `autofix` parameter:

  * **`autofix: true`** (default): Date format fixes are applied automatically without requiring user interaction. If all date fields in your schema have autofix enabled, the Bulk Fix step will be skipped entirely.

  * **`autofix: false`**: Date format fixes are suggested to the user during the Bulk Fix step, requiring manual approval before being applied.

    The enhanced date detection system can automatically handle:

  * **Ambiguous date formats** (e.g., distinguishing between MM/DD/YYYY and DD/MM/YYYY based on data patterns)

  * **Mixed formats within the same column** (e.g., some rows using `03/27/2024` and others using `27-Mar-2024`)

  * **Two-digit year conversion** with intelligent century detection

  * **Locale-aware parsing** that respects the field's configured locale for format interpretation

    This is particularly useful when you want to ensure users review date formatting changes, or when you want to streamline the import process for trusted data sources.

    <Note>
      The `autofix` parameter is currently only available for date fields. Datetime and time fields do not support this feature.
    </Note>

    By default, dates are output to the results in ISO-8601 format (e.g. `"2022-03-27"`).

    You can specify a locale for the date field, which must be a valid [BCP 47 locale string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locale_identification_and_negotiation). If not provided, the locale defaults to `"en-US"`.

    The locale will change how the date is displayed to the user with the display format. The locale will also affect the output format if a custom format is used.

    The default display format is the standard short form in the configured locale, for example:

    | Locale | Default format example |
    | ------ | ---------------------- |
    | en-US  | 3/27/2022              |
    | ar-SY  | ٢٧/٣/٢٠٢٢              |
    | de-DE  | 27.3.2022              |
    | pt-BR  | 27/03/2022             |
    | th-TH  | 27/3/2565              |
    | zh-CN  | 2022/3/27              |

    You can define your own display and/or output formats with a format string. For more information, see the [datetime formatting section](/reference/fields/field-types#datetime%E2%80%8B).
</div>

### Datetime[​](#datetime "Direct link to Datetime")

<div>
  > `type: "datetime"`

  ```json theme={null}
  {
    "type": ["datetime", {
      "locale": "<locale string>",
      "displayFormat": "<format string>",
      "outputFormat": "<format string>",
      "withSeconds": "<boolean>"
    }]
  }
  ```

  #### For handling a date and time together in one field[​](#for-handling-a-date-and-time-together-in-one-field "Direct link to For handling a date and time together in one field")

  The datetime type parses datetimes in several formats: ISO-8601, RFC-2822, and the configured display format in the configured locale.

  By default, dates are output to the results in ISO-8601 format, with no time zone offset (e.g. `"2022-03-27T15:20"`).

  By default, seconds are neither displayed nor output. You can change this by providing `withSeconds: true` in the field settings.

  You can specify a locale for the datetime field, which must be a valid [BCP 47 locale string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locale_identification_and_negotiation). If not provided, the locale defaults to `"en-US"`.

  The locale will change how the datetime is displayed to the user with the display format. The locale will also affect the output format if a custom format is used.

  The default display format is the standard short form in the configured locale, for example:

  | Locale | Default format example |
  | ------ | ---------------------- |
  | en-US  | 3/27/2022, 3:20 PM     |
  | ar-SY  | ٢٧/٣/٢٠٢٢, ٣:٢٠ م      |
  | de-DE  | 27.3.2022, 15:20       |
  | pt-BR  | 27/03/2022 15:20       |
  | th-TH  | 27/3/2565 15:20        |
  | zh-CN  | 2022/3/27 下午3:20       |

  You can define your own display and/or output formats with a format string. For more information, see the [datetime formatting section](/reference/fields/field-types#datetime%E2%80%8B).
</div>

### Time[​](#time "Direct link to Time")

<div>
  > `type: "time"`

  ```json theme={null}
  {
    "type": ["time", {
      "locale": "<locale string>",
      "displayFormat": "<format string>",
      "outputFormat": "<format string>",
      "withSeconds": "<boolean>"
    }]
  }
  ```

  #### For handling a time-of-day independent of date (i.e., a clock time)[​](#for-handling-a-time-of-day-independent-of-date-ie-a-clock-time "Direct link to For handling a time-of-day independent of date (i.e., a clock time)")

  The time type parses datetimes in several formats: ISO-8601, RFC-2822, and the configured display format in the configured locale.

  By default, times are output to the results in ISO-8601 format (e.g. `"15:20"`).

  By default, seconds are neither displayed nor output. You can change this by providing `withSeconds: true` in the field settings.

  You can specify a locale for the datetime field, which must be a valid [BCP 47 locale string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locale_identification_and_negotiation). If not provided, the locale defaults to `"en-US"`.

  The locale will change how the time is displayed to the user with the display format. The locale will also affect the output format if a custom format is used.

  The default display format is the standard time format in the specified locale, for example:

  | Locale | Default format example |
  | ------ | ---------------------- |
  | en-US  | 3:20 PM                |
  | ar-SY  | ٣:٢٠ م                 |
  | de-DE  | 15:20                  |
  | zh-CN  | 下午3:20                 |

  You can define your own display and/or output formats with a format string. For more information, see the [datetime formatting section](/reference/fields/field-types#datetime%E2%80%8B).
</div>

### Select[​](#select "Direct link to Select")

<div>
  > ```json theme={null}
  > {
  >   "type": "select",
  >   "selectOptions": [
  >     {
  >       "label": "string",
  >       "value": "string",
  >       "alternateMatches": ["string"],
  >       "exactMatchOnly": true
  >     }
  >   ]
  > }
  > ```
  >
  > or `type: ["select", { "allowCustom": true }]`

  Select fields let users choose from predefined options. You must provide an array of valid `selectOptions`, where the `label` is shown in the UI; the `value` is saved in the output.

  Select fields are treated differently during the import process. Expand the section below to learn more.

  <Expandable title="more about how select fields work">
    After the column matching step, the user will be prompted to match the values in their file to the given select options.

    <img alt="Select option matching" />

    On the review screen, the field will show as a dropdown menu that the user can pick an option from.

    <img alt="Select dropdown on the review screen" />

    A validation error will be shown if a value was not matched and does not equal one of the option labels.
  </Expandable>

  <Info>
    `selectOptions` can be overridden for individual cells using a row hook. See the [Row Hooks](/reference/hooks#row-hooks) documentation for details.
  </Info>

  Each select option can optionally include `alternateMatche`s\`, an array of strings. If an input value matches any of these, it will be mapped to that option's value.

  <Note>
    For a given select field, the labels, values, and alternate matches should be unique across all options. Each of these parameters is used to map imported data to select options, so conflicts will occur if multiple select options share the same matches.
  </Note>

  <Expandable title="more about allowCustom and exactMatchOnly">
    <ResponseField name="allowCustom" type="boolean">
      If set to true, select fields will allow the user to enter their own value. With `allowCustom` set to `true`, the user can either choose from the valid select options, or enter their own value. This treats the select options as autocomplete suggestions. Any value is considered valid, although you can add additional validations like normal.
    </ResponseField>

    <ResponseField name="exactMatchOnly" type="boolean">
      By default, Dromo will suggest matches to the user with fuzzy matching, and, if you have backend sync enabled, AI matching. If you would like to disable fuzzy and AI matching, and only suggest exact matches to the user, you can pass the setting `exactMatchOnly: true` with the field settings. Dromo will check the label, value, and alternateMatches for an exact match.
    </ResponseField>

    For example, this is how you would enable both custom values and exact matches:

    ```json theme={null}
    {
      "type": ["select", { "allowCustom": true, "exactMatchOnly": true }],
      "selectOptions": [
        {
          "label": "string",
          "value": "string",
          "alternateMatches": ["string"]
        }
      ]
    }
    ```
  </Expandable>
</div>

### Multi-Select[​](#multi-select "Direct link to Multi-Select")

<div>
  > ```json theme={null}
  > {
  >   "type": "multi-select",
  >   "selectOptions": [
  >     {
  >       "label": "string",
  >       "value": "string",
  >       "alternateMatches": ["string"]
  >     }
  >   ]
  > }
  > ```
  >
  > or
  >
  > ```json theme={null}
  > {
  >   "type": ["multi-select", {
  >     "delimiter": ",",
  >     "trimValues": true
  >   }],
  >   "selectOptions": [],
  >   "manyToOne": true
  > }
  > ```

  #### For fields that allow selecting multiple values from predefined options[​](#for-fields-that-allow-selecting-multiple-values-from-predefined-options "Direct link to For fields that allow selecting multiple values from predefined options")

  Multi-select fields let users choose multiple values from predefined options. You must provide an array of valid `selectOptions`, where the `label` is shown in the UI; the `value` is saved in the output. The field outputs as an array of strings (`string[]`) containing the selected option values.

  Multi-select fields are treated differently during the import process. Expand the section below to learn more.

  <Expandable title="more about how multi-select fields work">
    After the column matching step, the user will be prompted to match the values in their file to the given select options (similar to select fields).

    <img alt="Multi Select option matching" />

    On the review screen, the field will show as a multi-select dropdown or chip interface that the user can pick multiple options from.

    A validation error will be shown if a value was not matched and does not equal one of the option labels.
  </Expandable>

  <Info>
    `selectOptions` can be overridden for individual cells using a row hook. See the [Row Hooks](/reference/hooks#row-hooks) documentation for details.
  </Info>

  Each select option can optionally include `alternateMatches`, an array of strings. If an input value matches any of these, it will be mapped to that option's value.

  <Note>
    For a given multi-select field, the labels, values, and alternate matches should be unique across all options. Each of these parameters is used to map imported data to select options, so conflicts will occur if multiple select options share the same matches.
  </Note>

  #### Delimiter Configuration[​](#delimiter-configuration "Direct link to Delimiter Configuration")

  By default, multi-select fields parse input data using a comma (`,`) as the delimiter. You can customize this behavior:

  <ResponseField name="delimiter" type="string">
    The character used to separate multiple values in the input data. Common delimiters include `,`, `;`, `|`, or any custom character.
  </ResponseField>

  <ResponseField name="trimValues" type="boolean">
    Whether to trim whitespace from individual values after splitting. When `true`, values like `" apple , banana "` will be parsed as `["apple", "banana"]`.
  </ResponseField>

  Example configuration with custom delimiter:

  ```json theme={null}
  {
    "key": "skills",
    "label": "Skills",
    "type": ["multi-select", { "delimiter": ";", "trimValues": true }],
    "selectOptions": [
      { "label": "JavaScript", "value": "js" },
      { "label": "Python", "value": "py" },
      { "label": "Java", "value": "java" }
    ]
  }
  ```

  #### Many-to-One Mapping[​](#many-to-one-mapping "Direct link to Many-to-One Mapping")

  Multi-select fields support many-to-one column mapping by setting `manyToOne: true` on the field definition. This allows multiple source columns to be combined into a single multi-select field. This is useful when your input data has multiple columns that should be merged into one multi-select output.

  For example, if you have columns `"Interest1"`, `"Interest2"`, and `"Interest3"` in your CSV, you can map all of them to a single multi-select field with `manyToOne: true`, and the values will be combined into one array in the output.

  Example:

  ```json theme={null}
  {
    "key": "interests",
    "label": "Interests",
    "type": "multi-select",
    "selectOptions": [
      { "label": "Reading", "value": "reading" },
      { "label": "Gaming", "value": "gaming" },
      { "label": "Music", "value": "music" }
    ],
    "manyToOne": true
  }
  ```

  #### Validation[​](#validation "Direct link to Validation")

  Multi-select fields automatically validate that all selected values match one of the provided select options. Invalid values will result in an error message on the review screen.

  The field also checks for duplicate values within the same cell and displays a warning (not an error) if duplicates are found.
</div>

### Checkbox[​](#checkbox "Direct link to Checkbox")

> `type: "checkbox"`

<div>
  The checkbox field type is useful when you want to import a boolean (yes/no) field. The field will be displayed to the user as a checkbox and output as a JSON boolean (`true` or `false`).

  When importing, the following case-insensitive values are considered false: `""` (empty cell), `"0"`, `"off"`, `"n"`, `"no"`, `"false"`, `"disabled"`. All other values are considered true.
</div>

### Email[​](#email "Direct link to Email")

<div>
  > `type: "email"`

  Email fields are strings with built-in validation per the [HTML5 spec](https://html.spec.whatwg.org/multipage/input.html#email-state-\(type=email\)). There are some additional constraints: single domains (such as `contact@dromo`, with no TLD) and IP addresses are not allowed in the host portion.
</div>

### Country[​](#country "Direct link to Country")

<div>
  > `type: "country"`
  >
  > ```json theme={null}
  > type: [ "country", { format: <"2-letter" or "3-letter"> }]
  > ```

  Country fields validate values against a list of valid country codes (either ISO 3166 alpha-2 or alpha-3) based on the `format` option. If not specified, "2-letter" is used.
</div>

### Phone number[​](#phone-number "Direct link to Phone number")

<div>
  > `type: "phone-number"`
  >
  > ```json theme={null}
  > type: [ "phone-number",  { country: <2 letter iso country code>, format: "national" | "international" | "both", outputFormatted: boolean }]
  > ```

  Phone number fields can be used to validate phone numbers in many different scenarios.

  When format is `"international"` (default), the field validates full international numbers with country codes, displaying them with spaces (e.g., +1 212 867 5309) but outputting in E.164 ("+33123456789"), unless `outputFormatted: true`.

  With format: `"national"` and a country (e.g., `"US"`), it validates local numbers and displays them in national format (e.g., (212) 867-5309), outputting digits only unless outputFormatted: true.

  Use format: `"both"` with a country to accept both international and national formats. All values are displayed and output in international format.
</div>

### Social Security Number[​](#social-security-number "Direct link to Social Security Number")

<div>
  > `type: "ssn"`
  >
  > ```json theme={null}
  > type: [ "ssn", { outputDash: <boolean> }]
  > ```

  Social security number fields can be used to validate US SSNs. The input can be either 9 digits or 11 digits with dashes. The output is a string of digits, optionally including dashes if `outputDash` is set to `true`. This (obviously) does not validate the actual SSN.
</div>

### Domain[​](#domain "Direct link to Domain")

<div>
  > `type: "domain"`
  >
  > ```
  > type: [ "domain", { allowSubdomains: <boolean> }]
  > ```

  Domain fields validate input as a proper domain name (no paths, queries, or fragments), checking subdomains based on the `allowSubdomains` option, which defaults to true.

  If you need a field that accepts paths and query params, consider using an URL field.
</div>

### URL[​](#url "Direct link to URL")

<div>
  > `type: "url"`
  >
  > ```json theme={null}
  > type: ["url", { acceptedProtocols: array of accepted protocol strings. e.g: "https", "ftp">, acceptedDomains: <array of accepted domain strings. e.g: "google", "dromo"> }]
  > ```

  URL fields can be used to validate and normalize all URLs. You can optionally specify a list of accepted protocols (like `https`) and/or domains (`like dromo.io`).

  The value of the URL will be normalized to strip extra dashes and relative path references. For example, an input of https\:///dromo.io/foo/../bar is a valid URL, but will be normalized to the value `https://dromo.io/bar`.
</div>

### US State/Territory[​](#us-stateterritory "Direct link to US State/Territory")

<div>
  > `type: "us-state-territory"`

  US State/Territory fields can be used to validate values against standard US state and territory postal codes. The input can be both 2-letter ISO state/territory codes or 4-letter codes. e.g. `AL` or `US-AL`. The output is a 2-letter code.
</div>

### US Zipcode[​](#us-zipcode "Direct link to US Zipcode")

<div>
  > `type: "us-zip-code"`
  >
  > ```json theme={null}
  > type: ["us-zip-code",  { outputDash: <boolean>, format: <"5-digit"|"9-digit"> }]
  > ```

  US Zipcode fields can be used to validate values against US zip codes, either the 5-digit or 9-digit "ZIP+4" variant, specified by the `format` option.

  * `5-digit` format accepts 5  or 9 digit values (with or without dashes), but truncates 9-digit inputs to the first 5 digits. Shorter values are left-padded with zeros (e.g., `342` → `00342`).
  * `9-digit` format does not accept 5 digit values. It will accept only 9 digits, with or without dashes.

    Any value that contains characters other than dashes or digits will be invalid.
</div>

### UUID[​](#uuid "Direct link to UUID")

<div>
  > `type: "uuid"`

  ```json theme={null}
  type: ["uuid", { version: <number> }]
  ```

  The UUID field is a string field that validates UUID format and version number, if provided. The field uses the built-in `validate` function provided by `uuid` library. If `version` is provided, it will also check the UUID version using the `getVersion` from the `uuid` library.
</div>


# Field Validators
Source: https://developer.dromo.io/reference/fields/field-validators

Field validators allow you to enforce stricter rules about the data a user can import.

Indepedent of field types, Dromo provides a number of validators that you can use to ensure that get clean data in exactly the format you want them. You can use validators to highlight errors for the user and ensure that they fix the errors before submitting an import.

<img alt="A validator error message shown to the user" />

You can add validation to a field using the `validators` parameter—an array of objects, each with a `validate` rule. Optionally, include an `errorMessage` to show users a custom tooltip when validation fails.

## Validators

### Required

<div>
  <ResponseField name="validate" type="&#x22;required&#x22;">
    Specifies that the field cannot be empty.
  </ResponseField>

  <ResponseField name="errorMessage" type="string">
    Custom error message to display when validation fails.
  </ResponseField>
</div>

### Unique

<div>
  <ResponseField name="validate" type="&#x22;unique&#x22; | &#x22;unique_case_insensitive&#x22;">
    Specifies that all non-empty values in the column must be distinct (non-equal).

    You can also validate uniqueness case-insensitively with `{ validate: "unique_case_insensitive" }`.
  </ResponseField>

  <ResponseField name="errorMessage" type="string">
    Custom error message to display when validation fails.
  </ResponseField>
</div>

### Unique Across Multiple Fields

<div>
  <ResponseField name="validate" type="&#x22;unique_with&#x22;">
    The `unique_with` validator can be used to validate uniqueness across multiple fields.
  </ResponseField>

  <ResponseField name="uniqueKey" type="string">
    A unique identifier shared across all fields that should be validated together for uniqueness.
  </ResponseField>

  <ResponseField name="errorMessage" type="string">
    Custom error message to display when validation fails.
  </ResponseField>

  The `unique_with` validator can be used to validate uniqueness across multiple fields.

  To use it, place a `unique_with` validator on each field that you want to be part of the uniqueness validation, all sharing the same `uniqueKey`.

  Here is an example set of fields using `unique_with` validators used to validate that the combination of the first name and last name fields are unique.

  <CodeGroup>
    ```javascript theme={null}
    [
    {
        label: "First Name",
        key: "firstName",
        validators: [
        {
            validate: "unique_with",
            uniqueKey: "full name",
        },
        ],
    },
    {
        label: "Last Name",
        key: "lastName",
        validators: [
        {
            validate: "unique_with",
            uniqueKey: "full name",
        },
        ],
    },
    ]
    ```
  </CodeGroup>

  And here is an example of the validators in action:

  <img alt="unique with example" />
</div>

### Match a Regular Expression

<div>
  <ResponseField name="validate" type="&#x22;regex_match&#x22; | &#x22;regex_exclude&#x22;">
    You can validate that a field matches the given regular expression with the `regex_match` validator.

    Conversely, you can validate that a field does *not* match a regular expression with the `regex_exclude` validator.
  </ResponseField>

  <ResponseField name="regex" type="string | RegExp">
    The regular expression pattern to match against.
  </ResponseField>

  <ResponseField name="regexOptions" type="RegexOptions">
    Optional regex configuration options.
  </ResponseField>

  <ResponseField name="errorMessage" type="string">
    Custom error message to display when validation fails.
  </ResponseField>

  The Dromo uploader uses standard JavaScript regular expressions. You can set the `regex` key as either a `RegExp` literal/object or a string.

  If you choose to use a string, be careful to properly escape special characters in your regex. For example, the regex `/^"\d+"$/` should be passed in as `"^\"\\d+\"$"`. Additionally, if using a string, note that you cannot pass in regex flags directly in your regex. Instead, you may optionally provide a `regexOptions` parameter with the validator which takes an object with the following keys:

  * `ignoreCase: boolean` - Case insensitive flag (regex flag `i`)
  * `dotAll: boolean` - Matches all including any line breaks (regex flag `s`)
  * `multiline: boolean` - Multiline flag (regex flag `m`)
  * `unicode: boolean` - Unicode flag (regex flag `u`)
</div>

### Require with Other Fields

<div>
  <ResponseField name="validate" type="&#x22;require_with&#x22; | &#x22;require_without&#x22; | &#x22;require_with_all&#x22; | &#x22;require_without_all&#x22;">
    You can use these validators to require that a field be non-empty *only if* other fields are present or empty. There are four variations.
  </ResponseField>

  <ResponseField name="fields" type="string[]">
    Array of field keys to check against.
  </ResponseField>

  <ResponseField name="errorMessage" type="string">
    Custom error message to display when validation fails.
  </ResponseField>

  You can use these validators to require that a field be non-empty *only if* other fields are present or empty. There are four variations:

  > `{ validate: "require_with", fields: [<fieldKey>, ...] }`

  This will require that the field has a value if **any** of the fields listed in the `fields` array are **non-empty**.

  > `{ validate: "require_without", fields: [<fieldKey>, ...] }`

  This will require that the field has a value if **any** of the fields listed in the `fields` array are **empty**.

  > `{ validate: "require_with_all", fields: [<fieldKey>, ...] }`

  This will require that the field has a value if **all** of the fields listed in the `fields` array are **non-empty**.

  > `{ validate: "require_without_all", fields: [<fieldKey>, ...] }`

  This will require that the field has a value if **all** of the fields listed in the `fields` array are **empty**.
</div>

### Require with Other Field Values

<div>
  <ResponseField name="validate" type="&#x22;require_with_values&#x22; | &#x22;require_without_values&#x22; | &#x22;require_with_all_values&#x22; | &#x22;require_without_all_values&#x22;">
    You can use these validators to require that a field be non-empty *only if* other fields have specific values. There are four variations.
  </ResponseField>

  <ResponseField name="fieldValues" type="{ [fieldKey: string]: string }">
    Object mapping field keys to their required values.
  </ResponseField>

  <ResponseField name="errorMessage" type="string">
    Custom error message to display when validation fails.
  </ResponseField>

  You can use these validators to require that a field be non-empty *only if* other fields have specific values. There are four variations:

  > `{ validate: "require_with_values", fieldValues: { <fieldKey>: <fieldValue>, ... } }`

  This will require that the field has a value if **any** of the fields contain the corresponding value specified under `fieldValues`.

  > `{ validate: "require_without_values", fieldValues: { <fieldKey>: <fieldValue>, ... } }`

  This will require that the field has a value if **any** of the fields **do not** contain the corresponding value specified under `fieldValues`.

  > `{ validate: "require_with_all_values", fieldValues: { <fieldKey>: <fieldValue>, ... } }`

  This will require that the field has a value if **all** of the fields contain the corresponding value specified under `fieldValues`.

  > `{ validate: "require_without_all_values", fieldValues: { <fieldKey>: <fieldValue>, ... } }`

  This will require that the field has a value if **all** of the fields **do not** contain the corresponding value specified under `fieldValues`.
</div>

### Length

<div>
  <ResponseField name="validate" type="&#x22;length&#x22;">
    Validates that a field's value falls within a minimum or maximum number of characters.

    Either min, max, or both must be defined. Values are inclusive.

    The length validator cannot be used with non-string-based fields, such as number or date fields.
  </ResponseField>

  <ResponseField name="min" type="number">
    Minimum number of characters allowed.
  </ResponseField>

  <ResponseField name="max" type="number">
    Maximum number of characters allowed.
  </ResponseField>

  <ResponseField name="errorMessage" type="string">
    Custom error message to display when validation fails.
  </ResponseField>
</div>

### Alphabetical

<div>
  <ResponseField name="validate" type="&#x22;alphabetical&#x22;">
    Validates that a field's value only contains alphabetical characters (a-z, lowercase and uppercase).
  </ResponseField>

  <ResponseField name="errorMessage" type="string">
    Custom error message to display when validation fails.
  </ResponseField>
</div>


# Fields
Source: https://developer.dromo.io/reference/fields/fields

To implement Dromo in your application, you must first define a schema. A schema is an array of field objects. These fields will be matched to columns during the import process, and define the properties of the JSON payload passed back in the results.

## Basics[​](#basics "Direct link to Basics")

The most basic field consists of only a `key` and `label`. The field's key is its unique identifier, and will be the key of that field in the result JSON object. The field's label is how it will be displayed to the user.

* Schema
* Review screen
* Results

A basic schema could look like this:

<CodeGroup>
  ```javascript theme={null}
  fields: [
    {
      label: "First name",
      key: "firstName"
    },
    {
      label: "Last name",
      key: "lastName"
    },
    {
      label: "Membership ID",
      key: "memberId"
    }
  ]
  ```
</CodeGroup>

The user would then match these fields to the columns in their imported file, resulting in a review screen which looks like this:

<img alt="The review screen with data" />

And, when submitted, Dromo would provide you with a result data array like this:

<CodeGroup>
  ```json theme={null}
  [
    {
      "firstName": "Richard",
      "lastName": "Wysocki",
      "memberId": "38008"
    },
    {
      "firstName": "Paige",
      "lastName": "Pierce",
      "memberId": "29190"
    },
    {
      "firstName": "Paul",
      "lastName": "McBeth",
      "memberId": "27523"
    },
    {
      "firstName": "Kristin",
      "lastName": "Tattar",
      "memberId": "73986"
    },
    {
      "firstName": "Calvin",
      "lastName": "Heimburg",
      "memberId": "45971"
    },
    {
      "firstName": "Catrina",
      "lastName": "Allen",
      "memberId": "44184"
    },
    {
      "firstName": "Eagle",
      "lastName": "McMahon",
      "memberId": "37817"
    }
  ]
  ```
</CodeGroup>

## Field object reference[​](#field-object-reference "Direct link to Field object reference")

<ResponseField name="label" type="string">
  The human-friendly name of the field, shown to the user in the Dromo Uploader interface
</ResponseField>

<ResponseField name="key" type="string">
  The field's unique identifier, used as the key in the JSON results
</ResponseField>

<ResponseField name="type" type="FieldType">
  The field's type.

  Can be supplied in two formats:

  * As a string corresponding to a valid field type. If the field type accepts options, defaults will be used.
  * For field types which accept options, as a two element array where the first element is the string corresponding to a valid field type, and the second element is an object with type options.

  For more details, see [field types](/reference/fields/field-types).
</ResponseField>

<ResponseField name="description" type="string">
  An optional description of this field for the user. If you specify a value for this field, Dromo will show a ? icon in the importer that users can hover over to see this message.
</ResponseField>

<ResponseField name="alternateMatches" type="string[]">
  An array of alternate matches that this field to map to. See [column matching](#column-matching).
</ResponseField>

<ResponseField name="validators" type="Validator[]">
  An array of validator objects to validate this field. See [field validators](/reference/fields/field-validators).
</ResponseField>

<ResponseField name="selectOptions" type="{ label: string, value: string, alternateMatches?: string[] }[]">
  For select fields only, an array of possible picklist values. See the [select field type](/reference/fields/field-types#select).
</ResponseField>

<ResponseField name="readOnly" type="boolean">
  If `true`, the user will not be able to edit the data in this field.

  This is useful if you want to exclusively populate a virtual field using hooks.
</ResponseField>

<ResponseField name="hidden" type="boolean">
  If `true`, the field will be hidden from the user at all times. A hidden field can be set only using hooks.

  A user will not be able to match a column of data to the field. A user will not see the field in the review screen. The field will only be added to the submitted final result.

  Since a user cannot change the value of a hidden field, no validations can be set on a hidden field.
</ResponseField>

<ResponseField name="requireMapping" type="boolean">
  If `true`, the field must be mapped when matching columns. The user will not be able to progress to the data review screen unless this field has been matched to a column in the input file.

  Note: cells in this column aren't required to have any values; that can be validated using [the `required` validator](/reference/fields/field-validators#required).
</ResponseField>

<ResponseField name="manyToOne" type="boolean">
  If `true`, the field may have multiple data columns mapped to it.

  The result payload will have an array of all mapped columns' values instead of just a single value. Row hooks will have an entry in a `manyToOne` array for each mapped column.
</ResponseField>

## Column matching[​](#column-matching "Direct link to Column matching")

During the column matching step, Dromo will try to match columns headers in the user data to a corresponding `label` or `key` within your fields.

If you want to provide additional aliases that should automatically match to a given field, you can do so by setting `alternateMatches` for that field.

Column matching is case-sensitive.

Example:

<CodeGroup>
  ```javascript theme={null}
  {
    label: "City",
    key: "city",
    alternateMatches: ["municipality", "town", "locality"]
  }
  ```
</CodeGroup>


# Hooks
Source: https://developer.dromo.io/reference/hooks

Reference for column, row, bulk row, and step hooks, including callback inputs and outputs, row-cell transformations, dynamic fields with addField, validation messages, and lifecycle timing.

Hooks are a powerful feature that allow you to programmatically validate, transform, and enhance data during the import process. They integrate seamlessly with [field validation](/reference/fields/field-validators) and [results handling](/reference/results) to give you complete control over your data pipeline.

<Tip>
  Looking for simpler validation options? Check out [field validators](/reference/fields/field-validators) for built-in validation rules, or see [validating with external data](/guides/validate-external-data) for a row hook example.
</Tip>

The diagram below shows the general flow for Dromo. Column hooks run first and only once after the "column matching" stage. Batch row hooks run next during initialization, followed by standard and bulk row hooks. Standard and bulk row hooks also run after the user updates data; batch row hooks do not.

<img alt="Hook execution order throughout the Dromo import flow" />

## Column hooks[​](#column-hooks "Direct link to Column hooks")

Column hooks run on a specified column at the beginning of the data review step. They are run before the row hooks and will only run once during the import process. Column hooks are ideal for batch operations like API lookups or data enrichment for entire columns.

<Note>
  To register column hooks, use `registerColumnHook()` in the [JavaScript SDK](/reference/dromo-uploader-sdk) or the `columnHooks` prop in the [React component](/reference/react-dromo-uploader).
</Note>

Column hooks are called with a single argument, `values`, with an array of objects. Each object corresponds to one value in the column, and has two parameters.

<ResponseField name="index" type="number">
  The row index of the column value, starting with 0
</ResponseField>

<ResponseField name="value" type="string">
  The raw value as imported
</ResponseField>

Column hooks must return an array of objects in a similar format.

Column hooks may return the value async, wrapped in a promise.

<ResponseField name="index" type="number">
  The row index of the column value. This should be unchanged from the input.
</ResponseField>

<ResponseField name="value" type="string">
  The new value for this cell. If omitted, the value is left unchanged.
</ResponseField>

<ResponseField name="info" type="InfoMessage[]">
  An array of messages you would like to add to this cell.

  For more details, see [Info Messages](#working-with-info-messages).

  If omitted, no messages are added.
</ResponseField>

<AccordionGroup>
  <Accordion title="Sample input and output">
    Given the following imported data:

    |      Name     |                         Email                         |
    | :-----------: | :---------------------------------------------------: |
    |  Michelle Doe | [michelledoe@gmail.com](mailto:michelledoe@gmail.com) |
    |    Jane Doe   |     [janedoe@gmail.com](mailto:janedoe@gmail.com)     |
    |  Steve Jones  |     [steve@hotmail.com](mailto:steve@hotmail.com)     |
    | Wayne Gretzky |         [wayne@nhl.com](mailto:wayne@nhl.com)         |

    A column hook registered on the `Email` field would be passed the following data:

    <CodeGroup>
      ```javascript Input theme={null}
      [
        { value: "michelledoe@gmail.com", index: 0 },
        { value: "janedoe@gmail.com", index: 1 },
        { value: "steve@hotmail.com", index: 2 },
        { value: "wayne@nhl.com", index: 3 },
      ];
      ```
    </CodeGroup>

    This column hook could return something like this:

    <CodeGroup>
      ```javascript Output theme={null}
      [
        {
          index: 0,
          value: "michelledoe@aol.com",
          info: [
            {
              message: "Automatically corrected email domain",
              level: "info", // should be "info", "warning" or "error"
            },
          ],
        },
        // we can omit cells that don't need any changes or messages
        {
          index: 2,
          // Don't need to supply value if we're not changing it
          info: [
            {
              message: "Email not found",
              level: "error",
            },
          ],
        },
      ];
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Column hook example">
    <CodeGroup>
      ```javascript JavaScript theme={null}
      const fields = [
        {
          label: "Email",
          key: "email",
        },
      ];

      const settings = {
        importIdentifier: "Column Hooks Server Validation",
      };

      const user = {
        id: "12345",
      };

      const dromo = new DromoUploader("FRONTEND_API_KEY", fields, settings, user);

      dromo.registerColumnHook("email", function (values) {
        return values.map((row) => {
          const newRow = {
            index: row.index,
            value: "0" + row.value,
            info: [
              {
                message: "Prepended 0 to value",
                level: "info",
              },
            ],
          };
          return newRow;
        });
      });
      ```

      ```jsx React theme={null}
      <DromoUploader
        licenseKey={"FRONTEND_API_KEY"}
        user={{ id: "12345" }}
        fields={[
          {
            label: "Email",
            key: "email",
          },
        ]}
        settings={{
          importIdentifier: "Column Hooks Example",
        }}
        columnHooks={[
          {
            fieldName: "email",
            callback: (values) => {
              return values.map((row) => {
                const newRow = {
                  index: row.index,
                  value: "0" + row.value,
                  info: [
                    {
                      message: "Prepended 0 to value",
                      level: "info",
                    },
                  ],
                };
                return newRow;
              });
            },
          },
        ]}>
        Import Emails
      </DromoUploader>
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## Row hooks[​](#row-hooks "Direct link to Row hooks")

Row hooks run validation on imported records and return updated data and/or user messages. They come in three variants: standard, batch, and bulk.

<Note>
  To register row hooks, use `registerRowHook()`, `registerBatchRowHook()`, or `registerBulkRowHook()` in the [JavaScript SDK](/reference/dromo-uploader-sdk). React and Angular integrations provide the corresponding `rowHooks`, `batchRowHooks`, and `bulkRowHooks` props or inputs.
</Note>

Standard and bulk row hooks run once in `"init"` mode after the column matching step and before the user begins the review step. They run again in `"update"` mode after the user changes data. Batch row hooks run only during initialization and receive bounded slices of the dataset.

Row hooks are run again in `"update"` mode after each time the user changes any data, with only the changed rows.

### Standard row hooks[​](#standard-row-hooks "Direct link to Standard row hooks")

Standard row hooks are invoked once for every row on `init`, and once for every row that changed on `update`.

Standard row hooks are called with two arguments.

<ResponseField name="record" type="object">
  <ResponseField name="index" type="number">
    The index of this row
  </ResponseField>

  <ResponseField name="row" type="object">
    The `row` object will have keys matching the field key of each mapped field. Each of these keys will contain an object with data and metadata of that field in the given row.

    <ResponseField name="value" type="string">
      The value of this field at this row, as displayed to the user
    </ResponseField>

    <ResponseField name="resultValue" type="string | boolean | number | null">
      The value of this field at this row, as it will appear in the result data
    </ResponseField>

    <ResponseField name="info" type="InfoMessage[]" href="#working-with-info-messages">
      An array of any info messages you have previously added to this cell
    </ResponseField>

    <ResponseField name="selectOptions" type="{ label: string, value: string }[]">
      Overridden selectOptions previously added to this cell
    </ResponseField>
  </ResponseField>
</ResponseField>

<ResponseField name="mode" type="&#x22;init&#x22; | &#x22;update&#x22;">
  Mode will be `"init"` if running before the start of the review step, and `"update"` if running due to a user change.
</ResponseField>

<ResponseField name="manyToOne" type="{ value: string, resultValue: string | boolean | number | null, info: InfoMessage[], selectOptions: { label: string, value: string }[] }[]">
  If the field is [manyToOne](/reference/fields/field-types#manytoone), every mapped cell for this row appears as an array.
</ResponseField>

Row hooks should return the updated record in a similar format.

Row hooks may return the value async, wrapped in a promise.

<ResponseField name="row" type="object">
  The `row` object should contain keys matching the field key of each mapped field. If a mapped field is omitted, it will remain unchanged.

  Each field key object may have the following entries:

  <ResponseField name="value" type="string">
    The new value for this row
  </ResponseField>

  <ResponseField name="info" type="InfoMessage[]" href="#working-with-info-messages">
    New messages for this row. Messages returned will replace any previously set messages. If `info` is omitted, messages will remain unchanged.
  </ResponseField>

  <ResponseField name="selectOptions" type="{ label: string, value: string }[]">
    Select option overrides for this cell. If provided, the cell will use these select options for transforming values and validating instead of those set when the field was declared.
  </ResponseField>
</ResponseField>

<Info>
  When fetching external data, we recommend that you make any API calls in a column hook and then validate that the data remains correct using a row hook in `update` mode.
</Info>

<Accordion title="Standard row hook example">
  <CodeGroup>
    ```javascript JavaScript theme={null}
    const fields = [
      {
        label: "Email",
        key: "email",
      },
      {
        label: "State",
        key: "state",
        selectOptions: [{ label: "Alabama", value: "AL" }, { label: "Alaska", value: "AK" }],
      },
    ];

    const settings = {
      importIdentifier: "Row Hooks Example",
    };

    const user = {
      id: "12345",
    };

    const dromo = new DromoUploader("FRONTEND_API_KEY", fields, settings, user);

    dromo.registerRowHook(function (record, mode) {
      const newRecord = record;
      if (record.index < 10 && mode === "init") {
        newRecord.row.email.value = "0" + newRecord.row.email.value;
        newRecord.row.email.info = [
          {
            message: "Prepend 0 to value",
            level: "info",
          },
        ];
        newRecord.row.state.selectOptions = [
          { label: "Alberta", value: "AB"}, 
          { label: "British Colombia", value: "BC"}
        ];
      }
      return newRecord;
    });
    ```

    ```jsx React theme={null}
    <DromoUploader
      licenseKey={"FRONTEND_API_KEY"}
      user={{ id: "12345" }}
      fields={[
        {
          label: "Email",
          key: "email",
        },
        {
          label: "State",
          key: "state",
          selectOptions: [{ label: "Alabama", value: "AL" }, { label: "Alaska", value: "AK" }],
        },
      ]}
      settings={{
        importIdentifier: "Row Hooks Example",
      }}
      rowHooks={[
        (record) => {
          const newRecord = record;
          if (record.index < 10) {
            if (newRecord.row.email) {
              newRecord.row.email.value = "0" + newRecord.row.email.value;
              newRecord.row.email.info = [
                {
                  message: "Prepend 0 to value",
                  level: "info",
                },
              ];
            }
            newRecord.row.state.selectOptions = [
              { label: "Alberta", value: "AB"}, 
              { label: "British Colombia", value: "BC"}
            ];
          }
          return newRecord;
        },
      ]}>
      Import Contacts
    </DromoUploader>
    ```
  </CodeGroup>
</Accordion>

### Batch row hooks[​](#batch-row-hooks "Direct link to Batch row hooks")

Batch row hooks process large imports in bounded slices instead of passing the full dataset to one callback. They run only once during initialization, after column hooks and before standard and bulk row hooks.

The callback receives two arguments:

<ResponseField name="records" type="object[]">
  A slice of row hook record objects. The maximum number of records is controlled by [`batchRowHookBatchSize`](/reference/settings/settings#batchrowhookbatchsize), which defaults to `2000`.
</ResponseField>

<ResponseField name="batchNumber" type="number">
  The one-based number of the current batch. The first callback receives `1`, the second receives `2`, and so on.
</ResponseField>

Batch row hooks do not receive a mode argument because they never run in `"update"` mode. Return an array of row hook output objects with each record's original `index`. You may return only the fields that should change; omitted fields and rows remain unchanged. Async callbacks are supported.

<Accordion title="Batch row hook example">
  <CodeGroup>
    ```javascript JavaScript theme={null}
    const settings = {
      importIdentifier: "Large Contact Import",
      batchRowHookBatchSize: 5000,
    };

    const dromo = new DromoUploader("FRONTEND_API_KEY", fields, settings, user);

    dromo.registerBatchRowHook(async (records, batchNumber) => {
      const enrichedEmails = await enrichEmailBatch(records, batchNumber);

      return records.map((record) => ({
        index: record.index,
        row: {
          email: { value: enrichedEmails[record.index] },
        },
      }));
    });
    ```

    ```jsx React theme={null}
    <DromoUploader
      licenseKey="FRONTEND_API_KEY"
      user={user}
      fields={fields}
      settings={{
        importIdentifier: "Large Contact Import",
        batchRowHookBatchSize: 5000,
      }}
      batchRowHooks={[
        async (records, batchNumber) => {
          console.log(`Processing batch ${batchNumber}`);
          return records;
        },
      ]}
    >
      Import Contacts
    </DromoUploader>
    ```

    ```typescript Angular theme={null}
    import { IBatchRowHook } from "dromo-uploader-angular";

    batchRowHooks: IBatchRowHook[] = [
      async (records, batchNumber) => {
        console.log(`Processing batch ${batchNumber}`);
        return records;
      },
    ];
    ```

    ```html Angular template theme={null}
    <lib-dromo-uploader
      [licenseKey]="licenseKey"
      [user]="user"
      [fields]="fields"
      [settings]="settings"
      [batchRowHooks]="batchRowHooks"
    >
      Import Contacts
    </lib-dromo-uploader>
    ```
  </CodeGroup>
</Accordion>

### Bulk row hooks[​](#bulk-row-hooks "Direct link to Bulk row hooks")

Bulk row hooks are invoked a single time on `init` with the full dataset, and a single time on `update` with all of the changed rows.

Bulk row hooks are a good fit if you need to perform potentially long-running operations that can be optimized by processing all changes in a single function call.

Bulk row hooks work exactly like standard row hooks, except the first parameter is an array of record objects instead of a single record object. Similarly, bulk row hooks must return an array of record objects, preserving the `index` parameter of each record.

<Accordion title="Bulk row hook example">
  <CodeGroup>
    ```javascript JavaScript theme={null}
    const fields = [
      {
        label: "Email",
        key: "email",
      },
    ];

    const settings = {
      importIdentifier: "Row Hooks Example",
    };

    const user = {
      id: "12345",
    };

    const dromo = new DromoUploader("FRONTEND_API_KEY", fields, settings, user);

    dromo.registerBulkRowHook(function (records, mode) {
      return records.map((record) => {
        const newRecord = record;
        if (record.index < 10 && mode === "init") {
          newRecord.row.email.value = "0" + newRecord.row.email.value;
          newRecord.row.email.info = [
            {
              message: "Prepend 0 to value",
              level: "info",
            },
          ];
        }
        return newRecord;
      });
    });
    ```

    ```jsx React theme={null}
    <DromoUploader
      licenseKey={"FRONTEND_API_KEY"}
      user={{ id: "12345" }}
      fields={[
        {
          label: "Email",
          key: "email",
        },
      ]}
      settings={{
        importIdentifier: "Row Hooks Example",
      }}
      bulkRowHooks={[
        (records) => {
          return records.map((record) => {
            const newRecord = record;
            if (record.index < 10) {
              if (newRecord.row.email) {
                newRecord.row.email.value = "0" + newRecord.row.email.value;
                newRecord.row.email.info = [
                  {
                    message: "Prepend 0 to value",
                    level: "info",
                  },
                ];
              }
            }
            return newRecord;
          })
        },
      ]}>
      Import Contacts
    </DromoUploader>
    ```
  </CodeGroup>
</Accordion>

## Row delete hooks[​](#row-delete-hooks "Direct link to Row delete hooks")

Row delete hooks are called when a row (or rows) is removed from the table by the user.

Row delete hooks are called once for each row that was removed.

<ResponseField name="record" type="object">
  <ResponseField name="index" type="number">
    The index of this row
  </ResponseField>

  <ResponseField name="row" type="object">
    The `row` object will have keys matching the field key of each mapped field. Each of these keys will contain an object with data and metadata of that field in the given row.

    <ResponseField name="value" type="string">
      The value of this field at this row, as displayed to the user
    </ResponseField>

    <ResponseField name="resultValue" type="string | boolean | number | null">
      The value of this field at this row, as it will appear in the result data
    </ResponseField>

    <ResponseField name="info" type="InfoMessage[]" href="#working-with-info-messages">
      An array of any info messages you have previously added to this cell
    </ResponseField>
  </ResponseField>
</ResponseField>

<Accordion title="Row delete hook example">
  <CodeGroup>
    ```javascript JavaScript theme={null}
    dromo.registerRowDeleteHook(function (record) {
      console.log("Deleted row index: " + record.index);
    });
    ```

    ```jsx React theme={null}
    <DromoUploader
      licenseKey="FRONTEND_API_KEY"
      ...
      rowDeleteHooks={[(record) => console.log("Deleted row index: +" + record.index)]}
      ...>
      Launch Dromo
    </DromoUploader>
    ```
  </CodeGroup>
</Accordion>

## Step hooks[​](#step-hooks "Direct link to Step hooks")

Step hooks are callbacks that are invoked at different parts of the import process. In addition to fetching metadata about the import at that time, you can use them to call mutation functions like [`addField`](#instanceaddfield).

<Note>
  To register step hooks, use `registerStepHook()` in the [JavaScript SDK](/reference/dromo-uploader-sdk) or the `stepHooks` prop in the [React component](/reference/react-dromo-uploader). See the [using addField guide](/guides/using-addField) for advanced use cases.
</Note>

### `UPLOAD_STEP` hook[​](#upload_step-hook "Direct link to upload_step-hook")

This hook is called when the user has completed uploading a file and provides you with a 20 row data preview of that data.

The function is called with two arguments.

<ResponseField name="instance" type="DromoUploader" href="#the-dromo-uploader-instance">
  The Dromo Uploader instance which you can call mutation methods on
</ResponseField>

<ResponseField name="previewData" type="string[][]">
  An array of arrays containing the first 20 rows of raw uploaded data
</ResponseField>

<Accordion title="Upload step hook example">
  <CodeGroup>
    ```javascript JavaScript theme={null}
    dromo.registerStepHook("UPLOAD_STEP", function (instance, data) {
      instance.addField({
        label: "Full Name",
        key: "fullName",
      });
      console.log(data.filename, data.dataPreview);
    });
    ```

    ```jsx React theme={null}
    <DromoUploader
      licenseKey={"FRONTEND_API_KEY"}
      ...
      stepHooks: [
        {
          type: "UPLOAD_STEP",
          callback: (instance, data) => {
            instance.addField({
              label: "Full Name",
              key: "fullName",
            })
            console.log(data.filename, data.dataPreview);
          }
        }
      ],
      .../>
    ```
  </CodeGroup>
</Accordion>

### `REVIEW_STEP` hook[​](#review_step-hook "Direct link to review_step-hook")

This hook is triggered just before the final review screen loads (and before any of the row and column hooks).

The function is called with two arguments.

<ResponseField name="instance" type="DromoUploader" href="#the-dromo-uploader-instance">
  The Dromo Uploader instance which you can call mutation methods on
</ResponseField>

<ResponseField name="reviewStepData" type="object">
  <ResponseField name="rawHeaders" type="string[] | null">
    The raw headers from the uploaded file. If no file was uploaded (e.g. manual entry was used), this will be `null`.
  </ResponseField>

  <ResponseField name="headerMapping" type="{ [header: string]: string }">
    An object whose keys are the file headers and values are the field keys of the field the header was mapped to
  </ResponseField>

  <ResponseField name="fields" type="object">
    An object whose keys are the field keys and values are objects containing metadata about that field

    <ResponseField name="fileHeader" type="string | null">
      The header this field was mapped to. `null` if no file was uploaded.
    </ResponseField>

    <ResponseField name="fileHeaderIndex" type="number | null">
      The column header index this field was mapped to. `null` if no file was uploaded.
    </ResponseField>

    <ResponseField name="isCustom" type="boolean">
      Whether this field was added by the user as a custom field
    </ResponseField>

    <ResponseField name="manyToOne" type="boolean">
      Indicates if this field is [`manyToOne`](/reference/fields/field-types#manytoone).
    </ResponseField>

    <ResponseField name="fileHeaders" type="string[]">
      The headers that were mapped to the field if it is [`manyToOne`](/reference/fields/field-types#manytoone).
    </ResponseField>

    <ResponseField name="fileHeaderIndexes" type="number[]">
      The indexes of columns that were mapped to a [`manyToOne`](/reference/fields/field-types#manytoone) field.
    </ResponseField>
  </ResponseField>
</ResponseField>

<Accordion title="Review step hook example">
  <CodeGroup>
    ```javascript JavaScript theme={null}
    dromo.registerStepHook("REVIEW_STEP", function (instance, data) {
      instance.addField({
        label: "Full Name",
        key: "fullName",
      });
      console.log(data.rawHeaders, data.headerMapping, data.fields);
    });
    ```

    ```jsx React theme={null}
    <DromoUploader
      licenseKey={"FRONTEND_API_KEY"}
      ...
      stepHooks: [
        {
          type: "REVIEW_STEP", // to run immediately after a user uploads data, change this to UPLOAD_STEP
          callback: (instance, data) => {
            instance.addField({
              label: "Full Name",
              key: "fullName",
            })
            console.log(data.rawHeaders, data.headerMapping, data.fields);
          }
        },
      ],
      .../>
    ```
  </CodeGroup>
</Accordion>

### `REVIEW_STEP_POST_HOOKS` hook[​](#review_step_post_hooks-hook "Direct link to review_step_post_hooks-hook")

This hook is triggered during the review step after all of the initial row and column hooks have run (and after any \`REVIEW\_STEP\` hooks have run). It can be handy for doing batched updates to the data based on aggregated results from row or column hooks.

The function is called with two arguments.

<ResponseField name="instance" type="DromoUploader" href="#the-dromo-uploader-instance">
  The Dromo Uploader instance which you can call mutation methods on
</ResponseField>

<ResponseField name="reviewStepData" type="object">
  <ResponseField name="headerMapping" type="{ [header: string]: string }">
    An object whose keys are the file headers and values are the field keys of the field the header was mapped to
  </ResponseField>

  <ResponseField name="fields" type="object">
    An object whose keys are the field keys and values are objects containing metadata about that field

    <ResponseField name="fileHeader" type="string | null">
      The header this field was mapped to. `null` if no file was uploaded.
    </ResponseField>

    <ResponseField name="fileHeaderIndex" type="number | null">
      The column header index this field was mapped to. `null` if no file was uploaded.
    </ResponseField>

    <ResponseField name="isCustom" type="boolean">
      Whether this field was added by the user as a custom field
    </ResponseField>
  </ResponseField>
</ResponseField>

<Accordion title="Review step post hooks example">
  <CodeGroup>
    ```javascript JavaScript theme={null}
    dromo.registerStepHook("REVIEW_STEP_POST_HOOKS", function (instance, data) {
      instance.updateInfoMessages([
        {
          rowIndex: 5,
          fieldKey: "month",
          messages: [
            { level: "info", message: "Sales exceed previous month" },
          ],
        },
      ]);
      console.log(data.headerMapping, data.fields);
    });
    ```

    ```jsx React theme={null}
    <DromoUploader
      licenseKey={"FRONTEND_API_KEY"}
      ...
      stepHooks: [
        {
          type: "REVIEW_STEP_POST_HOOKS",
          callback: (instance, data) => {
            instance.updateInfoMessages([
              {
                rowIndex: 5,
                fieldKey: "month",
                messages: [
                  { level: "info", message: "Sales exceed previous month" },
                ],
              },
            ]);
            console.log(data.headerMapping, data.fields);
          }
        },
      ],
      .../>
    ```
  </CodeGroup>
</Accordion>

### `REVIEW_STEP_PRE_SUBMIT` hook[​](#review_step_pre_submit-hook "Direct link to review_step_pre_submit-hook")

This hook is triggered during the review step right after the user clicks 'Finish' but before [`beforeFinish`](/reference/results#the-beforefinish-callback) runs. It can be useful for customizing the 'Are you ready to submit?' dialog with info summarizing the changes and impact of the import data.

The function is called with two arguments.

<ResponseField name="instance" type="DromoUploader" href="#the-dromo-uploader-instance">
  The Dromo Uploader instance which you can call mutation methods on
</ResponseField>

<ResponseField name="reviewStepData" type="object">
  <ResponseField name="headerMapping" type="{ [header: string]: string }">
    An object whose keys are the file headers and values are the field keys of the field the header was mapped to
  </ResponseField>

  <ResponseField name="fields" type="object">
    An object whose keys are the field keys and values are objects containing metadata about that field

    <ResponseField name="fileHeader" type="string | null">
      The header this field was mapped to. `null` if no file was uploaded.
    </ResponseField>

    <ResponseField name="fileHeaderIndex" type="number | null">
      The column header index this field was mapped to. `null` if no file was uploaded.
    </ResponseField>

    <ResponseField name="isCustom" type="boolean">
      Whether this field was added by the user as a custom field
    </ResponseField>
  </ResponseField>
</ResponseField>

<Accordion title="Review step pre submit example">
  <CodeGroup>
    ```javascript JavaScript theme={null}
    dromo.registerStepHook("REVIEW_STEP_PRE_SUBMIT", function (instance, data) {
      instance.setConfirmationMessage(
        "<div>Adding 5 new contacts. Modifying 20 existing contacts.</div>",
        {
          submitButtonText: "Accept changes",
          cancelButtonText: "Cancel",
        }
      );
      console.log(data.headerMapping, data.fields);
    });
    ```

    ```jsx React theme={null}
    <DromoUploader
      licenseKey={"FRONTEND_API_KEY"}
      ...
      stepHooks: [
        {
          type: "REVIEW_STEP_PRE_SUBMIT",
          callback: (instance, data) => {
            instance.setConfirmationMessage(
              "<div>Adding 5 new contacts. Modifying 20 existing contacts.</div>",
              {
                submitButtonText: "Accept changes",
                cancelButtonText: "Cancel",
              }
            );
            console.log(data.headerMapping, data.fields);
          }
        },
      ],
      .../>
    ```
  </CodeGroup>
</Accordion>

## Working with info messages[​](#working-with-info-messages "Direct link to Working with info messages")

Dromo offers the ability to add info messages to data cells to enable custom validation and provide other feedback to the user. Info messages are a key part of the validation system and work alongside [field validators](/reference/fields/field-validators).

You can add and update info messages via [column hooks](#column-hooks), [row hooks](#row-hooks), and [the updateInfoMessages method](#instanceupdateinfomessages) in step hooks.

<Tip>
  For simple validation scenarios, consider using [built-in field validators](/reference/fields/field-validators) before implementing custom validation with info messages.
</Tip>

Info messages are provided as objects with these parameters.

<ResponseField name="message" type="string">
  The message to be displayed to the user in the review screen when they hover over the corresponding cell
</ResponseField>

<ResponseField name="level" type="&#x22;info&#x22; | &#x22;warning&#x22; | &#x22;error&#x22;">
  The nature of the message.

  * A cell with an `"error"` message is highlighted in red. It is considered a validation error and impacts the user's submission options based on [`invalidDataBehavior`](/reference/settings/settings#invaliddatabehavior)
  * A cell with a `"warning"` message is highlighted in yellow
  * A cell with an `"info"` message is highlighted in blue
</ResponseField>

## The Dromo Uploader instance[​](#the-dromo-uploader-instance "Direct link to The Dromo Uploader instance")

Step hooks provide access to the Dromo Uploader instance, which exposes methods to alter the import.

### `instance.addField`[​](#instanceaddfield "Direct link to instanceaddfield")

Adds a field to the schema after a step hook has completed.

By default, the field will be added to the end of the fields.

You may optionally provide a position object specifying where in the list of fields to insert the new one.

<ResponseField name="field" type="Field" href="/reference/fields/fields#field-object-reference">
  A field spec for the new field to add
</ResponseField>

<ResponseField name="position" type="{ before: string } | { after: string }">
  Specifies where in the list of fields to add the new one.

  If provided, must be an object of the form `{ before: fieldKey }` or `{ after: fieldKey }` where `fieldKey` is the `key` of a mapped field. If no mapped field with the given key exists, the new field will be added to the end.
</ResponseField>

<Check>
  For an example of concatenating or splitting fields, see the [Guide](/guides/using-addField).
</Check>

### `instance.removeField`[​](#instanceremovefield "Direct link to instanceremovefield")

Removes a field after a step hook has completed.

The field will no longer be visible on the data review screen nor included in the result data. Any validation errors or info messages will be discarded.

Can be used in conjuction with [`addField`](/reference/hooks#instanceaddfield) to concatenate columns and remove the originals, i.e. combine `firstName` + `lastName` into `fullName` and remove `firstName` and `lastName` from the result data.

<ResponseField name="fieldKey" type="string">
  Key of the field to be deleted.
</ResponseField>

<Check>
  For an example of concatenating or splitting fields, see the [Guide](/guides/using-addField).
</Check>

### `instance.updateInfoMessages`[​](#instanceupdateinfomessages "Direct link to instanceupdateinfomessages")

Updates the messages for targeted cells, overwriting any previous messages.

<ResponseField name="updates" type="object[]">
  An array of objects with an object for each cell to update the messages on

  <ResponseField name="rowIndex" type="number">
    The 0-indexed position of the row you are targeting
  </ResponseField>

  <ResponseField name="fieldKey" type="string">
    The key of the [field](/reference/fields/fields) you are targeting
  </ResponseField>

  <ResponseField name="manyToOneIndex" type="number">
    If `manyToOne` is enabled on a field, you can use this property to select which mapped column shall receive the updates.
  </ResponseField>

  <ResponseField name="messages" type="InfoMessage[]" href="#working-with-info-messages">
    An array of [infoMessages](#working-with-info-messages) which will be set for the cell at the specified row and field.

    An empty array will clear existing messages from the cell.
  </ResponseField>
</ResponseField>

<Accordion title="updateInfoMessages example">
  In this case, if you had previously set a message on the email field of row 3 or the phone field of row 8, these messages would be replaced with the new ones.

  <CodeGroup>
    ```javascript theme={null}
    instance.updateInfoMessages([
      {
        rowIndex: 3,
        fieldKey: "email",
        messages: [{ level: "warning", message: "Email has not been confirmed" }],
      },
      {
        rowIndex: 8,
        fieldKey: "phone",
        messages: [{ level: "error", message: "Phone number not in database" }],
      },
    ]);
    ```
  </CodeGroup>
</Accordion>

### `instance.addRows`[​](#instanceaddrows "Direct link to instanceaddrows")

Adds rows to the dataset. Returns an array of row IDs for the rows that were just added.

<ResponseField name="rows" type="object[]">
  Rows to be added to the dataset.

  <ResponseField name="index" type="number">
    Index where this row will be inserted. If omitted, row will be added to end of the dataset.
  </ResponseField>

  <ResponseField name="row" type="object">
    The `row` object should contain keys matching the field key of each mapped field. If a mapped field is omitted, it will remain unchanged.

    Each field key object may have the following entries:

    <ResponseField name="value" type="string">
      The new value for this row
    </ResponseField>

    <ResponseField name="info" type="InfoMessage[]" href="#working-with-info-messages">
      Info messages for this row.
    </ResponseField>

    <ResponseField name="selectOptions" type="{ label: string, value: string }[]">
      Select option overrides for this cell. If provided, the cell will use these select options for transforming values and validating instead of those set when the field was declared.
    </ResponseField>
  </ResponseField>
</ResponseField>

### `instance.removeRows`[​](#instanceremoverows "Direct link to instanceremoverows")

Removes rows rows the dataset.

<ResponseField name="rowIds" type="string[]">
  Rows to be removed. Row IDs can be read on any row or column hooks.
</ResponseField>

### `instance.setConfirmationMessage`[​](#instancesetconfirmationmessage "Direct link to instancesetconfirmationmessage")

Allows customization of the messaged displayed to the user after they click 'Finish'. Content can be plain text or HTML.

<ResponseField name="messageHTML" type="string">
  Message for finish confirmation alert modal. Text or HTML for embedding links or media.
</ResponseField>

<ResponseField name="options" type="{ submitButtonText?: string, cancelButtonText?: string }">
  Optionally override text for submit and cancel buttons.
</ResponseField>


# onUserEvent
Source: https://developer.dromo.io/reference/on-user-event

Receive real-time notifications when a user interacts with specific UI controls inside the Dromo importer.

## Overview

`onUserEvent` is a callback you can register on a `DromoUploader` instance to receive real-time notifications when a user interacts with specific UI controls inside the importer. It gives your host application observability into what the user is doing — useful for analytics, audit logging, conditional UI reactions, or debugging.

## Registration

```javascript theme={null}
const importer = new DromoUploader(licenseKey, fields, settings, user);

importer.onUserEvent((event) => {
  console.log(event.eventType, event.payload);
});
```

The method accepts a single callback function. It can be registered at any point before the user triggers the relevant interaction.

<Note>
  Only one callback can be registered per instance. Calling `onUserEvent` a second time replaces the first.
</Note>

## Callback Signature

```typescript theme={null}
onUserEvent(callback: (event: IUserEvent) => void): void
```

The callback receives one argument, an `IUserEvent` object:

```typescript theme={null}
interface IUserEvent<T extends EUserEventType = EUserEventType> {
  eventType: T;
  payload: IUserEventPayloadMap[T];
}
```

## Event Types

Currently one event type is emitted:

| `eventType`      | Description                                                     |
| ---------------- | --------------------------------------------------------------- |
| `"BUTTON_CLICK"` | Fired whenever the user clicks a tracked button in the importer |

### BUTTON\_CLICK Payload

When `eventType` is `"BUTTON_CLICK"`, the payload is:

```typescript theme={null}
interface IButtonClickPayload {
  buttonName: string; // see button name reference below
  step: string;       // the active step when the click occurred
}
```

**`step` values**

| Value             | Step                                   |
| ----------------- | -------------------------------------- |
| `"UPLOAD"`        | File upload / manual data entry screen |
| `"HEADER_SELECT"` | Header row selection screen            |
| `"COLUMN_MATCH"`  | Column mapping screen                  |
| `"SELECT_MATCH"`  | Value / select matching screen         |
| `"REVIEW"`        | Data review and validation screen      |

## Button Name Reference

The full set of `buttonName` values, grouped by step:

### Navigation (cross-step)

| Value      | Description             |
| ---------- | ----------------------- |
| `CONTINUE` | Primary continue action |
| `NEXT`     | Next step               |
| `GO_BACK`  | Back navigation         |
| `FINISH`   | Final submit / finish   |

### Upload step

| Value               | Description                                 |
| ------------------- | ------------------------------------------- |
| `UPLOAD_DATA`       | Upload a file                               |
| `ENTER_DATA`        | Open manual data entry                      |
| `DOWNLOAD_TEMPLATE` | Download the CSV template                   |
| `CONFIRM_SHEET`     | Confirm sheet selection (multi-sheet files) |

### Header select step

| Value                    | Description                       |
| ------------------------ | --------------------------------- |
| `HEADER_SELECT_CONTINUE` | Continue with selected header row |
| `NO_HEADER_ROW`          | Mark file as having no header row |

### Column match step

| Value                 | Description                |
| --------------------- | -------------------------- |
| `COLUMN_MATCH_IGNORE` | Ignore an unmatched column |
| `COLUMN_MATCH_REMOVE` | Remove an unmatched column |

### Select / value match step

| Value                      | Description                      |
| -------------------------- | -------------------------------- |
| `DATE_FIX_ACCEPT`          | Accept suggested date format fix |
| `DATE_FIX_UNDO`            | Undo date format fix             |
| `SELECT_MATCH_CLEAR`       | Clear a single-select match      |
| `MULTI_SELECT_MATCH_CLEAR` | Clear a multi-select match       |

### Review step

| Value                           | Description                        |
| ------------------------------- | ---------------------------------- |
| `FIND_AND_REPLACE_OPEN`         | Open find & replace panel          |
| `FIND_AND_REPLACE_CONFIRM`      | Confirm a find & replace operation |
| `FIND_AND_REPLACE_CANCEL`       | Cancel find & replace              |
| `SHOW_ROWS_WITH_ERRORS`         | Filter to rows with errors         |
| `CLEAR_ROWS_WITH_ERRORS_FILTER` | Clear the error filter             |
| `TRANSFORM_DATA_OPEN`           | Open AI transform panel            |
| `TRANSFORM_DATA_PREVIEW`        | Preview AI transform results       |
| `TRANSFORM_DATA_REGENERATE`     | Regenerate AI transform            |
| `TRANSFORM_DATA_CONFIRM`        | Confirm AI transform               |
| `TRANSFORM_DATA_CANCEL`         | Cancel AI transform                |
| `EXPORT_ALL`                    | Export all rows                    |
| `EXPORT_ERRORS_ONLY`            | Export only rows with errors       |
| `DOWNLOAD_XLSX`                 | Download data as XLSX              |
| `TOGGLE_SEARCH`                 | Toggle search bar                  |

### Exit confirmation modal

| Value          | Description                  |
| -------------- | ---------------------------- |
| `EXIT_CONFIRM` | Confirm exit / cancel import |
| `EXIT_CANCEL`  | Stay in the importer         |

### Generic alert / modal actions

| Value             | Description                         |
| ----------------- | ----------------------------------- |
| `ALERT_PRIMARY`   | Primary action on a generic alert   |
| `ALERT_SECONDARY` | Secondary action on a generic alert |

## Error Handling

Errors thrown inside your `onUserEvent` callback are caught by Dromo and logged as a warning — they will not crash the importer or interrupt the user's flow:

```
[Dromo-External-Error] There was an error in your onUserEvent callback.
```

## Example

```javascript theme={null}
importer.onUserEvent((event) => {
  if (event.eventType === "BUTTON_CLICK") {
    const { buttonName, step } = event.payload;

    analytics.track("dromo_button_click", {
      button: buttonName,
      step: step,
      userId: currentUser.id,
    });
  }
});
```

## Notes

* The callback is fire-and-forget from Dromo's perspective — the return value is ignored and the importer does not await it.
* The callback is registered on the importer instance, so each importer instance can have its own independent `onUserEvent` handler.
* The callback is not invoked in headless mode (server-side Lambda execution), only during interactive browser sessions.


# <DromoUploader> Component Props
Source: https://developer.dromo.io/reference/react-dromo-uploader

Reference for props accepted by the DromoUploader React component.

The `DromoUploader` component is the primary way to integrate Dromo into your React application. It accepts the following props:

<ResponseField name="licenseKey" type="string">
  Your Dromo front-end license key, which can be found in [the Dromo dashboard](https://dashboard.dromo.io/).
</ResponseField>

<ResponseField name="fields" type="Field[]" href="/reference/fields/fields">
  An array of [Field objects](/reference/fields/fields) which comprise your import schema.
</ResponseField>

<ResponseField name="settings" type="Settings" href="/reference/settings/settings">
  [Settings object](/reference/settings/settings) to change the behavior of the Dromo importer.
</ResponseField>

<ResponseField name="user" type="User" href="/reference/users">
  [User metadata object](/reference/users) to associate with the import.
</ResponseField>

<ResponseField name="schemaId" type="string">
  The ID of a pre-existing schema created in Schema Studio. If provided, the `fields`, `settings` (except `importIdentifier` and `developmentMode`), and `hooks` props will be ignored in favor of the saved schema's configuration. See [Usage with saved schemas](/getting-started/react#usage-with-saved-schemas).
</ResponseField>

<ResponseField name="rowHooks" type="RowHook[]" href="/reference/hooks#row-hooks">
  An array of [row hook](/reference/hooks#row-hooks) functions.
</ResponseField>

<ResponseField name="bulkRowHooks" type="BulkRowHook[]" href="/reference/hooks#bulk-row-hooks">
  An array of [bulk row hook](/reference/hooks#bulk-row-hooks) functions.
</ResponseField>

<ResponseField name="batchRowHooks" type="BatchRowHook[]" href="/reference/hooks#batch-row-hooks">
  An array of initialization-only [batch row hook](/reference/hooks#batch-row-hooks) functions. Each function receives a bounded slice of rows and its one-based batch number.
</ResponseField>

<ResponseField name="rowDeleteHooks" type="RowDeleteHook[]" href="/reference/hooks#row-delete-hooks">
  An array of [row delete hook](/reference/hooks#row-delete-hooks) functions called when users remove rows.
</ResponseField>

<ResponseField name="columnHooks" type="object[]" href="/reference/hooks#column-hooks">
  An array of [column hook](/reference/hooks#column-hooks) objects. Each object has two entries:

  <div>
    <ResponseField name="fieldName" type="string">
      The [field key](/reference/fields/fields) of the field this column hook should run on.
    </ResponseField>

    <ResponseField name="callback" type="ColumnHookFn" href="/reference/hooks#column-hooks">
      The [column hook](/reference/hooks#column-hooks) function.
    </ResponseField>
  </div>
</ResponseField>

<ResponseField name="stepHooks" type="object[]" href="/reference/hooks#step-hooks">
  An array of [step hook](/reference/hooks#step-hooks) objects. Each object has two entries:

  <div>
    <ResponseField name="type" type="'UPLOAD_STEP' | 'REVIEW_STEP' | 'REVIEW_STEP_POST_HOOKS' | 'REVIEW_STEP_PRE_SUBMIT'">
      The type of step hook.
    </ResponseField>

    <ResponseField name="callback" type="StepHookFn" href="/reference/hooks#step-hooks">
      A function matching the signature for the specified step hook type.
    </ResponseField>
  </div>
</ResponseField>

<ResponseField name="customSteps" type="CustomStepConfig[]" href="/reference/custom-steps">
  An array of [custom step](/reference/custom-steps) configurations inserted into the import flow.
</ResponseField>

<ResponseField name="fileParsers" type="{ extensions: string[], parseFile: ParseFileFn }[]" href="/reference/custom-file-parsers">
  An array of [custom file parser](/reference/custom-file-parsers) configurations.
</ResponseField>

<ResponseField name="beforeFinish" type="BeforeFinishCallbackFn" href="/reference/results#the-beforefinish-callback">
  A [beforeFinish callback function](/reference/results#the-beforefinish-callback) called immediately before completing the import to check results.
</ResponseField>

<ResponseField name="onResults" type="OnResultsCallbackFn" href="/reference/results#the-onresults-callback">
  An [onResults callback function](/reference/results#the-onresults-callback) called with the results after the user finishes the import.
</ResponseField>

<ResponseField name="onCancel" type="() => void">
  Called if the user leaves the Dromo Uploader before completing the import.
</ResponseField>

<ResponseField name="onUserEvent" type="(event: IUserEvent) => void" href="/reference/on-user-event">
  Called when the user interacts with a tracked control in the importer. See the [onUserEvent reference](/reference/on-user-event) for event payloads.
</ResponseField>

<ResponseField name="open" type="boolean">
  (Available in version >= 2.0.9)
  If provided, determines whether the Dromo importer modal should open. See [Controlling the Modal Programmatically](/getting-started/react#open-prop-vs-children-as-open-button).
</ResponseField>

<ResponseField name="developmentMode" type="boolean">
  Overrides the `developmentMode` setting if a `schemaId` is also provided. Defaults to `false`.
</ResponseField>

<ResponseField name="importIdentifier" type="string">
  Overrides the `importIdentifier` setting if a `schemaId` is also provided.
</ResponseField>


# Import Results Callbacks and Metadata
Source: https://developer.dromo.io/reference/results

Reference for Dromo's onResults and beforeFinish callbacks, returned row data, import metadata, and completion control.

## The `onResults` callback[​](#the-onresults-callback "Direct link to the-onresults-callback")

This callback is called when the user completes the import flow. `onResults` is called with two arguments.

<CodeGroup>
  ```js JavaScript theme={null}
  dromo.onResults(function (response, metadata) {  // Do something with the data here  console.log(response, metadata);});
  ```

  ```jsx React theme={null}
  <DromoUploader  ...  onResults={(response, metadata) =>    // Do something with the data here    console.log(response, metadata)  }>  Launch Dromo</DromoUploader>
  ```
</CodeGroup>

<ResponseField name="data" type="{ [key: string]: string | boolean | number | null }[]">
  An array of objects, one for each row in the final data.

  The keys of each object will be the field keys of each mapped field, and the values will be the final value of that field, based on the field's type.

  **Note: If a field is [`manyToOne`](/reference/fields/field-types#manytoone), the value will be an array.**
</ResponseField>

<ResponseField name="metadata" type="object">
  <ResponseField name="id" type="string | null">
    Dromo assigns a unique ID to each completed import that is synced to the backend. This ID can be used to retrieve the import from the [Dromo API](/api-reference).

    If [`backendSyncMode`](/reference/settings/settings#backendsyncmode) is `"DISABLED"`, the import ID will be `null`.
  </ResponseField>

  <ResponseField name="filename" type="string | null">
    The filename of the file that the user uploaded.

    `null` if the user did not upload a file (i.e. used manual entry).
  </ResponseField>

  <ResponseField name="importIdentifier" type="string">
    The [`importIdentifier`](/reference/settings/settings#importidentifier) of this import
  </ResponseField>

  <ResponseField name="user" type="User">
    The [user](/reference/users) associated with this import
  </ResponseField>

  <ResponseField name="rowsWithError" type="number[]">
    Array of row indices where at least one error appears.
  </ResponseField>

  <ResponseField name="errors" type="{ rowIndex: number, fieldKey: string, message: string, value: string }[]">
    Array of objects detailing all the errors in the upload.
  </ResponseField>

  <ResponseField name="fields" type="object">
    An object whose keys are the field keys and values are objects containing metadata about that field

    <ResponseField name="fileHeader" type="string | null">
      The header this field was mapped to. `null` if no file was uploaded.
    </ResponseField>

    <ResponseField name="fileHeaderIndex" type="number | null">
      The column header index this field was mapped to. `null` if no file was uploaded.
    </ResponseField>

    <ResponseField name="isCustom" type="boolean">
      Whether this field was added by the user as a custom field
    </ResponseField>

    <ResponseField name="manyToOne" type="boolean">
      Indicates if this field is [manyToOne](/reference/fields/field-types#manytoone).
    </ResponseField>

    <ResponseField name="fileHeaders" type="string[]">
      The headers that were mapped to the field if it is [manyToOne](/reference/fields/field-types#manytoone).
    </ResponseField>

    <ResponseField name="fileHeaderIndexes" type="number[]">
      The indexes of columns that were mapped to a [manyToOne](/reference/fields/field-types#manytoone) field.
    </ResponseField>
  </ResponseField>
</ResponseField>

## The `onCancel` callback[​](#the-oncancel-callback "Direct link to the-oncancel-callback")

This callback is called if the user exits from the import without completing it.

`onCancel` does not receive any arguments.

## The `beforeFinish` callback[​](#the-beforefinish-callback "Direct link to the-beforefinish-callback")

Sometimes, you may wish to perform validation on the final result data before the user leaves the import.

To accomplish this, you can define a `beforeFinish` callback. This callback will fire when the user finishes the import, and receives the same arguments as the `onResults` callback. The callback also receives a third argument, `instance`, with the instance of the uploader.

If you define a `beforeFinish` callback, you can cancel finishing the upload by returning an object in the format `{ cancel: true, message: "Message to user" }`. In this case, the user will remain on the Review Screen, with the given error message shown to the user. The `onResults` callback will not fire and the import will not complete. This process will repeat the next time the user submits the import.

Otherwise, if nothing is returned from the `beforeFinish` callback (or any other value is returned), the `onResults` callback will fire and the import will complete normally.

<ResponseField name="data" type="{ [key: string]: string | boolean | number | null }[]">
  An array of objects, one for each row in the final data.

  The keys of each object will be the field keys of each mapped field, and the values will be the final value of that field, based on the field's type.
</ResponseField>

<ResponseField name="metadata" type="object">
  <ResponseField name="filename" type="string | null">
    The filename of the file that the user uploaded.

    `null` if the user did not upload a file (i.e. used manual entry).
  </ResponseField>

  <ResponseField name="importIdentifier" type="string">
    The [`importIdentifier`](/reference/settings/settings#importidentifier) of this import
  </ResponseField>

  <ResponseField name="user" type="User">
    The [user](/reference/users) associated with this import
  </ResponseField>

  <ResponseField name="rowsWithError" type="number[]">
    Array of row indices where at least one error appears.
  </ResponseField>

  <ResponseField name="errors" type="{ rowIndex: number, fieldKey: string, message: string, value: string }[]">
    Array of objects detailing all the errors in the upload.
  </ResponseField>

  <ResponseField name="fields" type="object">
    An object whose keys are the field keys and values are objects containing metadata about that field

    <ResponseField name="fileHeader" type="string | null">
      The header this field was mapped to. `null` if no file was uploaded.
    </ResponseField>

    <ResponseField name="fileHeaderIndex" type="number | null">
      The column header index this field was mapped to. `null` if no file was uploaded.
    </ResponseField>

    <ResponseField name="isCustom" type="boolean">
      Whether this field was added by the user as a custom field
    </ResponseField>

    <ResponseField name="manyToOne" type="boolean">
      Indicates if this field is [manyToOne](/reference/fields/field-types#manytoone).
    </ResponseField>

    <ResponseField name="fileHeaders" type="string[]">
      The headers that were mapped to the field if it is [manyToOne](/reference/fields/field-types#manytoone).
    </ResponseField>

    <ResponseField name="fileHeaderIndexes" type="number[]">
      The indexes of columns that were mapped to a [manyToOne](/reference/fields/field-types#manytoone) field.
    </ResponseField>
  </ResponseField>
</ResponseField>

<ResponseField name="instance" type="DromoUploader">
  The Dromo Uploader instance which you can call mutation methods on
</ResponseField>

<CodeGroup>
  ```js JavaScript theme={null}
  dromo.beforeFinish(function (data, metadata, instance) {  if (data.length < 20) {    return { cancel: true, message: "You must import at least 20 rows" }  }});
  ```

  ```jsx React theme={null}
  <DromoUploader  ...  beforeFinish={(data, metadata, instance) =>    if (data.length < 20) {      return { cancel: true, message: "You must import at least 20 rows" }    }  }>  Launch Dromo</DromoUploader>
  ```
</CodeGroup>

## Custom fields[​](#custom-fields "Direct link to Custom fields")

If you have enabled [`allowCustomFields`](/reference/settings/settings#allowcustomfields), it will allow the user to add custom fields that are not part of the field schema. The name of the custom field will be added as a key to the result objects.

As an example, if the user defines a column name "fav\_color", the response would look like the following:

```
{  "name": "Jack",  "email_address": "jack@thehill.com",  "fav_color": "blue"}
```


# Deprecated Settings
Source: https://developer.dromo.io/reference/settings/deprecated

Deprecated settings are settings that are no longer supported and will be removed in a future version of Dromo. These settings are provided for backwards compatibility and will be removed in a future version of Dromo.

<ResponseField name="allowInvalidSubmit" type="boolean">
  <Warning>
    `allowInvalidSubmit` is deprecated in favor of the `invalidDataBehavior` setting.

    `allowInvalidSubmit = false` is equivalent to `invalidDataBehavior = "REMOVE_INVALID_ROWS"`.

    `allowInvalidSubmit = true` is equivalent to `invalidDataBehavior = "INCLUDE_INVALID_ROWS"`.
  </Warning>

  This option impacts the messaging on the final screen before submitting data. When this is set to `false`, Dromo will discard the records with errors and the user will see "Discard *X* rows with issues. Submit the rest." When this is set to `true`, Dromo will submit the records with errors and the user will see "Submit your data anyway (errors may occur).":

  <Expandable title="allowInvalidSubmit=false">
    <img alt="invalidSubmit false" />
  </Expandable>

  <Expandable title="allowInvalidSubmit=true">
    <img alt="invalidSubmit true" />
  </Expandable>
</ResponseField>

<ResponseField name="backendSync" type="boolean">
  <Warning>
    `backendSync` is deprecated in favor of `backendSyncMode`
    `backendSync = false` is equivalent to `backendSyncMode = "DISABLED"`
    `backendSync = true` is equivalent to `backendSyncMode = "FULL_DATA"`
  </Warning>
</ResponseField>

<ResponseField name="displayEncoding" type="boolean">
  <Warning>Removed in v2</Warning>

  Allows the user to specify an encoding for any files they upload. Dromo will default to the encoding that it detects. If `displayEncoding` is set to `true` (default), the encoding dropdown is visible in the importer:
</ResponseField>


# Settings
Source: https://developer.dromo.io/reference/settings/settings

Settings are supplied as an object to the Dromo instance on initialization. For details on how to supply settings to Dromo, see the Getting Started guide for the SDK you are using.

<ResponseField name="importIdentifier" type="string">
  This option identifies the data you are importing. If you have multiple imports in your application (i.e. *Customers* and *Sales*), you should specify different import identifiers for each type of import. The title of the importer modal will be "Add `importIdentifier`" unless you supply the [`title` option](#title).
</ResponseField>

<ResponseField name="title" type="string">
  Replaces the title of the importer modal. For instance, if we set `title` to "Enjoy Dromo!" you would see the title appear in the importer like this:

  <img alt="Importer title customized with the title setting" />

  <Note>
    The default for this will display "Add `importIdentifier`". For instance, if the `importIdentifier` is `Products`, it will say "Add Products".
  </Note>
</ResponseField>

<ResponseField name="invalidDataBehavior" type="&#x22;BLOCK_SUBMIT&#x22; | &#x22;REMOVE_INVALID_ROWS&#x22; | &#x22;INCLUDE_INVALID_ROWS&#x22;">
  This option impacts the user's experience when invalid data is present. When this is set to `"BLOCK_SUBMIT"`, Dromo will disable the 'Finish' button preventing the user from submitting with errors. When this is set to `"REMOVE_INVALID_ROWS"`, Dromo will remove any rows with errors and the user will see a dialog indicating "Discard *X* rows with issues. Submit the rest." When this is set to `"INCLUDE_INVALID_ROWS"`, Dromo will submit the records with errors and the user will see "Submit your data anyway (errors may occur).".

  |              `REMOVE_INVALID_ROWS`             |              `INCLUDE_INVALID_ROWS`             |                     `BLOCK_SUBMIT`                    |
  | :--------------------------------------------: | :---------------------------------------------: | :---------------------------------------------------: |
  | <img alt="Remove invalid rows confirmation" /> | <img alt="Include invalid rows confirmation" /> | <img alt="Blocked submit when invalid data exists" /> |
</ResponseField>

<ResponseField name="allowEmptySubmit" type="boolean">
  Controls whether the user can complete an import even if 0 rows will be submitted. This can be because there are no rows in the import data, or if `invalidDataBehavior` is set to `REMOVE_INVALID_ROWS` and all rows have at least one error.

  If set to `false`, the submit import button will be disabled when no rows would be submitted.
</ResponseField>

<ResponseField name="manualInputDisabled" type="boolean">
  Show or hide an input table for the user to manually input data. If this is set to `true`, then there will only be a file dropzone on the page.
</ResponseField>

<ResponseField name="manualInputOnly" type="boolean">
  Show or hide the file dropzone that appears when the importer is started. If this is set to `true`, then there will only be a manual input table on the page and the dropzone will be hidden. The `manualInputDisabled` and `manualInputOnly` settings cannot both be set to `true`.
</ResponseField>

<ResponseField name="backendSyncMode" type="&#x22;FULL_DATA&#x22; | &#x22;MAPPINGS_ONLY&#x22; | &#x22;DISABLED&#x22;">
  The `backendSyncMode` setting controls whether the upload data is sent to the Dromo server for storage, if only the column mapping is sent, or if all processing is completed in the browser.

  Setting `backendSyncMode` to `"FULL_DATA"` enables several features:

  * Viewing your uploads in the Dromo Dashboard
  * Using webhooks and the Dromo API to retrieve results
  * Using the `autoMapHeaders` setting

  It sends all the data from the upload to the Dromo backend for storage.

  Setting `backendSyncMode` to `"MAPPINGS_ONLY"` enables using the `autoMapHeaders` setting. In this mode, only the column mapping and unique values from `'select'` type fields will be stored in our backend.

  You can set `backendSync` to `"DISABLED"` if you have data privacy requirements, and you don't need the additional functionality the other modes provide.

  Dromo uses industry-standard best practices to secure your data on our servers.
</ResponseField>

<ResponseField name="webhookUrl" type="string">
  Requires [backendSyncMode](#backendsyncmode) = "FULL\_DATA"

  This is a URL that is called upon the completion of a successful upload through Dromo. Note: `backendSync` needs to be set to `true` for this to work. For more information on webhooks, see the [Webhooks](/reference/webhooks) documentation.
</ResponseField>

<ResponseField name="allowCustomFields" type="boolean">
  This settings allows users to create custom fields that are not included in the `fields` object. If set to `true`, a user will be able to type in a custom field name during the matching phase. These user-provided field names will be included as keys for the returned results.
</ResponseField>

<ResponseField name="initialData" type="{ [key: string]: string }[] | string[][]">
  This allows you to specify the data being uploaded, bypassing the CSV upload stage.

  You can supply this data in one of two forms:

  * As an array of objects, where each object represents a row. The object itself is a mapping of the `key` specified in [fields](/fields) and the value for that field in that row. As an example you could pass in:

    ```
    [  {    name: "Jack",    email_address: "jack@thehill.com",  },  {    name: "Jill",    email_address: "jill@thehill.com",  },];
    ```

  * As an array of arrays of strings, where each row is represented by an array, with the fields matching the order specified by [`fields`](/fields). For example:

    ```
    [  ["Jack", "jack@thehill.com"],  ["Jill", "jill@thehill.com"],];
    ```

    All of the supplied data must be in one form or the other – they cannot be mixed.
</ResponseField>

<ResponseField name="initialFile" type="File">
  The `initialFile` setting allows you to provide a [Web API File object](https://developer.mozilla.org/en-US/docs/Web/API/File), providing the Dromo importer with the raw data to parse and bypassing the user picking a file to import.

  The File object can come from a file input within your application, or you can build the file object from any source data using the [File constructor](https://developer.mozilla.org/en-US/docs/Web/API/File/File). The filename extension of the File object should match the format of the file (e.g. if you are providing an Excel file, the filename should end in ".xlsx".)
</ResponseField>

<ResponseField name="maxRecords" type="number">
  Specify the maximum number of records that a single file can import. This value does not include the headers of the file.

  If the number of rows in the file exceed this number, the user will be warned and the excess rows will be dropped.
</ResponseField>

<ResponseField name="batchRowHookBatchSize" type="number">
  Sets the maximum number of rows passed to each [batch row hook](/reference/hooks#batch-row-hooks) invocation. The value must be a positive integer.

  This setting has no effect unless a batch row hook is registered. Batch row hooks run only once during import initialization and receive a one-based batch number as their second argument.
</ResponseField>

<ResponseField name="maxFileSize" type="number">
  Specifies the maximum file size, in bytes, that can be imported. If the user selects a larger file, they will be shown an error message.

  The maximum file size must be a positive integer and cannot exceed 1 GiB (the default value).
</ResponseField>

<ResponseField name="developmentMode" type="boolean">
  Set this value to `true` when testing or in development environments. The importer will show a "development mode" banner and the imports will be flagged as development imports. These imports will not be charged against your account.
</ResponseField>

<ResponseField name="styleOverrides" type="object">
  Customizes the importer's colors, typography, controls, and other visual elements. See the complete [style overrides reference](/reference/settings/style-overrides).
</ResponseField>

<ResponseField name="textOverrides" type="object">
  Overrides supported error and interface text.

  <div>
    <ResponseField name="errors" type="Record<string, string>">
      Maps supported error keys to replacement messages.
    </ResponseField>

    <ResponseField name="ui" type="Record<'COLUMN_MATCH_SUBTITLE' | 'BULK_FIX_SUBTITLE', string>">
      Overrides the subtitle shown on the Column Matching or Bulk Fix step.
    </ResponseField>
  </div>

  ```javascript theme={null}
  settings: {
    textOverrides: {
      ui: {
        COLUMN_MATCH_SUBTITLE: "Match each spreadsheet column to a destination field",
        BULK_FIX_SUBTITLE: "Review and standardize unmatched values",
      },
    },
  }
  ```
</ResponseField>

<ResponseField name="autoMapHeaders" type="boolean">
  Requires [backendSyncMode](#backendsyncmode) = "MAPPINGS\_ONLY" or "FULL\_DATA"

  With this setting on, Dromo will try to automatically map the CSV headers to fields based off of previous uploads with the same `importIdentifier`. The user can still click back and change the mapping if needed.
</ResponseField>

<ResponseField name="skipBulkFixStep" type="boolean">
  If `true`, Dromo always skips the Bulk Fix step, even when select, multi-select, or date fields would otherwise require bulk fixing. This setting takes precedence over the automatic conditions that normally show the step.

  ```javascript theme={null}
  skipBulkFixStep: true
  ```
</ResponseField>

<ResponseField name="delimiter" type="string">
  Allows you to explicitly define a field delimiter for your file (i.e. `|`). By default, Dromo will attempt auto-detect the delimiter.
</ResponseField>

<ResponseField name="xmlParsingOptions" type="object">
  Configures client-side parsing for XML uploads.

  <div>
    <ResponseField name="forceArrayTags" type="string[]">
      XML tag names that should always be treated as arrays, including when only one matching element exists.
    </ResponseField>

    <ResponseField name="headerAlias" type="Record<string, string>">
      Maps XML tag names to the column headers Dromo should display.
    </ResponseField>

    <ResponseField name="enableAutoArrayHeuristics" type="boolean">
      Automatically recognizes plural parent and singular child tags, such as `<sales><sale>`, as arrays.
    </ResponseField>

    <ResponseField name="assumeSingleRootChildIsArray" type="boolean">
      Treats a single object nested beneath a single root tag as a one-row dataset.
    </ResponseField>
  </div>

  ```javascript theme={null}
  settings: {
    xmlParsingOptions: {
      forceArrayTags: ["contact"],
      headerAlias: { email_address: "Email" },
      enableAutoArrayHeuristics: true,
      assumeSingleRootChildIsArray: true,
    },
  }
  ```
</ResponseField>

<ResponseField name="templateDownloadFilename" type="string">
  If set, Dromo will generate a template CSV file using the fields you have defined on the import. Users will see a download link for this template file on the Upload screen of the Dromo importer. The value of this setting will be used as the filename of the template, plus the `.csv` extension.
</ResponseField>

<ResponseField name="browserExcelParsing" type="boolean">
  Activates the parsing of Excel files in the end user's browser. Either this setting or `backendSyncMode: "FULL_DATA"` must be active to enable Excel file parsing.

  Defaults to `true` in SDK version >= 2.0.0
</ResponseField>

<ResponseField name="passThroughUnmappedColumns" type="boolean">
  With this setting enabled, Dromo will include all columns not mapped or added as custom fields in the result payload.

  The values for each row will be in an object with the key `$unmapped`. The key for each value will correspond to the column index in the original file.

  Additionally, the `metadata` object passed to your `resultsCallback` will include a `rawHeaders` array containing the original column headers in order, allowing you to map column indexes to their actual header names.

  In the example below, we only mapped two columns to `firstName` and `email`. The remaining unmapped columns were added to the `$unmapped` object.

  ```javascript theme={null}
  // Example results
  [
    {
      "$unmapped": {
        "1": "Phillips",
        "3": "(124) 246-3980",
        "4": "United States",
        "5": "93715",
        "6": "",
        "7": "proposed terms"
      },
      "firstName": "Michael",
      "email": "jason@moxie.xyz"
    },
    {
      "$unmapped": {
        "1": "Kukreja",
        "3": "+1 124 246 3981",
        "4": "Canada",
        "5": "J6R",
        "6": "17-Dec-91",
        "7": "qualifying lead"
      },
      "firstName": "Mohit",
      "email": "info@hub.inc"
    }
  ]

  // metadata.rawHeaders
  ["Name", "Last Name", "Email", "Phone", "Country", "Zip", "Birthday", "Notes"]
  ```

  <Note>
    For a complete guide on working with unmapped columns including how to use `rawHeaders` to convert column indexes to header names, see the [Accessing Unmapped Columns guide](/guides/accessing-unmapped-columns).
  </Note>
</ResponseField>

## Step settings

### `uploadStep`[​](#uploadstep "Direct link to uploadstep")

The `settings.uploadStep` object contains settings for the Upload Step experience. It defaults to `{}`.

<ResponseField name="helpText" type="string">
  If set, the given string will be shown to the user on the Upload Step. This can be used to give the user additional context on what file they should upload.

  Content can be plain text or HTML.
</ResponseField>

<ResponseField name="sheetOverride" type="string">
  If set, the sheet selection modal will be skipped if a sheet matching the string is found in the workbook.

  If the uploaded file does not have sheets (e.g. a CSV), or the uploaded file has only one sheet, this setting has no effect.
</ResponseField>

<ResponseField name="templateDownloadOverrideURL" type="string">
  If set, the template download button will download from this URL instead of generating a CSV template from your schema fields.

  This allows you to provide a custom template file that may include additional formatting, instructions, or example data beyond what can be captured in the basic CSV template.

  The file will be downloaded with the same filename that would be used for the generated template.

  ```javascript theme={null}
  uploadStep: {
    templateDownloadOverrideURL: "https://your-domain.com/custom-template.xlsx"
  }
  ```
</ResponseField>

### `matchingStep`[​](#matchingstep "Direct link to matchingstep")

object

Default: `{}`

Settings for the Matching Step experience

<ResponseField name="matchToSchema" type="boolean">
  Added in v2

  By default, the user is asked to match or ignore all of the column names that exist in their file. If set to `true`, the user will instead be asked to match only the fields contained in the schema. This is particularly useful when a file may contain numerous irrelevant columns.
</ResponseField>

<ResponseField name="fuzzyMatchHeaders" type="boolean">
  Determines whether Dromo will use fuzzy matching to suggest column mappings during the matching step. If set to `false`, Dromo will only suggest columns whose headers exactly match a field's `label`, `key`, or `alternateMatches`.
</ResponseField>

<ResponseField name="helpText" type="string">
  If set, the given string will be shown to the user on the Matching Step. This can be used to give the user additional context on how to match the columns for your import.

  Content can be plain text or HTML.
</ResponseField>

<ResponseField name="headerRowOverride" type="number">
  If set, `matchingStep.headerRowOverride` will preset the header row to the 0-indexed row specified. If the header row is after the first row (i.e. `headerRowOverride` is set to a value greater than 0), rows before the header row will be discarded.
</ResponseField>

<ResponseField name="suggestCustomFirst" type="boolean">
  If set to true, matchingStep.suggestCustomFirst will prioritize the "Add custom field" option by displaying it at the top of the dropdown menu during column matching, rather than positioning it at the end.
</ResponseField>

### `matchValuesStep`[​](#matchvaluesstep "Direct link to matchvaluesstep")

object

Default: `{}`

Settings for the Bulk Fix step experience (formerly known as the Match Values step)

<ResponseField name="helpText" type="string">
  If set, the given string will be shown to the user on the Match Values Step. This can be used to give the user additional context on how they should match values with their select fields.

  Content can be plain text or HTML.
</ResponseField>

<ResponseField name="maxMappableSelectValues" type="number">
  The maximum number of unique values that can be mapped using the Match Values screen per field. If more than `maxMappableSelectValues` are found in a column of data, Dromo will indicate to the user that there are too many unique values to map on the Match Values screen. The maximum value that can be set for `maxMappableSelectValues` is 1000.
</ResponseField>

### `reviewStep`[​](#reviewstep "Direct link to reviewstep")

The `settings.reviewStep` object contains settings for the Review Step experience. It defaults to `{}`. The following settings are available:

<ResponseField name="processingText" type="string">
  If set, the given string will be shown to the user while the hooks are running at the beginning of the review step. This can be used to give the user additional context if you have any slow-running hooks.
</ResponseField>

<ResponseField name="helpText" type="string">
  If set, the given string will be shown to the user on the Review Step. This can be used to give the user additional context on what issues they should resolve on this step.

  Content can be plain text or HTML.
</ResponseField>

<ResponseField name="allowAddingRows" type="boolean">
  If false, Dromo will prevent the user from adding any new rows to the data.

  <Check>
    Dromo will disable manual input mode (user starts with an empty data table and adds data line by line instead of a file) if this setting is `false`. Manual input mode specifically requires adding rows.
  </Check>
</ResponseField>

<ResponseField name="allowRemovingRows" type="boolean">
  If false, Dromo will prevent the user from removing any rows from the data.
</ResponseField>

<ResponseField name="enableUserTransformations" type="boolean">
  If true, the 'Transform data' feature will be available on the review step.

  <Check>
    See the [Transform data guide](/guides/using-transform-data) for more information.
  </Check>
</ResponseField>

<ResponseField name="transformDataPrompts" type="string[] | null">
  An array of custom prompt strings displayed as clickable suggestions in the AI "Transform Data" modal. When set to a non-empty array, these strings replace the built-in localized prompts shown to the user. `null` or an empty array falls back to the default prompts.

  Requires [`enableUserTransformations`](#enableusertransformations) to be `true`.

  ```javascript theme={null}
  settings: {
    reviewStep: {
      enableUserTransformations: true,
      transformDataPrompts: [
        "Remove all rows where the email domain is not @company.com",
        "Normalize all phone numbers to E.164 format",
        "Fill blank 'country' cells with 'United States'",
      ],
    }
  }
  ```
</ResponseField>

<ResponseField name="highlightAutoFixes" type="boolean">
  If true, Dromo will highlight any cell that had substantive changes made by automatic transformations, such as:

  * Rounded number values
  * Modified datetime values
  * Select values changed from alternate matches
  * Left-padded zip codes or removed last 4 digits
  * Modified URLs
  * Adjusted phone numbers

    <Expandable title="an example">
      <img alt="Automatically fixed cells highlighted in the review table" />
    </Expandable>

    <Check>
      This feature can help users quickly identify and verify automatic transformations made to their data during the import process.
    </Check>
</ResponseField>

<ResponseField name="enableNavigatingErrors" type="boolean">
  When enabled, adds an error navigation panel to the Review Step that lets users move through validation errors one at a time and fix them inline.

  **Row headers**: Any row with a validation error displays a red circular info icon next to its row number. Clicking the icon opens the navigator panel anchored to that row's first error.

  **Navigator panel**: Slides in from the right of the table and lists all validation errors as cards — each showing the row number, column name, and error message.

  * **Column filter**: A dropdown filters the list to a single column.
  * **Prev/Next navigation**: Buttons and the `Alt+↑` / `Alt+↓` keyboard shortcuts step through errors in order, scrolling the table to each cell.
  * **Jump to cell**: Clicking any error card scrolls directly to that cell.
  * **Inline actions** (shown on the active error card):
    * **Clear** — removes the invalid cell value. For multi-select fields, only the invalid tokens are removed.
    * **Replace** — replaces the cell value with a new one. For select fields a valid-options dropdown is shown; for multi-select fields the chosen value is appended to the existing valid tokens; for all other fields a free-text input is shown.
  * **Closing the panel** (X button) resets the panel state and column filter.

    <img alt="Error navigator panel showing validation errors with inline Clear and Replace actions" />

  ```javascript theme={null}
  settings: {
    reviewStep: {
      enableNavigatingErrors: true
    }
  }
  ```
</ResponseField>

## Localization and sessions

<ResponseField name="locale" type="string">
  The language to display within the Dromo importer. Dromo supports the following internationalization (i18n) options:

  <Expandable title="Internationalization Options">
    * **bn** (Bengali)
    * **cs** (Czech)
    * **da** (Danish)
    * **de** (German)
    * **el** (Greek)
    * **en** (English)
    * **es** (Spanish)
    * **fi** (Finnish)
    * **fr** (French)
    * **hi** (Hindi)
    * **hr** (Croatian)
    * **hu** (Hungarian)
    * **id** (Indonesian)
    * **is** (Icelandic)
    * **it** (Italian)
    * **ja** (Japanese)
    * **ko** (Korean)
    * **lt** (Lithuanian)
    * **lv** (Latvian)
    * **ms** (Malay)
    * **nl** (Dutch)
    * **no** (Norwegian)
    * **pl** (Polish)
    * **pt** (Portuguese)
    * **ro** (Romanian)
    * **ru** (Russian)
    * **sw** (Swahili)
    * **sv** (Swedish)
    * **th** (Thai)
    * **tr** (Turkish)
    * **uk** (Ukrainian)
    * **vi** (Vietnamese)
    * **zh\_CN** (Chinese - Simplified)
    * **zh\_TW** (Chinese - Traditional)
  </Expandable>
</ResponseField>

<ResponseField name="savePartialSession" type="boolean">
  Requires [backendSyncMode](#backendsyncmode) = "FULL\_DATA"

  When enabled, Dromo will automatically save user progress throughout the import flow, allowing users to resume their session if they navigate away or close the browser.

  **Auto-Save Behavior:**

  * Progress is automatically saved to the backend with intelligent debouncing (\~700ms after changes)
  * Captures the complete state at each stage: upload, header selection, column matching, and data review
  * Includes column mappings, transformations, row data, and the uploaded file
  * Sessions are stored server-side and linked to a unique session identifier

  **Use Cases:**

  * Long-running imports where users may need to step away
  * Complex data mappings that take time to configure
  * Preventing data loss from accidental browser closures
  * Multi-session workflows where users return to complete imports later

  **Note:** Completed imports automatically clear their saved session data. Use [`hydrationId`](#hydrationid) for new integrations, or [`sessionId`](#sessionid) for the legacy flow, to restore a saved session. See the [Session Saving & Restoration Guide](/guides/saving-progress) for the full security model and API reference.

  ```javascript theme={null}
  settings: {
    backendSyncMode: "FULL_DATA",
    savePartialSession: true
  }
  ```
</ResponseField>

<ResponseField name="sessionId" type="string">
  Requires [backendSyncMode](#backendsyncmode) = "FULL\_DATA"

  Restores a previously saved import using the legacy session identifier. Sessions remain available for seven days after the most recent save.

  **Restoration Behavior:**

  * Fetches saved state from the backend using the raw session identifier and the widget's frontend license key
  * Validates that the session matches the current `importIdentifier`
  * Downloads and restores the uploaded file data
  * Rehydrates the UI to the exact stage where the user left off:
    * **Sheet Selection** → Returns to upload step
    * **Header Selection** → Restores headers and jumps to header selection
    * **Column Matching** → Restores mappings and jumps to column matching
    * **Data Review** → Restores full data grid and jumps to review step
  * Preserves all user work including mappings, transformations, and data edits

  For new integrations, prefer [`hydrationId`](#hydrationid), which avoids exposing the long-lived session identifier to the browser. Store `sessionId` on your backend so it can create a fresh hydration token when the user returns.

  **Use Cases:**

  * Resume workflows where users receive a session link to continue an import
  * Multi-step approval processes where different users complete different stages
  * Scheduled or delayed import completion

  **Note:** Use with [`savePartialSession`](#savepartialsession) enabled to create sessions that can be restored. See the [Session Saving & Restoration Guide](/guides/saving-progress) for the full token lifecycle and API reference.

  ```javascript theme={null}
  settings: {
    backendSyncMode: "FULL_DATA",
    sessionId: "1b6acf28-8748-4120-8d7a-4b7846d5e487"
  }
  ```
</ResponseField>

<ResponseField name="hydrationId" type="string">
  Requires [backendSyncMode](#backendsyncmode) = "FULL\_DATA"

  A short-lived signed access token used by the widget to create, read, update, and delete saved session state. The token identifies one session, so the widget does not need the raw `sessionId` when `hydrationId` is provided.

  Create a session from your backend with `POST /api/widget/session/v2/auth/`. When a user returns, mint a fresh token with `POST /api/widget/session/v2/{sessionId}/auth/`. Delete a session with `DELETE /api/widget/session/v2/{sessionId}/`.

  Hydration tokens default to a six-hour lifetime. Set `expires_in` in the create or resume API request to choose a different lifetime; this is an API parameter, not a widget setting. The underlying session expires seven days after its most recent save.

  <Warning>
    Call the session create, resume, and delete endpoints only from your backend with a backend license key. Pass the returned `hydrationId` to the widget, but never expose the backend key.
  </Warning>

  ```javascript theme={null}
  settings: {
    backendSyncMode: "FULL_DATA",
    savePartialSession: true,
    hydrationId: "<signed-token>"
  }
  ```

  See the [Session Saving & Restoration Guide](/guides/saving-progress) for the complete token lifecycle and API examples.
</ResponseField>


# Style Overrides
Source: https://developer.dromo.io/reference/settings/style-overrides

Customize the Dromo Uploader with your own CSS styles.

The Dromo Uploader supports custom CSS styling. You can use the `styleOverrides` prop to customize the appearance of the uploader.

<ResponseField name="styleOverrides" type="object">
  Specify custom CSS styling on any UI element to make it match your brand requirements.

  <Info>
    For a visual overlay of the available styling options, see the [guide to customizing styles](/guides/custom-styling).
  </Info>

  <div>
    <ResponseField name="global" type="object">
      Style overrides that affect the general UI of the Dromo Uploader

      <div>
        <ResponseField name="primaryTextColor" type="string">
          The primary text color
        </ResponseField>

        <ResponseField name="secondaryTextColor" type="string">
          The secondary text color
        </ResponseField>

        <ResponseField name="customFontURL" type="string">
          A URL to a custom font file
        </ResponseField>

        <ResponseField name="customFontFamily" type="string">
          The name of the font family provided by the custom font file
        </ResponseField>

        <ResponseField name="backgroundColor" type="string">
          Added in v2

          The background color of the modal
        </ResponseField>

        <ResponseField name="borderRadius" type="string">
          Added in v2

          The border radius of the modal
        </ResponseField>

        <ResponseField name="borderStyle" type="string">
          Added in v2

          The border style of the modal
        </ResponseField>

        <ResponseField name="borderWidth" type="string">
          Added in v2

          The border width of the modal
        </ResponseField>

        <ResponseField name="borderColor" type="string">
          Added in v2

          The border color of the modal
        </ResponseField>

        <ResponseField name="textColor" type="string">
          The general text color for UI elements
        </ResponseField>

        <ResponseField name="successColor" type="string">
          Color used for success states and messages
        </ResponseField>

        <ResponseField name="warningColor" type="string">
          Color used for warning states and messages
        </ResponseField>

        <ResponseField name="backdropBlur" type="boolean">
          Whether to apply a blur effect to the background when modals are open
        </ResponseField>
      </div>
    </ResponseField>

    <ResponseField name="primaryButton" type="object">
      Style overrides for the primary action button

      <div>
        <ResponseField name="borderRadius" type="string">
          The radius of the button
        </ResponseField>

        <ResponseField name="backgroundColor" type="string">
          The background color of the button
        </ResponseField>

        <ResponseField name="textColor" type="string">
          The color of the text in the button
        </ResponseField>

        <ResponseField name="border" type="string">
          The `border` shorthand property to apply to the button
        </ResponseField>

        <ResponseField name="hoverBackgroundColor" type="string">
          The background color of the button while hovering
        </ResponseField>

        <ResponseField name="hoverTextColor" type="string">
          The text color of the button while hovering
        </ResponseField>

        <ResponseField name="hoverBorder" type="string">
          The `border` shorthand property to apply to the button while hovering
        </ResponseField>

        <ResponseField name="disabledBackgroundColor" type="string">
          The background color of the button when it is disabled
        </ResponseField>

        <ResponseField name="disabledTextColor" type="string">
          The text color of the button when it is disabled
        </ResponseField>

        <ResponseField name="padding" type="string">
          The padding of the button
        </ResponseField>
      </div>
    </ResponseField>

    <ResponseField name="secondaryButton" type="object">
      Style overrides for the secondary action button

      <div>
        <ResponseField name="borderRadius" type="string">
          The radius of the button
        </ResponseField>

        <ResponseField name="backgroundColor" type="string">
          The background color of the button
        </ResponseField>

        <ResponseField name="textColor" type="string">
          The color of the text in the button
        </ResponseField>

        <ResponseField name="border" type="string">
          The `border` shorthand property to apply to the button
        </ResponseField>

        <ResponseField name="hoverBackgroundColor" type="string">
          The background color of the button while hovering
        </ResponseField>

        <ResponseField name="hoverTextColor" type="string">
          The text color of the button while hovering
        </ResponseField>

        <ResponseField name="hoverBorder" type="string">
          The `border` shorthand property to apply to the button while hovering
        </ResponseField>

        <ResponseField name="disabledBackgroundColor" type="string">
          The background color of the button when it is disabled
        </ResponseField>

        <ResponseField name="disabledTextColor" type="string">
          The text color of the button when it is disabled
        </ResponseField>

        <ResponseField name="padding" type="string">
          The padding of the button
        </ResponseField>
      </div>
    </ResponseField>

    <ResponseField name="tertiaryButton" type="object">
      Style overrides for the tertiary action button

      <div>
        <ResponseField name="borderRadius" type="string">
          The radius of the button
        </ResponseField>

        <ResponseField name="backgroundColor" type="string">
          The background color of the button
        </ResponseField>

        <ResponseField name="textColor" type="string">
          The color of the text in the button
        </ResponseField>

        <ResponseField name="border" type="string">
          The `border` shorthand property to apply to the button
        </ResponseField>

        <ResponseField name="hoverBackgroundColor" type="string">
          The background color of the button while hovering
        </ResponseField>

        <ResponseField name="hoverTextColor" type="string">
          The text color of the button while hovering
        </ResponseField>

        <ResponseField name="hoverBorder" type="string">
          The `border` shorthand property to apply to the button while hovering
        </ResponseField>

        <ResponseField name="disabledBackgroundColor" type="string">
          The background color of the button when it is disabled
        </ResponseField>

        <ResponseField name="disabledTextColor" type="string">
          The text color of the button when it is disabled
        </ResponseField>

        <ResponseField name="padding" type="string">
          The padding of the button
        </ResponseField>
      </div>
    </ResponseField>

    <ResponseField name="dropzone" type="object">
      Style overrides for the file dropzone on the upload screen

      <div>
        <ResponseField name="borderWidth" type="number">
          The width of the dropzone border in pixels
        </ResponseField>

        <ResponseField name="borderRadius" type="number">
          The radius of the dropzone border in pixels
        </ResponseField>

        <ResponseField name="borderColor" type="string">
          The color of the dropzone border
        </ResponseField>

        <ResponseField name="borderStyle" type="string">
          The style of the dropzone border
        </ResponseField>

        <ResponseField name="backgroundColor" type="string">
          The background color of the dropzone
        </ResponseField>

        <ResponseField name="color" type="string">
          The text color of the dropzone message
        </ResponseField>

        <ResponseField name="outline" type="string">
          The outline property of the dropzone
        </ResponseField>

        <ResponseField name="activeBorderColor" type="string">
          The border color while a file is being dragged over the dropzone
        </ResponseField>

        <ResponseField name="acceptBorderColor" type="string">
          The border color when the dragged file can be accepted
        </ResponseField>

        <ResponseField name="rejectBorderColor" type="string">
          The border color when the dragged file cannot be accepted
        </ResponseField>
      </div>
    </ResponseField>

    <ResponseField name="helpText" type="object">
      Style overrides for the help text boxes

      <div>
        <ResponseField name="textColor" type="string">
          The text color of the help text
        </ResponseField>

        <ResponseField name="backgroundColor" type="string">
          The background color of the help text box
        </ResponseField>
      </div>
    </ResponseField>

    <ResponseField name="stepperBar" type="object">
      Style overrides for the progress bar in the header

      <div>
        <ResponseField name="completeColor" type="string">
          The color of completed steps
        </ResponseField>

        <ResponseField name="incompleteColor" type="string">
          The color of steps that have not been started yet
        </ResponseField>

        <ResponseField name="currentColor" type="string">
          The color of the step currently in progress
        </ResponseField>

        <ResponseField name="fontSize" type="string">
          Added in v2

          The font size of the step text
        </ResponseField>

        <ResponseField name="completeFontWeight" type="string">
          Added in v2

          The font weight of completed steps
        </ResponseField>

        <ResponseField name="incompleteFontWeight" type="string">
          Added in v2

          The font weight of incomplete steps
        </ResponseField>

        <ResponseField name="currentFontWeight" type="string">
          Added in v2

          The font weight of the current step
        </ResponseField>

        <ResponseField name="backgroundColor" type="string">
          Added in v2

          The background color of the stepper bar
        </ResponseField>

        <ResponseField name="borderBottom" type="string">
          Added in v2

          The bottom border separating the stepper bar from the rest of the modal
        </ResponseField>
      </div>
    </ResponseField>

    <ResponseField name="dataTable" type="object">
      Style overrides for the data table (Handsontable) component

      <div>
        <ResponseField name="headerFontWeight" type="string">
          The font weight of column headers
        </ResponseField>

        <ResponseField name="headerBackgroundColor" type="string">
          The background color of column headers
        </ResponseField>

        <ResponseField name="headerTextColor" type="string">
          The text color of column headers
        </ResponseField>

        <ResponseField name="rowHeaderBackgroundColor" type="string">
          The background color of row headers (row numbers)
        </ResponseField>

        <ResponseField name="rowHeaderTextColor" type="string">
          The text color of row headers (row numbers)
        </ResponseField>

        <ResponseField name="cornerHeaderBackgroundColor" type="string">
          The background color of the corner header (top-left cell)
        </ResponseField>

        <ResponseField name="cellSelectionBorderColor" type="string">
          The border color of selected cells
        </ResponseField>

        <ResponseField name="cellSelectionBackgroundColor" type="string">
          The background color of selected cells
        </ResponseField>

        <ResponseField name="accentColor" type="string">
          General accent color that affects various interactive elements in the table
        </ResponseField>

        <ResponseField name="headerActiveBackgroundColor" type="string">
          The background color of active column headers
        </ResponseField>

        <ResponseField name="headerActiveTextColor" type="string">
          The text color of active column headers
        </ResponseField>

        <ResponseField name="headerHighlightedBackgroundColor" type="string">
          The background color of highlighted column headers
        </ResponseField>

        <ResponseField name="headerHighlightedTextColor" type="string">
          The text color of highlighted column headers
        </ResponseField>

        <ResponseField name="cellBackgroundColor" type="string">
          The background color of body cells
        </ResponseField>

        <ResponseField name="cellTextColor" type="string">
          The text color of body cells
        </ResponseField>

        <ResponseField name="cellHoverBackgroundColor" type="string">
          The background color of a hovered cell
        </ResponseField>

        <ResponseField name="cellHoverTextColor" type="string">
          The text color of a hovered cell
        </ResponseField>

        <ResponseField name="oddRowBackgroundColor" type="string">
          The background color of alternating odd rows
        </ResponseField>

        <ResponseField name="rowSelectedBackgroundColor" type="string">
          The background color of a selected row
        </ResponseField>

        <ResponseField name="rowSelectedBorderColor" type="string">
          The border color of a selected row
        </ResponseField>

        <ResponseField name="borderColor" type="string">
          The outer border color of the table
        </ResponseField>

        <ResponseField name="dividerColor" type="string">
          The color of grid lines between rows and columns
        </ResponseField>

        <ResponseField name="errorCellBackgroundColor" type="string">
          The background color of cells with error messages
        </ResponseField>

        <ResponseField name="errorCellHoverBackgroundColor" type="string">
          The hover background color of cells with error messages
        </ResponseField>

        <ResponseField name="warningCellBackgroundColor" type="string">
          The background color of cells with warning messages
        </ResponseField>

        <ResponseField name="warningCellHoverBackgroundColor" type="string">
          The hover background color of cells with warning messages
        </ResponseField>

        <ResponseField name="infoCellBackgroundColor" type="string">
          The background color of cells with informational messages
        </ResponseField>

        <ResponseField name="infoCellHoverBackgroundColor" type="string">
          The hover background color of cells with informational messages
        </ResponseField>

        <ResponseField name="readOnlyCellBackgroundColor" type="string">
          The background color of read-only cells
        </ResponseField>

        <ResponseField name="readOnlyCellTextColor" type="string">
          The text color of read-only cells
        </ResponseField>
      </div>
    </ResponseField>

    <ResponseField name="modalOverlay" type="object">
      Style overrides for modal overlay backdrop

      <div>
        <ResponseField name="backgroundColor" type="string">
          The background color of the modal overlay
        </ResponseField>

        <ResponseField name="opacity" type="string">
          The opacity of the modal overlay (0-100)
        </ResponseField>
      </div>
    </ResponseField>

    <ResponseField name="card" type="object">
      Style overrides for cards used in column matching and other importer screens.

      <div>
        <ResponseField name="backgroundColor" type="string">The card background color</ResponseField>
        <ResponseField name="containerBackgroundColor" type="string">The background color of the area containing cards</ResponseField>
        <ResponseField name="borderColor" type="string">The card border color</ResponseField>
        <ResponseField name="borderWidth" type="string">The card border width</ResponseField>
        <ResponseField name="borderRadius" type="string">The card border radius</ResponseField>
        <ResponseField name="textColor" type="string">The card text color</ResponseField>
        <ResponseField name="expandedBackgroundColor" type="string">The background color of expanded cards</ResponseField>
        <ResponseField name="iconColor" type="string">The color of icons in cards</ResponseField>
      </div>
    </ResponseField>

    <ResponseField name="dropdown" type="object">
      Style overrides for select controls and dropdown menus.

      <div>
        <ResponseField name="backgroundColor" type="string">The background color of the closed control</ResponseField>
        <ResponseField name="borderColor" type="string">The control border color</ResponseField>
        <ResponseField name="textColor" type="string">The selected value text color</ResponseField>
        <ResponseField name="errorBorderColor" type="string">The control border color in an error state</ResponseField>
        <ResponseField name="menuBackgroundColor" type="string">The background color of the open menu</ResponseField>
        <ResponseField name="optionHoverBackgroundColor" type="string">The background color of a hovered option</ResponseField>
        <ResponseField name="optionSelectedBackgroundColor" type="string">The background color of the selected option</ResponseField>
      </div>
    </ResponseField>

    <ResponseField name="errorNavigator" type="object">
      Style overrides for the Error Navigator panel shown during the Review Step when [`enableNavigatingErrors`](/reference/settings/settings#enablenavigatingerrors) is `true`. All color values accept any valid CSS color string (hex, rgb, hsl, CSS variables, etc.).

      <div>
        <ResponseField name="errorColor" type="string">
          Color applied to error-level indicator icons, error message text, and the error issue count badge.
        </ResponseField>

        <ResponseField name="warningColor" type="string">
          Color applied to warning-level indicator icons and warning message text.
        </ResponseField>

        <ResponseField name="accentColor" type="string">
          Color applied to the primary action buttons ("Replace", "Apply") and the active column filter chip border and text.
        </ResponseField>

        <ResponseField name="errorIconUrl" type="string | null">
          URL of a custom image to display in place of the default exclamation circle icon for error rows. The image renders at 12×12 px with `object-contain`. Set to `null` to use the default icon.
        </ResponseField>

        <ResponseField name="warningIconUrl" type="string | null">
          URL of a custom image to display in place of the default exclamation circle icon for warning rows. The image renders at 12×12 px with `object-contain`. Set to `null` to use the default icon.
        </ResponseField>
      </div>

      ```javascript theme={null}
      styleOverrides: {
        errorNavigator: {
          errorColor: "#B91C1C",
          warningColor: "#D97706",
          accentColor: "#6366F1",
          errorIconUrl: "https://cdn.example.com/error-icon.svg",
          warningIconUrl: null,
        }
      }
      ```
    </ResponseField>
  </div>
</ResponseField>


# The User Object
Source: https://developer.dromo.io/reference/users

Attach metadata about the end user launching a Dromo import with the user object and receive it alongside completed upload data.

This data will be stored alongside finished uploads, and is provided as a convenience to more easily identify the end user behind each upload. The DromoUploader does not utilize this data in any way, so you may supply arbitrary values for any key.

<ResponseField name="id" type="string">
  Unique identifier for the user
</ResponseField>

<ResponseField name="name" type="string">
  Display name of the user
</ResponseField>

<ResponseField name="email" type="string">
  Email address of the user
</ResponseField>

<ResponseField name="companyId" type="string">
  Unique identifier for the user's company
</ResponseField>

<ResponseField name="companyName" type="string">
  Name of the user's company
</ResponseField>


# Webhooks
Source: https://developer.dromo.io/reference/webhooks

You can use webhooks to get notified when your users complete an import using Dromo.

Dromo provides two kinds of webhooks:

* **Managed Webhooks** are managed in the Dromo dashboard. They provide context about the completed import, and can be applied to multiple schemas.
* **Basic webhooks** are configured by setting the [webhookUrl setting](/reference/settings/settings#webhookurl) in your import settings. This webhook can be configured dynamically at the time of import.

## Managed webhooks

Managed webhooks are configured in the dashboard on the [webhooks page](https://dashboard.dromo.io/webhooks). Click on the "New webhook" button to create your first webhook.

<img alt="Creating a new managed webhook" />

There are a few things to specify:

* **URL**: Provide a publicly accessible URL where the webhook should be sent.
* **Development Mode**: Toggle this setting to control whether the webhook fires for development imports or production imports, based on the developmentMode flag. This is helpful for testing webhooks in staging environments.
* **Schemas to Trigger On**: Choose when the webhook should be triggered using either or both of the following:
  * **Import Identifiers**: A list of importIdentifier values. The webhook will fire whenever an import with a matching identifier completes. Useful for dynamic imports.
  * **Saved Schemas**: Select from your predefined schemas in Schema Studio.

You can mix import identifiers and saved schemas as needed.

The next time an import is completed for a matching schema, you will receive a POST request like the following:

<CodeGroup>
  ```json theme={null}
  {
    "event": "import_completed", 
    "data": {
      "id": "025f399f-4370-4064-aed5-b8d16b597183",
      "filename": "contacts.csv", 
      "user": {
        "id": "user-123",
        "name": "Jasmine Clark",
        "email": "jclark@acme.com",
        "company_id": null,
        "company_name": null
      },
      "created_date": "2024-04-24T17:20:14.659349Z",
      "import_type": "EMBEDDED",
      "status": "SUCCESSFUL",
      "num_data_rows": 433,
      "development_mode": false,
      "has_data": true
    }
  }
  ```
</CodeGroup>

To get more details about the parameters, expand the following section:

<Expandable title="more about fields in the webhook">
  <ResponseField name="event" type="string">
    The event that triggered this webhook. Currently, this will always be `"import_completed"` unless your organization is using Dromo Headless (see below).
  </ResponseField>

  <ResponseField name="data" type="object">
    <ResponseField name="id" type="string">
      The id of the import. You can use this ID with the Dromo Imports API.
    </ResponseField>

    <ResponseField name="filename" type="string | null">
      The filename of the file uploaded by the user. This will be `null` if manual input or [initialData](/reference/settings/settings#initialdata) was used.
    </ResponseField>

    <ResponseField name="user" type="User">
      The user metadata supplied with this import
    </ResponseField>

    <ResponseField name="created_date" type="string">
      The completion time of the import, in ISO-8601 format
    </ResponseField>

    <ResponseField name="import_type" type="string">
      `"HEADLESS"` if the import was a Headless import, otherwise `"EMBEDDED"`
    </ResponseField>

    <ResponseField name="status" type="string">
      For standard (embedded) imports, currently will always be `"SUCCESSFUL"`. See below for Headless.
    </ResponseField>

    <ResponseField name="num_data_rows" type="number">
      The number of rows in the completed import
    </ResponseField>

    <ResponseField name="development_mode" type="boolean">
      Whether this import was completed in development mode
    </ResponseField>

    <ResponseField name="has_data" type="boolean">
      Whether the results of this import were saved using [backend sync](/reference/settings/settings#backendsyncmode).

      If `true`, you can fetch the import results using the [get import data endpoint](/api-reference/uploads/get-upload-metadata).
    </ResponseField>
  </ResponseField>
</Expandable>

<Note>
  When using managed webhooks with headless imports, Dromo exposes two additional events and data in the webhook:

  * A `"headless_import_needs_review"` event is triggered when a headless import enters the [needs review state](/getting-started/headless#import-needs-review).
  * A `"headless_import_failed"` event is triggered when a headless import encounters an unrecoverable error and goes to the [failed state](/getting-started/headless#import-failed).

  Completed headless imports, whether fully automated or completed using manual review, will trigger the standard `"import_completed"` event as detailed above.

  All headless import webhooks include an additional `"headless"` key in the `data` object. This will include data about the headless import in a format matching the [retrieve headless import endpoint](/api-reference/headless/retrieve-headless-import), with the exception that `"review_url"` and `"original_file_download"` are not exposed in the webhook for security reasons.
</Note>

## Basic webhooks

Basic webhooks are triggered when an import is completed, when the settings for that import included a [webhookUrl](/reference/settings/settings#webhookurl).

The webhooks are delivered to the configured URL via POST request in URL-encoded form format, and contain only a single key, `uploadId`.

<CodeGroup>
  ```sh theme={null}
  uploadId=7df3a66d-b7bb-4da6-9244-b4e22c7d7ab0
  ```
</CodeGroup>

This key can be used to fetch import data and metadata using the [Dromo API](https://developer.dromo.io/api#tag/uploads).


# Welcome to Dromo
Source: https://developer.dromo.io/welcome

Learn how Dromo helps applications import spreadsheets with column matching, validation, transformations, and clean structured results.

Dromo is an easy and intuitive spreadsheet importer that integrates seamlessly with your product. Dromo helps your users match columns, correct errors, perform complex validations, transform values, and upload perfectly formatted data.

<Card title="🚀 Try Our Live Demo" icon="play" href="https://demo.dromo.io">
  Experience Dromo with realistic data and see how easy data importing can be
</Card>

## Quick Start

Get up and running with Dromo in minutes. Choose the integration that works best for your stack:

<CardGroup>
  <Card title="JavaScript SDK" icon="js" href="/getting-started/javascript">
    Universal JavaScript implementation for any web application
  </Card>

  <Card title="React Component" icon="react" href="/getting-started/react">
    Pre-built React component with TypeScript support
  </Card>

  <Card title="Angular Component" icon="angular" href="/getting-started/angular">
    Native Angular implementation with full type safety
  </Card>

  <Card title="Schema Builder" icon="wrench" href="/guides/schema-builder">
    No-code schema creation in the Dromo Dashboard
  </Card>
</CardGroup>

## See Dromo in Action

<iframe />

## How Dromo Works

<Steps>
  <Step title="Define Your Schema">
    Specify the fields you want to import using our [Schema Builder](/guides/schema-builder) or define them programmatically with our SDKs.
  </Step>

  <Step title="Add Validations">
    Configure [validation rules](/fields) and [transformation hooks](/reference/hooks) to ensure data quality and provide real-time feedback.
  </Step>

  <Step title="Handle Results">
    Receive clean, validated JSON data that's ready to use in your application or database.
  </Step>

  <Step title="Customize Experience">
    Brand the importer to match your application with custom styling and user experience settings.
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Interactive Sandbox" icon="laptop-code" href="https://codesandbox.io/s/ux-demo-react-yez5e2">
    Explore a fully customized Dromo implementation
  </Card>

  <Card title="Get Help" icon="life-ring" href="mailto:support@dromo.io">
    Our team is here to help you succeed
  </Card>
</CardGroup>

<Note>
  **Questions?** Chat with us anytime using the chat bubble, or email us at [support@dromo.io](mailto:support@dromo.io).
</Note>