Skip to main content

Documentation Index

Fetch the complete documentation index at: https://support.affinity.co/llms.txt

Use this file to discover all available pages before exploring further.

​
Immediate Value

After this tutorial, you’ll have a written migration plan that prevents the most common import failures: duplicate contacts, mismatched fields, broken character encoding, and the dreaded “now I have to redo this” moment.

​
Prerequisites

  • You’ve completed Tutorial 0.2.
  • You have export access to your current CRM, spreadsheet, or whatever system holds your data.

​
Quick-Start Roadmap

  1. Decide what you’re actually importing
  2. Audit your source data for duplicates and inconsistent formats
  3. Identify primary keys and matching strategy
  4. Plan your field structure
  5. Prep your CSV: encoding, formats, special characters
  6. Decide your undo strategy
💡 The single best predictor of a clean import is whether you spent 30 minutes planning it. This tutorial is that 30 minutes.

​
Why Planning Your Migration Matters

Once data is imported, untangling mistakes is significantly harder than preventing them. A botched import creates duplicate profiles, mismatched fields, and orphaned records that you’ll spend weeks cleaning up. Affinity offers an undo for imports, but undo only works cleanly if you catch the problem fast — and undo doesn’t fix bad source data, only the import itself. Spend the time here.
See Data migration for an end-to-end overview of how Affinity handles imports.

​
Task 1: Decide What You’re Actually Importing

​
Context

Affinity supports four primary entity types in lists: Companies, People, Opportunities, and generic List Entries. You’ll likely need a mix. Start by writing down what you have and what shape it should take in Affinity.

​
Action

  1. List out your data sources: prior CRM (Salesforce, HubSpot, etc.), spreadsheets, LinkedIn export, manual lists, email exports.
  2. For each source, decide:
    • What entity type does this map to? (Companies? People? Both? Opportunities?)
    • What list does it belong in? (One per source, or merged into a master list?)
    • What’s the priority? Import high-signal data first — your active pipeline, key relationships. Skip historical clutter.
  3. Write the plan down. A spreadsheet works fine: one row per source, columns for “entity type,” “destination list,” “priority,” “row count.”
Resist the urge to import everything. Most migration problems come from importing low-quality historical data alongside the data you actually care about. Be selective.

​
Expected Outcome

A clear, written list of what’s being imported, in what order, and into which lists.

​
Task 2: Audit Your Source for Duplicates and Inconsistent Formats

​
Context

The biggest cleanup work happens before you import, not after. Affinity will create duplicate profiles if the same person exists in your source with different email addresses, different name spellings, or different company associations.

​
🎬 Watch

​
Action

  1. Sort your source data by email address and look for the same person appearing with different addresses (e.g., personal Gmail vs. work email).
  2. Sort by name and look for spelling variations (“Bob” vs “Robert”, “St.” vs “Saint”).
  3. Sort by company and standardize naming (“Acme, Inc.” vs “Acme Inc” vs “Acme”).
  4. Decide your canonical value for each duplicate set and update the source before importing.
💡 If you have thousands of rows, focus on the top 20% — your highest-priority contacts and companies. Don’t try to perfect 100% of the data upfront; clean as you go after the import for the rest.

​
Expected Outcome

Your source data is internally consistent: one canonical name, email, and company per real-world entity.

​
📚 Help Center

​
Task 3: Identify Primary Keys and Matching Strategy

​
Context

When Affinity imports, it needs to decide: is this row a new profile, or does it match an existing one? The answer is determined by your primary key — the field Affinity uses for matching. For people, it’s email address. For companies, it’s domain. Other fields are secondary.

​
Action

  1. For every person row, confirm there’s an email address populated.
  2. For every company row, confirm there’s a domain populated (e.g., acme.com, not “Acme Inc.”).
  3. Rows missing the primary key will be created fresh and won’t match existing profiles. Decide whether to skip those rows or backfill the primary key before importing.
Email is the primary key for people. Two rows with different emails will create two profiles even if the names match. If the same person has two emails, decide which one is canonical before importing.

​
Expected Outcome

Every row has a primary key, and you understand exactly which rows will match existing data vs. create new profiles.

