API Reference

Complete reference for the ImportWidget component props.

ImportWidget Props

Field Type

interface Field {
  name: string;        // Field identifier (used in output)
  label: string;       // Display label
  required?: boolean;  // Is this field required?
  type?: 'text' | 'email' | 'number' | 'date' | 'enum';
  enum?: EnumDefinition;
  validate?: ValidationRule[];
}

ValidationRule Type

interface ValidationRule {
  type: 'email' | 'number' | 'regex' | 'min' | 'max' |
        'minLength' | 'maxLength' | 'oneOf';
  value?: string | number | string[];
  message?: string;  // Custom error message
}

Validation Rule Details

All rules support an optional message property for custom error text.

EnumDefinition Type

interface EnumDefinition {
  values: string[];      // Allowed values
  hints?: string[];      // AI synonym hints (e.g. "active: enabled, on, yes")
  allowEmpty?: boolean;  // Allow empty/null values
  defaultValue?: string; // Default when no match found
}

Enum fields use a 6-step AI matching pipeline: exact match, case-insensitive match, customer learned mappings, global learned mappings, hint-based matching, and AI semantic matching. Each match includes a confidence score displayed in the value mapping review UI.

Editable Preview Cells

In the preview step, all cells are clickable for inline editing. This allows users to fix validation errors before importing without going back to their spreadsheet.

• Click any cell to start editing inline
• Real-time validation runs on a 300ms debounce as you type
• A green flash animation appears when an error is successfully fixed
• Keyboard navigation: Tab (next cell), Shift+Tab (previous cell), Enter (next row), Escape (cancel edit)
• All edits are preserved and used for the final import

Webhooks

Webhook delivery happens on import completion for Pro and Enterprise plans. Configure webhook endpoints in the dashboard under Webhooks.

Payload Format

{
  "event": "import.completed",
  "importId": "imp_abc123",
  "rowCount": 150,
  "templateName": "contacts",
  "timestamp": "2026-02-06T12:00:00Z"
}

• Webhooks are delivered to all active endpoints via POST
• Your endpoint should return a 200 status to acknowledge receipt
• Requires Pro or Enterprise tier

Theme Type

interface ImportWidgetTheme {
  primaryColor?: string;    // default: '#3b82f6'
  successColor?: string;    // default: '#10b981'
  errorColor?: string;      // default: '#ef4444'
  borderColor?: string;     // default: '#e2e8f0'
  borderRadius?: string;    // default: '8px'
  fontFamily?: string;      // default: system-ui
  fontSize?: string;        // default: '14px'
}

Output Data Format

The onComplete callback receives an array of objects, where each object has keys matching your field names:

// For fields: [{ name: 'email' }, { name: 'name' }]
// Output:
[
  { email: 'alice@example.com', name: 'Alice Smith' },
  { email: 'bob@example.com', name: 'Bob Jones' },
]

Relay Mode

When useDestination is enabled, ImportKit sends the imported data server-side to your configured API destination instead of returning raw rows to the browser. This is useful for large imports or when you want to avoid exposing your backend endpoint to the client.

Configure your destination URL and headers in the ImportKit dashboard under Settings → Destinations. The widget will POST the imported rows to your endpoint in batches.

RelayResult Interface

interface RelayResult {
  success: boolean;       // Whether the relay completed successfully
  totalRows: number;      // Total rows sent
  acceptedRows: number;   // Rows accepted by destination
  rejectedRows: number;   // Rows rejected by destination
  destinationResponse?: {
    status: number;       // HTTP status from your API
    body?: unknown;       // Response body from your API
  };
}

When relay is active, onComplete receives a RelayResult object instead of an ImportedRow[] array:

<ImportWidget
  apiKey="ik_live_..."
  templateId="tpl_contacts"
  useDestination={true}
  onComplete={(result: RelayResult) => {
    if (result.success) {
      console.log(`Sent ${result.totalRows} rows to destination`);
      console.log(`Accepted: ${result.acceptedRows}`);
    } else {
      console.error('Relay failed', result.destinationResponse);
    }
  }}
/>

• Relay mode requires a Pro or Enterprise plan
• You must configure a destination in the dashboard before enabling relay
• The destination endpoint must accept POST requests with JSON body
• Rows are sent in batches of up to 1,000 rows per request