Contact Management Feature¶

Overview¶

Contact Management (/contacts) is the core CRM feature of ConnectGain, providing comprehensive contact database management with advanced search, filtering, tagging, custom fields, and integration with deals, conversations, and tasks. It enables businesses to organize, segment, and manage customer relationships effectively.

Features¶

1. Contact Management¶

Create Contacts: - Add new contacts manually with: - First name, last name - Multiple phone numbers - Multiple email addresses - Company association - Tags - Custom fields - Opt-in status - Notes - Create deal option during contact creation

Edit Contacts: - Update contact information - Modify all contact fields - Update relationships

Delete Contacts: - Remove contacts (with cascade protection) - Bulk delete operations

Bulk Operations: - Bulk import from CSV - Bulk export to CSV - Bulk delete - Bulk merge - Bulk marketing opt-in / opt-out - Bulk add / remove tags

Contact Details View: - Comprehensive contact profile - All contact information - Communication history - Related deals - Related tasks - Notes timeline - Activity log

2. Search & Filtering¶

Advanced Search: - Search by: - Name (first, last, full) - Phone number (partial matching) - Email address - Company name - Tags - Custom fields - Real-time search results

Tag Filtering: - Filter by contact tags - All tags dropdown - Multiple tag selection

Open-deal counts appear as badges on contacts for reference; they are not a filter option.

Sorting Options: - Alphabetical (A-Z, Z-A) - Newest added (newest first, oldest first)

3. View Modes¶

Grid View (default): - Card-based layout - Contact cards with key info - Quick action buttons - Visual tags - Company badges

Table View: - Spreadsheet-style layout - Bulk selection - Inline actions - Export capabilities

(Only Grid and Table views exist. On mobile, Grid is used.)

4. Contact Organization¶

Tags System: - Flexible tagging - Create custom tags - Multiple tags per contact - Tag-based filtering - Auto-tagging by country - Tag management

Company Association: - Link contacts to companies - Company selection - Company creation from contact - Company details view

Custom Fields: - Extend contact data - Text fields - Number fields - Date fields - Dropdown fields

4. Custom Fields¶

Field Types: - Text - Number - Date - Boolean - Dropdown - Multi-select

Use Cases: - Store industry-specific data - Track custom attributes - Integration with external systems

5. Contact Import¶

CSV Import: - Bulk import contacts - Column mapping - Data validation - Duplicate detection - Import progress tracking - Error reporting

HubSpot Import: - CSV import using a HubSpot-export column mapping (no direct HubSpot API/OAuth connection; routed through the standard import-contacts function)

Duplicate Detection: - Find and merge duplicates - Automatic duplicate detection - Manual merge options - Merge conflict resolution

6. Contact Actions¶

Quick Actions: - View contact details - Edit contact - Delete contact - Send message - Make phone call - Open WhatsApp - Copy phone number - Copy email address

Bulk Actions: - Export selected contacts - Delete selected contacts - Merge selected contacts - Add / remove tags on selected contacts - Set marketing opt-in / opt-out

7. Contact Analytics¶

Deal Count: - Number of open deals per contact

Notes Count: - Number of notes per contact

Activity Timeline: - Recent activity tracking

Engagement Metrics: - Message frequency - Last contact date

8. Pagination¶

50 Contacts Per Page: - Efficient loading - Page navigation - Total count display

9. Auto-Tagging¶

Country-Based Tagging: - Automatically tag contacts by country - Phone number analysis - Country code detection - Batch processing - Progress tracking - Completion notifications

6. Call Tracking¶

Call Features: - Initiate calls from contact card - Initiate calls from contact details - Call event tracking - Call history per contact - Call status tracking (INITIATED, CONNECTED, COMPLETED, MISSED, FAILED) - Call duration tracking - Call notes - Link calls to conversations

Call Actions: - Click phone icon to initiate call - Opens device phone dialer - Automatically records call event - Tracks call status and duration - Add call notes after completion

7. Contact Relationships¶

Relationships: - Company association - Deal association - Conversation association - Task association - Note association

8. Contact Assignment¶

Assignment Features: - Assign a contact to a team member via the contact form ("Assign To") - Reassign by editing the contact

Use Cases¶

Use Case 1: Import Existing Customer Database¶

Scenario: Company wants to migrate 5,000 contacts from Excel to ConnectGain.

Steps: 1. Export contacts from Excel to CSV 2. Go to Contacts → Import 3. Upload CSV file 4. Map CSV columns to ConnectGain fields 5. Review import preview 6. Configure duplicate handling 7. Start import 8. Review import results 9. Fix any errors 10. Verify imported contacts

Expected Outcome: All contacts imported successfully with proper field mapping.

Use Case 2: Find Contact by Phone Number¶

Scenario: Customer calls, agent needs to find contact quickly.

Steps: 1. Go to Contacts 2. Enter phone number in search 3. View search results 4. Click on matching contact 5. View contact details and history

