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

# Data Imports

> Bulk import data from CSV and Excel files with guided mapping and validation

<Note>
  **Early Access** - The Dcycle CLI is currently available for enterprise customers.
  [Contact us](/docs/support) to learn more about access.
</Note>

## Overview

The `dcy imports` command provides a guided pipeline for bulk-importing data from CSV or Excel files. It handles column mapping, validation, error correction, and submission — all from the terminal.

**Supported data types (templates):**

| Template ID            | Description                               |
| ---------------------- | ----------------------------------------- |
| `invoices`             | Energy invoices (electricity, gas, water) |
| `vehicles`             | Fleet vehicles                            |
| `vehicle_consumptions` | Vehicle fuel consumption records          |
| `purchases`            | Purchased goods and services              |
| `business_travels`     | Business travel records                   |
| `logistics_requests`   | Transport requests                        |
| `logistics_recharges`  | Fuel recharges                            |
| `employees`            | Employee commute records                  |
| `wastes`               | Waste records                             |

***

## Import Workflow

A typical import follows these steps:

```
create → suggest-mapping → confirm-mapping → validate → [patch] → submit
```

1. **Create** — Upload your file and start an import session
2. **Suggest mapping** — Get AI-assisted column mapping suggestions
3. **Confirm mapping** — Lock in the column mapping
4. **Validate** — Check all rows for errors
5. **Patch** (optional) — Fix row-level errors
6. **Submit** — Process the import and create records

***

## Step 1: Explore the Template

Before importing, check what columns and formats the template expects:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# View template metadata
dcy imports template invoices
```

Output:

```
template_id: invoices
required_context_fields: facility_id
KEY                            TYPE       REQUIRED ALIASES
----------------------------------------------------------------------------------------------------
invoice_type                   category   yes      type, tipo
start_date                     date       yes      fecha_inicio, start
end_date                       date       yes      fecha_fin, end
consumption                    number     yes      consumo, kwh
provider                       text       no       proveedor, supplier
cost                           number     no       coste, cost, importe
```

### Get Available Options

For category columns, check what values are accepted:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# List countries
dcy imports options countries

# List fuel types
dcy imports options vehicle_fuels

# List invoice types
dcy imports options invoice_types
```

***

## Step 2: Create Import Session

Upload a file and start a new import session:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy imports create \
  --template invoices \
  --file invoices-2024.xlsx \
  --facility-id abc123-def456
```

Output:

```
import_id:      550e8400-e29b-41d4-a716-446655440000
file_name:      invoices-2024.xlsx
total_rows:     150
source_columns: type, start, end, kwh, provider, cost
sample_rows (first 3):
  [0] electricity | 2024-01-01 | 2024-01-31 | 4500 | Iberdrola | 890.50
  [1] natural_gas | 2024-01-01 | 2024-01-31 | 1200 | Naturgy | 320.00
  [2] electricity | 2024-02-01 | 2024-02-28 | 4200 | Iberdrola | 850.00
```

| Flag               | Required | Description                                           |
| ------------------ | -------- | ----------------------------------------------------- |
| `--template`       | Yes      | Template ID (see table above)                         |
| `--file`           | Yes      | Path to CSV or XLSX file                              |
| `--facility-id`    | Depends  | Facility UUID (required for invoices, wastes)         |
| `--project-id`     | No       | Project UUID to attach                                |
| `--sheet-name`     | No       | Sheet name for multi-sheet XLSX files                 |
| `--numeric-locale` | No       | Numeric locale hint (e.g. `es_ES` for comma decimals) |
| `--date-locale`    | No       | Date format: `dmy` or `mdy` for ambiguous dates       |
| `--folder-id`      | No       | Folder UUID to attach                                 |
| `--raw-file-id`    | No       | Link to a pre-existing file upload                    |
| `--org`            | No       | Organization ID override                              |

<Tip>
  Use `--numeric-locale es_ES` when your CSV uses commas as decimal separators (e.g. `4.500,50` instead of `4500.50`).
</Tip>

***

## Step 3: Map Columns

### Get AI Suggestions

The system analyzes your source columns and suggests mappings:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy imports suggest-mapping 550e8400-...
```

Output:

```
TEMPLATE COLUMN                SUGGESTED SOURCE               CONFIDENCE   REASON
----------------------------------------------------------------------------------------------------
invoice_type                   type                           0.95         exact match [auto-mapped]
start_date                     start                          0.88         alias match [suggested]
end_date                       end                            0.88         alias match [suggested]
consumption                    kwh                            0.92         alias match [auto-mapped]
provider                       provider                       0.95         exact match [auto-mapped]
cost                           cost                           0.70         fuzzy match [suggested]
```

Confidence tiers:

* **≥ 0.92** — `auto-mapped`: high confidence, ready to use
* **0.60–0.91** — `suggested`: review recommended
* **\< 0.60** — `unmapped`: manual mapping required

### Confirm the Mapping

Save the mapping to a JSON file and confirm it:

```json title="mapping.json" theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "invoice_type": "type",
  "start_date": "start",
  "end_date": "end",
  "consumption": "kwh",
  "provider": "provider",
  "cost": "cost"
}
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy imports confirm-mapping 550e8400-... --mapping-file mapping.json
```

### Check Unique Values

