Importing records, end to end
An import is read, validated and then applied one record at a time through the service that owns that record type. The file is never written straight into a table. Rows that fail validation and rows that match something already held are both reported rather than silently dropped, and the count that arrives is usually smaller than the count in the file, for reasons the report names.
The path an import takes#
- Trigger — you choose a file on a sheet in
#/data, or attach one and ask for it to be imported. - User event — the upload carries the file and the sheet it is meant for; the sheet decides which record type the rows will become.
- Authentication and workspace resolution — the workspace is resolved from the session first, and every row that follows is stamped with it. A row with no workspace stamp is invisible rather than missing.
- Ingest — the file goes through the same file service every attachment uses: content is checked, and a declaration or an archive that expands unreasonably is refused before parsing begins.
- Canonical record — the sheet's columns are mapped to fields on the real record. This is the step where a spreadsheet stops being a spreadsheet.
- Reasoning — matching, not invention. Each row is compared against what the workspace already holds so an import adds rather than duplicates.
- Knowledge, memory and rules — each candidate record is validated by its owning service, and contact-level rules apply: a suppressed or do-not-contact address stays suppressed after an import.
- Autonomy and approval — you are the actor, so channel autonomy is not consulted. Your permission on that record type is.
- Action — records are created or updated one at a time. A row that fails does not stop the next one.
- Result — a report: how many arrived, how many were updates rather than new records, how many were refused, and why for each.
- Relationship and timeline — new people and companies join the relationship graph, and an identity on a channel resolves to a person from that point on.
- Audit and usage — the import and the records it produced are recorded, so a row can be traced back to the file it came from.
Two stages account for nearly every surprise. Column mapping decides what a value *means*, and matching decides whether a row is a new record or a change to one you already had. Everything else is mechanical.
What the file itself has to satisfy#
The formats Connect reads with the standard library are PNG, JPEG and WebP for images; PDF; DOCX; XLSX; CSV and TSV; PPTX; and TXT, MD and JSON. For an import the useful ones are CSV, TSV and XLSX — a table with a header row and one record per line.
| Check | What it means | If it fails |
|---|---|---|
| Content, not extension | The file is identified by what is inside it | A spreadsheet saved with the wrong suffix is judged on its content |
| DOCTYPE and ENTITY declarations | An external-entity trick in a markup file | Refused outright, before parsing |
| Archive expansion | A small file that decompresses to something enormous | Refused outright |
| A header row | Column names to map fields from | A file with no header cannot be mapped and is not imported |
Those two safety refusals are absolute and they are not configurable. They happen at the file service, which both audiences share, so the behaviour is the same in an operator workspace and a customer one. The file was refused covers the difference between a refusal and a failure.
Matching, and why a row can become an update#
An import that produced a second copy of every customer you already had would be worse than no import. Each row is therefore matched against existing records before anything is written, and a match makes the row an update to that record rather than a new one. The grid keeps duplicates visible afterwards, so a match that should have happened and did not can be resolved by hand.
- An email address that already resolves to a person makes the row that person, not a second one.
- A phone number already on file does the same, which is how one person across phone, email and messaging stays one person.
- A company name alone is weaker evidence than an address or a domain, so a name-only match is treated cautiously rather than merged.
- Nothing is merged behind your back. Where the evidence is not strong enough, both records exist and the duplicates view shows the pair.
Reading the report you get at the end#
Compare the row count in the file with the arrived count.
Result The gap should be fully explained by the refused and matched counts; if it is not, the file had blank or partial rows that never became candidates.
Open the refusals grouped by reason rather than row by row.
Result Almost every import fails in a small number of shapes — one malformed date column, one required field left empty.
Fix the file, not the records, and import the corrected rows again.
Result Rows that already arrived match and become no-op updates, so a re-run is safe.
Check the duplicates view once, after the import rather than during it.
Result You see the pairs the matcher was not confident about together, instead of deciding one at a time under time pressure.
If rows are missing and the report does not account for them, some imported rows are missing walks through the causes in order of likelihood.
Questions#
Can I import into any of the thirteen sheets?
Import is offered on the sheets where a record can be meaningfully created from a table — people, companies, leads, prospects and the like. Sheets that are a record of something that happened, such as calls and conversations, are not places a spreadsheet can add to: those rows are produced by the events themselves.
What happens to a column my sheet does not have?
It is not imported. Extra columns are ignored rather than treated as an error, because a spreadsheet exported from another system almost always carries fields that have no home here. If a column matters, the place to put it is a field the record actually has, not a note nobody will read.
Does an import count against my plan's allowance?
Creating records is not a message and does not consume a sending allowance. What an import does consume is storage for the file itself, which is kept so a row can be traced to its source, and any model work you ask for afterwards — summarising or researching the imported list is separate work with its own cost.