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

# Add and Manage CRM Contacts

> Organize contacts, deals, and customer relationships in Hiveku CRM

Hiveku CRM is where every relationship lives — leads, clients, partners, vendors. Add contacts three different ways, tag them, move them through pipeline stages, and link them to tasks and campaigns.

<CardGroup cols={3}>
  <Card title="Easiest" icon="wand-magic-sparkles">
    Ask the AI to add them
  </Card>

  <Card title="One-off" icon="pencil">
    Manual entry
  </Card>

  <Card title="Bulk" icon="file-import">
    CSV import
  </Card>
</CardGroup>

<Tabs>
  <Tab title="AI Chat">
    ## Option 1: Ask the AI

    The fastest way to add a contact is to describe it.

    <Steps>
      <Step title="Open the AI chat">
        Click the **AI** tab in your project.
      </Step>

      <Step title="Describe the contact">
        ```
        Add Jane Smith (jane@acme.com) as a CRM contact at Acme Inc.
        Tag her as a hot lead. Add a note that she attended our webinar
        on April 12.
        ```

        The AI parses the details and creates the contact, tags, and note in one step.
      </Step>

      <Step title="Confirm">
        Go to **CRM > Contacts** to verify the entry. The AI also logs the creation in the contact's activity history.
      </Step>
    </Steps>

    <Tip>
      You can bulk-add too: *"Add these five contacts: Jane Smith ([jane@acme.com](mailto:jane@acme.com)), John Doe ([john@acme.com](mailto:john@acme.com))..."*. The AI handles the loop.
    </Tip>
  </Tab>

  <Tab title="Manual">
    ## Option 2: Add One Manually

    <Steps>
      <Step title="Open the CRM">
        Go to **CRM > Contacts**.
      </Step>

      <Step title="Click Add Contact">
        Fill in the form:

        * **Name** — first and last
        * **Email**
        * **Phone** (optional)
        * **Company**
        * **Tags** — see below
        * **Notes** — freeform text
      </Step>

      <Step title="Save">
        Click **Save**. The contact appears in the list immediately.
      </Step>
    </Steps>
  </Tab>

  <Tab title="CSV Import">
    ## Option 3: Bulk Import from CSV

    <Steps>
      <Step title="Download the template">
        Go to **CRM > Contacts > Import**, click **Download Template**, and open it in Excel or Sheets.
      </Step>

      <Step title="Fill in your data">
        Required columns: `name`, `email`. Optional: `phone`, `company`, `tags`, `notes`, plus any custom fields you've defined.

        <Warning>
          Don't rename the column headers — the import matches on exact names. Extra columns beyond the template are ignored.
        </Warning>
      </Step>

      <Step title="Upload">
        Drag the file onto the import page. You'll see a preview with validation — fix any errors, then click **Import**.

        Hiveku dedupes against existing contacts by email. Duplicates are merged, not duplicated.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Tags for Categorization

Use tags to slice your contact list: `client`, `lead`, `vendor`, `hot`, `cold`, `webinar-signup`, and so on. Apply multiple tags per contact and filter the list by any combination.

Tags are also what you target in outbound email campaigns — see [/how-tos/cold-email](/how-tos/cold-email).

## Custom Fields

Add your own fields to contacts — renewal date, favorite product, LinkedIn URL, preferred pronouns, annual revenue tier, anything. Custom fields are per-account and show up everywhere a contact does (table, detail page, merge variables).

<Steps>
  <Step title="Define the field">
    Go to **CRM > Settings > Custom Fields > Add Field**. Pick a name and a type (`text`, `number`, `date`, `multiline`, `select`). `multiline` preserves line breaks when you render the value in an email.
  </Step>

  <Step title="Set values on contacts">
    Open a contact. Custom fields render in a dedicated section on the detail page. Update inline, or bulk-update from the AI SDR (*"set renewal\_date to 2027-03-01 on all contacts tagged 'enterprise'"*).
  </Step>

  <Step title="Use as merge variables in emails">
    Any custom field name you've defined is available as `{{field_name}}` in Sales Sequences or one-off AI SDR emails. Multi-line values preserve `\n` as `<br/>`. Missing values render as empty strings.
  </Step>
</Steps>

<Tip>
  Field names become merge vars verbatim, so pick short, snake\_case names. `renewal_date` beats `Renewal Date (ISO)`.
</Tip>

## Saved Views

A **saved view** is a named filter + column layout on the contacts table. Build a useful slice once (filters + sort + visible columns), name it *"My prospects — no reply 7d+"*, and pin it to your sidebar. Each rep's views are personal.

