Contact Management - Mindhunters API Documentation

Contact Database

The Mindhunters contact database is your centralized repository for managing customer information. Store contact details, track interaction history, and segment audiences for targeted campaigns.

Key Features

Custom Fields

Define unlimited custom fields for your specific needs

Tags & Labels

Organize contacts with tags for easy filtering

Bulk Import/Export

Upload and download contacts in CSV format

Deduplication

Automatic detection and merging of duplicates

Creating Contacts

Via Dashboard

Navigate to Contacts

Go to Contacts in your Mindhunters dashboard

Add New Contact

Click “Add Contact” button

Fill in Details

Name (required)
Phone number (required, E.164 format)
Email (optional)
Custom fields
Tags

Save Contact

Click “Save” to add to database

Via API

Create contacts programmatically:

curl -X POST https://your-tenant.mindhunters.ai/api/v1/contacts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "phone": "+1234567890",
    "email": "john@example.com",
    "customFields": {
      "company": "Acme Corp",
      "role": "Manager",
      "industry": "Technology"
    },
    "tags": ["vip", "enterprise"],
    "timezone": "America/New_York",
    "language": "en"
  }'

Bulk Import

CSV Upload

Import multiple contacts at once using CSV: CSV Format:

name,phone,email,company,role,tags
John Doe,+1234567890,john@example.com,Acme Corp,Manager,"vip,enterprise"
Jane Smith,+0987654321,jane@example.com,Tech Inc,Director,"vip"
Bob Wilson,+1122334455,bob@example.com,StartupCo,Founder,"startup,tech"

Import Steps:

Prepare CSV

Create CSV with required fields: name, phone

Upload File

Go to Contacts → Click “Import” → Select CSV file

Map Fields

Map CSV columns to contact fields

Review & Import

Preview data and click “Import”

Requirements:

Phone numbers must be in E.164 format (+1234567890)
Maximum 10,000 contacts per import
File size limit: 5 MB

Handling Duplicates

During import, duplicates are detected by phone number:

Skip: Don’t import duplicates
Update: Update existing contacts with new data
Create New: Import as separate contacts

Custom Fields

Define custom fields to store business-specific information.

Creating Custom Fields

Via Dashboard
Via API

Go to Settings → Custom Fields
Click “Add Field”
Configure field:
- Name
- Type (text, number, date, dropdown)
- Required or optional
- Default value
Save

Field Types

Type	Description	Example
Text	Free-form text	Company name, notes
Number	Numeric values	Revenue, employee count
Date	Date values	Birthday, contract date
Dropdown	Predefined options	Industry, status
Boolean	True/false	VIP status, opted-in
URL	Website links	Company website

Common Custom Fields

B2B:

Company name
Job title
Industry
Company size
Annual revenue

B2C:

Age/Birthday
Gender
Interests
Purchase history
Loyalty tier

General:

Lead source
Lead score
Last interaction date
Notes
Preferred contact method

Tags & Segmentation

Using Tags

Tags help organize and filter contacts:

Example Tags

{
  "name": "John Doe",
  "tags": [
    "vip",
    "enterprise",
    "q1-2025",
    "product-interested"
  ]
}

Common Tag Categories:

Customer Type: vip, enterprise, sme, individual
Status: active, inactive, churned, prospect
Source: website, referral, event, advertisement
Interest: product-a, product-b, service-x
Campaign: q1-campaign, webinar-attendee

Creating Segments

Segments are saved filters for quick access: Example Segments:

VIP Customers
- Tag: vip
- Last interaction: < 30 days
- Status: active
Inactive Leads
- Status: prospect
- Last interaction: > 90 days
- Tag: !converted
Enterprise Prospects
- Custom field: company_size > 1000
- Tag: enterprise
- Status: prospect

Contact History

View complete interaction history for each contact:

Calls: All voice calls with durations and outcomes
Messages: WhatsApp and SMS history
Campaigns: Campaign participation
Notes: Manual notes added by team
Timeline: Chronological activity feed

Example History

Jan 15, 2025 - Voice Call - 3:45 duration - Survey completed
Jan 10, 2025 - WhatsApp - Order confirmation sent
Jan 5, 2025 - Campaign - Added to Q1 Survey campaign
Dec 20, 2024 - Voice Call - 2:30 duration - Appointment scheduled
Dec 15, 2024 - Note - "Customer interested in enterprise plan"

Searching & Filtering

Quick Search

Search contacts by:

Name
Phone number
Email
Custom field values

Advanced Filters

Apply multiple filters:

Example Filter

{
  "filters": {
    "tags": ["vip", "enterprise"],
    "status": "active",
    "customFields": {
      "industry": "Technology",
      "revenue": { "$gte": 1000000 }
    },
    "lastInteraction": {
      "$gte": "2025-01-01",
      "$lte": "2025-01-31"
    }
  }
}

Filter Operators:

$eq: Equals
$ne: Not equals
$gt: Greater than
$gte: Greater than or equal
$lt: Less than
$lte: Less than or equal
$in: In array
$nin: Not in array

Privacy & Compliance

Opt-Out Management

Manage contact preferences:

Do Not Call: Contact cannot be called
Do Not Message: Contact cannot receive messages
Opted Out: Completely opted out of all communication

