> ## 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.

# Data Import

> Import CSV data into objects and records with guided column mapping, a test run, and one-click undo.

## Overview

The data import wizard (sometimes called **migrations**) brings external data (exports
from Salesforce, HubSpot, Attio, or a spreadsheet) into Custral as
[objects](/data/objects/overview) and [records](/data/records/overview). You
upload one or more CSV files, map each column to a property, optionally run a
small test, then execute the full import. Find it under **Migrations → Import
Data**.

## How it works

The wizard moves through five steps, tracked on the import session's status:

<Steps>
  <Step title="Upload">
    Upload one or more CSV files. Custral parses the headers and a sample of rows
    to drive the next step.
  </Step>

  <Step title="Map">
    Map each column to an existing property or create a new one. Custral pre-fills
    mappings from common header names (e.g. "Email Address" → Email) and infers a
    property **type** from the header and sample data. You can target an existing
    object or create a new object per file, mark a column as the **identity**
    column, skip columns, and link files together with **relations**.
  </Step>

  <Step title="Preview">
    Review how the mapped data will land before anything is written.
  </Step>

  <Step title="Run">
    Run a **test** against a small sample first, or **execute** the full import.
    Processing happens in the background.
  </Step>

  <Step title="Review">
    The completion screen reports **Total / Imported / Failed** row counts, any
    new objects, properties, and relationships created, a per-row error list, and
    a timeline. From here you can **Undo** a completed import or **Retry** a
    failed one.
  </Step>
</Steps>

### Identity columns & upserts

Marking a column as the **identity** column lets Custral match incoming rows to
existing records by that value instead of always creating new ones, the way to
*update* records on re-import rather than duplicate them.

### Relations between files

When importing related files (e.g. Contacts and Companies) in one session, map a
**relation** from a column in one file to a column in another so Custral links
the resulting records.

### Undo

A completed import can be undone from the completion screen or history. Undo
deletes the records created in that session, so a bad mapping is recoverable.

## History

The screen opens on **import history**, every past session with its status.
Select a session to resume it (re-mapping, retrying, or reviewing results).

## Troubleshooting

| Symptom                              | Likely cause                                  | What to check                                                                      |
| ------------------------------------ | --------------------------------------------- | ---------------------------------------------------------------------------------- |
| Rows land as the wrong property type | Type inference guessed from the header/sample | Adjust the column's type in the **Map** step before running.                       |
| Re-importing created duplicates      | No **identity** column was set                | Mark the unique column (email, external id) as identity so rows upsert.            |
| Some rows failed                     | Per-row validation errors                     | Open the completion screen's **Errors** list. Each entry shows the row and reason. |
| Related records aren't linked        | No **relation** mapped between the files      | Add a relation from the source column to the target file's column in the Map step. |
| Imported the wrong file              | —                                             | Use **Undo Import** on the completed session to remove its records, then re-run.   |

<Note>
  Imports run in the background; large files keep processing after you leave the
  screen, check **Migration History** for status.
</Note>

## Related

* [Objects](/data/objects/overview): where imported records live.
* [Properties](/data/properties/overview): the column types you map to.
* [Jobs](/automation/jobs/overview): background job status.


## Related topics

- [Learn the Product](/start/onboarding/learn.md)
- [Bulk edit](/automation/jobs/bulk-edit.md)
- [Automations](/automation/overview.md)
- [Data Migration](/start/onboarding/migration.md)
- [Object Mapping](/data/properties/complex/object-mapping.md)