Contact Import & Export

Bulk Contact Import

CSV and Excel File Import

The system provides comprehensive bulk contact import capabilities for efficient contact management:

Supported File Formats:

CSV Files: Standard comma-separated values format
Excel Files: Both .xls and .xlsx formats supported
File Validation: Automatic format detection and validation
File Size Limits: Reasonable file size limits for performance

Import Process Overview:

File Upload: Upload contact files through the bulk upload interface
Header Parsing: Automatic detection and parsing of file headers
Field Mapping: Map file columns to contact database fields
Data Import: Batch processing for efficient contact creation

Import Authorization:

Contact creation permissions required for import operations
Team-based access control for import functionality
User authentication required for all import operations
Authorization checks before processing import files

Import Workflow

The contact import process follows a structured workflow:

Step 1: File Upload and Parsing

Upload CSV or Excel files through the bulk upload modal
Automatic file format validation (csv, xls, xlsx only)
Header extraction and row count calculation
File parsing with error handling for invalid formats

Step 2: Field Mapping Configuration

Display of detected file headers for mapping
Available contact fields presented for mapping selection
Mapping validation to prevent duplicate column assignments
Option to map all headers or only required columns

Step 3: Data Processing and Import

Contact data transformation using ContactDTO objects
Batch processing for efficient database operations (100 contacts per batch)
Individual contact creation fallback for failed batch operations
Import success tracking with total imported count

Pipedrive Import (Persons and Organizations)

Upload the Pipedrive “Persons” export (CSV/XLS/XLSX) from the Contacts → Bulk Upload/Import dialog under the “Pipedrive: Persons” tab.

What’s imported:

Contacts (from Persons): name, email, phone, company name, and basic fields
Optional link to existing client by company name

Behavior:

Idempotent mapping is maintained internally; duplicates are not hard-blocked to keep imports flexible
A summary (created/updated/skipped) is shown after completion

For Clients (from Organizations), open Clients → Bulk Upload/Import and use the “Pipedrive: Organizations” tab to import organization/company data into Clients. Supported formats: CSV, XLS, XLSX.

Import Field Mapping

Mapping File Columns to Contact Fields

The field mapping system provides flexible column-to-field assignment:

Mapping Configuration:

Column Index: Numerical index of columns in the uploaded file
Column Name: Original header name from the uploaded file
Mapped Column: Target contact field for data assignment
Mapping Validation: Required mapping specification for all used columns

Available Contact Fields:

All standard contact fields available for mapping through ContactDTO
Personal fields: first_name, last_name, email, phone, birth_date
Business fields: company_name, website, description
Address fields: address_line_1, city, zip, country
Social fields: skype, telegram, linkedin
System fields: client_id, outreach_id, company_id

Mapping Validation Rules:

Required Mappings: Each mapping must specify index and mapped column
Duplicate Prevention: Same contact field cannot be mapped to multiple columns
Column Validation: Mapped columns must be valid contact fields
Index Validation: Column indices must be valid integers

Advanced Mapping Features

The mapping system includes sophisticated validation and error prevention:

Mapping Validation:

Duplicate Detection: Prevents mapping multiple file columns to same contact field
Complete Mapping: Validates that all required mappings are specified
Column Consistency: Ensures mapped columns exist in contact field list
Mapping Completeness: Validates all file headers have mapping assignments

Error Prevention:

Frontend validation prevents invalid mapping configurations
Real-time validation feedback during mapping setup
Clear error messages for mapping conflicts
Mapping validation before import processing begins

Flexible Mapping Options:

Optional field mapping allows partial data import
Empty column mapping skips unused file columns
Flexible mapping supports various file structures
Custom field integration for extended data mapping

Import Validation

Data Validation and Error Handling

The import system includes comprehensive validation and error handling:

File Validation:

