# Linking a file to a record

A file is stored once and linked to the records it belongs to. The link is what makes the document appear on that company, deal or case, and what lets a question asked on that record reach it. Linking copies nothing, changes no contents, and can be removed later without the file going anywhere.

- **Status:** Available
- **Audience:** both
- **In the app:** #/data, #/relationships, #/pipeline
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/files-data/linking-files/

## Storage and linking are separate

The file service holds the document. A link is a separate statement that this document is relevant to that record. Keeping the two apart is why the same signed agreement can sit on the company and on the deal without two copies drifting apart, and why removing it from one leaves the other intact.

| Part | Owns | Changing it affects |
|---|---|---|
| The file | Contents, versions, provenance | Every record linked to it, because they all point at the same document |
| The link | The statement that a record is relevant | Only that record |
| The record | Its own fields, through its own service | Nothing about the file |

## Which records accept a file

The record's own service decides, not the file service. Where a record carries attachments the control to add one is on the record; where it does not, there is no control and no hidden route that creates the link anyway. This is the same rule the grid works under — the service that owns a record is the only thing that changes it, and nothing writes around the back of it.

The Files sheet in [the Data grid](/docs/files-data/data-grid/) is the inventory: every file in the workspace, whatever it is linked to. Start there when you know the document but not the record, and start from the record when it is the other way round.

## What the link changes

- **The document turns up where the work happens.** Anyone opening the deal sees it, rather than needing to know it exists.
- **A question asked on that record can reach it.** With the Assistant opened on a record, the files linked to that record are in scope — see [working on one record](/docs/assistant/record-context/).
- **It carries the file's whole chain.** The link is to the file, so later versions arrive with it; nothing needs relinking after a change.
- **It does not change permissions.** A file linked to a record is reachable by the people who can already reach that workspace. Linking is not sharing.

> **Careful** Linking a customer's document to the wrong company is the mistake worth watching for, because nothing about it looks wrong afterwards. The audit trail records who made the link, which is how it gets found; removing it is immediate and leaves the file untouched.

## Removing a link, and deleting a file

1. Remove the link from the record.
   - Result: The document stops appearing there. It still exists, still has every version, and is still on the Files sheet.
2. Check the other records it is linked to before assuming it is now unreachable.
   - Result: One file can be linked in several places; unlinking one is not withdrawal.
3. Deleting the file itself is a different, deliberate act.
   - Result: It removes the document and its chain, which is why it is not what the unlink control does.

Neither operation reaches outside your workspace. A link, like everything else here, is a scoped row: it cannot name a record in another workspace, and a row with no workspace stamp is invisible rather than shared — the point made in [data that is invisible rather than missing](/research/workspace-stamp/).

## Questions

### If I link one file to two records, are there two copies?

No. There is one document and two links. A change made anywhere produces a new version of the single file, and both records show it, which is exactly the behaviour you want for an agreement that concerns a company and a particular deal at the same time.

### Does an email attachment link itself to anything automatically?

An attachment arrives with the message it came on and belongs to that conversation. Attaching it to a company, a deal or a case is a decision somebody makes, because relevance to a record is a judgement rather than something that can be read off the file.

### Can the Assistant link a file for me?

It can propose it as part of a request, and the proposal names the exact record so a wrong one is visible before anything happens. It runs when you confirm, or waits in Needs You if the autonomy rule says a person decides.

## Related

- [The record of a file](https://connectbyjbrh.com/docs/files-data/file-audit/)
- [The Data grid](https://connectbyjbrh.com/docs/files-data/data-grid/)
- [Working on one record](https://connectbyjbrh.com/docs/assistant/record-context/)
- [Creating a file](https://connectbyjbrh.com/docs/files-data/create-file/)
- [Relationships in Connect](https://connectbyjbrh.com/docs/relationships/)
- [Sales in Connect](https://connectbyjbrh.com/docs/sales/)

## What this page is based on

- docs-source/sources/GENERAL.md §9 — one file service, both audiences
- docs-source/sources/GENERAL.md §3 — every scoped row carries a workspace
- `backend/app/file_workspace.py`
- `backend/app/audit.py`