​
📚 Help Center

  • How to import by Affinity Row ID — for advanced cases where you want to update existing records by Affinity’s internal ID instead of email/domain matching.

​
Task 4: Plan Your Field Structure

​
Context

Every column in your CSV will map to a field in Affinity. You have two choices for each column: map it to an existing field (recommended whenever possible), or create a new list-specific field for it.

​
Action

  1. Open the list you’ll be importing into. Click ”+ New Column” in the header and review what fields already exist.
  2. For each column in your source CSV, write down: “map to existing field [name]” or “create new field [name + type]”.
  3. For new fields, decide:
    • Field type: Text, Number, Date, Dropdown, Person, Company, Status, etc.
    • Global or list-specific? Global fields appear across all lists; list-specific fields only on this one.
  4. Create the new fields in Affinity before the import. Then they’ll be available in the mapping step.
💡 Don’t create new fields for every column. If a column is just “notes from sales call,” it might belong in the actual Notes feature, not as a field. Be ruthless about what deserves its own column.

​
Expected Outcome

Every column in your source maps cleanly to an existing or planned field in Affinity.

​
📚 Help Center

​
Task 5: Prep Your CSV — Encoding, Formats, Special Characters

​
Context

CSVs look simple but fail in subtle ways: wrong encoding, mixed delimiters, currency symbols in number fields, dates in ambiguous formats.

​
Action

  1. Encoding: Save your CSV as UTF-8. Excel sometimes defaults to Latin-1, which mangles accents and Asian characters.
  2. Delimiters: Use comma (,) as the column delimiter. Don’t mix with semicolons.
  3. Dates: Use ISO format (YYYY-MM-DD) — unambiguous across regions. Avoid MM/DD/YYYY if you have international data.
  4. Numbers: Strip currency symbols, commas, percent signs. $1,234.56 becomes 1234.56. Affinity will format on display.
  5. Booleans: Use true / false or yes / no. Be consistent.
  6. Test row: Save just the first 5–10 rows as a separate test CSV. Run that through Affinity first to catch encoding issues before committing to the full import.
Don’t import a CSV you haven’t opened. Open it in a text editor (not Excel) and confirm it looks the way you expect. Excel will silently transform your data — leading zeros stripped, dates reformatted, scientific notation applied to long numbers.

​
Expected Outcome

Your CSV is properly encoded, formatted, and tested with a small sample.

​
📚 Help Center

​
Task 6: Decide Your Undo Strategy

​
Context

Affinity supports undoing imports — but only cleanly if you catch the problem fast and haven’t manually edited records since the import. Plan your safety net up front.

​
Action

  1. Decide who’s running the import (you, or an admin partner).
  2. Plan to run the import during a quiet period — not in the middle of a busy week.
  3. Agree on a verification window: “We’ll spot-check within 1 hour, decide undo-or-keep within 4 hours.”
  4. Make sure your source CSV is saved and version-controlled. If you have to redo the import, you’ll thank yourself.
Undo is not unlimited. Affinity’s undo works best for recent imports. Older imports — especially if records have been edited since — may not undo cleanly.

​
Expected Outcome

You have a clear plan for what to do if the import goes sideways.

​
📚 Help Center

​
Common Questions

Q: Can I import to multiple lists at once? No. Each import targets one list. If you have data destined for multiple lists, run multiple imports. Q: What if my source has more rows than Affinity’s import limit? Split the CSV into chunks and run sequential imports. The destination list will accumulate them. Q: Do I need to deduplicate before importing if Affinity will match by email? For 80% of cases, Affinity’s matching handles it. But for edge cases (same person with two emails), manual cleanup beforehand prevents duplicate profiles you’ll spend hours merging later. Q: Can I undo just part of an import? No. Undo is all-or-nothing per import. If you want partial undo, you’ll need to manually delete the wrong rows or use the merge tool on the resulting duplicates.

​
Where to Go Next

➡️ Tutorial 0.4: Import Your Data — now actually execute the import, with source-specific guides for Salesforce, HubSpot, Pipedrive, Dynamics, Attio, LinkedIn, and more.