* **Create** — Filter / sort / show/hide columns on the contacts table, then click **Save view** and name it.
* **Switch** — Top-left of the contacts table, pick from your saved views.
* **Edit / delete** — On the view dropdown, click the pencil icon on the row.
* **Share** — Views are personal by default. Mark as **team view** to expose it to teammates.

Common useful views: "Hot leads (score > 70, not emailed 14d)", "Stale contacts I own (no activity 30d)", "Missing phone number", "Ready to enroll in cadence X".

## Pipeline Stages

Move contacts through the sales cycle visually.

<Steps>
  <Step title="Open Pipeline view">
    Go to **CRM > Pipeline**. Switch between **kanban** and **list** views in the top right.
  </Step>

  <Step title="Drag contacts between stages">
    Default stages: *New*, *Contacted*, *Qualified*, *Proposal*, *Closed Won*, *Closed Lost*.
  </Step>

  <Step title="Customize stages">
    Click the gear icon to add, rename, or reorder stages. Each stage can have a color and a probability percentage for deal forecasting.
  </Step>
</Steps>

## Tasks Linked to Contacts

From a contact's profile, click **Add Task** to create a follow-up.

* **Due date** — when to follow up
* **Assignee** — team member responsible
* **Linked contact** — auto-set to the current contact

Tasks appear in **CRM > Tasks**, in each assignee's dashboard, and overlaid on the contact's activity timeline.

## Activity History

Every contact has an activity timeline showing:

* Emails sent and received (if email is connected)
* Notes added
* Calls logged
* Tag and stage changes
* Tasks created and completed

Use this as a memory for every interaction — nothing falls through the cracks.

## Merge Duplicates

When two contact records are actually the same person (same email with different spellings, bounced imports, stale + new entry) → merge them so the history consolidates on one record.

Two ways in:

<Tabs>
  <Tab title="AI SDR (recommended for bulk)">
    Ask the AI SDR:

    ```
    Find duplicate contacts on the account where the email
    matches, ignoring case. Show me the pairs — don't merge yet.
    ```

    The AI SDR lists candidate pairs. Confirm a pair, then:

    ```
    Merge contact <loser_id> into contact <winner_id>.
    ```

    Because merge is destructive, you'll see an **approval card** first — confirming which record is the winner (survives) vs. loser (soft-deleted). Approve to run.
  </Tab>

  <Tab title="From the contact detail page">
    Open the record you want to keep (the *winner*). Click **More > Merge**, pick the duplicate (*loser*), review the diff, and confirm. The loser is soft-deleted — the row stays in the database for audit but doesn't appear in lists or searches.
  </Tab>
</Tabs>

### What gets merged

All history moves from loser → winner: activities, deals, companies, tags, custom fields, sequence enrollments, email events, suppressions. Any field blank on the winner gets backfilled from the loser (non-destructive — winner's existing values always win). The loser's `deleted_at` is set.

This is **not reversible** through the UI. The audit row preserves the merge, but un-merging requires manual SQL.

## Verifying It Works

After adding a contact, search for it by name or email in the top search bar. It should appear instantly in results. Open the profile to confirm all fields and tags are correct.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Duplicate contacts">
    Use the merge flow above — either via the AI SDR (best for finding pairs at scale) or from a contact's **More > Merge** menu (best for one-off cleanup). Fields combine with winner-first precedence; activity history unifies on the winner.
  </Accordion>

  <Accordion title="CSV import failed">
    The import usually fails because of a missing required column or malformed email. Open the template again, make sure `name` and `email` columns are spelled exactly as shown, and that every row has a valid email.
  </Accordion>

  <Accordion title="Contact not appearing in an outbound campaign">
    Campaigns target by tag or list. Check the contact's tags match the campaign's audience rule, and that the campaign is using a current list snapshot (lists can be refreshed from the list settings).
  </Accordion>

  <Accordion title="Tags not saving">
    Type the tag name and press **Enter** or **Tab** to commit it — free-typed text that isn't committed gets discarded on save.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Sales Sequences" icon="list-ol" href="/how-tos/crm-sales-sequences">
    Personal OAuth cadences — use your tagged contacts as audience
  </Card>

  <Card title="AI SDR" icon="robot" href="/how-tos/ai-sdr">
    The AI assistant for every CRM page
  </Card>

  <Card title="AI SDR Reminders" icon="bell" href="/how-tos/ai-sdr-reminders">
    Self-scheduled follow-up pings from the AI SDR
  </Card>

  <Card title="Cold Email" icon="envelope" href="/how-tos/cold-email">
    Launch outbound campaigns against tagged segments
  </Card>
</CardGroup>