Format Validation: Only CSV, XLS, and XLSX files accepted
File Structure: Header row detection and validation
Data Integrity: Row-by-row data validation during processing
Error Recovery: Graceful handling of file parsing errors

Data Validation During Import:

Contact Data Validation: Each contact validated against contact creation rules
Required Field Checking: First name requirement enforced during import
Email Format Validation: Email addresses validated for proper format
Field Length Validation: Field length limits enforced during import

Batch Import Error Handling:

Batch Processing: 100 contacts processed per batch for efficiency
Batch Failure Recovery: Individual contact creation fallback for failed batches
Success Tracking: Count of successfully imported contacts maintained
Error Isolation: Failed contacts don't prevent successful contact import

Import Error Recovery

The system provides robust error recovery mechanisms:

Batch Processing Benefits:

Large imports processed in manageable batches
Batch failures don't prevent other batches from succeeding
Memory efficiency for large contact import operations
Performance optimization for bulk operations

Individual Contact Fallback:

Failed batch operations fall back to individual contact creation
Individual contact errors are logged but don't stop import process
Partial import success allows maximum contact import completion
Detailed error logging for troubleshooting failed contacts

Error Reporting:

Failed contacts logged with detailed error information
Import success count provided for verification
Error messages returned for user feedback
Comprehensive logging for debugging import issues

Contact Export

Exporting Contact Data for External Use

The contact system supports data export for external analysis and backup:

Export Integration:

Contact data available through search and filtering APIs
JSON format export for API integration
Contact search results can be exported programmatically
Team-based export filtering for proper access control

Export Data Structure:

Contact data exported with all standard fields
Custom field values included in export data
Client relationship information included
Pipeline association data available in exports

Export Access Control:

Export operations require appropriate contact permissions
Team-based filtering ensures proper data access
User ownership filtering available for restricted exports
Authorization checks for all export operations

Export Features and Capabilities

Contact export integrates with broader system functionality:

Search-Based Export:

Export filtered contact lists based on search criteria
Team-specific contact export with proper access control
Contact data includes relationships and associations
Flexible export based on user permissions and access

API Integration:

Contact data available through API endpoints for external integration
JSON format for easy integration with external systems
Search functionality supports programmatic contact access
Real-time contact data export capabilities

Import Logging

Tracking and Debugging Import Operations

The import system includes comprehensive logging for monitoring and debugging:

Import Process Logging:

File Parser Logging: Dedicated file-parser log channel for file processing
Contact Import Logging: Dedicated contacts log channel for import operations
Row Processing: Individual row processing logged for debugging
Mapping Logging: Field mapping configuration logged for verification
Pipedrive Import Logging: Row keys, parsed values, and upsert actions logged for troubleshooting

Detailed Log Information:

File Processing: File headers, row counts, and parsing results
Mapping Data: Complete mapping configuration and applied mappings
Contact Data: Individual contact data transformation and creation
Batch Operations: Batch processing results and success/failure tracking

Error Logging and Debugging:

File Parsing Errors: Detailed error logging for file processing failures
Import Failures: Comprehensive error logging for failed contact imports
Individual Contact Errors: Specific error messages for failed contact creation
Stack Trace Logging: Complete error context for debugging

Import Monitoring and Analysis

The logging system supports import monitoring and performance analysis:

Performance Monitoring:

Batch Performance: Monitoring of batch processing efficiency
Import Success Rates: Tracking of successful vs. failed imports
Processing Time: Performance metrics for import operations
Error Patterns: Analysis of common import failure patterns

Import Analytics:

Import Volume: Tracking of contact import volumes over time
Success Metrics: Analysis of import success rates and patterns
Error Analysis: Identification of common import issues
Performance Optimization: Data for optimizing import processes

Troubleshooting Support:

Detailed Error Context: Complete error information for issue resolution
Import Tracing: Full audit trail of import operations
Data Validation Logging: Validation failure tracking and analysis
System Health Monitoring: Import system performance and reliability tracking