> ## Documentation Index
> Fetch the complete documentation index at: https://docs.custral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Importing records

> Bring records in from a spreadsheet, a Google Sheet or a connected app, with Stella or the import screen.

You can bring records into Custral from three places:

* **A file.** A CSV or Excel export from your old tool.
* **A Google Sheet.** Paste its link. The sheet must be shared as "Anyone with the link can view".
* **A connected app** that supports data sync, such as HubSpot. Custral reads the tables you pick straight from the app.

Every import is checked before anything is written, can be undone for 30 days, and never stores a value in a field it doesn't fit.

<Tip>Try your first import in a [sandbox](/start/sandboxes/overview). Nothing you import there touches your live workspace.</Tip>

## Import with Stella

During setup, each tool you said you use gets a task on the home checklist ("Bring in your Zendesk data"). Opening it starts a chat with [Stella, your AI teammate](/ai/overview), already set up for that tool:

1. Stella says what comes across from that tool, what stays behind, and how to get the data out (an export file, a Sheets link, or a direct read).
2. You drop the file or paste the link. Stella maps each column to a field and asks only about the columns it isn't sure of. A column with nowhere to go can become a new field.
3. Stella runs a **dry run** and shows you the counts in a card. Nothing has been written yet.
4. You press **Start**. The card shows progress, then what was created, updated and skipped.

Opening the same task again reopens the same chat. You can also start an import in any Stella chat by dropping a file or pasting a Sheets link.

## The dry run

Before you start, the dry run reads the whole file against your workspace and reports:

| Line | What it means |
| - | - |
| **New** | Rows that don't match an existing record and will create one. |
| **Updated** | Rows that match an existing record and would change at least one field. |
| **Unchanged** | Rows that match a record and change nothing. |
| **Possible duplicates** | New rows whose name matches an existing record. They are still created unless you change the mapping; nothing merges on a name alone. |
| **Didn't fit** | Cells that don't fit their field (a word in a number field, a malformed email). They are left empty and listed by column. |
| **New options** | Values in a select or status column that aren't options yet. They are added as options. |
| **Records limit** | Where the import leaves you against your plan's records limit. |

Rows **match** an existing record by the column you mark as the identifier (an email, a domain, a phone number, or an id). Matching ignores case, spacing and formatting, so `ACME.com` and `https://www.acme.com/` match.

### When a row matches an existing record

Choose what happens to the fields it carries:

* **Fill empty fields** (the default). Only fields that are empty on the record are written.
* **Overwrite with the file.** The file's values replace what's there.
* **Skip them.** Matched records are left alone.

## While it runs and after

An import runs in the background. You can close the chat or the import screen; the card picks up where it is when you come back. **Stop** halts it after the current batch.

When it finishes you see what was created, updated, unchanged and skipped. If some rows didn't import, **Download failed rows** gives you a CSV of those rows with the reason for each, so you can fix them and import that file.

If an import stops partway (an outage, or you pressed Stop), **Resume** continues it. Rows already imported are matched, not added twice, so Resume needs an identifier column on every file.

## Undo

**Undo** removes the records the import created and puts back the values it changed on records that already existed. A field someone edited after the import is kept as they left it.

* You can undo your own import, or anyone's if you have **Can delete** in the workspace.
* Undo is available for 30 days after the import finishes.
* Addresses a tool's export listed as unsubscribed stay on your do-not-email list after an undo.

## Keep in sync

After importing from a connected app, a workspace admin can turn on **Keep in sync**. Custral then keeps those records updated from the app.

* **One way only.** Changes in the app come into Custral. Edits in Custral don't go back to the app.
* **Synced fields are read-only in Custral**, so a sync can't silently overwrite an edit. Edit them in the app.
* **Deletes don't carry over.** A record deleted in the app stays in Custral.
* The object shows a **Synced from …** badge with the last sync time. Open it to see each sync, why one is paused, and **Stop syncing**. Stopping keeps the records and unlocks their fields.
* A sync pauses rather than going past your records limit.

## The import screen

The **Import** screen (from the command palette, or when you create an object) runs the same import step by step: upload, map columns, dry run, run. Its history lists past imports, with **Undo** for each.

## Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;This sheet isn't shared&#x22;">
    Custral reads a Google Sheet through its link, so it must be shared as "Anyone with the link can view". In the sheet, choose **Share** → **General access** → **Anyone with the link**. A private sheet works if you download it as CSV and drop the file instead.
  </Accordion>

  <Accordion title="Start is turned off and the dry run says I'm over my records limit">
    The import would take the workspace past its plan's records limit, so it won't start. Import a smaller file, remove records you don't need, or move to a bigger plan.
  </Accordion>

  <Accordion title="A column wasn't imported">
    The dry run lists skipped columns and cells that didn't fit. A column mapped to a field you can't edit is skipped and named in the results. Ask an admin for **Can edit** on that field, or map the column somewhere else.
  </Accordion>

  <Accordion title="I can't edit a field: it says the field is synced">
    The field is kept up to date by a connected app. Edit it in the app, or have an admin stop the sync from the object's **Synced from …** badge.
  </Accordion>

  <Accordion title="Undo isn't available">
    Undo is open for 30 days after an import finishes, and only to the person who ran it or someone with **Can delete**. An import that is still running has to finish or be stopped first.
  </Accordion>

  <Accordion title="Keep in sync isn't offered">
    It's offered only for an import from a connected app, and only workspace admins can turn it on.
  </Accordion>
</AccordionGroup>

## Related

* [Records](/data/records/overview)
* [Fields](/data/records/fields)
* [Objects](/data/objects/overview)
* [Restricting one property](/team/permissions/overview#restricting-one-property)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.