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

# Validate Import

> Validate mapped rows and return paginated row-level results

Run validation on the import session using the specified column mapping. Returns a summary of valid/error rows plus paginated row-level validation results. Use `errors_only=true` to focus on rows that need attention.

> [!NOTE]
>
> You can optionally include `value_mappings` to pre-resolve category values the user remapped by hand (e.g. mapping `"Camión"` → `"truck"` for the `vehicle_type` column).

## Request

### Headers

**x-api-key** `string` *required*

Your API key for authentication

**Example:** `sk_live_1234567890abcdef`

**x-organization-id** `string` *required*

Your organization UUID

**Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`

### Path Parameters

**import\_id** `string` *required*

UUID of the import session

**Example:** `"11111111-1111-1111-1111-111111111111"`

### Query Parameters

**page** `integer` (default: 1)

Page number (1-indexed)

**page\_size** `integer` (default: 50)

Rows per page (1–500)

**errors\_only** `boolean` (default: false)

When `true`, only return rows with validation errors

### Body Parameters

**mapping** `object` *required*

Column mapping to use for validation: `{target_column: source_column | null}`

**Example:** `{"origin": "origin", "destination": "destination", "weight": "weight_kg"}`

**value\_mappings** `object`

User-defined value remappings for category columns. Map of `{target_column: {raw_value: canonical_value}}`.

Leave it out to keep the value mappings of the previous validation (the ones
[`GET /status`](https://code.dcycle.io/api-reference/imports/get-status) returns), so validating again with only the column mapping does
not lose them. Send `{}` to clear them.

**Example:** `{"vehicle_type": {"Camión": "truck", "Furgoneta": "van"}}`

**context** `object`

Session context to store before validating, so the rows validate with it, for example the facility of a wastes
file: `{"facility_id": "…"}`. String values; only the template's required and submit context fields are accepted. Values are checked
as on create (facility access, transport direction), and a field the template makes immutable keeps the value it
has. Omit it to keep the session's context.

## Response

**import\_id** `string`

UUID of the import session

**total\_rows** `integer`

Total number of data rows

**valid\_rows** `integer`

Number of rows that passed validation

**error\_rows** `integer`

Number of rows with at least one validation error

**errors\_by\_column** `object`

Error counts per column key. Example: `{"weight": 2, "date": 1}`

**shape\_warnings** `object`

Warnings about the overall data shape (e.g. missing columns)

**rows** `array[object]`

Paginated row-level validation output

**Row Object**

**row\_index** `integer`

Zero-based index of the row in the original file

**data** `object`

Row data keyed by target column name

**errors** `object`

Validation errors keyed by column. Each value is an array of error objects with `rule`, `params`, and `message`.

**page** `integer`

Current page number

**page\_size** `integer`

Rows per page

**total\_pages** `integer`

Total number of pages

## Example

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.dcycle.io/v2/imports/11111111-1111-1111-1111-111111111111/validate?page=1&page_size=50&errors_only=false" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "mapping": {
      "origin": "origin",
      "destination": "destination",
      "weight": "weight_kg",
      "vehicle_type": "vehicle_type",
      "date": "date"
    },
    "value_mappings": {
      "vehicle_type": {"Camión": "truck", "Furgoneta": "van"}
    }
  }'
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests
import os

headers = {
    "x-api-key": os.getenv("DCYCLE_API_KEY"),
    "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
    "Content-Type": "application/json",
}

import_id = "11111111-1111-1111-1111-111111111111"

response = requests.post(
    f"https://api.dcycle.io/v2/imports/{import_id}/validate",
    headers=headers,
    params={"page": 1, "page_size": 50, "errors_only": False},
    json={
        "mapping": {
            "origin": "origin",
            "destination": "destination",
            "weight": "weight_kg",
            "vehicle_type": "vehicle_type",
            "date": "date",
        },
        "value_mappings": {
            "vehicle_type": {"Camión": "truck", "Furgoneta": "van"}
        },
    },
)

result = response.json()
print(f"Valid: {result['valid_rows']}/{result['total_rows']}")
print(f"Errors: {result['error_rows']} rows")
for row in result["rows"]:
    if row["errors"]:
        print(f"  Row {row['row_index']}: {row['errors']}")
```

