> ## Documentation Index
> Fetch the complete documentation index at: https://developers.mindhunters.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Contact Management

> Organize and manage your contact database with custom fields and segmentation

## 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

<CardGroup cols={2}>
  <Card title="Custom Fields" icon="list-check">
    Define unlimited custom fields for your specific needs
  </Card>

  <Card title="Tags & Labels" icon="tags">
    Organize contacts with tags for easy filtering
  </Card>

  <Card title="Bulk Import/Export" icon="file-arrow-up">
    Upload and download contacts in CSV format
  </Card>

  <Card title="Deduplication" icon="copy">
    Automatic detection and merging of duplicates
  </Card>
</CardGroup>

## Creating Contacts

### Via Dashboard

<Steps>
  <Step title="Navigate to Contacts">
    Go to **Contacts** in your Mindhunters dashboard
  </Step>

  <Step title="Add New Contact">
    Click **"Add Contact"** button
  </Step>

  <Step title="Fill in Details">
    * Name (required)
    * Phone number (required, E.164 format)
    * Email (optional)
    * Custom fields
    * Tags
  </Step>

  <Step title="Save Contact">
    Click **"Save"** to add to database
  </Step>
</Steps>

### Via API

Create contacts programmatically:

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  const createContact = async () => {
    const response = await fetch(
      'https://your-tenant.mindhunters.ai/api/v1/contacts',
      {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_API_TOKEN',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          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'
        })
      }
    );

    return await response.json();
  };
  ```

  ```python Python theme={null}
  import requests

  url = "https://your-tenant.mindhunters.ai/api/v1/contacts"
  headers = {
      "Authorization": "Bearer YOUR_API_TOKEN",
      "Content-Type": "application/json"
  }
  payload = {
      "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"
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()
  ```
</CodeGroup>

## Bulk Import

### CSV Upload

Import multiple contacts at once using CSV:

**CSV Format:**

```csv theme={null}
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:**

<Steps>
  <Step title="Prepare CSV">
    Create CSV with required fields: name, phone
  </Step>

  <Step title="Upload File">
    Go to Contacts → Click **"Import"** → Select CSV file
  </Step>

  <Step title="Map Fields">
    Map CSV columns to contact fields
  </Step>

  <Step title="Review & Import">
    Preview data and click **"Import"**
  </Step>
</Steps>

**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

<Tabs>
  <Tab title="Via Dashboard">
    1. Go to **Settings** → **Custom Fields**
    2. Click **"Add Field"**
    3. Configure field:
       * Name
       * Type (text, number, date, dropdown)
       * Required or optional
       * Default value
    4. Save
  </Tab>

  <Tab title="Via API">
    Custom fields are defined per contact in the `customFields` object.
  </Tab>
</Tabs>

### 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:

```javascript Example Tags theme={null}
{
  "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:**

1. **VIP Customers**
   * Tag: vip
   * Last interaction: \< 30 days
   * Status: active

2. **Inactive Leads**
   * Status: prospect
   * Last interaction: > 90 days
   * Tag: !converted

3. **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:

```javascript Example Filter theme={null}
{
  "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:**

```javascript theme={null}
{
  "phone": "+1234567890",
  "preferences": {
    "doNotCall": true,
    "doNotMessage": false,
    "optedOut": false
  }
}
```

### GDPR Compliance

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:**

```bash theme={null}
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:

1. Review suggested merges
2. Select which data to keep
3. Merge contacts
4. 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

<Tabs>
  <Tab title="Dashboard Export">
    1. Go to **Contacts**
    2. Apply filters (optional)
    3. Click **"Export"**
    4. Choose CSV or Excel
    5. Download file
  </Tab>

  <Tab title="API Export">
    ```bash theme={null}
    curl -X GET "https://your-tenant.mindhunters.ai/api/v1/contacts?limit=1000" \
      -H "Authorization: Bearer YOUR_API_TOKEN"
    ```
  </Tab>
</Tabs>

**Exported Data Includes:**

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

## Best Practices

<AccordionGroup>
  <Accordion title="Keep Data Clean" icon="broom">
    * Regularly review and update contacts
    * Remove or archive inactive contacts
    * Merge duplicates promptly
    * Validate phone numbers and emails
  </Accordion>

  <Accordion title="Use Custom Fields Wisely" icon="sliders">
    * Define fields that provide value
    * Keep field names consistent
    * Don't create too many fields
    * Document field purposes
  </Accordion>

  <Accordion title="Tag Strategically" icon="tags">
    * Use consistent naming convention
    * Create tag categories
    * Remove outdated tags
    * Don't over-tag contacts
  </Accordion>

  <Accordion title="Segment for Personalization" icon="filter">
    * Create meaningful segments
    * Use segments for targeted campaigns
    * Update segments regularly
    * Test segment performance
  </Accordion>

  <Accordion title="Respect Privacy" icon="shield">
    * Honor opt-out requests immediately
    * Comply with GDPR and privacy laws
    * Secure sensitive data
    * Document consent
  </Accordion>
</AccordionGroup>

## 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

### WhatsApp

Send messages to contacts:

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

## API Operations

### List Contacts

```bash theme={null}
GET /api/v1/contacts?page=1&limit=50&tags=vip&status=active
```

### Get Contact

```bash theme={null}
GET /api/v1/contacts/{id}
```

### Update Contact

```bash theme={null}
PATCH /api/v1/contacts/{id}
Content-Type: application/json

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

### Delete Contact

```bash theme={null}
DELETE /api/v1/contacts/{id}
```

See [API Reference](/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

<CardGroup cols={2}>
  <Card title="Campaigns" icon="bullhorn" href="/guides/services/campaigns">
    Create campaigns with your contacts
  </Card>

  <Card title="Voice Agents" icon="microphone" href="/guides/services/voice-agents">
    Set up AI agents to call contacts
  </Card>

  <Card title="WhatsApp" icon="message" href="/guides/services/whatsapp">
    Send WhatsApp messages to contacts
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    View contact API endpoints
  </Card>
</CardGroup>