Import Leads

Bulk import leads from CSV or Sheets with field mapping and round-robin distribution.

Overview

Import Leads lets you bulk add or update leads from a CSV/XLSX file directly into your Dashboard. You'll upload a file, map your columns to Kraya fields, preview how many records will be created vs updated, pick a target Pipeline and Stage (or use Round Robin distribution), optionally assign an Auto Followup sequence, and run the import in the background.

This feature is useful when you have lead data in spreadsheets and want to bulk import it into Kraya without manual entry.

What you can do

Bulk import leads from CSV/XLSX files (up to 25,000 rows per upload)
Map your file's columns to Kraya fields (Name, Email, Phone, and custom attributes)
Use "Do Not Import" for any column you want to skip
Preview how many leads will be created vs updated before submitting (dry-run)
Choose the target Pipeline and Stage for imported leads (required, unless using Round Robin)
Optionally use Round Robin distribution to automatically assign leads to sales pipelines
Optionally assign an Auto Followup sequence as part of the import
Create new custom attributes during mapping if needed
Choose whether to update existing leads or skip them
Run the import as a background job while you continue working

How it works (user-facing)

Upload: You upload a CSV/XLSX file with a header row
Column mapping: Kraya suggests a column mapping for commonly named fields using similarity matching; you can adjust each column or set it to "Do Not Import"
Preview: Preview shows a dry-run count of how many leads would be created vs updated based on your mapping
Matching rules: Existing leads are matched by email and/or phone; phone numbers are normalized (non-digits removed, 10-digit numbers get "91" prepended)
Pipeline/Stage selection: You must select a Pipeline and Stage (unless using Round Robin). Imported leads (both new and matched) will be placed in that selection
Round Robin (optional): Instead of selecting a pipeline/stage, you can choose Round Robin distribution to automatically assign leads to sales pipelines
Sequence assignment (optional): Optionally assign an Auto Followup sequence; this will set or update the sequence for the imported leads
Update existing leads (optional): Choose whether to update existing leads or skip them (only create new ones)
Background processing: After you submit, a banner confirms that "Import is in progress." You can safely navigate away; processing continues in the background. Check the target Stage to see results

Step-by-step guide

Open the Dashboard
- Click Import (top actions near bulk update/export)
Upload your file (CSV or XLSX)
- Drag and drop or select your file
- Ensure the first row is headers (Name, Email, Phone, etc.)
- Maximum file size: 25,000 rows per upload
Map your columns
- For each column, pick the Kraya field it should populate. Use "Do Not Import" to skip a column
- Kraya auto-suggests mappings based on column name similarity (e.g., "Phone Number" → "phone", "E-mail" → "email")
- Need a new attribute? Choose "Create New Attribute" option during mapping, enter the attribute name, and it will be created
- Tips:
  - Map at least Phone (recommended). Email is optional but helps with matching
  - Use clear header names so auto-mapping works better
  - Custom attributes must match existing attributes (case-insensitive) or be created during mapping
Preview (dry-run)
- Click Preview to see how many rows will create new leads vs update existing ones
- Preview processes the file in chunks and matches against existing leads
- If counts look off, review your mapping—especially Phone and Email
- Preview shows: Total creates, Total updates
Choose Pipeline & Stage (required, unless using Round Robin)
- Select the Pipeline and Stage where you want these leads to be placed
- This applies to both newly created and matched (updated) leads
- You must have access to the selected pipeline
Optional: Round Robin Distribution
- Instead of selecting a pipeline/stage, you can choose Round Robin distribution
- Leads will be automatically assigned to sales pipelines based on Round Robin configuration
- Only works if Round Robin is configured for your organization
Optional: Assign an Auto Followup Sequence
- Pick a sequence to assign to these leads now
- You can change or clear sequences later from the Dashboard/Extension
- Sequence must be active
Optional: Update existing leads
- Choose whether to update existing leads or skip them (only create new ones)
- If unchecked, existing leads are skipped (not updated)
- If checked, existing leads are updated with new data from the import
Submit the import
- Click Import. You'll see a banner that the import is in progress
- You can continue working or navigate away; processing runs in the background
- Import is processed in chunks of 2,500 rows
Verify results
- Open the target Pipeline/Stage to see the imported and updated leads
- Use search/filters if you're importing a large batch
- Check that custom attributes were created/updated correctly

