# Importing a prospect list, end to end

An import is a bulk version of creating one prospect, and every row goes through the same checks a discovered candidate does. The file is read, rows are resolved against what you already know, survivors become prospect records, and research fills in what your spreadsheet could not prove. The summary at the end is the only convenient moment to act on what failed.

- **Status:** Available
- **Audience:** both
- **In the app:** #/prospects, #/data
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/workflows/list-import/

## The import, stage by stage

1. Trigger — a file is attached on the prospects screen or imported into the prospects sheet of the Data grid.
2. User event — the upload itself, attributed to the person who made it; every row that follows carries that attribution.
3. Authentication and workspace resolution — the workspace is entered first, and the file is stored scoped and under row-level security like any other asset.
4. Ingest — CSV, TSV or XLSX is read with the standard library; files carrying DOCTYPE or ENTITY declarations, and archives that expand far beyond their size, are refused before parsing.
5. Canonical record — each surviving row becomes a prospect, with supplied values marked as supplied rather than proved.
6. Reasoning and research — research runs over the new rows to produce claims, a score and a fit reason, exactly as it would for a discovered candidate.
7. Knowledge, memory and rules — identity resolution runs per row, and suppression and do-not-contact are consulted before anything is considered contactable.
8. Autonomy and approval — none is needed to import; nothing is sent by an import, and outreach remains a separate flow with its own gates.
9. Action through a provider — model calls for research only. No message reaches anybody on the list.
10. Result — new prospects, merged prospects, matched customers and rejected rows, each counted in the summary.
11. Relationship and timeline — rows that matched an existing Person or Company are shown as those relationships rather than created again.
12. Audit and usage — the import is recorded with who ran it, and the research it triggered is booked to the workspace's ledger.

## What happens to one row

| Condition | Outcome | Where you see it |
|---|---|---|
| New, resolvable organisation | Created as a prospect and researched | The list, and the count above it |
| Matches a prospect you already have | Merged; supplied values fill gaps only | The summary, as a merge |
| Matches somebody in your relationships | Not created; reported as a customer match | The summary, and the existing Person |
| Address is suppressed | Created, not contactable | The prospect, with the suppression's origin |
| No resolvable subject | Rejected | The summary, with the reason |
| Address column empty | Created, next action is not email | The gap between qualified and ready to send |

> **Note** A merge never lets a supplied value overwrite an evidence-backed one. That rule is what makes re-importing a corrected file safe, and it is why the second import of the same list is usually cheap: most rows match, and matching costs nothing.

## Working the summary

1. Read the rejected rows first and fix them in the source file.
   - Result: They are almost always structural — a merged cell, a header row repeated mid-file, an address column with no organisation beside it.
2. Read the customer matches next.
   - Result: Each one is a business you already know that you were about to prospect. Whether it is a false match matters, and this is the moment it is easy to check.
3. Let research finish before judging the list.
   - Result: Scores, fit reasons and contactability come from research, so a freshly imported list looks thin and unqualified until it has run.
4. Re-import the corrected file.
   - Result: Rows that already exist merge rather than duplicate; only the genuinely new ones cost research.

## How an import disappoints

**Far fewer prospects than rows** — Customer matches and merges, in that order of likelihood. The summary has the exact split.
**The file was refused outright** — A declaration or expansion refusal, which is a security decision rather than a parsing problem. Export a plain CSV from the source application.
**Everything is unqualified** — Research has not run yet, or the rows describe organisations your brief does not describe. Both are visible on any single prospect.
**Addresses you supplied are not being used** — They are, but the prospect may still be uncontactable for a compliance reason. Open the prospect and read the suppression.
**The counts moved less than expected** — Compare against the summary rather than the file. The difference between them is exactly rejections plus merges.

## Questions

### Does importing count against anything?

Storing rows does not, but researching them is ordinary AI work and is booked to the workspace's ledger like any other. A very large import is therefore a research decision as much as a data one.

### Can I import into a workspace that already has prospects?

That is the usual case, and matching is what makes it safe. Rows that describe an organisation you already hold merge into it rather than creating a second record with half the evidence.

### Is the uploaded file kept?

It goes through the same file service as everything else, scoped to the workspace and under row-level security, so it is stored the way any other attached document is rather than being read and thrown away.

## Related

- [Uploading your own list](https://connectbyjbrh.com/docs/prospects/prospect-upload/)
- [Resolving a prospect to an existing relationship](https://connectbyjbrh.com/docs/prospects/prospect-identity/)
- [Evidence for a contact address](https://connectbyjbrh.com/docs/prospects/contact-evidence/)
- [Files and data in Connect](https://connectbyjbrh.com/docs/files-data/)
- [The numbers above the list](https://connectbyjbrh.com/docs/prospects/prospect-counts/)
- [Researching one prospect, end to end](https://connectbyjbrh.com/docs/workflows/prospect-research/)

## What this page is based on

- `docs-source/sources/GENERAL.md` §9 — the file service, formats and refusals
- `docs-source/sources/CHANNELS.md` §4 — identity resolution and evidence
- `backend/app/prospect_upload.py`, `backend/app/file_workspace.py`
- Connect capability registry (`docs-source/facts.py`)