Importing contacts

Add contacts manually, in bulk via CSV, or directly from the Lead Harvester extension.

Contacts are the audience for every workflow, broadcast, and automation in Apexium. There are three ways to get contacts into your workspace.

Manual create

Best for: one-off additions, testing.

Head to Contacts → New contact. The form collects:

  • Email — primary identifier. Optional, but recommended; many workflows trigger on email events.
  • Phone — for SMS workflows + caller ID matching.
  • First name + last name — used in mail-merge tokens.
  • Title + company — surfaces on contact cards; company links to the Companies table if you've added the company first.
  • Tags — comma-separated; create new tags on the fly.
  • Custom fields — any fields your workspace has defined under Settings → Custom fields.

The form validates email format + phone format (E.164 recommended). Duplicate prevention: if you submit an email that already exists in this workspace, you'll get a "merge or skip" prompt rather than a silent overwrite.

CSV bulk import

Best for: migrating from another CRM, importing harvested lead lists, onboarding.

Head to Contacts → Import. Upload a CSV file (max 50MB per file). The importer:

  1. Parses the header row and asks you to map columns to Apexium contact fields. Custom fields supported.
  2. Previews the first 5 rows so you can confirm mapping looks right.
  3. Runs the import in the background — large files stream as Inngest jobs so the UI doesn't block.
  4. Shows a per-row outcome report when done: created / updated / skipped (duplicates) / errored (malformed rows).

CSV format tips

  • Header row required. Column order doesn't matter — you map them in the UI.
  • Encoding: UTF-8. Excel sometimes exports as Windows-1252; if non-ASCII characters look mangled, re-save the file as "CSV UTF-8" before uploading.
  • Email column — if present, used as the dedup key. Without an email column the importer treats every row as a new contact.
  • Tags column — semicolon-separated values become individual tags (one cell with vip;newsletter;trial creates 3 tags).
  • Date columns — ISO 8601 (2026-05-14) or US (05/14/2026) both work; the importer auto-detects.

Dedup behavior

The importer matches on email (case-insensitive). When a match is found:

  • Existing email present + your row matches: tagged fields merge; name/phone/title only fill if the existing row has NULL (won't clobber user-curated data).
  • Tags: union (your CSV tags add to existing tags; never remove).
  • Custom fields: jsonb merge (your values overwrite same-keyed existing values).

If you want a strict "overwrite everything" import, delete the existing contacts first (Contacts → bulk select → delete) then import fresh.

Via the Lead Harvester extension

Best for: continuous lead flow from social/web sources.

The Lead Harvester Chrome extension scrapes leads from social media, group posts, and other public sources. With Apexium platform integration:

  1. Generate a harvester API key under Settings → Harvester (one-time setup).
  2. Paste it into the extension's settings panel.
  3. The extension now pushes captured leads directly into your Apexium contacts table — no manual CSV step.

Leads arrive with custom_fields.source = "harvester" tagging so you can build workflows that trigger only on harvested contacts (e.g., "send a 'noticed you in [group]' email to every harvester-source contact within 1 hour of import").

See harvester quickstart for the full extension setup including scanning settings + keyword filters.

Custom fields

Beyond the built-in contact fields, you can define custom fields under Settings → Custom fields. Custom fields live in a custom_fields jsonb column on the contact row — no schema migration needed; new fields are queryable immediately.

Common custom field uses:

  • Lifecycle stage — dropdown: lead / prospect / customer / churned
  • Lifetime value — number; populated by a Stripe webhook
  • Source URL — text; tracks where a harvested lead came from (auto-populated by the extension)

Custom fields can be referenced in workflows via the expression engine ({{contact.custom_fields.lifecycle_stage}} etc.).

Tags

Tags are simple labels (no values) used for segmenting. A contact can have any number of tags. Create them on the fly when adding a contact; manage them centrally under Settings → Tags (rename, merge, delete).

Common tag patterns:

  • Source tags — webinar-jan, harvester-fb-group-x, csv-import-march
  • Behavior tags — opened-promo, clicked-pricing, replied-to-cold-email
  • Status tags — do-not-contact, vip, trial-expired

Tags integrate with workflow triggers and audience selection in broadcasts.

What to do next