Before validating, preview how category values will be resolved:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy imports unique-values 550e8400-... --mapping-file mapping.json
```

Output:

```
invoice_type  ←  type  [3 unique]
  electricity                      → electricity                    [resolved]
  natural_gas                      → natural_gas                    [resolved]
  agua                             → -                              [unresolved]
```

Unresolved values will appear as validation errors. Fix them in your file or patch them after validation.

***

## Step 4: Validate

Run validation to check all rows against the template rules:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy imports validate 550e8400-... --mapping-file mapping.json
```

Output:

```
valid_rows: 147 / 150  |  error_rows: 3  |  page 1/1
errors by column:
  invoice_type: 2
  consumption: 1
[45] invoice_type=agua, start=2024-03-01, end=2024-03-31, kwh=500 | errors: {"invoice_type":"invalid value"}
[89] invoice_type=agua, start=2024-06-01, end=2024-06-30, kwh=300 | errors: {"invoice_type":"invalid value"}
[120] invoice_type=electricity, start=2024-09-01, end=2024-09-30, kwh= | errors: {"consumption":"required"}
```

| Flag             | Default | Description                          |
| ---------------- | ------- | ------------------------------------ |
| `--mapping-file` | —       | Path to JSON mapping file (required) |
| `--page`         | `1`     | Page number                          |
| `--page-size`    | `50`    | Rows per page                        |
| `--errors-only`  | `false` | Only show rows with errors           |

### Browse Rows

Inspect all rows (or just error rows) with pagination:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Show error rows only
dcy imports rows 550e8400-... --errors-only --page-size 100

# Show all rows page by page
dcy imports rows 550e8400-... --page 1 --page-size 20
```

***

## Step 5: Fix Errors (Optional)

Patch individual row values without re-uploading the file:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy imports patch 550e8400-... --corrections '[
  {"row_index": 45, "column": "invoice_type", "value": "water"},
  {"row_index": 89, "column": "invoice_type", "value": "water"},
  {"row_index": 120, "column": "consumption", "value": "450"}
]'
```

Output:

```
updated_rows: 3  |  total_errors_remaining: 0
```

Then re-validate to confirm all errors are resolved:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy imports validate 550e8400-... --mapping-file mapping.json --errors-only
```

***

## Step 6: Submit

Once validation passes, submit the import for processing:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy imports submit 550e8400-... --partner dcycle
```

Output:

```
status:            submitted
rows_submitted:    150
file_id:           abc12345-...
processing_job_id: def67890-...
```

| Flag              | Default  | Description                                |
| ----------------- | -------- | ------------------------------------------ |
| `--partner`       | `dcycle` | Partner slug (required)                    |
| `--ignore-errors` | `false`  | Submit even if rows have validation errors |
| `--org`           | —        | Organization ID override                   |

***

## Managing Sessions

### Check Session Status

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy imports status 550e8400-...
```

Output shows current status (`created`, `parsed`, `mapped`, `validating`, `validated`, `submitting`, `submitted`, `failed`, `expired`), row counts, and processing info.

### List All Sessions

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy imports list

# Short alias
dcy imports ls

# Filter by status
dcy imports list --status validated

# Filter by template
dcy imports list --template invoices

# Include expired sessions
dcy imports list --include-expired
```

| Flag                | Default | Description              |
| ------------------- | ------- | ------------------------ |
| `--status`          | —       | Filter by session status |
| `--template`        | —       | Filter by template ID    |
| `--user-id`         | —       | Filter by user UUID      |
| `--include-expired` | `false` | Include expired sessions |
| `--page`            | `1`     | Page number              |
| `--page-size`       | `20`    | Sessions per page        |

### Delete a Session

Remove a non-submitted session and its cached data:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy imports delete 550e8400-...
```

***

## Complete Example

End-to-end import of energy invoices:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 1. Check template requirements
dcy imports template invoices --format json | jq '.columns[] | {key, type, required}'

# 2. Upload file
SESSION=$(dcy imports create \
  --template invoices \
  --file invoices-q1.xlsx \
  --facility-id abc123 \
  --numeric-locale es_ES \
  --format json | jq -r '.import_id')

echo "Session: $SESSION"

# 3. Get mapping suggestions and save
dcy imports suggest-mapping $SESSION --format json | jq '.suggestions' > mapping.json

# 4. Validate
dcy imports validate $SESSION --mapping-file mapping.json

# 5. Fix any errors
dcy imports validate $SESSION --mapping-file mapping.json --errors-only --format json \
  | jq '.rows[] | {row: .row_index, errors: .errors}'

# 6. Submit
dcy imports submit $SESSION --partner dcycle
```

<Tip>
  All `imports` subcommands support `--format json` for scripting. Pipe through `jq` to extract fields like `import_id`, `total_rows`, or `error_rows`.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Emissions Data" icon="leaf" href="/cli/emissions-data">
    Manage invoices, purchases, and travel data
  </Card>

  <Card title="Files" icon="file" href="/cli/files">
    Upload and process documents
  </Card>

  <Card title="Examples" icon="code" href="/cli/examples">
    See end-to-end workflow examples
  </Card>

  <Card title="Configuration" icon="gear" href="/cli/configuration">
    Set up environments and API keys
  </Card>
</CardGroup>