Importing Contacts

The KI Agency platform supports bulk contact import from Excel and CSV files with advanced phone number validation and formatting. This guide explains how to import contacts efficiently and troubleshoot common issues.

Import Process Overview

The contact import system is designed to handle large volumes of contacts while ensuring data quality and preserving existing contact information:

• Batch Processing: Imports are processed in batches of 1,000 contacts for optimal performance
• Phone Validation: All phone numbers are automatically validated and formatted
• Intelligent Merging: Duplicate contacts are automatically merged, combining information from both sources
• Error Handling: Invalid contacts are reported with detailed error messages

Benefits of Smart Merging

The system's intelligent merging feature provides several advantages:

• No Data Loss: When importing contacts that already exist, new information is added without removing existing data
• Cumulative Tags: Tags from multiple imports accumulate, making it easy to categorize contacts over time
• Metadata Enrichment: Each import can add new metadata fields without overwriting existing ones
• Flexible Updates: Update only the fields you want by leaving others empty in your import file
• Safe Re-imports: You can safely re-import the same contact list multiple times - the system will merge the data intelligently

---

How to Import Contacts

Step 1: Prepare Your Contact Data

Before importing, ensure your contact data includes:

• First Name: Contact's first name
• Last Name: Contact's last name (optional but recommended)
• Phone Number: Contact's phone number in any format
• Email: Email address (optional)
• Tags: Custom tags for categorization (optional) - you can add multiple tags separated by commas
• Metadata: Additional custom information (optional)

Step 2: Use the Import Feature

1. Navigate to the Contacts section
2. Click the Import Contacts button
3. Upload your contact file (Excel .xlsx, .xls, or CSV .csv format)
4. Wait for the import to complete
5. Review the import results

Step 3: Download Sample File

If you need help with the correct file format:

1. Look for the "Sample excel file" link next to the import button
2. Download the sample file to see the expected format
3. Use this as a template for your contact data

---

Phone Number Handling

The system includes advanced phone number processing:

Automatic Formatting

• International Format: All phone numbers are converted to E.164 international format (e.g., +491234567890)
• Country Detection: The system automatically detects and formats numbers based on regional settings
• Format Validation: Invalid phone numbers are identified and reported

Supported Input Formats

The system accepts phone numbers in various formats:

• +49 123 456 7890 (International with spaces)
• 0049 123 456 7890 (International with country code)
• (0123) 456-7890 (Local format with brackets and dashes)
• 123 456 7890 (Simple format with spaces)
• 1234567890 (Numbers only)

Invalid Numbers

Phone numbers that cannot be validated are:

• Skipped during import
• Listed in the error report
• Not added to your contact list

---

Supported File Formats

The contact import system supports multiple file formats to make importing convenient:

Excel Files (.xlsx, .xls)

• Recommended format: Modern Excel workbooks (.xlsx)
• Legacy support: Older Excel files (.xls) are also supported
• Easy to use: Most users are familiar with Excel format
• Template available: Download the sample Excel file for the correct format

CSV Files (.csv)

• Text format: Comma-separated values format
• Universal compatibility: Works with most spreadsheet programs
• Simple structure: Plain text format that's easy to generate programmatically

File Requirements

• Maximum size: 30MB per file
• Required headers: File must contain at least header row and one data row
• Column structure: Use the column names shown in the sample file

Tip: We recommend using the Excel format (.xlsx) as it provides better reliability and is easier to work with. You can download a sample Excel file from the import interface to get started quickly.

---

Import Results

After each import, you'll receive a detailed report:

Success Metrics

• Imported: Number of contacts successfully processed (includes new contacts and merged duplicates)
• Processed: Total contacts processed
• Skipped: Contacts with invalid or missing required data

Error Reporting

• Invalid Phone Numbers: Numbers that couldn't be formatted
• Missing Required Fields: Contacts without essential information
• Processing Errors: Technical issues during import

Sample Import Report

Import completed: 1000 processed, 25 errors

Results:
- Imported: 975 contacts (750 new, 225 merged with existing)
- Errors: 25 (invalid phone number format)

---

Duplicate Handling

The system intelligently handles duplicate contacts to preserve your data:

Phone Number Matching

• Contacts with the same phone number (after formatting) are considered duplicates
• When a duplicate is found, the system merges the information instead of skipping it
• Duplicate detection works across your entire contact database

Smart Data Merging

When importing a contact that already exists (same phone number), the system:

