Skip to main content
Import contacts from an existing CRM, snapshot, or partner list. Onchain Suite maps your columns automatically, parses wallet addresses across chains, and holds anything that needs attention rather than dropping it silently.

​
Limits and formats

Imports run in the background on a queue, so a large file keeps processing even if you navigate away, and an interrupted run recovers on its own. Track progress from the import’s status. Larger files upload directly to storage first, then import; you can also download a sample CSV or JSON to see the expected shape.
A list is required for every import. Contacts imported without one wouldn’t appear in any audience, so the import won’t start until you pick a list. Tags are optional on top of that.

​
Columns

You don’t have to rename your headers. Common column names are recognized automatically. Matching ignores case, spaces, underscores, and hyphens, so Wallet Address, wallet_address, and walletaddress are the same column. Anything unrecognized is kept as a contact attribute rather than discarded, so no column is lost, and those attributes are usable later in SQL and merge variables. You can also map columns explicitly to override the automatic matching, and there are presets for common tools.
Every row needs at least one usable identifier: an email or a wallet. A row with neither is reported as an error rather than imported.

​
Wallet parsing

Wallet columns are parsed for both EVM and Solana addresses. A value that can’t be parsed is reported with a reason rather than dropped quietly: Spreadsheet quirks like a leading apostrophe on a text-formatted cell are handled.

​
Warnings vs errors

When the import finishes, results are split so you can see exactly what needs fixing:
  • Errors. The row didn’t import, for example because it had no usable identifier.
  • Warnings. The row imported, but something was incomplete, for example a wallet that was supplied but couldn’t be parsed.
Both are sampled in the import status. A file that imports “successfully” can still carry warnings, so check the sample.

​
Write behavior

An import can be tuned to how it should merge with existing contacts: You can also turn on privacy protection for an import so the contacts it creates are protected on the way in.

​
When you’re over capacity

If an import would push you past your plan’s contact limit, the extra contacts aren’t rejected. They’re quarantined: stored and counted, kept out of every audience (they carry no tags or list membership), and released automatically once you add capacity. Contacts awaiting email confirmation via double opt-in are held the same way.

​
Exporting

Export a list or segment back out to a file. Exports run on the same queue and recover if interrupted.

​
Managing lists and tags

Rename or delete tags and lists as your taxonomy evolves. A tag that backs a list can’t be deleted out from under it; remove the list first. To clear a workspace entirely, deleting all contacts is possible but guarded: you confirm the exact current contact count, and it’s limited to Owners and Admins.

​
Good practices

  • Decide your source of truth before a large import.
  • Import into a clearly named list so the contacts are findable immediately.
  • Run a dry run first on an unfamiliar file to see how columns map and how many rows would import.
  • Review the warnings sample; a file that imports “successfully” can still have unparsed wallets.
  • Export only the fields a workflow actually needs.