Expected Outcome: Contact found instantly with full history visible.

Use Case 3: Tag Contacts for Campaign¶

Scenario: Marketing wants to send campaign to "VIP Customers" only.

Steps: 1. Go to Contacts 2. Filter contacts by criteria (e.g., deals > $10,000) 3. Select all filtered contacts 4. Add tag "VIP Customer" 5. Go to Broadcast (/broadcast) 6. Create a campaign targeting the "VIP Customer" tag 7. Send campaign

Expected Outcome: Campaign sent only to VIP customers.

Use Case 4: Merge Duplicate Contacts¶

Scenario: System has duplicate contacts that need merging.

Steps: 1. Go to Contacts → Find Duplicates 2. Review duplicate suggestions 3. Select contacts to merge 4. Choose primary contact 5. Review merged data 6. Confirm merge 7. Verify merged contact

Expected Outcome: Duplicates merged into single contact with all data preserved.

Use Case 5: Assign Contacts to Sales Team¶

Scenario: Sales manager wants to distribute contacts evenly among team.

Steps: 1. Go to Contacts 2. Filter contacts (e.g., no assignee, tag "Lead") 3. Select contacts to assign 4. Click "Assign" 5. Select team member 6. Confirm assignment 7. Verify assignments

Expected Outcome: Contacts distributed evenly among sales team.

Test Cases¶

Test Case 1: Create Contact¶

Test: Verify contact creation

Steps: 1. Go to Contacts 2. Click "New Contact" 3. Fill in required fields: - First Name: "John" - Last Name: "Doe" - Phone: "+1234567890" - Email: "john@example.com" 4. Add optional fields: - Company: "Acme Inc" - Tags: ["Customer", "VIP"] - Custom Fields: { "Industry": "Technology" } 5. Click "Save" 6. Verify contact appears in list 7. Open contact details 8. Verify all data saved correctly

Expected Result: Contact created successfully with all data preserved

Test Case 2: Search Contact by Name¶

Test: Verify name search functionality

Steps: 1. Create test contact: "John Doe" 2. Go to Contacts 3. Enter "John" in search 4. Verify contact appears in results 5. Enter "Doe" in search 6. Verify contact appears 7. Enter "John Doe" in search 8. Verify contact appears 9. Enter "Doe John" in search 10. Verify contact appears (reversed name)

Expected Result: Contact found by first name, last name, full name, and reversed name

Test Case 3: Search Contact by Phone¶

Test: Verify phone number search

Steps: 1. Create contact with phone: "+1234567890" 2. Search for "1234567890" 3. Verify contact found 4. Search for "234567890" 5. Verify contact found (partial match) 6. Search for "+1-234-567-890" 7. Verify contact found (formatted number)

Expected Result: Contact found by full phone, partial phone, and formatted phone

Test Case 4: Bulk Import Contacts¶

Test: Verify CSV import functionality

Steps: 1. Create CSV file with 100 contacts 2. Go to Contacts → Import 3. Upload CSV file 4. Map columns: - First Name → first_name - Last Name → last_name - Email → emails - Phone → phones 5. Review preview 6. Start import 7. Wait for import completion 8. Verify import results: - Success count: 100 - Error count: 0 9. Verify contacts in list 10. Check imported data accuracy

Expected Result: All contacts imported successfully with correct data mapping

Test Case 5: Update Contact¶

Test: Verify contact update functionality

Steps: 1. Create contact 2. Open contact details 3. Click "Edit" 4. Update fields: - Change first name - Add phone number - Add tag - Update custom field 5. Save changes 6. Verify updates reflected 7. Check updated_at timestamp

Expected Result: Contact updated successfully with all changes preserved

Test Case 6: Delete Contact¶

Test: Verify contact deletion

Steps: 1. Create contact 2. Create related conversation 3. Create related deal 4. Create related task 5. Delete contact 6. Verify contact deleted 7. Verify cascade deletion: - Conversation deleted - Deal deleted - Task deleted

Expected Result: Contact and all related data deleted (cascade)

Test Case 7: Tag Management¶

Test: Verify tagging functionality

Steps: 1. Create contact 2. Add tag "Customer" 3. Add tag "VIP" 4. Verify tags displayed 5. Remove tag "Customer" 6. Verify tag removed 7. Filter contacts by tag "VIP" 8. Verify contact appears in filtered list 9. Bulk tag multiple contacts 10. Verify all contacts tagged

Expected Result: Tag management works correctly for single and bulk operations

Test Case 8: Custom Fields¶

Test: Verify custom fields functionality

Steps: 1. Go to Contacts 2. Edit a contact 3. Add a custom field (e.g. "Industry" = "Technology") 4. Save contact 5. Verify custom field saved 6. Reopen the contact and verify the custom field persists

Expected Result: Custom fields can be added to a contact and saved

Test Case 9: Contact Assignment¶

