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 distribute the leads across your sales pipelines with Round Robin — choosing exactly which pipelines and which stage per pipeline), 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 — pick which of your Round Robin sales pipelines to split the leads across, and the stage leads land in for each pipeline
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 single pipeline/stage, choose "Distribute via Round Robin". A dedicated screen then lets you pick which of your Round Robin sales pipelines to split this import across, and the stage the leads land in for each pipeline. The leads are divided evenly across your selected 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, select the "Distribute via Round Robin" card ("Assigns leads evenly")
- This option only appears if Round Robin is available for your organization
- When selected, an info message "Auto-assigned by Round Robin." is shown on the card
- Click Next to open the Round Robin pipelines screen (adds one extra step to the wizard)

6a) Pick Round Robin pipelines and stages (Round Robin only)

The "Import Leads: Round Robin pipelines" screen shows one row per pipeline, pre-filled with all sales pipelines enabled for Round Robin
The screen explains: "Leads are split evenly across these pipelines. Remove any you don't want, and pick the stage leads land in for each."
Each row has:
- A Pipeline dropdown — a pipeline can only be chosen once across all rows
- A Stages dropdown — defaults to that pipeline's Round Robin stage (shown by its stage name); you can pick a different stage for that pipeline
Remove a row with the delete icon (available when more than one row exists). A removed pipeline receives no leads from this import
Click "Select another pipeline" to add back a pipeline you removed
At least one pipeline must be selected. If none is selected, Next is disabled and you'll see "Select at least one pipeline to distribute leads across."
Click Next to continue to the review screen

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
- Review your selections — with Round Robin, the review screen shows "Auto-assigned by Round Robin" as the assignment
- 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
- With Round Robin, check each pipeline you selected — leads are split evenly across them, in the stage you picked per pipeline
- 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 single pipeline/stage, choose "Distribute via Round Robin" — the leads in this import are split evenly across sales pipelines you choose
Choosing pipelines: After selecting Round Robin, a dedicated screen lists all your sales pipelines enabled for Round Robin, pre-selected. Remove any pipeline you don't want; only the pipelines you keep receive leads from this import. Use "Select another pipeline" to add a removed pipeline back
Choosing stages: Each pipeline row has its own Stages dropdown. It defaults to that pipeline's Round Robin stage (shown by name); you can pick any other stage on that pipeline instead. The chosen stage applies to every lead this import places into that pipeline
Even split: Leads are distributed one by one across your selected pipelines in rotation, so each selected pipeline receives a roughly equal share of this import
Independent of the normal rotation: The split is calculated within this import only. It does not use or advance the Round Robin rotation that assigns leads arriving from other sources (forms, integrations, manual assignment)
Requirements:
- Round Robin must be enabled at the organization level
- At least one Sales pipeline must be enabled for Round Robin (the RR pool)
- At least one pipeline must be kept selected on the Round Robin screen
Behavior:
- Each lead lands in its assigned pipeline's chosen stage (or the pipeline's Round Robin stage if you left the default)
- If Round Robin assignment fails for a lead (e.g., no valid target stage), that lead is skipped (not created/updated)
Sequence assignment: Auto Followup sequences can still be assigned when using Round Robin
Also available in WhatsApp broadcasts: The same pipeline and stage selection appears when you upload a CSV in a WhatsApp broadcast and choose 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 split evenly across the pipelines you selected, each landing in the stage you picked for that pipeline
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
- With Round Robin, remember the leads are spread across every pipeline you selected
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
"No Sales pipelines are enabled for Round Robin" on the Round Robin screen
- No sales pipeline is currently enabled for Round Robin, so there's nothing to distribute across
- Enable Round Robin on at least one Sales pipeline in the Round Robin settings, or go back and pick a specific Pipeline and Stage instead
"Select at least one pipeline to distribute leads across."
- You removed every pipeline row on the Round Robin screen
- Add at least one pipeline back with "Select another pipeline", or go back and choose a specific Pipeline and Stage
"One or more selected pipelines are not enabled for Round Robin." when submitting
- A pipeline you selected was removed from Round Robin (or deleted) after you opened the wizard
- Go back to the Round Robin screen, remove the affected pipeline, and submit again
"Selected stage does not belong to pipeline '...'." when submitting
- The stage you picked for a pipeline no longer exists on that pipeline (it may have been deleted or moved while the wizard was open)
- Re-open the Round Robin screen and pick a current stage for that pipeline
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 selected pipeline has a valid target stage (the default is that pipeline's Round Robin stage)
- If Round Robin assignment fails for a lead, that lead is 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 → If Round Robin was used, check every pipeline you selected on the Round Robin screen (leads are split across them)

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 → Did you keep at least one pipeline selected on the Round Robin screen?
    - No → Add a pipeline back with "Select another pipeline"
    - Yes → Does each selected pipeline have a valid target stage?
      - No → Pick a stage on the Round Robin screen (or set the pipeline's Round Robin stage in settings)
      - Yes → Contact support with the approximate import time

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?
- Yes, with Round Robin. Choose "Distribute via Round Robin" and pick the pipelines to split the import across, with a stage per pipeline. Without Round Robin, it's one Pipeline and Stage per import.
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 "Distribute via Round Robin" instead of selecting a pipeline/stage, then pick the pipelines and stages on the next screen.
Can I choose which pipelines Round Robin uses for an import?
- Yes. The Round Robin screen starts with all your Round Robin sales pipelines pre-selected; remove the ones you don't want. Only the pipelines you keep receive leads from this import.
Which stage do Round Robin leads land in?
- Each pipeline row has its own Stages dropdown. If you leave the default, leads land in that pipeline's Round Robin stage; otherwise they land in the stage you picked.
Does an import affect my normal Round Robin rotation?
- No. The import splits its leads evenly within the import itself and does not use or advance the Round Robin rotation for leads arriving from other sources.
What happens if Round Robin assignment fails?
- The lead is skipped (not created/updated). Check that each selected pipeline has a valid target stage.
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 - Automatic lead assignment to sales pipelines