Data Imports

Early Access - The Dcycle CLI is currently available for enterprise customers. Contact us to learn more about access.

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

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

Step 1: Explore the Template

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

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

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

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

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

Step 3: Map Columns

Get AI Suggestions

The system analyzes your source columns and suggests mappings:

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:

mapping.json

{
  "invoice_type": "type",
  "start_date": "start",
  "end_date": "end",
  "consumption": "kwh",
  "provider": "provider",
  "cost": "cost"
}

dcy imports confirm-mapping 550e8400-... --mapping-file mapping.json

Check Unique Values

Before validating, preview how category values will be resolved:

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:

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:

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

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:

dcy imports validate 550e8400-... --mapping-file mapping.json --errors-only

Step 6: Submit

Once validation passes, submit the import for processing:

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

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

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:

dcy imports delete 550e8400-...

Complete Example

End-to-end import of energy invoices:

# 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

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

Next Steps

Invoices

Manage energy invoices for Scope 1 and Scope 2 emissions

Files

Upload and process documents

Examples

See end-to-end workflow examples

Configuration

Set up environments and API keys

Getting Started

Commands

Examples

Overview

Import Workflow

Step 1: Explore the Template

Get Available Options

Step 2: Create Import Session

Step 3: Map Columns

Get AI Suggestions

Confirm the Mapping

Check Unique Values

Step 4: Validate

Browse Rows

Step 5: Fix Errors (Optional)

Step 6: Submit

Managing Sessions

Check Session Status

List All Sessions

Delete a Session

Complete Example

Next Steps

Invoices

Files

Examples

Configuration

​Overview

​Import Workflow

​Step 1: Explore the Template

​Get Available Options

​Step 2: Create Import Session

​Step 3: Map Columns

​Get AI Suggestions

​Confirm the Mapping

​Check Unique Values

​Step 4: Validate

​Browse Rows

​Step 5: Fix Errors (Optional)

​Step 6: Submit

​Managing Sessions

​Check Session Status

​List All Sessions

​Delete a Session

​Complete Example

​Next Steps

Invoices

Files

Examples

Configuration

Overview

Import Workflow

Step 1: Explore the Template

Get Available Options

Step 2: Create Import Session

Step 3: Map Columns

Get AI Suggestions

Confirm the Mapping

Check Unique Values

Step 4: Validate

Browse Rows

Step 5: Fix Errors (Optional)

Step 6: Submit

Managing Sessions

Check Session Status

List All Sessions

Delete a Session

Complete Example

Next Steps