• Name and Email: Updates only if you provide new values in the import
• Metadata: Combines existing metadata with new metadata (both are kept)
• Tags: Merges all tags from both the existing contact and the import, removing duplicates
• Other Fields: Preserves existing data if no new value is provided

Example:

Existing Contact:
- Name: John Doe
- Email: john@example.com
- Tags: ["customer", "priority"]
- Metadata: {"source": "website", "status": "active"}

Imported Contact (same phone):
- Name: (empty)
- Email: john.doe@example.com
- Tags: ["vip", "priority"]
- Metadata: {"region": "north", "score": "95"}

Result after Import:
- Name: John Doe (kept from existing)
- Email: john.doe@example.com (updated with new value)
- Tags: ["customer", "priority", "vip"] (merged, duplicates removed)
- Metadata: {"source": "website", "status": "active", "region": "north", "score": "95"} (both merged)

Batch Duplicates

• If the same phone number appears multiple times in a single import batch
• The first occurrence is processed, and subsequent duplicates within the batch are merged
• All contacts are counted as "imported" since data merging happens automatically

---

Large Import Performance

For importing large numbers of contacts:

Batch Processing

• Contacts are processed in batches of 1,000
• Progress is logged for each batch
• Large imports (10,000+ contacts) are handled efficiently

Performance Tips

• Clean Data: The system merges duplicates intelligently. However, if your import file contains many exact duplicates (same phone number with identical data), removing them beforehand can speed up the import process
• Valid Formats: Ensure phone numbers are in recognizable formats
• Complete Information: Include all available data to create rich contact profiles through merging

---

Troubleshooting Common Issues

No Contacts Imported

Possible Causes:

• All phone numbers in the import file are invalid
• File format is not supported (must be .xlsx, .xls, or .csv)
• Required fields are missing (especially lastname)
• File is empty or contains only headers

Solutions:

• Check phone number formats in your data
• Ensure your file is in Excel (.xlsx, .xls) or CSV (.csv) format
• Download and use the sample Excel file as a template
• Verify that the lastname column contains data
• Review error messages for specific issues

High Error Rate

Possible Causes:

• Many phone numbers are in unsupported formats
• Data contains non-phone number values in phone fields
• Missing required contact information

Solutions:

• Clean your data before import
• Use standard phone number formats
• Ensure all required fields are populated

Import Takes Too Long

Possible Causes:

• Very large import file
• Network connectivity issues
• System processing other operations

Solutions:

• Break large imports into smaller batches
• Import during off-peak hours
• Contact support if issues persist

---

Importing Contacts with Tags

Tags are an excellent way to organize and categorize your contacts. When importing contacts, you can include tags in your import file to automatically assign them to contacts.

How Tags Work During Import

• Adding Tags: Include tags in the tags column of your import file. Multiple tags can be separated by commas.
• Merging Tags: When you re-import a contact (identified by phone number), the system intelligently merges tags from both the existing contact and the new import.
• Updating Contacts: This is a powerful feature for adding tags to existing contacts without manually editing each one.

Tag Import Example

If you want to add a "VIP" tag to existing contacts, simply create an import file with their phone numbers and the new tag. The existing contact information will be preserved, and the new tag will be added to any tags they already have.

---

Best Practices

Data Preparation

• Use the sample file: Download the sample Excel file to ensure correct format
• Enrich Your Data: Don't worry about duplicates - the system merges data intelligently
• Standard Formats: Use consistent phone number formats when possible
• Complete Information: Include as many fields as possible (name, email, tags, metadata)
• Choose the right format: Excel (.xlsx) is recommended for best compatibility
• Consistent Tags: Use consistent tag names to make filtering and organization more effective

Import Strategy

• Test First: Try a small batch before importing large datasets
• Monitor Results: Review import reports to identify patterns in errors
• Regular Imports: Consider smaller, regular imports instead of large bulk imports

Data Quality

• Verify Sources: Ensure imported data comes from reliable sources
• Regular Cleanup: Periodically review and clean your contact database
• Compliance: Ensure imported contacts comply with privacy regulations

---

API Import

For advanced users and integrations, the contact import API provides:

• Programmatic access to the import functionality
• Real-time import status and results
• Integration with external systems and databases

For API documentation, contact your system administrator or refer to the technical documentation.

---

If you encounter issues with contact imports or need assistance with large-scale imports, please contact your system administrator or our support team.