```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const axios = require('axios');

const headers = {
  'x-api-key': process.env.DCYCLE_API_KEY,
  'x-organization-id': process.env.DCYCLE_ORG_ID,
  'Content-Type': 'application/json',
};

const importId = '11111111-1111-1111-1111-111111111111';

axios.post(`https://api.dcycle.io/v2/imports/${importId}/validate`, {
  mapping: {
    origin: 'origin',
    destination: 'destination',
    weight: 'weight_kg',
    vehicle_type: 'vehicle_type',
    date: 'date',
  },
  value_mappings: {
    vehicle_type: { 'Camión': 'truck', 'Furgoneta': 'van' },
  },
}, {
  headers,
  params: { page: 1, page_size: 50, errors_only: false },
}).then(response => {
  const { valid_rows, total_rows, error_rows } = response.data;
  console.log(`Valid: ${valid_rows}/${total_rows}, Errors: ${error_rows}`);
});
```

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "import_id": "11111111-1111-1111-1111-111111111111",
  "total_rows": 240,
  "valid_rows": 237,
  "error_rows": 3,
  "errors_by_column": {
    "weight": 2,
    "date": 1
  },
  "shape_warnings": {},
  "rows": [
    {
      "row_index": 0,
      "data": {
        "origin": "Madrid",
        "destination": "Barcelona",
        "weight": "1500",
        "vehicle_type": "truck",
        "date": "2024-03-15"
      },
      "errors": {}
    },
    {
      "row_index": 14,
      "data": {
        "origin": "Valencia",
        "destination": "Sevilla",
        "weight": "abc",
        "vehicle_type": "van",
        "date": "2024-03-16"
      },
      "errors": {
        "weight": [
          {
            "rule": "type_numeric",
            "params": {"value": "abc"},
            "message": "Expected a numeric value"
          }
        ]
      }
    }
  ],
  "page": 1,
  "page_size": 50,
  "total_pages": 5
}
```

## Common Errors

### 401 Unauthorized

**Cause:** Missing or invalid API key

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}
```

### 403 Forbidden

**Cause:** The authenticated user is not a member of the organization

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}
```

### 404 Not Found

**Cause:** The import session does not exist or belongs to another organization. Both cases return the same response, so a session id from another organization is indistinguishable from one that does not exist.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"code": "NOT_FOUND", "detail": "ImportSessionModel with id='1b2c3d4e-5f60-7182-93a4-b5c6d7e8f901' not found"}
```

**Cause:** The session's project is no longer one your organization can import into (for example, the organization was unlinked from it). Every step of the session answers this, not only the submit. Create a new session on a project you work in.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"code": "PROJECT_NOT_FOUND", "detail": "Project with id='9a8b7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4' not found"}
```

### 400 Bad Request

**Cause:** `context` names a field the session's template does not take

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"code": "IMPORT_CONTEXT_FIELD_NOT_ALLOWED", "detail": "Context fields not accepted for this template: project_id"}
```

### 409 Conflict

**Cause:** `context` changes a field the template makes immutable once set

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"code": "IMPORT_SESSION_CONTEXT_IMMUTABLE", "detail": "Import session context fields cannot be changed: lca_id"}
```

## Related Endpoints

> [card] [Confirm Mapping](https://code.dcycle.io/api-reference/imports/confirm-mapping.md)
>
> Persist the mapping before validating

> [card] [Submit Import](https://code.dcycle.io/api-reference/imports/submit.md)
>
> Submit the validated session for processing

> [card] [Get Unique Values](https://code.dcycle.io/api-reference/imports/get-unique-values.md)
>
> Inspect category values before validation

> [card] [Import Overview](https://code.dcycle.io/api-reference/imports/overview.md)
>
> Full workflow guide


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.