File requirements

Formats: CSV and XLSX (Excel files)
Maximum size: Up to 25,000 rows per upload
Header row: Required (first row should contain column names)
Encoding: UTF-8 recommended
Recommended fields per row:
- Phone: Required (to message via WhatsApp). Should include country code or be 10 digits (will get "91" prepended)
- Email: Optional (helps with matching existing leads)
- Name: Optional (recommended for better lead management)

Column mapping

Auto-mapping:

Kraya automatically suggests mappings based on column name similarity
Uses fuzzy matching to match common variations (e.g., "Phone Number", "Phone", "Mobile" → "phone")
You can adjust any mapping manually

Default fields:

Name: Maps to lead's name field
Email: Maps to lead's email field
Phone: Maps to lead's phone field

Custom attributes:

Unmapped headers are not auto-created as attributes
If you need a new attribute, use "Create New Attribute" option during mapping
New attributes are created immediately and can be used in the same import
Custom attributes must match existing attributes (case-insensitive) or be created during mapping
Maximum custom attributes per organization: 10 on the free plan, 50 on paid plans. If you reach the cap while mapping, you'll see "Max attributes limit reached (50)" and the "Create New Attribute" option is blocked until you remove an existing attribute.

"Do Not Import":

Use this to skip any column completely
Skipped columns are not processed

Mapping validation:

At least Phone or Email must be mapped (recommended: Phone)
Name mapping is recommended but not required
All columns must be mapped or set to "Do Not Import" before proceeding

Matching logic (updates vs creates)

Matching rules:

Existing leads are matched by Phone and/or Email
Phone numbers are normalized: non-digit characters are removed, then 10-digit numbers get "91" prepended
Email matching is case-insensitive
If both phone and email are provided, phone-based matching takes precedence
Matching is done after normalization, so "9876543210" and "91-9876-543210" will match the same lead

Update vs create:

If a match is found (by phone or email) → the lead is updated
If no match is found → a new lead is created
If "Update existing leads" is unchecked, existing leads are skipped (not updated)

Within-file duplicates:

Duplicate rows for the same phone/email are de-duplicated during processing
Only the first valid occurrence is used
Subsequent duplicates are skipped

Priority:

If both phone and email are present, phone-based matching generally takes precedence
If phone matches but email doesn't, the lead is still matched by phone
If email matches but phone doesn't, the lead is matched by email

Phone number normalization

Process:
- Non-digit characters are removed first (spaces, dashes, parentheses, etc.)
- If the resulting number is 10 digits, "91" is prepended (default country code)
- Example: "9876543210" → "919876543210"
- Example: "91-9876-543210" → "919876543210"
Matching: Leads are matched by normalized phone number
Validation: Phone numbers must be 7-15 digits after normalization
Invalid phones: Rows with invalid phone numbers (after normalization) are skipped

Custom attribute creation

During mapping: You can create new custom attributes by selecting "Create New Attribute" for any unmapped column
Attribute name: Enter the attribute name (case-sensitive, but matching is case-insensitive)
Immediate availability: New attributes are created immediately and can be used in the same import
Limits: Maximum custom attributes per organization: 10 on the free plan, 50 on paid plans
Sync: New attributes are automatically synced to all existing leads (background job)
Case-insensitive matching: Attribute matching is case-insensitive, but the original case is preserved

Round Robin distribution

Option: Instead of selecting a pipeline/stage, you can choose Round Robin distribution
How it works: Leads are automatically assigned to sales pipelines based on Round Robin configuration
Requirements:
- Round Robin must be enabled at the organization level
- At least one Sales pipeline must be enabled for Round Robin (the RR pool)
- Each participating Sales pipeline has a target stage (defaults to "New Lead")
Behavior:
- Leads are distributed sequentially across the Sales pipelines in the pool, in rotation order
- Each lead lands in the next Sales pipeline's RR target stage; that pipeline's owner effectively owns it (Round Robin rotates across pipelines, not individual agents)
- If Round Robin assignment fails (empty pool, no valid target stage), the lead is skipped (not created/updated)
Sequence assignment: Auto Followup sequences can still be assigned when using Round Robin

