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

# How to import contacts

> Bulk-import the contacts in a dataset into your active account, and watch the import through to completion.

# How to import contacts

`contacts-import` loads the contacts in a dataset into your active account under
a tag. This guide covers finding the dataset and running the import.

<Note>
  Before you start, make sure you're signed in and have an active account
  selected — see
  [how to select and onboard an account](/docs/how-to/select-and-onboard-account).
  Without an active account, `contacts-import` exits with `No account id...`.
</Note>

***

## 1. Find the dataset to import

The CLI doesn't create datasets — you import one produced by a prior
[search](/docs/reference/search) or agent run. List your datasets to get its id:

```bash theme={null}
landbase-cli datasets list
```

```json theme={null}
[
  {
    "id": "ds_abc123",
    "name": "CRM Export Jun 2026",
    "created_at": "2026-06-05T10:00:00Z",
    "row_count": 952,
    "status": "ready"
  }
]
```

Inspect a specific one if you need to confirm its contents before importing:

```bash theme={null}
landbase-cli datasets show ds_abc123
```

See the [datasets command reference](/docs/reference/datasets) for the full set of
dataset commands.

***

## 2. Start the import and watch it

Pass the dataset id and a tag for the imported contacts. `--watch` streams
progress to stderr and writes the terminal status to stdout when the import
finishes:

```bash theme={null}
echo '{"datasetId":"ds_abc123","tagName":"Q2 outreach"}' \
  | landbase-cli contacts-import start --json - --watch
```

```json theme={null}
{
  "importId": 7,
  "phase": "completed",
  "percent": 100,
  "counts": { "total": 952, "imported": 940, "merged": 12, "skipped": 40, "invalid": 8 },
  "error": null
}
```

Read `counts` to see what landed: `imported` rows were written, `merged` rows
folded into existing contacts, and `skipped` + `invalid` rows didn't count toward
the processed `total`.

Once the import is `completed`, you can review it in the web app on the import
history page at
[app.landbase.com/data/imported-contacts?tab=history](https://app.landbase.com/data/imported-contacts?tab=history).
Make sure you're viewing the same account you imported into.

<Tip>
  Prefer `--watch` (or `contacts-import wait <importId>`) over rolling your own
  polling loop. Drive your own loop only if you need a custom cadence — call
  `contacts-import status <importId>` on a backoff.
</Tip>

***

## 3. If something fails

* **`No account id...`** — no active account; see
  [how to select and onboard an account](/docs/how-to/select-and-onboard-account).
* **`VALIDATION_ERROR`** — the `datasetId` is unknown or not accessible to this
  account; confirm it with `landbase-cli datasets show <dataset-id>`.
* **`CONFLICT`** — the import was already enqueued; don't retry, just poll
  `landbase-cli contacts-import status <importId>`.
* **`TIMEOUT` on `--watch`** — the import is still running server-side under the
  `importId` in the error's `meta`; resume with
  `landbase-cli contacts-import status <importId>`.

***

## Related

* [contacts-import command reference](/docs/reference/contacts-import)
* [datasets command reference](/docs/reference/datasets)
* [How to select and onboard an account](/docs/how-to/select-and-onboard-account)
* [Output schemas](/docs/reference/output-schemas#contacts-import)