Test: Verify contact assignment

Steps: 1. Create contact 2. Verify no assignee 3. Assign to user "John Smith" 4. Verify assignee set 5. Filter contacts by assignee 6. Verify contact appears 7. Reassign to "Jane Doe" 8. Verify assignee updated 9. Bulk assign multiple contacts 10. Verify all contacts assigned

Expected Result: Contact assignment works for single and bulk operations

Test Case 10: Duplicate Detection¶

Test: Verify duplicate detection and merging

Steps: 1. Create contact: "John Doe", "+1234567890" 2. Create duplicate contact: "John Doe", "+1234567890" 3. Go to Contacts → Find Duplicates 4. Verify duplicates detected 5. Select both contacts 6. Choose primary contact 7. Merge contacts 8. Verify merged contact has all data 9. Verify duplicate contact deleted

Expected Result: Duplicates detected and merged correctly

Test Case 11: Contact Views¶

Test: Verify different view modes

Steps: 1. Go to Contacts 2. Switch to Grid view 3. Verify cards displayed 4. Switch to Table view 5. Verify table displayed 6. Test sorting in table view 7. Test filtering in both views 8. Verify data consistency

Expected Result: All view modes work correctly with consistent data

Test Case 12: Contact Export¶

Test: Verify contact export

Steps: 1. Create 10 test contacts 2. Go to Contacts 3. Click "Export" 4. Select export format: CSV 5. Select fields to export 6. Download file 7. Open CSV file 8. Verify all contacts exported 9. Verify data accuracy

Expected Result: Contacts exported correctly with accurate data

API Integration¶

Create Contact¶

Endpoint: POST /rest/v1/contacts

Request:

{
 "organization_id": "org-uuid",
 "first_name": "John",
 "last_name": "Doe",
 "phones": ["+1234567890"],
 "emails": ["john@example.com"],
 "tags": ["customer", "vip"],
 "custom_fields": {
 "industry": "Technology"
 }
}

Search Contacts¶

Endpoint: POST /functions/v1/search-contacts

Request:

{
 "searchTerm": "John",
 "tags": ["customer"],
 "dealStatus": "open"
}

Bulk Import¶

Endpoint: POST /functions/v1/import-contacts

Request:

{
 "csvData": "First Name,Last Name,Email\nJohn,Doe,john@example.com",
 "organizationId": "org-uuid"
}

Best Practices¶

Data Quality
Use consistent phone number format
Validate email addresses
Keep names standardized
Use tags consistently
Organization
Use tags for categorization
Assign contacts to team members
Link contacts to companies
Keep custom fields organized
Import
Clean data before import
Map fields carefully
Review preview before importing
Handle duplicates appropriately
Search
Use specific search terms
Combine filters for precision
Save frequently used searches
Use tags for quick filtering
Maintenance
Regular duplicate cleanup
Update contact information
Archive inactive contacts
Review and update tags

Troubleshooting¶

Import Errors¶

Issue: Contacts not importing

Solutions: - Check CSV format - Verify field mapping - Check data validation errors - Review import logs

Search Not Finding Contacts¶

Issue: Known contacts not appearing in search

Solutions: - Check search term spelling - Verify phone number format - Check organization filter - Try different search terms

Duplicate Contacts¶

Issue: Multiple entries for same contact

Solutions: - Use duplicate detection tool - Merge duplicates - Standardize import process - Use unique identifiers

Last Updated: January 2025

Contact Management Feature¶

Overview¶

Features¶

1. Contact Management¶

2. Search & Filtering¶

3. View Modes¶

4. Contact Organization¶

4. Custom Fields¶

5. Contact Import¶

6. Contact Actions¶

7. Contact Analytics¶

8. Pagination¶

9. Auto-Tagging¶

6. Call Tracking¶

7. Contact Relationships¶

8. Contact Assignment¶

Use Cases¶

Use Case 1: Import Existing Customer Database¶

Use Case 2: Find Contact by Phone Number¶

Use Case 3: Tag Contacts for Campaign¶

Use Case 4: Merge Duplicate Contacts¶

Use Case 5: Assign Contacts to Sales Team¶

Test Cases¶

Test Case 1: Create Contact¶

Test Case 2: Search Contact by Name¶

Test Case 3: Search Contact by Phone¶

Test Case 4: Bulk Import Contacts¶

Test Case 5: Update Contact¶

Test Case 6: Delete Contact¶

Test Case 7: Tag Management¶

Test Case 8: Custom Fields¶

Test Case 9: Contact Assignment¶

Test Case 10: Duplicate Detection¶

Test Case 11: Contact Views¶

Test Case 12: Contact Export¶

API Integration¶

Create Contact¶

Search Contacts¶

Bulk Import¶

Best Practices¶

Troubleshooting¶

Import Errors¶

Search Not Finding Contacts¶

Duplicate Contacts¶

Related Documentation¶