Limits & behavior

Upload limit: 25,000 rows per import
Pipeline & Stage selection: Required to start the import (unless using Round Robin)
Placement:
- All imported leads (new and existing matches) are placed into the selected Pipeline/Stage
- With Round Robin, leads are distributed across configured pipelines
Auto Followups:
- If you select a sequence, it will be assigned to the imported leads
- You can edit/clear sequences later from the Dashboard/Extension
- Sequence must be active
Background processing:
- Import runs as a background job
- You'll see an "Import in progress" banner
- Processing happens in chunks of 2,500 rows
- You can navigate away and continue working
- There is no separate history list; check your target Stage to review results
Phone formatting:
- Phone numbers are normalized (non-digits removed)
- 10-digit numbers get "91" prepended automatically
- Provide a clean, valid number (with country code) for best results
Email validation:
- Invalid emails are silently set to null (don't cause import to fail)
- Email matching is case-insensitive
Custom attributes:
- Maximum custom attributes per organization: 10 on the free plan, 50 on paid plans
- New attributes are created immediately during import
- Attributes are synced to all existing leads (background job)
Chunking:
- Preview processes in chunks of 10,000 rows
- Import processes in chunks of 2,500 rows
- Large imports may take several minutes to complete

Common edge cases and how to handle them

"Import didn't start" or button disabled
- Ensure you selected both Pipeline and Stage (unless using Round Robin)
- Confirm you mapped at least Phone (recommended)
- Check that all columns are mapped or set to "Do Not Import"
Preview shows 0 creates and 0 updates
- Check column mapping—especially Phone and Email
- Make sure the file has a header row and data rows
- Verify phone numbers are in valid format (7-15 digits after normalization)
- Check that email addresses are valid (if email is mapped)
"Pipeline not found" or access issues
- You may not have access to the selected pipeline
- Ask your org admin to grant access or pick a pipeline you own
- Verify the pipeline exists and is active
Rows with missing/invalid phone numbers
- Phone is required for matching
- Fix formatting (digits only, include country code or use 10 digits)
- Invalid phone numbers (after normalization) are skipped
- Rows with invalid phones won't create or update leads
Custom attribute not available in the list
- Use the "Create New Attribute" option during mapping
- Enter the attribute name and it will be created immediately
- Then re-map the column to the newly created attribute
- Check if you've reached your plan's custom attribute limit (10 on the free plan, 50 on paid plans)
Imported leads are not visible
- Open the selected Pipeline/Stage and refresh
- Use search/filters to locate recent imports
- Check if the import is still in progress (banner should show status)
- Verify you're looking in the correct pipeline/stage
Large imports feel slow
- Import processes in chunks of 2,500 rows
- Large imports (25,000 rows) may take 10-15 minutes
- You can navigate away and continue working
- Check the target Stage after a few minutes
Round Robin distribution not working
- Verify Round Robin is enabled at the organization level
- Check that at least one Sales pipeline is enabled for Round Robin (the RR pool)
- Confirm each participating pipeline has a valid RR target stage
- If Round Robin assignment fails, leads are skipped (not created/updated)
Custom attributes not saving
- Verify attribute names match existing attributes (case-insensitive)
- Check that you created the attribute during mapping if it's new
- Ensure you haven't reached your plan's custom attribute limit (10 on the free plan, 50 on paid plans)
- New attributes are synced to all existing leads (background job, may take a few minutes)
Email not updating
- Invalid email formats are silently set to null (don't cause import to fail)
- Check that email addresses are in valid format (e.g., user@example.com)
- Email matching is case-insensitive
Duplicate leads created
- Verify phone numbers are normalized correctly (10-digit numbers get "91" prepended)
- Check that phone numbers include country code or are 10 digits
- Within-file duplicates are de-duplicated (only first occurrence is used)
- Existing leads are matched by normalized phone number

Troubleshooting

Decision tree: Import won't start

Did you select both Pipeline and Stage (or Round Robin)?
- No → Select both and retry (or choose Round Robin)
- Yes → Is Phone mapped?
  - No → Map Phone and retry
  - Yes → Are all columns mapped or set to "Do Not Import"?
    - No → Map all columns and retry
    - Yes → Try a smaller sample file (10-50 rows) to validate mapping

Decision tree: Preview counts look wrong

Is the header row correct and unique?
- No → Fix headers and retry
- Yes → Are Phone/Email columns mapped correctly?
  - No → Re-map correctly and preview again
  - Yes → Check for unexpected delimiters/encoding; re-save the CSV/XLSX and retry
  - Yes → Verify phone numbers are in valid format (7-15 digits after normalization)

Decision tree: I don't see the imported leads

Is the banner still showing "Import in progress"?
- Yes → Wait a few minutes; then refresh the Dashboard
- No → Open the selected Pipeline/Stage and search for a known phone/email from the file
- No → Check if Round Robin was used (leads may be in different pipelines)

Decision tree: Custom attribute mapping failed

Did you create the attribute during mapping?
- No → Create it during mapping and re-map the column
- Yes → Re-open mapping and re-select the newly created attribute
- Yes → Check if you've reached your plan's custom attribute limit (10 on the free plan, 50 on paid plans)

Decision tree: Round Robin not working

Is Round Robin enabled at the organization level?
- No → Enable org-level Round Robin first
- Yes → Are Sales pipelines enabled for Round Robin?
  - No → Enable at least one Sales pipeline for Round Robin
  - Yes → Does each participating pipeline have a valid RR target stage?
    - No → Set the RR target stage (defaults to "New Lead")
    - Yes → Check logs for Round Robin assignment failures

Decision tree: Duplicate leads created

Are phone numbers normalized correctly?
- Check if 10-digit numbers are getting "91" prepended
- Verify phone numbers include country code or are 10 digits
Are there duplicates in the file?
- Within-file duplicates are de-duplicated (only first occurrence is used)
Are existing leads being matched?
- Verify phone/email matching is working (check existing leads in Dashboard)

FAQs

Can I update existing leads with this import?
- Yes. Kraya matches by phone and/or email. Matches are updated if "Update existing leads" is checked; otherwise they're skipped. Others are created.
Do I need Email?
- No. Phone is required (to enable WhatsApp messages). Email is optional but helps with matching existing leads.
Can I import to multiple pipelines or stages at once?
- No. One Pipeline and Stage per import (unless using Round Robin). Run multiple imports if needed.
Can I cancel an import after it starts?
- No. Let it complete, then adjust leads as needed. The import runs as a background job.
Will unmapped columns create new attributes automatically?
- No. If you need a new attribute, use the "Create New Attribute" option during mapping.
Can I assign Auto Followups during import?
- Yes. Pick a sequence in the import flow. You can change/clear it later from the Dashboard/Extension.
What's the maximum file size?
- 25,000 rows per upload. Split larger files into multiple imports if needed.
How does phone number normalization work?
- Non-digit characters are removed, then 10-digit numbers get "91" prepended. Example: "9876543210" → "919876543210".
What happens if email is invalid?
- Invalid emails are silently set to null (don't cause import to fail). The row is still processed.
Can I use Round Robin distribution?
- Yes, if Round Robin is configured for your organization. Choose Round Robin instead of selecting a pipeline/stage.
What happens if Round Robin assignment fails?
- The lead is skipped (not created/updated). Check Round Robin configuration and agent assignments.
How long does a large import take?
- Imports process in chunks of 2,500 rows. A 25,000-row import may take 10-15 minutes. You can navigate away and continue working.
Can I create custom attributes during import?
- Yes. Use "Create New Attribute" option during mapping. New attributes are created immediately and can be used in the same import.
What's the limit on custom attributes?
- 10 custom attributes per organization on the free plan, 50 on paid plans.
How are duplicates handled?
- Within-file duplicates are de-duplicated (only first occurrence is used). Existing leads are matched by normalized phone/email.
What if I don't want to update existing leads?
- Uncheck "Update existing leads" option. Existing leads will be skipped (not updated), only new leads will be created.

Dashboard - Viewing and managing imported leads
Auto Followups - Assigning sequences during import
WhatsApp Messages - Messaging imported leads
Google Sheets Integration - Automatic syncing from Google Sheets
Connect Kraya API - Programmatic lead creation/updates
Round Robin Distribution - Automatic lead assignment to sales pipelines