Setting Opt-Out:

{
  "phone": "+1234567890",
  "preferences": {
    "doNotCall": true,
    "doNotMessage": false,
    "optedOut": false
  }
}

Support for GDPR requirements:

Right to Access: Export contact data
Right to Deletion: Delete contact and all data
Right to Rectification: Update contact information
Consent Management: Track consent status

Deleting Contact Data:

curl -X DELETE https://your-tenant.mindhunters.ai/api/v1/contacts/{id} \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Deduplication

Mindhunters automatically detects duplicate contacts based on:

Phone number (primary key)
Email address
Name + similar phone

Merging Duplicates

When duplicates are detected:

Review suggested merges
Select which data to keep
Merge contacts
Update campaign assignments

Merge Strategy:

Keep most recent data
Combine tags from both
Merge custom fields
Preserve all history

Exporting Contacts

Export contacts for analysis or backup:

Export Options

Dashboard Export
API Export

Go to Contacts
Apply filters (optional)
Click “Export”
Choose CSV or Excel
Download file

Exported Data Includes:

All standard fields
Custom fields
Tags
Creation and update dates
Opt-out preferences

Best Practices

Keep Data Clean

Regularly review and update contacts
Remove or archive inactive contacts
Merge duplicates promptly
Validate phone numbers and emails

Use Custom Fields Wisely

Define fields that provide value
Keep field names consistent
Don’t create too many fields
Document field purposes

Tag Strategically

Use consistent naming convention
Create tag categories
Remove outdated tags
Don’t over-tag contacts

Segment for Personalization

Create meaningful segments
Use segments for targeted campaigns
Update segments regularly
Test segment performance

Respect Privacy

Honor opt-out requests immediately
Comply with GDPR and privacy laws
Secure sensitive data
Document consent

Integration with Other Features

Campaigns

Use contacts in campaigns:

Select specific contacts
Apply segment filters
Import campaign-specific lists
Track campaign participation

Voice Agents

Contacts are automatically:

Called by AI agents in campaigns
Associated with call transcriptions
Updated with call outcomes
Tracked in contact history

Send messages to contacts:

Use contact database for broadcasts
Track message delivery status
Handle replies automatically
Update contact preferences

API Operations

List Contacts

GET /api/v1/contacts?page=1&limit=50&tags=vip&status=active

Get Contact

GET /api/v1/contacts/{id}

Update Contact

PATCH /api/v1/contacts/{id}
Content-Type: application/json

{
  "tags": ["vip", "q1-2025"],
  "customFields": {
    "last_purchase": "2025-01-15"
  }
}

Delete Contact

DELETE /api/v1/contacts/{id}

See API Reference for complete documentation.

Troubleshooting

Import Failed

Common issues:

Invalid phone number format (use E.164: +1234567890)
Duplicate entries in CSV
File size too large (max 5 MB)
Invalid CSV format

Solution: Validate data, fix formatting, split large files.

Duplicate Contacts

Causes:

Multiple imports without deduplication
Slightly different phone numbers
API creates without checking

Solution: Use deduplication tools, merge duplicates.

Custom Field Not Showing

Causes:

Field not created
Permission issue
Cache issue

Solution: Create field in settings, refresh page.

Next Steps

Campaigns

Create campaigns with your contacts

Voice Agents

Set up AI agents to call contacts

Send WhatsApp messages to contacts

API Reference

View contact API endpoints

Getting Started

Services

Developer Tools

​Contact Database

​Key Features

Custom Fields

Tags & Labels

Bulk Import/Export

Deduplication

​Creating Contacts

​Via Dashboard

​Via API

​Bulk Import

​CSV Upload

​Handling Duplicates

​Custom Fields

​Creating Custom Fields

​Field Types

​Common Custom Fields

​Tags & Segmentation

​Using Tags

​Creating Segments

​Contact History

​Example History

​Searching & Filtering

​Quick Search

​Advanced Filters

​Privacy & Compliance

​Opt-Out Management

​GDPR Compliance

​Deduplication

​Merging Duplicates

​Exporting Contacts

​Export Options

​Best Practices

​Integration with Other Features

​Campaigns

​Voice Agents

​WhatsApp

​API Operations

​List Contacts

​Get Contact

​Update Contact

​Delete Contact

​Troubleshooting

​Import Failed

​Duplicate Contacts

​Custom Field Not Showing

​Next Steps

Campaigns

Voice Agents

WhatsApp

API Reference

Contact Database

Key Features

Creating Contacts

Via Dashboard

Via API

Bulk Import

CSV Upload

Handling Duplicates

Custom Fields

Creating Custom Fields

Field Types

Common Custom Fields

Tags & Segmentation

Using Tags

Creating Segments

Contact History

Example History

Searching & Filtering

Quick Search

Advanced Filters

Privacy & Compliance

Opt-Out Management

GDPR Compliance

Deduplication

Merging Duplicates

Exporting Contacts

Export Options

Best Practices

Integration with Other Features

Campaigns

Voice Agents

WhatsApp

API Operations

List Contacts

Get Contact

Update Contact

Delete Contact

Troubleshooting

Import Failed

Duplicate Contacts

Custom Field Not Showing

Next Steps