Skip to main content
Bulk-import the contacts in a dataset into the active account under a tag. Start an import, read a snapshot of its progress, or block until it reaches a terminal phase. Optionally choose what wins when an imported row matches a contact you already have — see duplicate handling.
contacts-import is a platform-mode command. Before running it:
  1. landbase-cli auth login — authenticate the session.
  2. landbase-cli account set — pick and persist the target account.
  3. Have a datasetId from a prior search or agent run — the CLI does not produce datasets, so run a search/agent flow first.
Without an active account the command exits with No account id...; pass --account=<id> per call as an escape hatch.

​
contacts-import start

Start an import. Reads a JSON body — { datasetId, tagName, importId?, onDuplicate? } — and enqueues processing in one call. Pass - to read the body from stdin. Returns { importId, runRef }. With --watch, the command stays attached, polls until the import is terminal, and writes the final status to stdout instead of the start response. Usage
​
string
required
Path to a JSON file with the import body, or - to read it from stdin. Body shape: { "datasetId": "<dataset-id>", "tagName": "Q2 outreach", "importId"?: 7, "onDuplicate"?: "keep" | "update" }. datasetId and tagName (1–100 chars) are required; importId resumes an existing draft; onDuplicate picks the duplicate-handling policy.
Flags

​
contacts-import status

Read one status snapshot. Designed for scripts that drive their own polling loop. Usage
​
integer
required
The import id returned by contacts-import start.
Prints a lean, stable shape — { importId, phase, percent, counts, error } — where keys are present in every phase and null until known. See output schemas.

​
contacts-import wait

Block until the import is terminal, then print the final status to stdout. Runs the same polling loop as start --watch, streaming a progress line to stderr per poll. Backoff schedule: 5s, 10s, then a 20s cap; overall timeout 30 minutes. Usage
​
integer
required
The import id to wait on.
Prefer wait (or start --watch) over an external polling loop unless you need a custom cadence. Avoid sub-second polling — it won’t return results faster and may trip rate limits.

​
Duplicate handling

onDuplicate decides what wins when an imported row matches a contact that already exists in the account. It’s optional — omit it (or send null) and the server’s default handling applies, exactly as before. Matched rows land in counts.merged either way.
Either policy still updates profile fields (job title, location, …) from the file when the file carries a value — onDuplicate only toggles the identity fields. Blank values never clear existing data, and contacts locked by an active campaign are never overwritten.

​
Phases

phase is the value to branch on. The import is done once it reaches a terminal phase.

​
Errors

​
Examples